Aether-3438 add docs about how to add a new enterprise
Change-Id: I049b15bb3b1be9e4676dce93426623c561e1f41a
diff --git a/developer/images/rocgui.png b/developer/images/rocgui.png
index c2b388f..eca93a5 100644
--- a/developer/images/rocgui.png
+++ b/developer/images/rocgui.png
Binary files differ
diff --git a/developer/roc-api.rst b/developer/roc-api.rst
index 98088e2..06a937b 100644
--- a/developer/roc-api.rst
+++ b/developer/roc-api.rst
@@ -10,6 +10,8 @@
e.g. on a local system (if the GUI has been port-forwarded on port 8183)
*http://localhost:8183/aether-roc-api/*
+For Aether-In-A-Box deployment the API can be found at *http://<hostname>:31194/aether-roc-api/*
+
On the Production system it would be *https://roc.aetherproject.org/aether-roc-api/*
.. note:: Opening this in a browser will display a HTML view of the API (powered by *ReDoc*).
@@ -33,27 +35,31 @@
Endpoints are named based on the type of object. Some examples:
-* `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.
+* `GET http://roc/targets`. Get a list of enterprises.
+* `GET http://roc/aether/v2.1.0/starbucks/application`. Get the list of applications in the Starbucks enterprise.
+* `GET http://roc/aether/v2.1.0/starbucks/site`. Get the list of sites in the Starbucks enterprise.
+* `GET http://roc/aether/v2.1.0/starbucks/site/starbucks-seattle`. Get details of the 'seattle' site in the Starbucks enterprise.
+* `POST http://roc/aether/v2.1.0/starbucks/site/newsite`. Create a new (or update existing) site in the Starbucks enterprise.
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).
+Enterprises
+------------
+The API is segmented by `enterprise`, as the Aether ROC is a multi Tenant system. Each of the URLs shown
+above has an example enterprise built in to the path. If a valid enterprise is not given, the results will
+be empty.
+
Identifying and Referencing Objects
-----------------------------------
-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
+Every object contains an `id` - 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`.
+turn belongs to an `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.
+In addition to an `id`, most identifiable objects also include a `display-name` and a `description`.
+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. References
are constructed using the `id` field of the referenced object. It is an error to attempt to create
@@ -65,34 +71,22 @@
Several fields are common to all models in Aether:
-* `<modelname>-id`. The identifier for objects of this model.
+* `<objectname>-id`. The identifier for objects.
* `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.
-As these fields are common to all models, they will be omitted from the per-model descriptions below.
+As these fields are common to all objects, they will be omitted from the per-object descriptions below.
Key Aether Objects
------------------
-The following is a list of Aether models, generally organized in a top-down manner.
-
-Enterprise
-~~~~~~~~~~
-
-`Enterprise` forms the root of a customer-specific Enterprise hierarchy. The `Enterprise` model is
-referenced by many other objects, and allows those objects to be scoped to a particular Enterprise
-for ownership and role-based access control purposes. `Enterprise` contains the following fields:
-
-* `connectivity-service`. A list of connectivity services that realize connectivity for this
- enterprise. A connectivity service is a reference to the SD-Core, and reflects either a 4G or a
- 5G core.
+The following is a list of Aether models elements (objects), generally organized in a top-down manner.
Site
~~~~
-`Enterprises` are further divided into `Sites`. A site is a point of presence for an `Enterprise` and
-may be either physical or logical (i.e. a single geographic location could in theory contain several
-logical sites). Site contains the following fields:
+A site is a point of presence for an `Enterprise` and may be either physical or logical (i.e. a single
+geographic location could in theory contain several logical sites). Site contains the following fields:
* `imsi-definition`. A description of how IMSIs are constructed for this site. Contains the following
sub-fields:
@@ -104,13 +98,6 @@
`CCCNNNEEESSSSSS` will construct IMSIs using a 3-digit MCC, 3-digit MNC, 3-digit ENT, and a
6-digit subscriber.
-* `small-cell` A list of 5G gNodeB or Access Point or Radios. Each small cell has the following:
-
- * `small-cell-id`. Identifier for the small cell. Serves the same purpose as other `id` fields.
- * `address`. Hostname of the small cell.
- * `tac`. Type Allocation Code.
- * `enable`. If set to `true`, the small cell is enabled. Otherwise, it is disabled.
-
* `monitoring` Configuration of how the monitoring framework of the site can be connected:
* `edge-cluster-prometheus-url` the URL of the site's Edge cluster Prometheus service
@@ -122,6 +109,27 @@
be used for the `display-name` as a convention.
* `description` an optional description
+The site also contains sub objects like:
+
+* Devices
+* Device Group
+* IP Domain
+* Sim Card
+* Small Cell
+* Slice
+* UPF
+
+Device
+~~~~~~
+
+A device represents a UE (User Equipment) registered on the Aether system. The devices are then referenced
+by the `device-group` object.
+
+* imei - the International Mobile Equipment Identifier of the device
+* sim-card - a reference to the `sim-card` object
+* state - a set of attributes that report the state of the device - includes `ip-address`,
+ `connected` and `last-connected`
+
Device-Group
~~~~~~~~~~~~
@@ -139,6 +147,25 @@
* `traffic-class`. The traffic class to be used for devices in this group.
+SIM Card
+~~~~~~~~
+The Sim Card is used to represent a subscriber in the Aether system. When provisioned correctly there is
+a 1:1 relationship between SIM Card and Device, with the identifier of the SIM Card being defined in the
+Device
+
+* `iccid` - the Integrated Circuit Card Identifier - which should be unique to any SIM Card
+* `imsi` - the International Mobile Subscriber Identifier - the identifier of the Subscriber in Aether
+
+Small Cell
+~~~~~~~~~~
+
+`Small cell` is list of 5G gNodeB or Access Point or Radios. Each small cell has the following:
+
+ * `small-cell-id`. Identifier for the small cell. Serves the same purpose as other `id` fields.
+ * `address`. Hostname of the small cell.
+ * `tac`. Type Allocation Code.
+ * `enable`. If set to `true`, the small cell is enabled. Otherwise, it is disabled.
+
Slice
~~~~~
@@ -163,10 +190,12 @@
* `mbr.uplink-burst-size`, `mbr.downlink-burst-size`. Maximum burst sizes in bytes for
the maximum bit rates.
+
Application
~~~~~~~~~~~
-`Application` specifies an application and the endpoints for the application. Applications are
+`Application` specifies an application and the endpoints for the application. Applications are be shared
+across Sites for an enterprise, and so are defined at the top level of the model. Applications are
the termination point for traffic from the UPF. Contains the following fields:
* `address`. The DNS name or IP address of the endpoint.
@@ -187,18 +216,11 @@
Supporting Aether Objects
-------------------------
-Connectivity-Service
-~~~~~~~~~~~~~~~~~~~~
-
-`Connectivity-Service` specifies the URL of an SD-Core control plane.
-
-* `core-5g-endpoint`. Endpoint of a `config4g` or `config5g` core.
-* `acc-prometheus-url`. Prometheus endpoint where metrics may be queried regarding this connectivity service.
IP-Domain
~~~~~~~~~
-`IP-Domain` specifies IP and DNS settings and has the following fields:
+`IP-Domain` (beneath Site) specifies IP and DNS settings and has the following fields:
* `dnn`. Data network name for 5G, or APN for 4G.
* `dns-primary`, `dns-secondary`. IP addresses for DNS servers.
@@ -212,7 +234,8 @@
~~~~~~~~
`Template` contains connectivity settings that are pre-configured by Aether Operations.
-Templates are used to initialize `Slice` objects. `Template` has the following fields:
+Templates are used to initialize `Slice` objects, and are shared across Sites for an enterprise.
+`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 Slice's application filter matches. `ALLOW-PUBLIC` is
@@ -227,7 +250,7 @@
Traffic-Class
~~~~~~~~~~~~~
-Specifies the class of traffic. Contains the following:
+Specifies the class of traffic, and is shared across Sites in an enterprise. Contains the following:
* `arp`. Allocation and Retention Priority.
* `qci`. QoS class identifier.
@@ -237,8 +260,8 @@
UPF
~~~
-Specifies the UPF that should forward packets. A UPF can only be used by one Slice at a time.
-Has the following fields:
+Specifies the UPF that should forward packets. The UPF is part of the Site object, and also can only be
+used by one Slice at a time. It has the following fields:
* `address`. Hostname or IP address of UPF.
* `port`. Port number of UPF.
diff --git a/developer/roc.rst b/developer/roc.rst
index fc2b282..5c05d95 100644
--- a/developer/roc.rst
+++ b/developer/roc.rst
@@ -35,13 +35,13 @@
helm repo update
# install atomix
- export ATOMIX_CONTROLLER_VERSION=0.6.8
+ export ATOMIX_CONTROLLER_VERSION=0.6.9
helm -n kube-system install atomix-controller atomix/atomix-controller --version $ATOMIX_CONTROLLER_VERSION
- export ATOMIX_RAFT_VERSION=0.1.16
+ export ATOMIX_RAFT_VERSION=0.1.26
helm -n kube-system install atomix-raft-storage atomix/atomix-raft-storage --version $ATOMIX_RAFT_VERSION
# install the onos operator
- ONOS_OPERATOR_VERSION=0.5.1
+ ONOS_OPERATOR_VERSION=0.5.3
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
@@ -75,10 +75,14 @@
- 0.6.8
- 0.1.16
- 0.5.1
+ * - 2.1.8-
+ - 0.6.9
+ - 0.1.26
+ - 0.5.3
Verify that these services were installed properly.
You should see pods for *atomix-controller*, *atomix-raft-storage-controller*,
-*onos-operator-config*, and *onos-operator-topo*.
+*onos-operator-app*, and *onos-operator-topo*.
Execute these commands::
helm -n kube-system list
@@ -91,15 +95,7 @@
You’ll want to override several of the defaults in the ROC helm charts::
cat > values-override.yaml <<EOF
- import:
- onos-gui:
- enabled: true
-
- onos-gui:
- ingress:
- enabled: false
-
- aether-roc-gui-v2:
+ aether-roc-gui-v2-1:
ingress:
enabled: false
EOF
@@ -125,17 +121,23 @@
The ROC usually comes up in a blank state -- there are no Enterprises, UEs, or other artifacts present in it.
The mega-patch is an example patch that populates the ROC with some sample enterprises, UEs, slices, etc.
+
Execute the following::
# launch a port-forward for the API
# this will continue to run in the background
+
kubectl -n micro-onos port-forward service/aether-roc-api --address 0.0.0.0 8181:8181 &
+ curl http://localhost:8181/targets
+ # It should show a list of the configure enterprises: [{"name":"defaultent"},{"name":"acme"},{"name":"starbucks"}
+
git clone https://github.com/onosproject/aether-roc-api.git
# execute the mega-patch (it will post via CURL to localhost:8181)
bash ~/path/to/aether-roc-api/examples/MEGA_Patch_20.curl
+.. note:: To configure Aether-In-a-Box - no port-forward is necessary - use the URL *http://<hostname>:31194/aether-roc-api/*
You may wish to customize the mega patch.
@@ -144,7 +146,7 @@
You could configure it to push to a live aether-in-a-box core by doing something like this::
- sed -i 's^http://aether-roc-umbrella-sdcore-test-dummy/v1/config/5g^http://webui.omec.svc.cluster.local:9089/config^g' MEGA_Patch_20.curl
+ sed -i 's^http://aether-roc-umbrella-sdcore-test-dummy/v1/config/5g^http://webui.omec.svc.cluster.local:9089/config^g' MEGA_Patch_21.curl
#apply the patch
./MEGA_Patch_20.curl
@@ -162,6 +164,57 @@
|ROCGUI|
+Adding new Enterprises
+----------------------
+
+Enterprises are stored in `onos-topo` outside of `onos-config` are are usually only created by system administrators
+during the onboarding of new customers (tenants) on Aether.
+
+There is currently no way of adding new Enterprises through the ROC GUI or the ROC API - it can be
+done in the 2 ways in the following sections.
+
+Enterprises are specified as Entities using CRDs, and the `onos-operator` ensures that these are created
+as `entitites` inside `onos-topo`.
+
+To check that the current list of enterprises (as CRDs), the following command may be used::
+
+ kubectl -n micro-onos get entities
+
+and to check that the `onos-operator` does indeed take effect, the ROC API endpoint `/targets` can be used to list the
+`enterprises`.
+
+Another option is to use the `onos-cli` pod to query `onos-topo` directly::
+
+ kubectl -n micro-onos exec deployment/onos-cli -- onos topo get entities -v
+
+Adding new Enterprises through Helm Chart
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To have an entity added at **start up of the cluster** it can be added through the Helm Chart in the `values.yaml`
+under `enterprises`. e.g.::
+
+ enterprises:
+ - id: starbucks
+ name: Starbucks Enterprise
+ lat: 52.5150
+ long: 13.3885
+
+This will load the `enterprise` as an Entity CRD through the `onos-operator`.
+
+Adding new Enterprises through `onos-topo`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+New `enterprises` can be added to a live running system through the `onos-topo` command line (bypassing
+the `onos-operator`). For example::
+
+ kubectl -n micro-onos exec deployment/onos-cli -- \
+ onos topo create entity new-enterprise \
+ -a onos.topo.Configurable='{"address”:”sdcore-adapter-v2-1:5150”,”version”:”2.1.x”,”type”:”aether”}' \
+ -a onos.topo.TLSOptions='{"insecure":true}' \
+ -a onos.topo.Asset='{"name”:”New Enterprise”}' \
+ -a onos.topo.MastershipState='{}' \
+ -k aether
+
Uninstalling the ``aether-roc-umbrella`` Helm chart
---------------------------------------------------
@@ -174,6 +227,9 @@
# fix stuck finalizers in operator CRDs
kubectl -n micro-onos patch entities connectivity-service-v2 --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]' && \
+ kubectl -n micro-onos patch entities starbucks --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]' && \
+ kubectl -n micro-onos patch entities acme-v2 --type json --patch='[ { "op": "remove", "path": "/metadata/finalizers" } ]' && \
+ kubectl -n micro-onos patch entities defult-ent --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" } ]' && \
@@ -186,6 +242,10 @@
Port forwarding is often necessary to allow access to ports inside of Kubernetes pods that use ClusterIP addressing.
Note that you typically need to leave a port-forward running (you can put it in the background).
Also, If you redeploy the ROC and/or if a pod crashes then you might have to restart a port-forward.
+
+.. note:: With Aether-In-a-Box no port-forward is necessary - the GUI can be accessed
+ at ``http://<hostname>:31194`` and the API at ``http://<hostname>:31194/aether-roc-api/``
+
The following port-forwards may be useful::
# aether-roc-api
@@ -194,7 +254,7 @@
# aether-roc-gui
- kubectl -n micro-onos port-forward service/aether-roc-gui-v2 --address 0.0.0.0 8183:80
+ kubectl -n micro-onos port-forward service/aether-roc-gui-v2-1 --address 0.0.0.0 8183:80
# grafana
@@ -217,7 +277,7 @@
Custom images may be used by editing the values-override.yaml file.
For example, to deploy a custom ``sdcore-adapter``::
- sdcore-adapter-v2:
+ sdcore-adapter-v2-1:
prometheusEnabled: false
image:
repository: my-private-repo/sdcore-adapter
@@ -246,14 +306,14 @@
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
+ - name: aether-2
+ image: onosproject/aether-2.0.x:2.0.3-aether-2.0.x
+ endpoint: localhost
+ port: 5152
+ - name: aether-2-1
+ image: onosproject/aether-2.1.x:2.1.3-aether-2.1.x
+ endpoint: localhost
+ port: 5153
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.
@@ -268,7 +328,7 @@
Then you can inspect a specific pod/container::
- kubectl -n micro-onos logs deployment/sdcore-adapter-v2
+ kubectl -n micro-onos logs deployment/sdcore-adapter-v2-1
.. _securing_roc:
@@ -287,7 +347,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-v2.openidc.issuer=https://keycloak-dev.onlab.us/auth/realms/master \
+ --set aether-roc-gui-v2-1.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
diff --git a/dict.txt b/dict.txt
index 39d0a63..48b0c22 100644
--- a/dict.txt
+++ b/dict.txt
@@ -146,6 +146,7 @@
hssdb
iPXE
iface
+imei
incrementing
ip
jitter
@@ -235,6 +236,7 @@
sd
sdcore
sdfabric
+seattle
simapp
smf
smgmt
