AETHER-2011 (part1)
Add basic 1.5 release documentation framework
Update edge deployment docs
- Describe different topologies and add deployment diagrams
- Split out Pronto BOM and diagrams
- Make BESS diagram a SVG
Updates to Sphinx and modules, fixed linkcheck to have a timeout/retry
for faulty webservers.
Fix spelling and formatting issue across entire site, remove "Smart
quotes" that cause the spellchecker to throw errors. Add many more
dictionary entries. Make spelling fail the build. Fix all spelling and
grammar errors that triggered failures.
Add autosectionlabel, and manage duplicate section names where they
existed.
Updated readme on image/diagram embedding
Added docs on PoE power cycle with Aruba switches (Pronto)
Change-Id: I7f9f7afae13788f9fe29bfe2683a295ba7b8914e
diff --git a/amp/roc.rst b/amp/roc.rst
index 8c27633..6228922 100755
--- a/amp/roc.rst
+++ b/amp/roc.rst
@@ -42,14 +42,14 @@
Other tools, such as Istio, could be leveraged to provide service meshes.
- The ROC does not configure *Edge Services*.
- While the ROC’s modeling support is general and could be leveraged to support an edge service, and an
+ While the ROC's modeling support is general and could be leveraged to support an edge service, and an
adapter could be written to configure an edge service, promoting an edge service to ROC management would
be the exception rather than the rule. Edge services have their own GUIs and APIs, perhaps belonging to
a 3rd-party service provider.
-Although we call out the tasks that ROC doesn’t do itself, it’s often still necessary for the ROC to be aware
+Although we call out the tasks that ROC doesn't do itself, it's often still necessary for the ROC to be aware
of the actions these other components have taken.
-For example, while the ROC doesn’t implement a service dependency graph, it is the case that the ROC is aware
+For example, while the ROC doesn't implement a service dependency graph, it is the case that the ROC is aware
of how services are related. This is necessary because some of the actions it takes affect multiple services
(e.g., a ROC-supported operation on a subscriber profile might result in the ROC making calls to SD-Core,
SD-RAN, and SD-Fabric).
@@ -65,7 +65,7 @@
Aether.
- This ROC API must support new end-to-end abstractions that cross multiple subsystems of Aether.
- For example, “give subscriber X running application Y QoS guarantee Z'' is an abstraction that potentially
+ For example, "give subscriber X running application Y QoS guarantee Z" is an abstraction that potentially
spans SD-RAN, SD-Fabric.
The ROC defines and implements such end-to-end abstractions.
@@ -74,7 +74,7 @@
- The ROC must offer an *Enterprise GUI* to Enterprise Personnel, so they may configure the connectivity aspects
of their particular edge site.
- It’s possible this GUI shares implementation with the Operations GUI, but the presentation, content, and
+ It's possible this GUI shares implementation with the Operations GUI, but the presentation, content, and
workflow may differ.
- The ROC must support *versioning* of configuration, so changes can be rolled back as necessary, and an audit
@@ -93,7 +93,7 @@
An important aspect of the ROC is that it maintains a data model that represents all the abstractions, such as
subscribers and profiles, it is responsible for.
-The ROC’s data model is based on YANG specifications.
+The ROC's data model is based on YANG specifications.
YANG is a rich language for data modeling, with support for strong validation of the data stored in the models.
YANG allows relations between objects to be specified, adding a relational aspect that our previous approaches
(for example, protobuf) did not directly support.
@@ -130,10 +130,10 @@
- Multi-step workflows (aka Wizards) to break a complex task into smaller guided steps.
The *Portal* is an angular-based typescript GUI.
-The GUI uses REST API to communicate with the aether-roc-api layer, which in turn communicates with aether-config
+The GUI uses REST API to communicate with the ``aether-roc-api`` layer, which in turn communicates with aether-config
via gNMI.
The GUI implementation is consistent with modern GUI design, implemented as a single-page application and includes
-a “commit list” that allows several changes to be atomically submitted together.
+a "commit list" that allows several changes to be atomically submitted together.
Views within the GUI are handcrafted, and as new models are added to Aether, the GUI must be adapted to incorporate
the new models.
@@ -145,13 +145,13 @@
language when Grafana and Prometheus are already able to do that and we can leverage them.
GUI pages can be constructed that embed the Grafana renderer.
-aether-roc-api
-""""""""""""""
+``aether-roc-api``
+""""""""""""""""""
-Aether-roc-api a REST API layer that sits between the portals and aether-config.
-The southbound layer of aether-roc-api is gNMI.
-This is how aether-roc-api talks to aether-config.
-Aether-roc-api at this time is entirely auto-generated; developers need not spend time manually creating REST APIs
+``aether-roc-api`` a REST API layer that sits between the portals and aether-config.
+The southbound layer of ``aether-roc-api`` is gNMI.
+This is how ``aether-roc-api`` talks to aether-config.
+``aether-roc-api`` at this time is entirely auto-generated; developers need not spend time manually creating REST APIs
for their models.
The API layer serves multiple purposes:
@@ -163,16 +163,16 @@
- The API layer is yet another place for semantic translation to take place.
Although the API layer is currently auto-generated, it is possible that additional methods could be added.
- gNMI supports only “GET” and “SET”, whereas the aether-roc-api natively supports “GET”, “PUT”, “POST”, “PATCH”,
- and “DELETE”.
+ gNMI supports only "GET" and "SET", whereas the ``aether-roc-api`` natively supports "GET", "PUT", "POST", "PATCH",
+ and "DELETE".
aether-config
"""""""""""""
-*Aether-config* (a Aether-specific deployment of the “\ *onos-config*\ ” microservice) is the core of the ROC’s
+*Aether-config* (a Aether-specific deployment of the "\ *onos-config*\ " microservice) is the core of the ROC's
configuration system.
Aether-config is a component that other teams may use in other contexts.
-It’s possible that an Aether deployment might have multiple instances of aether-config used for independent purposes.
+It's possible that an Aether deployment might have multiple instances of aether-config used for independent purposes.
The job of aether-config is to store and version configuration data.
Configuration is pushed to aether-config through the northbound gNMI interface, is stored in an Atomix database
(not shown in the figure), and is pushed to services and devices using a southbound gNMI interface.
@@ -181,8 +181,8 @@
""""""""
Not every device or service beneath the ROC supports gNMI, and in the case where it is not supported, an adapter is
-written to translate between gNMI and the device’s or service’s native API.
-For example, a gNMI → REST adapter exists to translate between the ROC’s modeling and the Aether Connectivity
+written to translate between gNMI and the device's or service's native API.
+For example, a gNMI → REST adapter exists to translate between the ROC's modeling and the Aether Connectivity
Control (SD-Core) components. The adapter is not necessarily only a syntactic translation, but may also be a
semantic translation.
[1]_ This supports a logical decoupling of the models stored in the ROC and the interface used by the southbound
@@ -202,7 +202,7 @@
For example, the workflow engine may examine the high-level Enterprise modeling and make changes to the Operations
modeling to achieve the Enterprise behavior.
-Previously this component was referred to as “onos-ztp”.
+Previously this component was referred to as "onos-ztp".
It is expected that a workflow engine would both read and write the aether-config data model, as well as respond to
external events.
@@ -218,7 +218,7 @@
The analytics engine is also where analytics would be related to config models in aether-config, in order for
Enterprise or Operations personnel to take action in response to data and insights received through analytics.
-Action doesn’t necessarily have to involve humans.
+Action doesn't necessarily have to involve humans.
It is expected that the combination of Analytics Engine and Workflow Engine could automate a response.
The analytics engine also provides an opportunity to implement access control from the telemetry API.
@@ -234,9 +234,9 @@
aether-config separately. Operators are considered a best practice in Kubernetes.
Modules are loaded into the process primarily for performance and simplicity reasons.
-The design team has had experience with other systems (for example, Voltha and XOS) where modules were decoupled
+The design team has had experience with other systems (for example, VOLTHA and XOS) where modules were decoupled
and message buses introduced between them, but that can lead to both complexity issues and performance bottlenecks
-in those systems. The same module and operator pattern will be applied to aether-roc-api.
+in those systems. The same module and operator pattern will be applied to ``aether-roc-api``.
Aether Modeling
---------------
@@ -282,14 +282,14 @@
communications between components that speak gNMI.
For example, the communication between aether-config and its adapters uses gNMI and therefore uses mutual TLS.
Distributing certificates between components is a problem outside the scope of the ROC.
-It’s assumed that another tool will be responsible for distribution, renewing certificates before they expire, etc.
+It's assumed that another tool will be responsible for distribution, renewing certificates before they expire, etc.
For components that speak REST, HTTPS is used to secure the connection, and authentication can take place using
mechanisms within the HTTPS protocol (basic auth, tokens, etc).
Oath2 and OpenID Connect are leveraged as an authorization provider when using these REST APIs.
.. [1]
- Adaptors are an ad hoc approach to implementing the workflow engine,
+ Adapters are an ad hoc approach to implementing the workflow engine,
where they map models onto models, including the appropriate semantic
translation. This is what we originally did in XOS, but we prefer a
more structured approach for ROC.