Merge "draft navigation section"
diff --git a/SUMMARY.md b/SUMMARY.md
index df56009..0274795 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -1,6 +1,7 @@
# Summary
* [Overview](overview.md)
+ * [Navigating the Guide](navigate.md)
* [Installation Guide](README.md)
* [Hardware Requirements](prereqs/hardware.md)
* [Connectivity Requirements](prereqs/networking.md)
@@ -43,16 +44,16 @@
* [RCORD](rcord/README.md)
* [vOLT](olt-service/README.md)
* [vRouter](vrouter/README.md)
-* [Modeling Guide](xos/README.md)
- * [XOS Modeling Framework](xos/dev/xproto.md)
- * [Core Models](xos/core_models.md)
- * [Security Policies](xos/security_policies.md)
- * [Writing Synchronizers](xos/dev/synchronizers.md)
- * [Design Guidelines](xos/dev/sync_arch.md)
- * [Implementation Details](xos/dev/sync_impl.md)
- * [Synchronizer Reference](xos/dev/sync_reference.md)
* [Development Guide](developer/developer.md)
* [Getting the Source Code](developer/getting_the_code.md)
+ * [Writing Models and Synchronizers](xos/README.md)
+ * [XOS Modeling Framework](xos/dev/xproto.md)
+ * [Core Models](xos/core_models.md)
+ * [Security Policies](xos/security_policies.md)
+ * [Writing Synchronizers](xos/dev/synchronizers.md)
+ * [Design Guidelines](xos/dev/sync_arch.md)
+ * [Implementation Details](xos/dev/sync_impl.md)
+ * [Synchronizer Reference](xos/dev/sync_reference.md)
* [Developer Workflows](developer/workflows.md)
* [Building Docker Images](developer/imagebuilder.md)
* [Platform Services](developer/platform.md)
diff --git a/developer/developer.md b/developer/developer.md
index fef811f..a1fc60c 100644
--- a/developer/developer.md
+++ b/developer/developer.md
@@ -1,9 +1,8 @@
# Development Guide
-This guide describes workflows and best practices for developers. If
-you are a service developer, you will need to consult this guide and
-the companion [Modeling Guide](../xos/README.md) that describes how
-define models and synchronizers for services being onboarded into
+This guide describes workflows and best practices for developers.
+If you are a service developer, this includes information on how to
+write models and synchronizers for services being on-boarded into
CORD. If you are a platform developer, you will find information about
the platform services typically integrated into CORD (e.g.,
Kubernetes, OpenStack, VTN). Service developers may be interested in
diff --git a/navigate.md b/navigate.md
new file mode 100644
index 0000000..a92bb01
--- /dev/null
+++ b/navigate.md
@@ -0,0 +1,88 @@
+# Navigating the Guide
+
+The guide is organized around the major stages in the lifecycle of CORD:
+
+* [Installation](README.md): Installing (and later upgrading) CORD.
+* [Operations](operating_cord/operating_cord.md): Operating an already
+ installed CORD deployment.
+* [Development](developer/developer.md): Developing new functionality
+ to be included in CORD.
+* [Testing](cord-tester/README.md): Testing functionality to be
+ included in CORD.
+
+## Navigating CORD
+
+These are all fairly obvious. What's less obvious is the relationship among
+the toolset (and corresponding specification files) used for each stage.
+Understanding these relationships is helpful in navigating CORD.
+
+* **Installation (Helm):** Installing CORD means installing a collection
+ of Docker containers in a Kubernetes cluster. We use 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.
+ More information about `helm-charts` can be found [here](charts/helm.md).
+
+* **Operations (TOSCA):** A running CORD POD supports multiple Northbound
+ Interfaces (e.g,. a GUI and REST API), but we typically use `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. More information about `TOSCA`
+ can be found [here](xos-tosca/README.md).
+
+* **Development (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 on-boarded 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. More information about `xproto` (and
+ other details about on-boarding a service) can be found
+ [here](xos/dev/xproto.md).
+
+* **Testing (Jenkins):** Full CORD PODS (as well as individual components
+ of CORD) are installed on both physical and virtual environment, and run
+ through a series of tests. Full PODS are tested nightly, and individual
+ components are tested upon every commit Gerrit. These tests are specified
+ using `Jenkinfiles` and `JJB`. An overview of how CORD is tested can be found
+ [here](cord-tester/README.md).
+
+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.
+
+* Not all services run as Docker containers. Some services run in VMs
+ managed by OpenStack (this is currently the case for M-CORD) 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 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.