AETHER-3297 update roc developer docs
Change-Id: I7677f12d94f5c4c23b10bef3fcf69190fbc3cb15
diff --git a/developer/roc-api.rst b/developer/roc-api.rst
index 2ba3605..98088e2 100644
--- a/developer/roc-api.rst
+++ b/developer/roc-api.rst
@@ -15,7 +15,7 @@
.. note:: Opening this in a browser will display a HTML view of the API (powered by *ReDoc*).
To access the raw YAML format use
- ``curl -H "Accept: application/yaml" http://localhost:8183/aether-roc-api/aether-4.0.0-openapi3.yaml``
+ ``curl -H "Accept: application/yaml" http://localhost:8183/aether-roc-api/aether-2.0.0-openapi3.yaml``
This YAML format can be imported in to various different tools e.g. |postman_link|
Background
@@ -33,10 +33,10 @@
Endpoints are named based on the type of object. Some examples:
-* `GET http://roc/aether/v4.0.0/connectivity-service-v3/enterprise/`. Get a list of enterprises.
-* `GET http://roc/aether/v4.0.0/connectivity-service-v3/enterprise/Starbucks`. Get the Starbucks enterprise.
-* `POST http://roc/aether/v4.0.0/connectivity-service-v3/enterprise`. Create a new enterprise.
-* `PATCH http://roc/aether/v4.0.0/connectivity-service-v3/site/Starbucks-NewYork`. Update the Starbucks New York site.
+* `GET http://roc/aether/v2.0.0/connectivity-service-v2/enterprises`. Get a list of enterprises.
+* `GET http://roc/aether/v2.0.0/connectivity-service-v2/enterprises/starbucks`. Get the Starbucks enterprise.
+* `POST http://roc/aether/v2.0.0/connectivity-service-v2/enterprises`. Create a new enterprise.
+* `POST http://roc/aether/v2.0.0/connectivity-service-v2/enterprises/enterprise/starbucks/site/starbucks-newyork`. Update the Starbucks New York site.
This document is a high-level description of the objects that can be interacted with. For a
low-level description, see the specification (:ref:`developer/roc-api:Access` section above).
@@ -47,13 +47,15 @@
Every object contains an `id` that is used to identify the object. The `id` is only unique within
the scope of a particular type of object. For example, a site may be named `foo` and a device-group
may also be named `foo`, and the two names do not conflict because they are different object types.
+The `id` is model specific. For example, a site has a `site-id` and an slice has a
+`slice-id`. The models are generally nested, for example `slice` is a member of `site`, which in
+turn is a member of `enterprise`.
In addition to the `id`, most identifiable objects also include a `display-name`. The `display-name`
may be changed at any time by the user without affecting behavior. In contrast, the `id` is immutable,
and the only way to change an `id` is to delete the object and make a new one.
-Some objects contain references to other objects. For example, many objects contain references to
-the `Enterprise` object, which allows them to be associated with a particular enterprise. References
+Some objects contain references to other objects. References
are constructed using the `id` field of the referenced object. It is an error to attempt to create
a reference to an object that does not exist. Deleting an object while there are open references
to it from other objects is also an error.
@@ -63,7 +65,7 @@
Several fields are common to all models in Aether:
-* `id`. The identifier for objects of this model.
+* `<modelname>-id`. The identifier for objects of this model.
* `description`. A human-readable description, used to store additional context about the object.
* `display-name`. A human-readable name that is shown in the GUI.
@@ -92,7 +94,6 @@
may be either physical or logical (i.e. a single geographic location could in theory contain several
logical sites). Site contains the following fields:
-* `enterprise`. A link to the `Enterprise` that owns this site.
* `imsi-definition`. A description of how IMSIs are constructed for this site. Contains the following
sub-fields:
@@ -127,54 +128,40 @@
`Device-Group` allows multiple devices to be logically grouped together. `Device-Group` contains
the following fields:
-* `imsis`. A list of IMSI ranges. Each range has the following
- fields:
-
- * `imsi-id`. Identifier of the IMSI. Serves the same purpose as other `id` fields.
- * `imsi-range-from`. First subscriber in the range.
- * `imsi-range-to`. Last subscriber in the range. Can be omitted if the range only contains one
- IMSI. It is recommended to not use this feature, and to represent all IMSIs as singletons. This
- field will be deprecated in the future.
+* `devices`. A list of Devices. Each device has an `enable` field which can be used to
+ enable or disable the device.
* `ip-domain`. Reference to an `IP-Domain` object that describes the IP and DNS settings for UEs
within this group.
-* `site`. Reference to the site where this `Device-Group` may be used. Indirectly identifies the
- `Enterprise` as `Site` contains a reference to `Enterprise`.
+* `mbr`. Per-device maximum bitrate in bits per second that the application will be limited to:
-* `device`. Per-device related QoS settings:
+ * `uplink` the `mbr` from device to slice
+ * `downlink` the `mbr` from slice to device
- * `mbr`. The maximum bitrate in bits per second that the application will be limited to:
+* `traffic-class`. The traffic class to be used for devices in this group.
- * `uplink` the `mbr` from device to slice
- * `downlink` the `mbr` from slice to device
+Slice
+~~~~~
- * `traffic-class`. The traffic class to be used for devices in this group.
-
-Virtual Cellular Service
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-`Virtual Cellular Service (VCS)` connects a `Device-Group` to an `Application`. `VCS` has the
+`Slice` connects a `Device-Group` to an `Application`. `Slice` has the
following fields:
-* `device-group`. A list of `Device-Group` objects that can participate in this `VCS`. Each
+* `device-group`. A list of `Device-Group` objects that can participate in this `Slice`. Each
entry in the list contains both the reference to the `Device-Group` as well as an `enable`
field which may be used to temporarily remove access to the group.
* `default-behavior`. May be set to either `ALLOW-ALL`, `DENY-ALL`, or `ALLOW-PUBLIC`. This is
the rule to use if no other rule in the filter matches. `ALLOW-PUBLIC` is a special alias
that denies all private networks and then allows everything else.
* `filter`. A list of `Application` objects that are either allowed or denied for this
- `VCS`. Each entry in the list contains both a reference to the `Application` as well as an
+ `Slice`. Each entry in the list contains both a reference to the `Application` as well as an
`allow` field which can be set to `true` to allow the application or `false` to deny it. It
also has a `priority` field which can be used to order the applications when considering the
enforcing of their `allow` or `deny` conditions.
* `upf`. Reference to the User Plane Function (`UPF`) that should be used to process packets
- for this `VCS`. It's permitted for multiple `VCS` to share a single `UPF`.
-* `enterprise`. Reference to the `Enterprise` that owns this `VCS`.
-* `site`. Reference to the `Site` where this `VCS` is deployed. Aether maintains the restriction
- that the `Site` of the `UPF` and `Device-Group` must match the `Site` of the `VCS`.
+ for this `Slice`. It's permitted for multiple `Slice` to share a single `UPF`.
* `SST`, `SD`. Slice identifiers. These are assigned by Aether Operations.
-* `slice.mbr.uplink`, `slice.mbr.downlink`. Slice-total Uplink and downlink maximum bit rates in bps.
-* `slice.mbr.uplink-burst-size`, `slice.mbr.downlink-burst-size`. Maximum burst sizes in bytes for
- the maximum bit rates.
+* `mbr.uplink`, `mbr.downlink`. Slice-total Uplink and downlink maximum bit rates in bps.
+* `mbr.uplink-burst-size`, `mbr.downlink-burst-size`. Maximum burst sizes in bytes for
+ the maximum bit rates.
Application
~~~~~~~~~~~
@@ -197,9 +184,6 @@
* `traffic-class`. Traffic class to be used when UEs send traffic to this Application endpoint.
-* `enterprise`. Link to an `Enterprise` object that owns this application. May be left empty
- to indicate a global application that may be used by multiple enterprises.
-
Supporting Aether Objects
-------------------------
@@ -228,10 +212,10 @@
~~~~~~~~
`Template` contains connectivity settings that are pre-configured by Aether Operations.
-Templates are used to initialize `VCS` objects. `Template` has the following fields:
+Templates are used to initialize `Slice` objects. `Template` has the following fields:
* `default-behavior`. May be set to either `ALLOW-ALL`, `DENY-ALL`, or `ALLOW-PUBLIC`. This is
- the rule to use if no other rule in the VCS's application filter matches. `ALLOW-PUBLIC` is
+ the rule to use if no other rule in the Slice's application filter matches. `ALLOW-PUBLIC` is
a special alias that denies all private networks and then allows everything else.
* `sst`, `sd`. Slice identifiers.
* `uplink`, `downlink`. Guaranteed uplink and downlink bandwidth.
@@ -253,7 +237,7 @@
UPF
~~~
-Specifies the UPF that should forward packets. A UPF can only be used by one VCS at a time.
+Specifies the UPF that should forward packets. A UPF can only be used by one Slice at a time.
Has the following fields:
* `address`. Hostname or IP address of UPF.
diff --git a/developer/roc.rst b/developer/roc.rst
index 079a8cf..fb9f93b 100644
--- a/developer/roc.rst
+++ b/developer/roc.rst
@@ -35,11 +35,11 @@
# install atomix
export ATOMIX_CONTROLLER_VERSION=0.6.8
helm -n kube-system install atomix-controller atomix/atomix-controller --version $ATOMIX_CONTROLLER_VERSION
- export ATOMIX_RAFT_VERSION=0.1.15
+ export ATOMIX_RAFT_VERSION=0.1.16
helm -n kube-system install atomix-raft-storage atomix/atomix-raft-storage --version $ATOMIX_RAFT_VERSION
# install the onos operator
- ONOS_OPERATOR_VERSION=0.4.14
+ ONOS_OPERATOR_VERSION=0.5.1
helm install -n kube-system onos-operator onosproject/onos-operator --version $ONOS_OPERATOR_VERSION
.. note:: The ROC is sensitive to the versions of Atomix and onos-operator installed. The values
@@ -69,6 +69,10 @@
- 0.6.8
- 0.1.15
- 0.4.14
+ * - 2.0.29-
+ - 0.6.8
+ - 0.1.16
+ - 0.5.1
Verify that these services were installed properly.
You should see pods for *atomix-controller*, *atomix-raft-storage-controller*,
@@ -93,7 +97,7 @@
ingress:
enabled: false
- aether-roc-gui-v3:
+ aether-roc-gui-v2:
ingress:
enabled: false
EOF
@@ -103,10 +107,7 @@
Add the necessary helm repositories::
- # obtain username and password from Michelle and/or ONF infra team
- export repo_user=<username>
- export repo_password=<password>
- helm repo add aether --username "$repo_user" --password "$repo_password" https://charts.aetherproject.org
+ helm repo add aether https://charts.aetherproject.org
``aether-roc-umbrella`` will bring up the ROC and its services::
@@ -170,7 +171,7 @@
not getting cleaned up. The following may be useful::
# fix stuck finalizers in operator CRDs
- kubectl -n micro-onos patch entities connectivity-service-v4 --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]' && \
+ kubectl -n micro-onos patch entities connectivity-service-v2 --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]' && \
kubectl -n micro-onos patch entities plproxy-amp --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]' && \
kubectl -n micro-onos patch entities plproxy-acc --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]' && \
kubectl -n micro-onos patch kind plproxy --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]' && \
@@ -191,7 +192,7 @@
# aether-roc-gui
- kubectl -n micro-onos port-forward service/aether-roc-gui-v4 --address 0.0.0.0 8183:80
+ kubectl -n micro-onos port-forward service/aether-roc-gui-v2 --address 0.0.0.0 8183:80
# grafana
@@ -214,17 +215,12 @@
Custom images may be used by editing the values-override.yaml file.
For example, to deploy a custom ``sdcore-adapter``::
- sdcore-adapter-v3:
-
- prometheusEnabled: false
-
+ sdcore-adapter-v2:
+ prometheusEnabled: false
image:
-
- repository: my-private-repo/sdcore-adapter
-
- tag: my-tag
-
- pullPolicy: Always
+ repository: my-private-repo/sdcore-adapter
+ tag: my-tag
+ pullPolicy: Always
The above example assumes you have published a docker images at ``my-private-repo/sdcore-adapter:my-tag``.
My particular workflow is to deploy a local-docker registry and push my images to that.
@@ -240,23 +236,25 @@
Developing using a custom onos-config
-------------------------------------
-The onos-operator is responsible for building model plugins at runtime. To do this, it needs source code
-for onos-config that matches the onos-config image that is deployed. One way to do this is to fork the
-onos-config repository and commit your onos-config changes to a personal repository, and then reference
-that personal repository in the values.yaml. For example::
+The onos-config helm chart is responsible for loading model plugins at runtime. You can override which
+plugins it loads, and optionally override the image for onos-config as well. For example::
- onos-config:
- plugin:
- compiler:
- target: "github.com/mygithubaccount/onos-config@mytag"
- image:
- repository: mydockeraccount/onos-config
- tag: mytag
- pullPolicy: Always
+ onos-config:
+ image:
+ tag: mytag
+ repository: mydockeraccount/onos-config
+ modelPlugins:
+ - name: aether-2
+ image: mydockeraccount/aether-2.0.x:mytag
+ endpoint: localhost
+ port: 5152
+ - name: aether-4
+ image: mydockeraccount/aether-4.x:mytag
+ endpoint: localhost
+ port: 5153
-In the above example, the operator will pull the image from `mydockeraccount`, and it'll pull the
-onos-config code from `mygithubaccount`. Using a personal docker account is not strictly necessary;
-images can also be built and tagged entirely locally.
+In the above example, the onos-config image will be pulled from `mydockeraccount`, and it will install
+two plugins for v2 and v4 models, from that same docker account.
Inspecting logs
---------------
@@ -268,7 +266,7 @@
Then you can inspect a specific pod/container::
- kubectl -n micro-onos logs deployment/sdcore-adapter-v4
+ kubectl -n micro-onos logs deployment/sdcore-adapter-v2
.. _securing_roc:
@@ -287,7 +285,7 @@
helm -n micro-onos install aether-roc-umbrella aether/aether-roc-umbrella \
--set onos-config.openidc.issuer=https://keycloak-dev.onlab.us/auth/realms/master \
--set aether-roc-api.openidc.issuer=https://keycloak-dev.onlab.us/auth/realms/master \
- --set aether-roc-gui-v4.openidc.issuer=https://keycloak-dev.onlab.us/auth/realms/master \
+ --set aether-roc-gui-v2.openidc.issuer=https://keycloak-dev.onlab.us/auth/realms/master \
--set prom-label-proxy-acc.config.openidc.issuer=https://keycloak-dev.onlab.us/auth/realms/master \
--set prom-label-proxy-amp.config.openidc.issuer=https://keycloak-dev.onlab.us/auth/realms/master
@@ -393,7 +391,7 @@
--data-urlencode 'client_id=aether-roc-gui' \
--data-urlencode 'username=alicea' \
--data-urlencode 'password=password' \
- --data-urlencode 'scope=openid profile email groups' | jq "access_token"
+ --data-urlencode 'scope=openid profile email groups' | jq "{access_token}"
The key will expire after 24 hours.
@@ -499,20 +497,20 @@
through the Slice, DeviceGroup, and other objects to see that they were
created as expected.
-2. Examine the log of the ``sdcore-adapter-v3`` container. It should be
+2. Examine the log of the ``sdcore-adapter-v2`` container. It should be
attempting to push the mega-patch’s changes. If you don’t have a core
available, it may be failing the push, but you should see the attempts.
-3. Change an object in the GUI. Watch the ``sdcore-adapter-v3`` log file and
+3. Change an object in the GUI. Watch the ``sdcore-adapter-v2`` log file and
see that the adapter attempts to push the change.
-4. Try POSTing a change via the API. Observe the ``sdcore-adapter-v3`` log
+4. Try POSTing a change via the API. Observe the ``sdcore-adapter-v2`` log
file and see that the adapter attempts to push the change.
5. Deploy a 5G Aether-in-a-Box (See :doc:`Setting Up Aether-in-a-Box
<aiab>`), modify the mega-patch to specify the URL for the Aether-in-a-Box
``webui`` container, POST the mega-patch, and observe that the changes were
- correctly pushed via the ``sdcore-adapter-v3`` into the ``sd-core``’s
+ correctly pushed via the ``sdcore-adapter-v2`` into the ``sd-core``’s
``webui`` container (``webui`` container log will show configuration as it
is received)