Add index and cleanup design docs on stable/fraser

- Add toplevel index to design docs on stable/fraser
- Add headers to each of the design docs
- Added usage of Clover container to install Jaeger/Prometheus
in combination in tracing and monitoring docs
- Minor edits including removing TODO/TBD

Change-Id: I1a33544a5b3d6be4147810ef9472b8d72cdec28c
Signed-off-by: Eddie Arrage <eddie.arrage@huawei.com>

4 files changed, 62 insertions, 12 deletions

diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..0d81d0d
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,15 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV, Authors of Clover
+
+========================
+OPNFV Clover Design Docs
+========================
+
+.. toctree::
+   :maxdepth: 2
+
+   logging
+   monitoring
+   tracing
diff --git a/docs/logging.rst b/docs/logging.rst
index 05f3f5b..db0a22e 100644
--- a/docs/logging.rst
+++ b/docs/logging.rst
@@ -1,3 +1,10 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV, Authors of Clover
+
+.. _logging:
+
 #######
 Logging
 #######
@@ -21,11 +28,10 @@ The scripts in ``clover/logging`` validates fluentd installation::
 
     python clover/logging/validate.py
 
-It validates the installation with the following criterias
+It validates the installation with the following criteria:
 
 #. existence of fluented pod
 #. fluentd input is configured correctly
-#. TBD
 
 **************************
 Understanding how it works
@@ -62,7 +68,7 @@ Istio defines when to log by creating a custom resource ``rule``. For example:
 This rule specifies that all instances of ``newlog.logentry`` that matches the
 expression will be handled by the specified handler ``handler.fluentd``. We
 shall explain ``instances`` and ``handler`` later. The expression ``true`` means
-whenever a request arrive at Mixer, it will trigger the actions defined belows.
+whenever a request arrives at Mixer, it will trigger the actions defined below.
 
 ``rule`` is a custom resource definition from `Istio installation`_.
 
@@ -139,7 +145,7 @@ By the way, ``logentry`` is also a custom resource definition created by Istio.
 Where to log
 ============
 
-For log, the handler defines where these information will be handled, in this
+For log, the handler defines where this information will be handled, in this
 example, a fluentd daemon on fluentd-es.logging:24224.
 
 .. code-block:: yaml
diff --git a/docs/monitoring.rst b/docs/monitoring.rst
index 44b01e3..76c19b6 100644
--- a/docs/monitoring.rst
+++ b/docs/monitoring.rst
@@ -1,3 +1,10 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV, Authors of Clover
+
+.. _monitoring:
+
 ##########
 Monitoring
 ##########
@@ -6,26 +13,33 @@ Monitoring
 Installation
 ************
 
-Currently, we use the Istio build-in prometheus addon to install prometheus::
+Currently, we use the Istio built-in Prometheus add-on to install Prometheus::
 
     cd <istio-release-path>
     kubectl apply -f install/kubernetes/addons/prometheus.yaml
 
+
+Alternatively, both Prometheus and Jaeger can be installed in combination with the
+Clover container using the command::
+
+    $ sudo docker run --rm \
+    -v ~/.kube/config:/root/.kube/config \
+    opnfv/clover \
+    /bin/bash -c '/home/opnfv/repos/clover/samples/scenarios/view.sh'
+
 ********
 Validate
 ********
 
-Setup port-forwarding for prometheus by executing the following command::
+Setup port-forwarding for Prometheus by executing the following command::
 
     kubectl -n istio-system port-forward $(kubectl -n istio-system get pod -l app=prometheus -o jsonpath='{.items[0].metadata.name}') 9090:9090 &
 
-Run the scripts in ``clover/monitoring`` validates prometheus installation::
+Run the scripts in ``clover/monitoring`` to validate the Prometheus installation::
 
     python clover/monitoring/validate.py
 
-It validates the installation with the following criterias
+It validates the installation with the following criteria:
 
-#. [DONE] prometheus pod is in Running state
-#. [DONE] prometheus is conneted to monitoring targets
-#. [TODO] test collecting telemetry data from istio
-#. [TODO] TBD
+#. Prometheus pod is in running state
+#. Prometheus is connected to monitoring targets
diff --git a/docs/tracing.rst b/docs/tracing.rst
index b83274c..35b36aa 100644
--- a/docs/tracing.rst
+++ b/docs/tracing.rst
@@ -1,3 +1,10 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International
+.. License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV, Authors of Clover
+
+.. _tracing:
+
 #######
 Tracing
 #######
@@ -12,6 +19,14 @@ following command::
 
     kubectl apply -n istio-system -f https://raw.githubusercontent.com/jaegertracing/jaeger-kubernetes/master/all-in-one/jaeger-all-in-one-template.yml
 
+Alternatively, both Prometheus and Jaeger can be installed in combination with the
+Clover container using the command::
+
+    $ sudo docker run --rm \
+    -v ~/.kube/config:/root/.kube/config \
+    opnfv/clover \
+    /bin/bash -c '/home/opnfv/repos/clover/samples/scenarios/view.sh'
+
 The standard Jaeger REST port is at 16686. To make this service available outside of the
 Kubernetes cluster via any node IP in the cluster, use the following command::