Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 1 | .. vim: syntax=rst |
| 2 | |
| 3 | Aether ROC Control API |
| 4 | ====================== |
| 5 | |
Sean Condon | 257687f | 2021-08-23 11:13:20 +0100 | [diff] [blame] | 6 | Access |
| 7 | ------ |
| 8 | The ROC API specification can be accessed from the running ROC cluster at the API URL. |
| 9 | |
| 10 | e.g. on a local system (if the GUI has been port-forwarded on port 8183) |
| 11 | *http://localhost:8183/aether-roc-api/* |
| 12 | |
| 13 | On 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 |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 18 | ``curl -H "Accept: application/yaml" http://localhost:8183/aether-roc-api/aether-4.0.0-openapi3.yaml`` |
Sean Condon | 257687f | 2021-08-23 11:13:20 +0100 | [diff] [blame] | 19 | This YAML format can be imported in to various different tools e.g. |postman_link| |
| 20 | |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 21 | Background |
| 22 | ---------- |
| 23 | |
| 24 | The Aether ROC control API is available via REST or via gNMI. It is expected that most external |
| 25 | consumers of the API will use REST. |
| 26 | |
| 27 | The 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 | |
| 34 | Endpoints are named based on the type of object. Some examples: |
| 35 | |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 36 | * `GET http://roc/aether/v4.0.0/connectivity-service-v3/enterprise/`. Get a list of enterprises. |
| 37 | * `GET http://roc/aether/v4.0.0/connectivity-service-v3/enterprise/Starbucks`. Get the Starbucks enterprise. |
| 38 | * `POST http://roc/aether/v4.0.0/connectivity-service-v3/enterprise`. Create a new enterprise. |
| 39 | * `PATCH http://roc/aether/v4.0.0/connectivity-service-v3/site/Starbucks-NewYork`. Update the Starbucks New York site. |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 40 | |
| 41 | This document is a high-level description of the objects that can be interacted with. For a |
Sean Condon | 257687f | 2021-08-23 11:13:20 +0100 | [diff] [blame] | 42 | low-level description, see the specification (:ref:`developer/roc-api:Access` section above). |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 43 | |
| 44 | Identifying and Referencing Objects |
| 45 | ----------------------------------- |
| 46 | |
| 47 | Every object contains an `id` that is used to identify the object. The `id` is only unique within |
| 48 | the scope of a particular type of object. For example, a site may be named `foo` and a device-group |
| 49 | may also be named `foo`, and the two names do not conflict because they are different object types. |
| 50 | |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 51 | In addition to the `id`, most identifiable objects also include a `display-name`. The `display-name` |
| 52 | may be changed at any time by the user without affecting behavior. In contrast, the `id` is immutable, |
| 53 | and the only way to change an `id` is to delete the object and make a new one. |
| 54 | |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 55 | Some objects contain references to other objects. For example, many objects contain references to |
| 56 | the `Enterprise` object, which allows them to be associated with a particular enterprise. References |
| 57 | are constructed using the `id` field of the referenced object. It is an error to attempt to create |
| 58 | a reference to an object that does not exist. Deleting an object while there are open references |
| 59 | to it from other objects is also an error. |
| 60 | |
| 61 | Common Model Fields |
| 62 | ------------------- |
| 63 | |
| 64 | Several fields are common to all models in Aether: |
| 65 | |
| 66 | * `id`. The identifier for objects of this model. |
| 67 | * `description`. A human-readable description, used to store additional context about the object. |
| 68 | * `display-name`. A human-readable name that is shown in the GUI. |
| 69 | |
| 70 | As these fields are common to all models, they will be omitted from the per-model descriptions below. |
| 71 | |
| 72 | Key Aether Objects |
| 73 | ------------------ |
| 74 | |
| 75 | The following is a list of Aether models, generally organized in a top-down manner. |
| 76 | |
| 77 | Enterprise |
| 78 | ~~~~~~~~~~ |
| 79 | |
| 80 | `Enterprise` forms the root of a customer-specific Enterprise hierarchy. The `Enterprise` model is |
| 81 | referenced by many other objects, and allows those objects to be scoped to a particular Enterprise |
| 82 | for ownership and role-based access control purposes. `Enterprise` contains the following fields: |
| 83 | |
| 84 | * `connectivity-service`. A list of connectivity services that realize connectivity for this |
Zack Williams | 1ae109e | 2021-07-27 11:17:04 -0700 | [diff] [blame] | 85 | enterprise. A connectivity service is a reference to the SD-Core, and reflects either a 4G or a |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 86 | 5G core. |
| 87 | |
| 88 | Site |
| 89 | ~~~~ |
| 90 | |
| 91 | `Enterprises` are further divided into `Sites`. A site is a point of presence for an `Enterprise` and |
| 92 | may be either physical or logical (i.e. a single geographic location could in theory contain several |
| 93 | logical sites). Site contains the following fields: |
| 94 | |
| 95 | * `enterprise`. A link to the `Enterprise` that owns this site. |
| 96 | * `imsi-definition`. A description of how IMSIs are constructed for this site. Contains the following |
| 97 | sub-fields: |
| 98 | |
| 99 | * `mcc`. Mobile country code. |
| 100 | * `mnc`. Mobile network code. |
| 101 | * `enterprise`. A numeric enterprise id. |
| 102 | * `format`. A mask that allows the above three fields to be embedded into an IMSI. For example |
| 103 | `CCCNNNEEESSSSSS` will construct IMSIs using a 3-digit MCC, 3-digit MNC, 3-digit ENT, and a |
| 104 | 6-digit subscriber. |
| 105 | |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 106 | * `small-cell` A list of 5G gNodeB or Access Point or Radios. Each small cell has the following: |
| 107 | |
| 108 | * `small-cell-id`. Identifier for the small cell. Serves the same purpose as other `id` fields. |
| 109 | * `address`. Hostname of the small cell. |
| 110 | * `tac`. Type Allocation Code. |
| 111 | * `enable`. If set to `true`, the small cell is enabled. Otherwise, it is disabled. |
| 112 | |
| 113 | * `monitoring` Configuration of how the monitoring framework of the site can be connected: |
| 114 | |
| 115 | * `edge-cluster-prometheus-url` the URL of the site's Edge cluster Prometheus service |
| 116 | * `edge-monitoring-prometheus-url` the URL of the site's Edge monitoring Prometheus service |
| 117 | * `edge-device` a list of monitoring devices that verify end-to-end connectivity |
| 118 | |
| 119 | * `edge-device-id` the identifier of the edge monitoring device. Serves the same purpose as other `id` fields. |
| 120 | * `display-name` the user-friendly name for the edge device. It is recommended that the short hostname |
| 121 | be used for the `display-name` as a convention. |
| 122 | * `description` an optional description |
| 123 | |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 124 | Device-Group |
| 125 | ~~~~~~~~~~~~ |
| 126 | |
| 127 | `Device-Group` allows multiple devices to be logically grouped together. `Device-Group` contains |
| 128 | the following fields: |
| 129 | |
| 130 | * `imsis`. A list of IMSI ranges. Each range has the following |
| 131 | fields: |
| 132 | |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 133 | * `imsi-id`. Identifier of the IMSI. Serves the same purpose as other `id` fields. |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 134 | * `imsi-range-from`. First subscriber in the range. |
| 135 | * `imsi-range-to`. Last subscriber in the range. Can be omitted if the range only contains one |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 136 | IMSI. It is recommended to not use this feature, and to represent all IMSIs as singletons. This |
| 137 | field will be deprecated in the future. |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 138 | * `ip-domain`. Reference to an `IP-Domain` object that describes the IP and DNS settings for UEs |
| 139 | within this group. |
| 140 | * `site`. Reference to the site where this `Device-Group` may be used. Indirectly identifies the |
| 141 | `Enterprise` as `Site` contains a reference to `Enterprise`. |
| 142 | |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 143 | * `device`. Per-device related QoS settings: |
| 144 | |
| 145 | * `mbr`. The maximum bitrate in bits per second that the application will be limited to: |
| 146 | |
| 147 | * `uplink` the `mbr` from device to slice |
| 148 | * `downlink` the `mbr` from slice to device |
| 149 | |
| 150 | * `traffic-class`. The traffic class to be used for devices in this group. |
| 151 | |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 152 | Virtual Cellular Service |
| 153 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
| 154 | |
| 155 | `Virtual Cellular Service (VCS)` connects a `Device-Group` to an `Application`. `VCS` has the |
| 156 | following fields: |
| 157 | |
| 158 | * `device-group`. A list of `Device-Group` objects that can participate in this `VCS`. Each |
| 159 | entry in the list contains both the reference to the `Device-Group` as well as an `enable` |
| 160 | field which may be used to temporarily remove access to the group. |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 161 | * `default-behavior`. May be set to either `ALLOW-ALL`, `DENY-ALL`, or `ALLOW-PUBLIC`. This is |
| 162 | the rule to use if no other rule in the filter matches. `ALLOW-PUBLIC` is a special alias |
| 163 | that denies all private networks and then allows everything else. |
| 164 | * `filter`. A list of `Application` objects that are either allowed or denied for this |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 165 | `VCS`. Each entry in the list contains both a reference to the `Application` as well as an |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 166 | `allow` field which can be set to `true` to allow the application or `false` to deny it. It |
| 167 | also has a `priority` field which can be used to order the applications when considering the |
| 168 | enforcing of their `allow` or `deny` conditions. |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 169 | * `upf`. Reference to the User Plane Function (`UPF`) that should be used to process packets |
| 170 | for this `VCS`. It's permitted for multiple `VCS` to share a single `UPF`. |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 171 | * `enterprise`. Reference to the `Enterprise` that owns this `VCS`. |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 172 | * `site`. Reference to the `Site` where this `VCS` is deployed. Aether maintains the restriction |
| 173 | that the `Site` of the `UPF` and `Device-Group` must match the `Site` of the `VCS`. |
| 174 | * `SST`, `SD`. Slice identifiers. These are assigned by Aether Operations. |
| 175 | * `slice.mbr.uplink`, `slice.mbr.downlink`. Slice-total Uplink and downlink maximum bit rates in bps. |
| 176 | * `slice.mbr.uplink-burst-size`, `slice.mbr.downlink-burst-size`. Maximum burst sizes in bytes for |
| 177 | the maximum bit rates. |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 178 | |
| 179 | Application |
| 180 | ~~~~~~~~~~~ |
| 181 | |
| 182 | `Application` specifies an application and the endpoints for the application. Applications are |
| 183 | the termination point for traffic from the UPF. Contains the following fields: |
| 184 | |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 185 | * `address`. The DNS name or IP address of the endpoint. |
| 186 | * `endpoint`. A list of endpoints. Each has the following fields: |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 187 | |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 188 | * `name`. Name of the endpoint. Used as a key. |
| 189 | * `port-start`. Starting port number. |
| 190 | * `port-end`. Ending port number. |
| 191 | * `protocol`. `TCP|UDP`, specifies the protocol for the endpoint. |
| 192 | * `mbr`. The maximum bitrate in bits per second that UEs sending traffic to the application endpoint |
| 193 | will be limited to: |
| 194 | |
| 195 | * `uplink` the `mbr` from device to application |
| 196 | * `downlink` the `mbr` from application to device |
| 197 | |
| 198 | * `traffic-class`. Traffic class to be used when UEs send traffic to this Application endpoint. |
| 199 | |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 200 | * `enterprise`. Link to an `Enterprise` object that owns this application. May be left empty |
| 201 | to indicate a global application that may be used by multiple enterprises. |
| 202 | |
| 203 | Supporting Aether Objects |
| 204 | ------------------------- |
| 205 | |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 206 | Connectivity-Service |
| 207 | ~~~~~~~~~~~~~~~~~~~~ |
| 208 | |
Zack Williams | 1ae109e | 2021-07-27 11:17:04 -0700 | [diff] [blame] | 209 | `Connectivity-Service` specifies the URL of an SD-Core control plane. |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 210 | |
| 211 | * `core-5g-endpoint`. Endpoint of a `config4g` or `config5g` core. |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 212 | * `acc-prometheus-url`. Prometheus endpoint where metrics may be queried regarding this connectivity service. |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 213 | |
| 214 | IP-Domain |
| 215 | ~~~~~~~~~ |
| 216 | |
| 217 | `IP-Domain` specifies IP and DNS settings and has the following fields: |
| 218 | |
| 219 | * `dnn`. Data network name for 5G, or APN for 4G. |
| 220 | * `dns-primary`, `dns-secondary`. IP addresses for DNS servers. |
| 221 | * `subnet`. Subnet to allocate to UEs. |
| 222 | * `admin-status`. Tells whether these ip-domain settings should be used, or whether they |
| 223 | should be drained from UEs. |
| 224 | * `mtu`. Ethernet maximum transmission unit. |
| 225 | * `enterprise`. `Enterprise that owns this `IP-Domain`. |
| 226 | |
| 227 | Template |
| 228 | ~~~~~~~~ |
| 229 | |
| 230 | `Template` contains connectivity settings that are pre-configured by Aether Operations. |
| 231 | Templates are used to initialize `VCS` objects. `Template` has the following fields: |
| 232 | |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 233 | * `default-behavior`. May be set to either `ALLOW-ALL`, `DENY-ALL`, or `ALLOW-PUBLIC`. This is |
| 234 | the rule to use if no other rule in the VCS's application filter matches. `ALLOW-PUBLIC` is |
| 235 | a special alias that denies all private networks and then allows everything else. |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 236 | * `sst`, `sd`. Slice identifiers. |
| 237 | * `uplink`, `downlink`. Guaranteed uplink and downlink bandwidth. |
| 238 | * `traffic-class`. Link to a `Traffic-Class` object that describes the type of traffic. |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 239 | * `slice.mbr.uplink`, `slice.mbr.downlink`. Slice-total Uplink and downlink maximum bit rates in bps. |
| 240 | * `slice.mbr.uplink-burst-size`, `slice.mbr.downlink-burst-size`. Maximum burst sizes in bytes for |
| 241 | the maximum bit rates. |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 242 | |
| 243 | Traffic-Class |
| 244 | ~~~~~~~~~~~~~ |
| 245 | |
| 246 | Specifies the class of traffic. Contains the following: |
| 247 | |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 248 | * `arp`. Allocation and Retention Priority. |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 249 | * `qci`. QoS class identifier. |
| 250 | * `pelr`. Packet error loss rate. |
| 251 | * `pdb`. Packet delay budget. |
| 252 | |
| 253 | UPF |
| 254 | ~~~ |
| 255 | |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 256 | Specifies the UPF that should forward packets. A UPF can only be used by one VCS at a time. |
| 257 | Has the following fields: |
Scott Baker | 00df5a8 | 2021-08-13 16:01:57 -0700 | [diff] [blame] | 258 | |
| 259 | * `address`. Hostname or IP address of UPF. |
| 260 | * `port`. Port number of UPF. |
| 261 | * `enterprise`. Enterprise that owns this UPF. |
Zack Williams | 90578fa | 2021-11-04 11:57:23 -0700 | [diff] [blame] | 262 | * `site`. The Site that this UPF is located at. |
| 263 | * `config-endpoint` URL for configuring the UPF |
Sean Condon | 257687f | 2021-08-23 11:13:20 +0100 | [diff] [blame] | 264 | |
| 265 | .. |postman_link| raw:: html |
| 266 | |
| 267 | <a href="http://postman.com" target="_blank">Postman</a> |