consistency pass over operations guide
Change-Id: Idb6fe53727536fca81d24ceba3a58c66780fb9dd
diff --git a/SUMMARY.md b/SUMMARY.md
index fa6e39f..2123400 100644
--- a/SUMMARY.md
+++ b/SUMMARY.md
@@ -15,7 +15,7 @@
* [Bringing Up CORD](profiles/intro.md)
* [R-CORD](profiles/rcord/install.md)
* [OLT Setup](openolt/README.md)
- * [MCORD](profiles/mcord/install.md)
+ * [M-CORD](profiles/mcord/install.md)
* [EnodeB Setup](profiles/mcord/enodeb-setup.md)
* [Helm Reference](charts/helm.md)
* [XOS-CORE](charts/xos-core.md)
@@ -27,16 +27,17 @@
* [VTN Setup](prereqs/vtn-setup.md)
* [M-CORD](charts/mcord.md)
* [Operations Guide](operating_cord/operating_cord.md)
- * General info
- * [Diagnostics](operating_cord/diag.md)
+ * [General Info](operating_cord/general.md)
* [REST API](operating_cord/rest_apis.md)
* [TOSCA](xos-tosca/README.md)
* [XOSSH](xos/dev/xossh.md)
* [XOS Internals](operating_cord/xos_internals.md)
* [XOS Containers](xos/xos_internals.md)
* [XOS Configuration](xos/modules/xosconfig.md)
- * [RCORD](profiles/rcord/configuration.md)
- * [Services](operating_cord/services.md)
+ * [Configuring Profiles](operating_cord/profiles.md)
+ * [R-CORD](profiles/rcord/configuration.md)
+ * [M-CORD](profiles/mcord/configuration.md)
+ * [Configuring Services](operating_cord/services.md)
* [Fabric](fabric/README.md)
* [vRouter](vrouter/README.md)
* [Modeling Guide](xos/README.md)
diff --git a/operating_cord/elk_stack.md b/operating_cord/elk_stack.md
new file mode 100644
index 0000000..a2d45d6
--- /dev/null
+++ b/operating_cord/elk_stack.md
@@ -0,0 +1,69 @@
+# Diagnostics
+
+CORD uses ELK Stack for logging information at all levels. CORD’s ELK Stack
+logger collects information from several components, including the XOS Core,
+API, and various Synchronizers. On a running physical POD, the logs can be
+accessed at `http://<head-node>/app/kibana`. For CORD-in-a-box these logs can
+be accessed at `http://<head-node>:8080/app/kibana`.
+
+There is also a second way of accessing low-level logs with additional
+verbosity that do not make it into ELK Stack. This involves accessing log
+messages in various containers directly. You may do so by running the following
+command on the head node.
+
+```shell
+docker logs < container-name
+```
+
+For most purposes, the logs in ELK Stack should contain enough information
+to diagnose problems. Furthermore, these logs thread together facts across
+multiple components by using the identifiers of XOS data model objects.
+
+> Important!
+>
+> Before you can start using ELK stack, you must initialize its index. To do
+> so:
+>
+> 1) Replace `logstash-*` with `*` in the text box marked "Index pattern."
+>
+> 2) Pick `@timestamp` as the "Time Filter Field Name."
+>
+> Configuring the default logstash- index pattern will lead to HTTP errors in
+> your browser. If you did this by accident, then delete it under Management ->
+> Index Patterns, and create another pattern as described above.
+
+More information about using
+[Kibana](https://www.elastic.co/guide/en/kibana/current/getting-started.html)
+to access ELK Stack logs is available elsewhere, but to illustrate how the
+logging system is used in CORD, consider the following example quieries.
+
+The first example query enlists log messages in the implementation of a
+particular service synchronizer, in a given time range:
+
+```sql
++synchronizer_name:vtr-synchronizer AND +@timestamp:[now-1h TO now]
+```
+
+A second query gets log messages that are linked to the _Network_ data model
+across all services:
+
+```sql
++model_name: Network
+```
+
+The same query can be refined to include the identifier of the specific
+_Network_ object in question. You can obtain the object id from the object’s
+page in the XOS GUI.
+
+```sql
++model_name: Network AND +pk:7
+```
+
+A final example lists log messages in a service synchronizer that
+contain Python exceptions, and will usually correspond to anomalous
+execution:
+
+```sql
++synchronizer_name: vtr-synchronizer AND +exception
+```
+
diff --git a/operating_cord/general.md b/operating_cord/general.md
new file mode 100644
index 0000000..c5ae0d3
--- /dev/null
+++ b/operating_cord/general.md
@@ -0,0 +1,13 @@
+# General Info
+
+CORD's operations and management interface is primarily defined by
+its Northbound API. There is typically more than one variant of this
+interface, and they are auto-generated from the models loaded into
+CORD, as described [elsewhere](../xos/README.md). Most notably:
+
+* A RESTful version of this API is documented [here](rest_apis.md).
+
+* A TOSCA version is typically used to configure and provision a
+ POD. Later sections of this guide give examples of TOSCA workflows
+ used to provision and configure various [profiles](profiles.md)
+ and [services](services.md).
diff --git a/operating_cord/operating_cord.md b/operating_cord/operating_cord.md
index 9b6f9a7..5de08ea 100644
--- a/operating_cord/operating_cord.md
+++ b/operating_cord/operating_cord.md
@@ -1,17 +1,20 @@
-# Operating CORD
+# Operations Guide
This guide defines various processes and procedures for operating a
-CORD POD. It assumes the [build-and-install](../README.md) has already
-completed, and you want to operate and manage a running POD.
+CORD POD. It assumes the [install](../README.md) is already
+complete, and you want to operate and manage a running POD.
Today, CORD most often runs for demo, development, or evaluation
purposes, so this guide is limited to simple procedures suitable for
such settings. We expect more realistic operational scenarios will be
supported in the future.
-It is also the case that CORD's operations and management interface
-is primarily defined by its Northbound API. The RESTful version of
-this API is documented [here](rest_apis.md)
-This API is auto-generated from a set of models, where CORD's
-model-based design is describe [elsewhere](../xos/README.md).
+
+
+
+
+
+
+
+
diff --git a/operating_cord/profiles.md b/operating_cord/profiles.md
new file mode 100644
index 0000000..15850b7
--- /dev/null
+++ b/operating_cord/profiles.md
@@ -0,0 +1,7 @@
+# Configuring Profiles
+
+Configuring and provisioning profiles involves creating the service
+graph that is to run on a POD, and provisoning the resources (e.g.,
+compute instances and networks) that are to run those services. This
+is typically done using a TOSCA workflow. This section documents
+example TOSCA workflows for the R-CORD and M-CORD profiles.
diff --git a/operating_cord/rest_apis.md b/operating_cord/rest_apis.md
index d507149..7b29be0 100644
--- a/operating_cord/rest_apis.md
+++ b/operating_cord/rest_apis.md
@@ -1,10 +1,8 @@
-# CORD REST APIs
+# RESTful APIs
-## XOS
-
-A RESTful interface is available for configuring and controlling XOS. It is
-auto-generated from the set of [models](/xos/README.md) configured into the POD
-manifest, and includes both core and service-specific models.
+A RESTful interface is available for configuring and controlling CORD. It is
+auto-generated from the set of [models](/xos/README.md) configured
+into the POD manifest, and includes both core and service-specific models.
* [Core](https://guide.opencord.org/{{ book.branch }}/api/xos/#/core)
* [Address Manager](https://guide.opencord.org/{{ book.branch }}/api/xos/#/addressmanager)
diff --git a/operating_cord/services.md b/operating_cord/services.md
index 9bc789a..ded5c92 100644
--- a/operating_cord/services.md
+++ b/operating_cord/services.md
@@ -1,5 +1,7 @@
-# Services
+# Configuring Services
-This sections contains detailed instructions about how the single service works.
-It describe what the models and the dependencies of a service are,
-thus is particularly useful in case you want to create your own service chain.
\ No newline at end of file
+This sections contains detailed instructions about how to configure
+individual services. Among other things, it describes what services
+depend on, which is particularly useful in case you want to create
+your own service graph. As with profiles, services are typically
+configured using a TOSCA workflow.
diff --git a/profiles/mcord/configuration.md b/profiles/mcord/configuration.md
new file mode 100644
index 0000000..9e55602
--- /dev/null
+++ b/profiles/mcord/configuration.md
@@ -0,0 +1,6 @@
+# M-CORD Configuration
+
+Once all the components needed for M-CORD are up and running on your POD,
+you'll need to configure XOS with the proper configuration.
+Since this configuration is environment specific, you'll need to create your own,
+but the following can serve as a reference for it:
diff --git a/profiles/rcord/configuration.md b/profiles/rcord/configuration.md
index a77fc88..a2847f5 100644
--- a/profiles/rcord/configuration.md
+++ b/profiles/rcord/configuration.md
@@ -1,9 +1,9 @@
-# RCORD POD Configuration
+# R-CORD Configuration
Once all the components needed for RCORD-Lite are up and running on your POD,
-you'll need to configure XOS with the proper configuration.
-Being this configuration environment specific, you'll need to create your own,
-here is a reference for it:
+you'll need to configure XOS with the proper configuration.
+Since this configuration is environment specific, you'll need to create your own,
+but the following can serve as a reference for it:
```yaml
tosca_definitions_version: tosca_simple_yaml_1_0
@@ -125,9 +125,9 @@
please refer to the [RCORD Service](../../rcord/README.md) guide for
more informations.
-### Zero touch Subscriber provisioning
+### Zero-Touch Subscriber Provisioning
-This feature, also referred to as "bottom-up provisioning" enables autodiscovery
+This feature, also referred to as "bottom-up provisioning" enables auto-discovery
of subscriber and their validation through an external OSS.
Here is the expected workflow:
@@ -153,7 +153,7 @@
For reference we are providing a sample implemetation, available here:
[hippie-oss](https://github.com/opencord/hippie-oss)
-_NOTE: this implementation will validate any subscriber that come online_
+> **Note:** This implementation currently validates any subscriber that comes online.
To deploy the `hippie-oss` service you can look [here](../../charts/hippie-oss.md).