blob: 602ebdf0a88115c074fc079e0637a4cddf882531 [file] [log] [blame]
Andy Bavierf73c3d22021-08-30 10:29:06 -07001.. vim: syntax=rst
2
3Setting Up Aether-in-a-Box
4==========================
5
Andy Bavier840e0b42021-09-16 17:10:23 -07006Aether-in-a-Box (AiaB) provides an easy way to deploy Aether's SD-CORE and ROC
7components, and then run basic tests to validate the installation.
8This guide describes the steps to set up AiaB.
Andy Bavierf73c3d22021-08-30 10:29:06 -07009
Andy Bavier840e0b42021-09-16 17:10:23 -070010AiaB can be set up with a 4G or 5G SD-CORE. In either case, SD-CORE configuration
11can be done with or without the ROC. The ROC
12provides an interactive GUI for examining and changing the configuration, and is used to
13manage the production Aether; it can be deployed to test the integration between
14ROC and SD-CORE. If the ROC is not deployed, a simple tool called SimApp
15is used to configure the required state in SD-CORE for testing core functionality.
16
17Helm charts are the primary method of installing the SD-CORE and ROC resources.
18AiaB offers a great deal of flexibility regarding which Helm chart versions to install:
19
20* Local definitions of charts (for testing Helm chart changes)
21* Latest published charts (for deploying a development version of Aether)
22* Specified versions of charts (for deploying a specific Aether release)
23
24AiaB can be run on a bare metal machine or VM. System prerequisites:
Andy Bavierf73c3d22021-08-30 10:29:06 -070025
26* Ubuntu 18.04
27* Kernel 4.15 or later
28* Haswell CPU or newer
29
30Clone Repositories
31------------------
32
Andy Bavier840e0b42021-09-16 17:10:23 -070033To initialize the AiaB environment, first clone the following repository
34using your Gerrit ID::
Andy Bavierf73c3d22021-08-30 10:29:06 -070035
Andy Bavier840e0b42021-09-16 17:10:23 -070036 cd ~
37 git clone "ssh://<username>@gerrit.opencord.org:29418/aether-in-a-box"
38
39If you are going to install AiaB using published Helm charts, you can proceed to the
40next section.
41
42If you wish to install SD-CORE from local Helm charts, clone these additional repositories::
43
44 mkdir -p ~/cord
45 cd ~/cord
Andy Bavierf73c3d22021-08-30 10:29:06 -070046 git clone "ssh://<username>@gerrit.opencord.org:29418/helm-charts"
47 git clone "ssh://<username>@gerrit.opencord.org:29418/aether-helm-charts"
48
Andy Bavier840e0b42021-09-16 17:10:23 -070049If you wish to install the ROC from local Helm charts, clone these::
50
51 mkdir -p ~/cord
52 cd ~/cord
53 git clone https://github.com/atomix/atomix-helm-charts.git
54 git clone https://github.com/onosproject/onos-helm-charts.git
55 git clone https://github.com/onosproject/sdran-helm-charts.git # Private repo
56
57Now change to *~/aether-in-a-box* directory.
Andy Bavierf73c3d22021-08-30 10:29:06 -070058
59Set up Authentication Tokens
60----------------------------
61
Andy Bavier840e0b42021-09-16 17:10:23 -070062Edit the file *configs/authentication*.
Andy Bavierf73c3d22021-08-30 10:29:06 -070063
64Fill out REGISTRY_USERNAME and REGISTRY_CLI_SECRET as follows:
65
66* Log into the `Aether Harbor Registry <https://registry.aetherproject.org>`_ using your Crowd credentials
67* Select *User Profile* from the drop-down menu in the upper right corner
68* For REGISTRY_USERNAME, use the *Username* in your profile
69* Copy the *CLI secret* to the clipboard and paste to REGISTRY_CLI_SECRET
70
Andy Bavier840e0b42021-09-16 17:10:23 -070071If you wish to install SD-CORE using Aether's published Helm charts, or if you are installing the ROC, also
72fill out REPO_USERNAME and REPO_PASSWORD with the information needed to authenticate with Aether's Helm
73chart repository.
Andy Bavierf73c3d22021-08-30 10:29:06 -070074
Andy Bavier840e0b42021-09-16 17:10:23 -070075If you have already set up AiaB but you used incorrect credentials, first clean up AiaB as described
76in the `Cleanup`_ section, then edit *configs/authentication* and re-build AiaB.
Andy Bavierf73c3d22021-08-30 10:29:06 -070077
Andy Bavier840e0b42021-09-16 17:10:23 -070078Installing the ROC
79------------------
Andy Bavierf73c3d22021-08-30 10:29:06 -070080
Andy Bavier840e0b42021-09-16 17:10:23 -070081Note that you must install the ROC *before* installing SD-CORE.
82If you are not using the ROC to configure SD-CORE, you can skip this step.
Andy Bavierf73c3d22021-08-30 10:29:06 -070083
Andy Bavier840e0b42021-09-16 17:10:23 -070084First choose whether you will install the 4G or 5G SD-CORE. To install the ROC to
85configure the 4G SD-CORE::
Andy Bavierf73c3d22021-08-30 10:29:06 -070086
Andy Bavier840e0b42021-09-16 17:10:23 -070087 make roc-4g-models
88
89To install the ROC to configure the 5G SD-CORE::
90
91 make roc-5g-models
92
93By default the above commands install the ROC from the local charts in the Git repos cloned
94earlier. In order to install the ROC using the latest published charts, add *CHARTS=latest*
95to the command, e.g.,::
96
97 CHARTS=latest make roc-4g-models
98
99To install the Aether 1.5 release candidate version, add *CHARTS=rc-1.5*::
100
101 CHARTS=rc-1.5 make roc-4g-models
102
103Start the 4G SD-CORE
104--------------------
105
106If you are installing the 5G SD-CORE, you can skip this step.
107
108To deploy the 4G SD-CORE and run a simple ping test::
109
110 make test
111
112By default the above commands install the 4G SD-CORE from the local charts in the Git repos cloned
113earlier. In order to install the SD-CORE using the latest published charts, add *CHARTS=latest*
114to the command, e.g.,::
115
116 CHARTS=latest make test
117
118To install the Aether 1.5 release candidate version, add *CHARTS=rc-1.5*::
Andy Bavierf73c3d22021-08-30 10:29:06 -0700119
120 CHARTS=rc-1.5 make test
121
Andy Bavier840e0b42021-09-16 17:10:23 -0700122Start the 5G SD-CORE
123--------------------
Andy Bavierf73c3d22021-08-30 10:29:06 -0700124
Andy Bavier840e0b42021-09-16 17:10:23 -0700125If you have already installed the 4G SD-CORE, you must skip this step. Only one version of
126the SD-CORE can be installed at a time.
Andy Bavierf73c3d22021-08-30 10:29:06 -0700127
Andy Bavier840e0b42021-09-16 17:10:23 -0700128To deploy the 5G SD-CORE::
Andy Bavierf73c3d22021-08-30 10:29:06 -0700129
Andy Bavier840e0b42021-09-16 17:10:23 -0700130 make 5gc
Andy Bavierf73c3d22021-08-30 10:29:06 -0700131
Andy Bavier840e0b42021-09-16 17:10:23 -0700132By default the above commands install the 5G SD-CORE from the local charts in the Git repos cloned
133earlier. In order to install the SD-CORE using the latest published charts, add *CHARTS=latest*
134to the command, e.g.,::
Andy Bavierf73c3d22021-08-30 10:29:06 -0700135
Andy Bavier840e0b42021-09-16 17:10:23 -0700136 CHARTS=latest make 5gc
Andy Bavierf73c3d22021-08-30 10:29:06 -0700137
Andy Bavier840e0b42021-09-16 17:10:23 -0700138To install the Aether 1.5 release candidate version, add *CHARTS=rc-1.5*::
Andy Bavierf73c3d22021-08-30 10:29:06 -0700139
Andy Bavier840e0b42021-09-16 17:10:23 -0700140 CHARTS=rc-1.5 make 5gc
Andy Bavierf73c3d22021-08-30 10:29:06 -0700141
142You can use *gnbsim* to test 5G functionality. For example, to run the 5G user registration::
143
144 kubectl -n omec exec gnbsim-0 -- /go/src/gnbsim/gnbsim register
145
Andy Bavier840e0b42021-09-16 17:10:23 -0700146Currently there is no ping test for the 5G SD-CORE.
Andy Bavierf73c3d22021-08-30 10:29:06 -0700147
Andy Bavier840e0b42021-09-16 17:10:23 -0700148Cleanup
149-------
Andy Bavierf73c3d22021-08-30 10:29:06 -0700150
Andy Bavier840e0b42021-09-16 17:10:23 -0700151The first time you build AiaB, it takes a while because it sets up the Kubernetes cluster.
152Subsequent builds will be much faster if you follow these steps to clean up the Helm charts without
153destroying the Kubernetes cluster.
Andy Bavierf73c3d22021-08-30 10:29:06 -0700154
Andy Bavier840e0b42021-09-16 17:10:23 -0700155* Clean up the 4G SD-CORE: *make reset-test*
156* Clean up the 5G SD-CORE: *make reset-5g-test*
157* Clean up the ROC: *make roc-clean*
158
159It's normal for the above commands to take a minute or two to complete.
160
161As an example, suppose that you want to test the 4G SD-CORE with the ROC, and then the 5G SD-CORE
162with the ROC. You could run these commands::
163
164 CHARTS=latest make roc-4g-models # Install ROC with 4G configuration
165 CHARTS=latest make test # Install 4G SD-CORE and run ping test
166 make reset-test
167 make roc-clean
168 CHARTS=latest make roc-5g-models # Install ROC with 5G configuration
169 CHARTS=latest make 5gc # Install 5G SD-CORE
170 make reset-5g-test
171 make roc-clean
172
173Developer Loop
174--------------
175
176Suppose you wish to test a new build of a 5G SD-CORE services. You can deploy custom images
177by editing `~/aether-in-a-box/5g-core-values.yaml`, for example::
Andy Bavierf73c3d22021-08-30 10:29:06 -0700178
179 images:
180 tags:
181 webui: registry.aetherproject.org/omecproject/5gc-webui:onf-release3.0.5-roc-935305f
182 pullPolicy: IfNotPresent
Andy Bavierf73c3d22021-08-30 10:29:06 -0700183
Andy Bavier840e0b42021-09-16 17:10:23 -0700184To upgrade a running 5G SD-CORE with the new image, or to deploy the 5G SD-CORE with the image::
Andy Bavierf73c3d22021-08-30 10:29:06 -0700185
Andy Bavierf73c3d22021-08-30 10:29:06 -0700186 make 5gc
Andy Bavier840e0b42021-09-16 17:10:23 -0700187
188Troubleshooting / Known Issues
189------------------------------
190
191If you suspect a problem, first verify that all pods are in Running state::
192
193 kubectl -n omec get pods
194 kubectl -n aether-roc get pods
195
196If the pods are stuck in ImagePullBackOff state, then it's likely an issue with credentials. See the
197`Set up Authentication Tokens`_ section.
198
1994G Test Fails
200^^^^^^^^^^^^^
201Occasionally *make test* (for 4G) fails for unknown reasons; this is true regardless of which Helm charts are used.
202If this happens, first try cleaning up AiaB and re-running the test. If *make test* fails consistently, check
203whether the configuration has been pushed to the SD-CORE::
204
205 kubectl -n omec logs config4g-0 | grep "Successfully"
206
207You should see that a device group and slice has been pushed::
208
209 [INFO][WebUI][CONFIG] Successfully posted message for device group 4g-oaisim-user to main config thread
210 [INFO][WebUI][CONFIG] Successfully posted message for slice default to main config thread
211
212Then tail the *config4g-0* log and make sure that the configuration has been successfully pushed to all
213SD-CORE components.
214
2155G Test Fails
216^^^^^^^^^^^^^
217Currently the 5G *gnbsim* does not support data packets, though the UE can successfully register.
218For example the *gnbsim register* command gets stuck here::
219
220 ip address in string 172.250.0.1
221 err <nil>
222 UE address - 172.250.0.1
223 Assigned address to UE address 172.250.0.1
224 sent message NGAP-PDU Session Resource Setup Response
225 Failed to write gtpu packet
226 Sent uplink gtpu packet
227 Failed to write gtpu packet
228 Sent uplink gtpu packet
229 Failed to write gtpu packet
230 Sent uplink gtpu packet
231
232Fixing this is work-in-progress.