more tweaking + figure
Change-Id: I0f0ce86f737728b33c04a5fa6cb48a689c4a72ac
diff --git a/docs/README.md b/docs/README.md
index 4e042a7..424dd76 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,18 +1,17 @@
# XOS Overview
-XOS provides a framework for defining a set of declarative models and
-then using those models to manage a collection of components that have
-been configured into an operational system. XOS is itself deployed as
-a set of micro-services, collectively forming an
-*Extensible Service Control Plane* that:
+XOS provides a framework for operationalizing a collection of
+disaggregated components. More specifically, XOS defines an
+*Extensible Service Control Plane* that provides value in two
+ways:
-* Serves as a single unifying interface to a collection of backend
- services, avoiding the management silos that otherwise result from
+* It serves as a single unifying OAM interface to a collection of backend
+ services, avoiding the operational silos that otherwise result from
disaggregation. This includes a framework for creating and
operating on services across organizational boundaries, across a range
- of implementations, and across multiple tenants.
+ of implementation choices, and across multiple tenants.
-* Implements end-to-end service chains across a service mesh, supporting
+* It manages end-to-end service chains across a service mesh, supporting
visibility and control at the granularity of individual subscribers
or flows. This provides a fine-grain means to correlate diagnostic and
monitoring information, allocate resources and isolate performance,
@@ -20,20 +19,21 @@
XOS is currently being used in three projects:
-* **CORD Controller:** XOS is a central part of CORD, providing a coherent
- service control plane that runs on on top of a mix of disaggregated
+* **CORD Controller:** XOS is a central part of CORD (Central Office
+ Re-architected as a Datacenter), providing a coherent service
+ control plane that runs on on top of a mix of disaggregated
access technologies, legacy VNFs running in OpenStack VMs, horizontally
scalable micro-services running in Kubernetes, and SDN control
applications running on ONOS.
* **Network Edge Mediator (NEM):** XOS is being used to provide a
mediation layer for SEBA (Software-Enabled Broadband Access),
- addressing the challenge of how to integrate an edge site with different
+ addressing the challenge of how to integrate an edge sites with different
(and potentially multiple) global orchestrators and legacy OSS/BSS.
* **End-to-End Service Chains in a Multi-Cloud:** XOS is being used
to manage end-to-end service chains that span customer premises,
- edge sites, Internet exchange points, and commodity clouds.
+ operator edge sites, Internet exchanges, and commodity clouds.
For additional white papers describing XOS, see the project
[wiki page](https://wiki.opencord.org/display/CORD/XOS+and+the+CORD+Controller).
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 30258b7..72bed9b 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -1,6 +1,7 @@
# Summary
* [Introduction](README.md)
+ * [End-to-End Example](use_case.md)
* [Installing XOS](install.md)
* [Download Source Code](repo.md)
* [XOS Containers](xos_internals.md)
diff --git a/docs/auto-configuration.png b/docs/auto-configuration.png
new file mode 100644
index 0000000..608b81e
--- /dev/null
+++ b/docs/auto-configuration.png
Binary files differ
diff --git a/docs/book.json b/docs/book.json
index cf106cf..1312ebb 100644
--- a/docs/book.json
+++ b/docs/book.json
@@ -10,7 +10,6 @@
"plugins": [
"anchorjs",
"smart-nav-collapse",
- "page-toc",
"versions-select"
]
}
diff --git a/docs/use.md b/docs/use.md
index ac6ea70..399a316 100644
--- a/docs/use.md
+++ b/docs/use.md
@@ -11,7 +11,8 @@
generate code for several elements required to control the system
(including an API that serves the set of models that have been
loaded into XOS). Service developers typically write one or more
- models to on-board their service.
+ xproto models to on-board their service. Platform developers
+ sometimes extend xosgenx to support new target elements.
* **Synchronizer Framework:** XOS defines a
[synchronization framework](dev/synchronizers.md)
diff --git a/docs/use_case.md b/docs/use_case.md
new file mode 100644
index 0000000..28fe655
--- /dev/null
+++ b/docs/use_case.md
@@ -0,0 +1,70 @@
+# End-to-End Example
+
+This section gives a brief overview of lifecycle management in CORD,
+illustrating the role XOS plays in operationalizing a system built from
+a collection of disaggregated services.
+
+![auto configuration](auto-configuration.png)
+
+As depicted in this diagram, CORD adopts a three-layer approach:
+
+* **Installation (Helm):** Installing CORD means installing a collection
+ of Docker containers in a Kubernetes cluster. CORD uses Helm to carry
+ out the installation, with the valid configurations defined by a set of
+ `helm-charts`. These charts specify the version of each container to be
+ deployed, and so they also play a role in upgrading a running system.
+
+* **Operations (TOSCA):** A running CORD POD supports multiple Northbound
+ Interfaces (e.g., a GUI and REST API), but CORD typically uses `TOSCA` to specify
+ a workflow for configuring and provisioning a running system. A freshly
+ installed CORD POD has a set of control plane and platform level containers
+ running (e.g., XOS, ONOS, OpenStack), but until provisioned using `TOSCA`,
+ there are no services and no service graph.
+
+* **Integration (XOS):** The services running in an operational system
+ are typically deployed as Docker containers, paired with a model that
+ specifies how the service is to be integrated into CORD. This model is
+ writen in the `xproto` modeling language, and processed by the XOS
+ tool-chain. Among other things, this tool-chain generates the
+ TOSCA-engine that is used to process the configuration and provisioning
+ workflows used to operate CORD.
+
+These tools and containers are inter-related as follows:
+
+* An initial install brings up a set of XOS-related containers (e.g., `xos-core`,
+ `xos-gui`, `xos-tosca`) that have been configured with a base set of models.
+ Of these, the `xos-tosca` container implements the TOSCA engine, which
+ takes TOSCA workflows as input and configures/provisions CORD accordingly.
+
+* While the install and operate stages are distinct, for convenience,
+ some helm-charts elect to launch a `tosca-loader` container
+ (in Kubernetes parlance, it's a *job* and not a *service*) to load an initial
+ TOSCA workflow into a newly deployed set of services. This is how a
+ service graph is typically instantiated.
+
+* While the CORD control plane is deployed as a set of Docker
+ containers, not all of the services themselves run in containers.
+ Some services run in VMs managed by OpenStack and some
+ services are implemented as ONOS applications that have been
+ packaged using Maven. In such cases, the VM image and the
+ Maven package are still specified in the TOSCA workflow.
+
+* Every service (whether implemented in Docker, OpenStack, or ONOS)
+ has a counter-part *synchronizer* container running as part of the CORD
+ control plane (e.g., `volt-synchronizer` for the vOLT service). Typically,
+ the helm-chart for a service launches this synchronizer container, whereas
+ the TOSCA worflow creates, provisions, and initializes the backend container,
+ VM, or ONOS app.
+
+* Bringing up additional services in a running POD involves executing
+ helm-charts to install the new service's synchronizer container, which
+ in turn loads the corresponding new models into XOS. This load then
+ triggers and upgrade and restart of the TOSCA engine (and other NBIs),
+ which is a pre-requisite for configuring and provisioning that new service.
+
+* Upgrading an existing service is similar to bringing up a new service,
+ where we depend on Kubernetes to incrermentally roll out the containers
+ that implement the service (and rollback if necessarily), and we depend
+ on XOS to migrate from the old model to the new model (and support
+ both old and new APIs during the transition period). Upgrading existing
+ services has not been thoroughly tested.