blob: 42ce0f89abd24b84fba26e5088f50528ba888a8a [file] [log] [blame]
Scott Bakerfab7c9e2021-07-29 17:12:16 -07001.. vim: syntax=rst
2
3Aether ROC Developer Guide
4==========================
5
6Background / Development Environment
7------------------------------------
8
9This document assumes familiarity with Kubernetes and Helm, and that a Kubernetes/Helm development
10environment has already been deployed in the developers work environment.
Zack Williams1ae109e2021-07-27 11:17:04 -070011
12This development environment can use any of a number of potential mechanisms -- including KinD, kubeadm, etc.
13
Scott Bakerfab7c9e2021-07-29 17:12:16 -070014The Aether-in-a-Box script is one potential way to setup a development environment, but not the only way.
15As an alternative to the developers local machine, a remote environment can be set up, for example on
Zack Williams1ae109e2021-07-27 11:17:04 -070016cloud infrastructure such as Cloudlab.
Scott Bakerfab7c9e2021-07-29 17:12:16 -070017
Sean Condoneb95cd62021-08-04 19:44:18 +010018.. note:: When ROC is deployed it is unsecured by default, with no Authentication or Authorization.
19 To secure ROC so that the Authentication and Authorization can be tested, follow the Securing ROC
20 guide below :ref:`securing_roc`
21
Scott Bakerfab7c9e2021-07-29 17:12:16 -070022Installing Prerequisites
23------------------------
24
25Atomix and onos-operator must be installed::
26
27 # create necessary namespaces
28 kubectl create namespace micro-onos
29
Andy Bavier4c425412021-08-27 14:39:38 -070030 # add repos
31 helm repo add atomix https://charts.atomix.io
32 helm repo add onosproject https://charts.onosproject.org
33 helm repo update
34
Scott Bakerfab7c9e2021-07-29 17:12:16 -070035 # install atomix
Sean Condon70dcf702021-08-24 10:57:29 +010036 export ATOMIX_CONTROLLER_VERSION=0.6.8
Sean Condon257687f2021-08-23 11:13:20 +010037 helm -n kube-system install atomix-controller atomix/atomix-controller --version $ATOMIX_CONTROLLER_VERSION
Sean Condon70dcf702021-08-24 10:57:29 +010038 export ATOMIX_RAFT_VERSION=0.1.9
39 helm -n kube-system install atomix-raft-storage atomix/atomix-raft-storage --version $ATOMIX_RAFT_VERSION
Scott Bakerfab7c9e2021-07-29 17:12:16 -070040
41 # install the onos operator
Sean Condon1df1fcf2021-09-20 09:45:39 +010042 ONOS_OPERATOR_VERSION=0.4.10
Sean Condon257687f2021-08-23 11:13:20 +010043 helm install -n kube-system onos-operator onosproject/onos-operator --version $ONOS_OPERATOR_VERSION
Scott Bakerfab7c9e2021-07-29 17:12:16 -070044
Sean Condon257687f2021-08-23 11:13:20 +010045.. note:: The ROC is sensitive to the versions of Atomix and onos-operator installed. The values
Sean Condon1df1fcf2021-09-20 09:45:39 +010046 shown above are correct for the 1.3.x versions of the *aether-roc-umbrella*.
Sean Condon257687f2021-08-23 11:13:20 +010047
48.. list-table:: ROC support component version matrix
Sean Condon70dcf702021-08-24 10:57:29 +010049 :widths: 40 20 20 20
Sean Condon257687f2021-08-23 11:13:20 +010050 :header-rows: 1
51
52 * - ROC Version
53 - Atomix Controller
54 - Atomix Raft
55 - Onos Operator
Sean Condon70dcf702021-08-24 10:57:29 +010056 * - 1.2.25-1.2.45
Sean Condon257687f2021-08-23 11:13:20 +010057 - 0.6.7
58 - 0.1.8
59 - 0.4.8
Sean Condon70dcf702021-08-24 10:57:29 +010060 * - 1.3.0-
61 - 0.6.8
62 - 0.1.9
Sean Condon1df1fcf2021-09-20 09:45:39 +010063 - 0.4.10
Scott Bakerfab7c9e2021-07-29 17:12:16 -070064
65Verify that these services were installed properly.
66You should see pods for *atomix-controller*, *atomix-raft-storage-controller*,
67*onos-operator-config*, and *onos-operator-topo*.
68Execute these commands::
69
Sean Condon257687f2021-08-23 11:13:20 +010070 helm -n kube-system list
Scott Bakerfab7c9e2021-07-29 17:12:16 -070071 kubectl -n kube-system get pods | grep -i atomix
72 kubectl -n kube-system get pods | grep -i onos
73
Scott Bakerfab7c9e2021-07-29 17:12:16 -070074Create a values-override.yaml
75-----------------------------
76
77Youll want to override several of the defaults in the ROC helm charts::
78
79 cat > values-override.yaml <<EOF
80 import:
Scott Bakerb46a6ed2021-08-02 14:03:10 -070081 onos-gui:
82 enabled: true
Scott Bakerfab7c9e2021-07-29 17:12:16 -070083
84 onos-gui:
Scott Bakerb46a6ed2021-08-02 14:03:10 -070085 ingress:
86 enabled: false
Scott Bakerfab7c9e2021-07-29 17:12:16 -070087
88 aether-roc-gui-v3:
Scott Bakerb46a6ed2021-08-02 14:03:10 -070089 ingress:
90 enabled: false
Scott Bakerfab7c9e2021-07-29 17:12:16 -070091 EOF
92
Zack Williams1ae109e2021-07-27 11:17:04 -070093Installing the ``aether-roc-umbrella`` Helm chart
94-------------------------------------------------
Scott Bakerfab7c9e2021-07-29 17:12:16 -070095
96Add the necessary helm repositories::
97
98 # obtain username and password from Michelle and/or ONF infra team
99 export repo_user=<username>
100 export repo_password=<password>
Sean Condon1df1fcf2021-09-20 09:45:39 +0100101 helm repo add aether --username "$repo_user" --password "$repo_password" https://charts.aetherproject.org
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700102
Zack Williams1ae109e2021-07-27 11:17:04 -0700103``aether-roc-umbrella`` will bring up the ROC and its services::
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700104
Sean Condon1df1fcf2021-09-20 09:45:39 +0100105 helm -n micro-onos install aether-roc-umbrella aether/aether-roc-umbrella -f values-override.yaml
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700106
107 kubectl wait pod -n micro-onos --for=condition=Ready -l type=config --timeout=300s
108
109
Sean Condonf918f642021-08-04 14:32:53 +0100110.. _posting-the-mega-patch:
111
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700112Posting the mega-patch
113----------------------
114
115The ROC usually comes up in a blank state -- there are no Enterprises, UEs, or other artifacts present in it.
116The mega-patch is an example patch that populates the ROC with some sample enterprises, UEs, slices, etc.
117Execute the following::
118
119 # launch a port-forward for the API
120 # this will continue to run in the background
121 kubectl -n micro-onos port-forward service/aether-roc-api --address 0.0.0.0 8181:8181 &
122
123 git clone https://github.com/onosproject/aether-roc-api.git
124
125 # execute the mega-patch (it will post via CURL to localhost:8181)
126 bash ~/path/to/aether-roc-api/examples/MEGA_Patch.curl
127
128
129You may wish to customize the mega patch.
Zack Williams1ae109e2021-07-27 11:17:04 -0700130
131For example, by default the patch configures the ``sdcore-adapter`` to push to
132``sdcore-test-dummy``.
133
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700134You could configure it to push to a live aether-in-a-box core by doing something like this::
135
136 sed -i 's^http://aether-roc-umbrella-sdcore-test-dummy/v1/config/5g^http://webui.omec.svc.cluster.local:9089/config^g' MEGA_Patch.curl
137
138 #apply the patch
139 ./MEGA_Patch.curl
140
141(Note that if your Aether-in-a-Box was installed on a different machine that port-forwarding may be necessary)
142
143
144Expected CURL output from a successful mega-patch post will be a UUID.
Zack Williams1ae109e2021-07-27 11:17:04 -0700145
146You can also verify that the mega-patch was successful by going into the
147``aether-roc-gui`` in a browser (see the section on useful port-forwards
148below). The GUI may open to a dashboard that is unpopulated -- you can use the
149dropdown menu (upper-right hand corner of the screen) to select an object such
150as VCS and you will see a list of VCS.
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700151
152 |ROCGUI|
153
Zack Williams1ae109e2021-07-27 11:17:04 -0700154Uninstalling the ``aether-roc-umbrella`` Helm chart
155---------------------------------------------------
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700156
157To tear things back down, usually as part of a developer loop prior to redeploying again, do the following::
158
159 helm -n micro-onos del aether-roc-umbrella
160
161If the uninstall hangs or if a subsequent reinstall hangs, it could be an issue with some of the CRDs
162not getting cleaned up. The following may be useful::
163
164 # fix stuck finalizers in operator CRDs
165
166 kubectl -n micro-onos patch entities connectivity-service-v2 --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]'
167
168 kubectl -n micro-onos patch entities connectivity-service-v3 --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]'
169
170 kubectl -n micro-onos patch kind aether --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]'
171
172Useful port forwards
173--------------------
174
175Port forwarding is often necessary to allow access to ports inside of Kubernetes pods that use ClusterIP addressing.
176Note that you typically need to leave a port-forward running (you can put it in the background).
177Also, If you redeploy the ROC and/or if a pod crashes then you might have to restart a port-forward.
178The following port-forwards may be useful::
179
180 # aether-roc-api
181
182 kubectl -n micro-onos port-forward service/aether-roc-api --address 0.0.0.0 8181:8181
183
184 # aether-roc-gui
185
186 kubectl -n micro-onos port-forward service/aether-roc-gui --address 0.0.0.0 8183:80
187
188 # grafana
189
190 kubectl -n micro-onos port-forward service/aether-roc-umbrella-grafana --address 0.0.0.0 8187:80
191
192 # onos gui
193
194 kubectl -n micro-onos port-forward service/onos-gui --address 0.0.0.0 8182:80
195
Zack Williams1ae109e2021-07-27 11:17:04 -0700196``aether-roc-api`` and ``aether-roc-gui`` are in our experience the most useful two port-forwards.
197
198``aether-roc-api`` is useful to be able to POST REST API requests.
199
200``aether-roc-gui`` is useful to be able to interactively browse the current configuration.
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700201
Sean Condon257687f2021-08-23 11:13:20 +0100202.. note:: Internally the ``aether-roc-gui`` operates a Reverse Proxy on the ``aether-roc-api``. This
203 means that if you have done a ``port-forward`` to ``aether-roc-gui`` say on port ``8183`` there's no
204 need to do another on the ``aether-roc-api`` instead you can access the API on
205 ``http://localhost:8183/aether-roc-api``
206
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700207Deploying using custom images
208-----------------------------
209
210Custom images may be used by editing the values-override.yaml file.
Zack Williams1ae109e2021-07-27 11:17:04 -0700211For example, to deploy a custom ``sdcore-adapter``::
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700212
213 sdcore-adapter-v3:
214
215 prometheusEnabled: false
216
217 image:
218
219 repository: my-private-repo/sdcore-adapter
220
221 tag: my-tag
222
223 pullPolicy: Always
224
Zack Williams1ae109e2021-07-27 11:17:04 -0700225The above example assumes you have published a docker images at ``my-private-repo/sdcore-adapter:my-tag``.
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700226My particular workflow is to deploy a local-docker registry and push my images to that.
227Please do not publish ONF images to a public repository unless the image is intended to be public.
228Several ONF repositories are private, and therefore their docker artifacts should also be private.
229
230There are alternatives to using a private docker repository.
Zack Williams1ae109e2021-07-27 11:17:04 -0700231For example, if you are using kubeadm, then you may be able to simply tag the image locally.
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700232If you’re using KinD, then you can push a local image to into the kind cluster::
233
234 kind load docker-image sdcore-adapter:my-tag
235
Scott Bakerabcfc6e2021-09-08 22:37:51 -0700236Developing using a custom onos-config
237-------------------------------------
238
239The onos-operator is responsible for building model plugins at runtime. To do this, it needs source code
240for onos-config that matches the onos-config image that is deployed. One way to do this is to fork the
241onos-config repository and commit your onos-config changes to a personal repository, and then reference
242that personal repository in the values.yaml. For example::
243
244 onos-config:
245 plugin:
246 compiler:
247 target: "github.com/mygithubaccount/onos-config@mytag"
248 image:
249 repository: mydockeraccount/onos-config
250 tag: mytag
251 pullPolicy: Always
252
253In the above example, the operator will pull the image from `mydockeraccount`, and it'll pull the
254onos-config code from `mygithubaccount`. Using a personal docker account is not strictly necessary;
255images can also be built and tagged entirely locally.
256
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700257Inspecting logs
258---------------
259
260Most of the relevant Kubernetes pods are in the micro-onos namespace.
261The names may change from deployment to deployment, so start by getting a list of pods::
262
263 kubectl -n micro-onos get pods
264
265Then you can inspect a specific pod/container::
266
267 kubectl -n micro-onos logs sdcore-adapter-v3-7468cc58dc-ktctz sdcore-adapter-v3
268
Sean Condoneb95cd62021-08-04 19:44:18 +0100269.. _securing_roc:
270
271Securing ROC
272------------
273
Zack Williams1ae109e2021-07-27 11:17:04 -0700274When deploying ROC with the ``aether-roc-umbrella`` chart, secure mode can be enabled by
Sean Condoneb95cd62021-08-04 19:44:18 +0100275specifying an OpenID Connect (OIDC) issuer like::
276
Andy Baviere86261e2021-09-21 11:05:18 -0700277 helm -n micro-onos install aether-roc-umbrella aether/aether-roc-umbrella \
Sean Condon948aeaa2021-09-29 12:08:30 +0100278 --set onos-config.openidc.issuer=http://k3u-keycloak:80/auth/realms/master \
279 --set aether-roc-gui-v3.openidc.issuer=http://k3u-keycloak:5557/auth/realms/master
Sean Condoneb95cd62021-08-04 19:44:18 +0100280
Sean Condon948aeaa2021-09-29 12:08:30 +0100281The choice of OIDC issuer in this case is ``keycloak-389-umbrella``, or alternately ``dex-ldap-umbrella`` (deprecated).
Sean Condoneb95cd62021-08-04 19:44:18 +0100282
Sean Condon948aeaa2021-09-29 12:08:30 +0100283``keycloak-389-umbrella``
284"""""""""""""""""""""""""
285
286Keycloak is an Open Source Identity and Access Management for Modern Applications and
287Services. It can be used as an OIDC Issuer than can act as a front end to several authentication systems
288e.g. LDAP, Crowd, Google, GitHub
289
290``keycloak-389-umbrella`` is a Helm chart that combines a Keycloak server with an LDAP
291installation (389 Directory Server), and an LDAP administration tool. It can be deployed in to the
292same cluster namespace as ``aether-roc-umbrella``.
293
294Its LDAP server is populated with 7 different users in the 2 example enterprises - *starbucks* and *acme*.
295
296When running it should be available at *http://k3u-keycloak:5557/auth/realms/master/.well-known/openid-configuration*.
297
298See `keycloak-389-umbrella <https://github.com/onosproject/onos-helm-charts/tree/master/keycloak-389-umbrella#readme>`_
299for more details.
300
301In a production environment, the public Aether Keycloak (with its LDAP server populated with Aether users and groups) should be used.
302See `public keycloak <https://keycloak.opennetworking.org/auth/realms/master/.well-known/openid-configuration>`_ for more details.
303
304.. note:: Your RBAC access to ROC will be limited by the groups you belong to in its LDAP store.
305
306``dex-ldap-umbrella`` (Deprecated)
307""""""""""""""""""""""""""""""""""
Sean Condoneb95cd62021-08-04 19:44:18 +0100308
309Dex is a cloud native OIDC Issuer than can act as a front end to several authentication systems
310e.g. LDAP, Crowd, Google, GitHub
311
Sean Condon948aeaa2021-09-29 12:08:30 +0100312``dex-ldap-umbrella`` is a Helm chart that combines a Dex server with an OpenLDAP
Zack Williams1ae109e2021-07-27 11:17:04 -0700313installation, and an LDAP administration tool. It can be deployed in to the
314same cluster namespace as ``aether-roc-umbrella``.
Sean Condoneb95cd62021-08-04 19:44:18 +0100315
316Its LDAP server is populated with 7 different users in the 2 example enterprises - *starbucks* and *acme*.
317
318When running it should be available at *http://dex-ldap-umbrella:5556/.well-known/openid-configuration*.
319
320See `dex-ldap-umbrella <https://github.com/onosproject/onos-helm-charts/tree/master/dex-ldap-umbrella#readme>`_
321for more details.
322
323As an alternative there is a public Dex server connected to the ONF Crowd server, that allows
324ONF staff to login with their own credentials:
325See `public dex <https://dex.aetherproject.org/dex/.well-known/openid-configuration>`_ for more details.
326
327.. note:: Your RBAC access to ROC will be limited by the groups you belong to in Crowd.
328
329Role Based Access Control
Zack Williams1ae109e2021-07-27 11:17:04 -0700330"""""""""""""""""""""""""
331
Sean Condoneb95cd62021-08-04 19:44:18 +0100332When secured, access to the configuration in ROC is limited by the **groups** that a user belongs to.
333
334* **AetherROCAdmin** - users in this group have full read **and** write access to all configuration.
335* *<enterprise>* - users in a group the lowercase name of an enterprise, will have **read** access to that enterprise.
336* **EnterpriseAdmin** - users in this group will have read **and** write access the enterprise they belong to.
337
Sean Condon948aeaa2021-09-29 12:08:30 +0100338 For example in *keycloak-389-umbrella* the user *Daisy Duke* belongs to *starbucks* **and**
Sean Condoneb95cd62021-08-04 19:44:18 +0100339 *EnterpriseAdmin* and so has read **and** write access to items linked with *starbucks* enterprise.
340
341 By comparison the user *Elmer Fudd* belongs only to *starbucks* group and so has only **read** access to items
342 linked with the *starbucks* enterprise.
343
344Requests to a Secure System
Zack Williams1ae109e2021-07-27 11:17:04 -0700345"""""""""""""""""""""""""""
346
Sean Condoneb95cd62021-08-04 19:44:18 +0100347When configuration is retrieved or updated through *aether-config*, a Bearer Token in the
Zack Williams1ae109e2021-07-27 11:17:04 -0700348form of a JSON Web Token (JWT) issued by the selected OIDC Issuer server must accompany
Sean Condoneb95cd62021-08-04 19:44:18 +0100349the request as an Authorization Header.
350
Zack Williams1ae109e2021-07-27 11:17:04 -0700351This applies to both the REST interface of ``aether-roc-api`` **and** the *gnmi* interface of
352``aether-rconfig``.
Sean Condoneb95cd62021-08-04 19:44:18 +0100353
354In the Aether ROC, a Bearer Token can be generated by logging in and selecting API Key from the
355menu. This pops up a window with a copy button, where the key can be copied.
356
357The key will expire after 24 hours.
358
359.. image:: images/aether-roc-gui-copy-api-key.png
360 :width: 580
361 :alt: Aether ROC GUI allows copying of API Key to clipboard
362
363Accessing the REST interface from a tool like Postman, should include this Auth token.
364
365.. image:: images/postman-auth-token.png
366 :width: 930
367 :alt: Postman showing Authentication Token pasted in
368
369Logging
Zack Williams1ae109e2021-07-27 11:17:04 -0700370"""""""
371
Sean Condoneb95cd62021-08-04 19:44:18 +0100372The logs of *aether-config* will contain the **username** and **timestamp** of
373any **gnmi** call when security is enabled.
374
375.. image:: images/aether-config-log.png
376 :width: 887
377 :alt: aether-config log message showing username and timestamp
378
Sean Condon435be9a2021-08-06 14:28:37 +0100379Accessing GUI from an external system
Zack Williams1ae109e2021-07-27 11:17:04 -0700380"""""""""""""""""""""""""""""""""""""
381
Sean Condon435be9a2021-08-06 14:28:37 +0100382To access the ROC GUI from a computer outside the Cluster machine using *port-forwarding* then
383it is necessary to:
384
385* Ensure that all *port-forward*'s have **--address=0.0.0.0**
386* Add to the IP address of the cluster machine to the **/etc/hosts** of the outside computer as::
387
Sean Condon948aeaa2021-09-29 12:08:30 +0100388 <ip address of cluster> k3u-keycloak aether-roc-gui
389* Verify that you can access the Keycloak server by its name *http://k3u-keycloak:5557/auth/realms/master/.well-known/openid-configuration*
Zack Williams1ae109e2021-07-27 11:17:04 -0700390* Access the GUI through the hostname (rather than ip address) ``http://aether-roc-gui:8183``
Sean Condon435be9a2021-08-06 14:28:37 +0100391
Sean Condoneb95cd62021-08-04 19:44:18 +0100392Troubleshooting Secure Access
Zack Williams1ae109e2021-07-27 11:17:04 -0700393"""""""""""""""""""""""""""""
394
Sean Condoneb95cd62021-08-04 19:44:18 +0100395While every effort has been made to ensure that securing Aether is simple and effective,
396some difficulties may arise.
397
Sean Condon948aeaa2021-09-29 12:08:30 +0100398One of the most important steps is to validate that the OIDC Issuer (Keycloak server) can be reached
Sean Condoneb95cd62021-08-04 19:44:18 +0100399from the browser. The **well_known** URL should be available and show the important endpoints are correct.
400
Sean Condon948aeaa2021-09-29 12:08:30 +0100401.. image:: images/keycloak-389-umbrella-well-known.png
Sean Condoneb95cd62021-08-04 19:44:18 +0100402 :width: 580
Sean Condon948aeaa2021-09-29 12:08:30 +0100403 :alt: Keycloak Well Known page
Sean Condoneb95cd62021-08-04 19:44:18 +0100404
405If logged out of the Browser when accessing the Aether ROC GUI, accessing any page of the application should
Sean Condon948aeaa2021-09-29 12:08:30 +0100406redirect to the Keycloak login page.
Sean Condoneb95cd62021-08-04 19:44:18 +0100407
Sean Condon948aeaa2021-09-29 12:08:30 +0100408.. image:: images/keycloak-ldap-login-page.png
Sean Condoneb95cd62021-08-04 19:44:18 +0100409 :width: 493
Sean Condon948aeaa2021-09-29 12:08:30 +0100410 :alt: Keycloak Login page
Sean Condoneb95cd62021-08-04 19:44:18 +0100411
412When logged in the User details can be seen by clicking the User's name in the drop down menu.
413This shows the **groups** that the user belongs to, and can be used to debug RBAC issues.
414
415.. image:: images/aether-roc-gui-user-details.png
416 :width: 700
417 :alt: User Details page
418
Sean Condon948aeaa2021-09-29 12:08:30 +0100419When you sign out of the ROC GUI, if you are not redirected to the Keycloak Login Page,
Sean Condoneb95cd62021-08-04 19:44:18 +0100420you should check the Developer Console of the browser. The console should show the correct
Sean Condon948aeaa2021-09-29 12:08:30 +0100421OIDC issuer (Keycloak server), and that Auth is enabled.
Sean Condoneb95cd62021-08-04 19:44:18 +0100422
423.. image:: images/aether-roc-gui-console-loggedin.png
424 :width: 418
425 :alt: Browser Console showing correct configuration
426
Scott Bakerb46a6ed2021-08-02 14:03:10 -0700427ROC Data Model Conventions and Requirements
428-------------------------------------------
429
430The MEGA-Patch described above will bring up a fully compliant sample data model.
431However, it may be useful to bring up your own data model, customized to a different
432site of sites. This subsection documents conventions and requirements for the Aether
Zack Williams1ae109e2021-07-27 11:17:04 -0700433modeling within the ROC.
Scott Bakerb46a6ed2021-08-02 14:03:10 -0700434
435The ROC models must be configured with the following:
436
437* A default enterprise with the id `defaultent`.
438* A default ip-domain with the id `defaultent-defaultip`.
439* A default site with the id `defaultent-defaultsite`.
440 This site should be linked to the `defaultent` enterprise.
441* A default device group with the id `defaultent-defaultsite-default`.
442 This device group should be linked to the `defaultent-defaultip` ip-domain
443 and the `defaultent-defaultsite` site.
444
445Each Enterprise Site must be configured with a default device group and that default
446device group's name must end in the suffix `-default`. For example, `acme-chicago-default`.
447
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700448Some exercises to get familiar
449------------------------------
450
Zack Williams1ae109e2021-07-27 11:17:04 -07004511. Deploy the ROC and POST the mega-patch, go into the ``aether-roc-gui`` and click
452 through the VCS, DeviceGroup, and other objects to see that they were
453 created as expected.
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700454
Zack Williams1ae109e2021-07-27 11:17:04 -07004552. Examine the log of the ``sdcore-adapter-v3`` container. It should be
456 attempting to push the mega-patchs changes. If you dont have a core
457 available, it may be failing the push, but you should see the attempts.
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700458
Zack Williams1ae109e2021-07-27 11:17:04 -07004593. Change an object in the GUI. Watch the ``sdcore-adapter-v3`` log file and
460 see that the adapter attempts to push the change.
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700461
Zack Williams1ae109e2021-07-27 11:17:04 -07004624. Try POSTing a change via the API. Observe the ``sdcore-adapter-v3`` log
463 file and see that the adapter attempts to push the change.
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700464
Andy Bavierf73c3d22021-08-30 10:29:06 -07004655. Deploy a 5G Aether-in-a-Box (See :doc:`Setting Up Aether-in-a-Box
466 <aiab>`), modify the mega-patch to specify the URL for the Aether-in-a-Box
Zack Williams1ae109e2021-07-27 11:17:04 -0700467 ``webui`` container, POST the mega-patch, and observe that the changes were
468 correctly pushed via the ``sdcore-adapter-v3`` into the ``sd-core``s
469 ``webui`` container (``webui`` container log will show configuration as it
470 is received)
Scott Bakerfab7c9e2021-07-29 17:12:16 -0700471
472.. |ROCGUI| image:: images/rocgui.png
Sean Condoneb95cd62021-08-04 19:44:18 +0100473 :width: 945
474 :alt: ROC GUI showing list of VCS