blob: 98088e23b451fa350eae52c010a4214925abf2fe [file] [log] [blame]
Scott Baker00df5a82021-08-13 16:01:57 -07001.. vim: syntax=rst
2
3Aether ROC Control API
4======================
5
Sean Condon257687f2021-08-23 11:13:20 +01006Access
7------
8The ROC API specification can be accessed from the running ROC cluster at the API URL.
9
10e.g. on a local system (if the GUI has been port-forwarded on port 8183)
11*http://localhost:8183/aether-roc-api/*
12
13On the Production system it would be *https://roc.aetherproject.org/aether-roc-api/*
14
15.. note:: Opening this in a browser will display a HTML view of the API (powered by *ReDoc*).
16
17 To access the raw YAML format use
Scott Baker6bd3d192022-03-03 14:50:38 -080018 ``curl -H "Accept: application/yaml" http://localhost:8183/aether-roc-api/aether-2.0.0-openapi3.yaml``
Sean Condon257687f2021-08-23 11:13:20 +010019 This YAML format can be imported in to various different tools e.g. |postman_link|
20
Scott Baker00df5a82021-08-13 16:01:57 -070021Background
22----------
23
24The Aether ROC control API is available via REST or via gNMI. It is expected that most external
25consumers of the API will use REST.
26
27The REST API supports the typical GET, POST, PATCH, DELETE operations:
28
29* GET. Retrieve an object.
30* POST. Create an object.
31* PUT, PATCH. Modify an existing object.
32* DELETE. Delete an object.
33
34Endpoints are named based on the type of object. Some examples:
35
Scott Baker6bd3d192022-03-03 14:50:38 -080036* `GET http://roc/aether/v2.0.0/connectivity-service-v2/enterprises`. Get a list of enterprises.
37* `GET http://roc/aether/v2.0.0/connectivity-service-v2/enterprises/starbucks`. Get the Starbucks enterprise.
38* `POST http://roc/aether/v2.0.0/connectivity-service-v2/enterprises`. Create a new enterprise.
39* `POST http://roc/aether/v2.0.0/connectivity-service-v2/enterprises/enterprise/starbucks/site/starbucks-newyork`. Update the Starbucks New York site.
Scott Baker00df5a82021-08-13 16:01:57 -070040
41This document is a high-level description of the objects that can be interacted with. For a
Sean Condon257687f2021-08-23 11:13:20 +010042low-level description, see the specification (:ref:`developer/roc-api:Access` section above).
Scott Baker00df5a82021-08-13 16:01:57 -070043
44Identifying and Referencing Objects
45-----------------------------------
46
47Every object contains an `id` that is used to identify the object. The `id` is only unique within
48the scope of a particular type of object. For example, a site may be named `foo` and a device-group
49may also be named `foo`, and the two names do not conflict because they are different object types.
Scott Baker6bd3d192022-03-03 14:50:38 -080050The `id` is model specific. For example, a site has a `site-id` and an slice has a
51`slice-id`. The models are generally nested, for example `slice` is a member of `site`, which in
52turn is a member of `enterprise`.
Scott Baker00df5a82021-08-13 16:01:57 -070053
Zack Williams90578fa2021-11-04 11:57:23 -070054In addition to the `id`, most identifiable objects also include a `display-name`. The `display-name`
55may be changed at any time by the user without affecting behavior. In contrast, the `id` is immutable,
56and the only way to change an `id` is to delete the object and make a new one.
57
Scott Baker6bd3d192022-03-03 14:50:38 -080058Some objects contain references to other objects. References
Scott Baker00df5a82021-08-13 16:01:57 -070059are constructed using the `id` field of the referenced object. It is an error to attempt to create
60a reference to an object that does not exist. Deleting an object while there are open references
61to it from other objects is also an error.
62
63Common Model Fields
64-------------------
65
66Several fields are common to all models in Aether:
67
Scott Baker6bd3d192022-03-03 14:50:38 -080068* `<modelname>-id`. The identifier for objects of this model.
Scott Baker00df5a82021-08-13 16:01:57 -070069* `description`. A human-readable description, used to store additional context about the object.
70* `display-name`. A human-readable name that is shown in the GUI.
71
72As these fields are common to all models, they will be omitted from the per-model descriptions below.
73
74Key Aether Objects
75------------------
76
77The following is a list of Aether models, generally organized in a top-down manner.
78
79Enterprise
80~~~~~~~~~~
81
82`Enterprise` forms the root of a customer-specific Enterprise hierarchy. The `Enterprise` model is
83referenced by many other objects, and allows those objects to be scoped to a particular Enterprise
84for ownership and role-based access control purposes. `Enterprise` contains the following fields:
85
86* `connectivity-service`. A list of connectivity services that realize connectivity for this
Zack Williams1ae109e2021-07-27 11:17:04 -070087 enterprise. A connectivity service is a reference to the SD-Core, and reflects either a 4G or a
Scott Baker00df5a82021-08-13 16:01:57 -070088 5G core.
89
90Site
91~~~~
92
93`Enterprises` are further divided into `Sites`. A site is a point of presence for an `Enterprise` and
94may be either physical or logical (i.e. a single geographic location could in theory contain several
95logical sites). Site contains the following fields:
96
Scott Baker00df5a82021-08-13 16:01:57 -070097* `imsi-definition`. A description of how IMSIs are constructed for this site. Contains the following
98 sub-fields:
99
100 * `mcc`. Mobile country code.
101 * `mnc`. Mobile network code.
102 * `enterprise`. A numeric enterprise id.
103 * `format`. A mask that allows the above three fields to be embedded into an IMSI. For example
104 `CCCNNNEEESSSSSS` will construct IMSIs using a 3-digit MCC, 3-digit MNC, 3-digit ENT, and a
105 6-digit subscriber.
106
Zack Williams90578fa2021-11-04 11:57:23 -0700107* `small-cell` A list of 5G gNodeB or Access Point or Radios. Each small cell has the following:
108
109 * `small-cell-id`. Identifier for the small cell. Serves the same purpose as other `id` fields.
110 * `address`. Hostname of the small cell.
111 * `tac`. Type Allocation Code.
112 * `enable`. If set to `true`, the small cell is enabled. Otherwise, it is disabled.
113
114* `monitoring` Configuration of how the monitoring framework of the site can be connected:
115
116 * `edge-cluster-prometheus-url` the URL of the site's Edge cluster Prometheus service
117 * `edge-monitoring-prometheus-url` the URL of the site's Edge monitoring Prometheus service
118 * `edge-device` a list of monitoring devices that verify end-to-end connectivity
119
120 * `edge-device-id` the identifier of the edge monitoring device. Serves the same purpose as other `id` fields.
121 * `display-name` the user-friendly name for the edge device. It is recommended that the short hostname
122 be used for the `display-name` as a convention.
123 * `description` an optional description
124
Scott Baker00df5a82021-08-13 16:01:57 -0700125Device-Group
126~~~~~~~~~~~~
127
128`Device-Group` allows multiple devices to be logically grouped together. `Device-Group` contains
129the following fields:
130
Scott Baker6bd3d192022-03-03 14:50:38 -0800131* `devices`. A list of Devices. Each device has an `enable` field which can be used to
132 enable or disable the device.
Scott Baker00df5a82021-08-13 16:01:57 -0700133* `ip-domain`. Reference to an `IP-Domain` object that describes the IP and DNS settings for UEs
134 within this group.
Scott Baker6bd3d192022-03-03 14:50:38 -0800135* `mbr`. Per-device maximum bitrate in bits per second that the application will be limited to:
Scott Baker00df5a82021-08-13 16:01:57 -0700136
Scott Baker6bd3d192022-03-03 14:50:38 -0800137 * `uplink` the `mbr` from device to slice
138 * `downlink` the `mbr` from slice to device
Zack Williams90578fa2021-11-04 11:57:23 -0700139
Scott Baker6bd3d192022-03-03 14:50:38 -0800140* `traffic-class`. The traffic class to be used for devices in this group.
Zack Williams90578fa2021-11-04 11:57:23 -0700141
Scott Baker6bd3d192022-03-03 14:50:38 -0800142Slice
143~~~~~
Zack Williams90578fa2021-11-04 11:57:23 -0700144
Scott Baker6bd3d192022-03-03 14:50:38 -0800145`Slice` connects a `Device-Group` to an `Application`. `Slice` has the
Scott Baker00df5a82021-08-13 16:01:57 -0700146following fields:
147
Scott Baker6bd3d192022-03-03 14:50:38 -0800148* `device-group`. A list of `Device-Group` objects that can participate in this `Slice`. Each
Scott Baker00df5a82021-08-13 16:01:57 -0700149 entry in the list contains both the reference to the `Device-Group` as well as an `enable`
150 field which may be used to temporarily remove access to the group.
Zack Williams90578fa2021-11-04 11:57:23 -0700151* `default-behavior`. May be set to either `ALLOW-ALL`, `DENY-ALL`, or `ALLOW-PUBLIC`. This is
152 the rule to use if no other rule in the filter matches. `ALLOW-PUBLIC` is a special alias
153 that denies all private networks and then allows everything else.
154* `filter`. A list of `Application` objects that are either allowed or denied for this
Scott Baker6bd3d192022-03-03 14:50:38 -0800155 `Slice`. Each entry in the list contains both a reference to the `Application` as well as an
Zack Williams90578fa2021-11-04 11:57:23 -0700156 `allow` field which can be set to `true` to allow the application or `false` to deny it. It
157 also has a `priority` field which can be used to order the applications when considering the
158 enforcing of their `allow` or `deny` conditions.
Scott Baker00df5a82021-08-13 16:01:57 -0700159* `upf`. Reference to the User Plane Function (`UPF`) that should be used to process packets
Scott Baker6bd3d192022-03-03 14:50:38 -0800160 for this `Slice`. It's permitted for multiple `Slice` to share a single `UPF`.
Zack Williams90578fa2021-11-04 11:57:23 -0700161* `SST`, `SD`. Slice identifiers. These are assigned by Aether Operations.
Scott Baker6bd3d192022-03-03 14:50:38 -0800162* `mbr.uplink`, `mbr.downlink`. Slice-total Uplink and downlink maximum bit rates in bps.
163* `mbr.uplink-burst-size`, `mbr.downlink-burst-size`. Maximum burst sizes in bytes for
164 the maximum bit rates.
Scott Baker00df5a82021-08-13 16:01:57 -0700165
166Application
167~~~~~~~~~~~
168
169`Application` specifies an application and the endpoints for the application. Applications are
170the termination point for traffic from the UPF. Contains the following fields:
171
Zack Williams90578fa2021-11-04 11:57:23 -0700172* `address`. The DNS name or IP address of the endpoint.
173* `endpoint`. A list of endpoints. Each has the following fields:
Scott Baker00df5a82021-08-13 16:01:57 -0700174
Zack Williams90578fa2021-11-04 11:57:23 -0700175 * `name`. Name of the endpoint. Used as a key.
176 * `port-start`. Starting port number.
177 * `port-end`. Ending port number.
178 * `protocol`. `TCP|UDP`, specifies the protocol for the endpoint.
179 * `mbr`. The maximum bitrate in bits per second that UEs sending traffic to the application endpoint
180 will be limited to:
181
182 * `uplink` the `mbr` from device to application
183 * `downlink` the `mbr` from application to device
184
185 * `traffic-class`. Traffic class to be used when UEs send traffic to this Application endpoint.
186
Scott Baker00df5a82021-08-13 16:01:57 -0700187Supporting Aether Objects
188-------------------------
189
Scott Baker00df5a82021-08-13 16:01:57 -0700190Connectivity-Service
191~~~~~~~~~~~~~~~~~~~~
192
Zack Williams1ae109e2021-07-27 11:17:04 -0700193`Connectivity-Service` specifies the URL of an SD-Core control plane.
Scott Baker00df5a82021-08-13 16:01:57 -0700194
195* `core-5g-endpoint`. Endpoint of a `config4g` or `config5g` core.
Zack Williams90578fa2021-11-04 11:57:23 -0700196* `acc-prometheus-url`. Prometheus endpoint where metrics may be queried regarding this connectivity service.
Scott Baker00df5a82021-08-13 16:01:57 -0700197
198IP-Domain
199~~~~~~~~~
200
201`IP-Domain` specifies IP and DNS settings and has the following fields:
202
203* `dnn`. Data network name for 5G, or APN for 4G.
204* `dns-primary`, `dns-secondary`. IP addresses for DNS servers.
205* `subnet`. Subnet to allocate to UEs.
206* `admin-status`. Tells whether these ip-domain settings should be used, or whether they
207 should be drained from UEs.
208* `mtu`. Ethernet maximum transmission unit.
209* `enterprise`. `Enterprise that owns this `IP-Domain`.
210
211Template
212~~~~~~~~
213
214`Template` contains connectivity settings that are pre-configured by Aether Operations.
Scott Baker6bd3d192022-03-03 14:50:38 -0800215Templates are used to initialize `Slice` objects. `Template` has the following fields:
Scott Baker00df5a82021-08-13 16:01:57 -0700216
Zack Williams90578fa2021-11-04 11:57:23 -0700217* `default-behavior`. May be set to either `ALLOW-ALL`, `DENY-ALL`, or `ALLOW-PUBLIC`. This is
Scott Baker6bd3d192022-03-03 14:50:38 -0800218 the rule to use if no other rule in the Slice's application filter matches. `ALLOW-PUBLIC` is
Zack Williams90578fa2021-11-04 11:57:23 -0700219 a special alias that denies all private networks and then allows everything else.
Scott Baker00df5a82021-08-13 16:01:57 -0700220* `sst`, `sd`. Slice identifiers.
221* `uplink`, `downlink`. Guaranteed uplink and downlink bandwidth.
222* `traffic-class`. Link to a `Traffic-Class` object that describes the type of traffic.
Zack Williams90578fa2021-11-04 11:57:23 -0700223* `slice.mbr.uplink`, `slice.mbr.downlink`. Slice-total Uplink and downlink maximum bit rates in bps.
224* `slice.mbr.uplink-burst-size`, `slice.mbr.downlink-burst-size`. Maximum burst sizes in bytes for
225 the maximum bit rates.
Scott Baker00df5a82021-08-13 16:01:57 -0700226
227Traffic-Class
228~~~~~~~~~~~~~
229
230Specifies the class of traffic. Contains the following:
231
Zack Williams90578fa2021-11-04 11:57:23 -0700232* `arp`. Allocation and Retention Priority.
Scott Baker00df5a82021-08-13 16:01:57 -0700233* `qci`. QoS class identifier.
234* `pelr`. Packet error loss rate.
235* `pdb`. Packet delay budget.
236
237UPF
238~~~
239
Scott Baker6bd3d192022-03-03 14:50:38 -0800240Specifies the UPF that should forward packets. A UPF can only be used by one Slice at a time.
Zack Williams90578fa2021-11-04 11:57:23 -0700241Has the following fields:
Scott Baker00df5a82021-08-13 16:01:57 -0700242
243* `address`. Hostname or IP address of UPF.
244* `port`. Port number of UPF.
245* `enterprise`. Enterprise that owns this UPF.
Zack Williams90578fa2021-11-04 11:57:23 -0700246* `site`. The Site that this UPF is located at.
247* `config-endpoint` URL for configuring the UPF
Sean Condon257687f2021-08-23 11:13:20 +0100248
249.. |postman_link| raw:: html
250
251 <a href="http://postman.com" target="_blank">Postman</a>