clover fraser: preliminary documents checkin

* add preliminary Clover Fraser release notes
* add preliminary Clover Fraser user guide

Change-Id: I84b0ae1538aaa175245dd47d90ac2343eaa26cc4
Signed-off-by: Stephen Wong <stephen.kf.wong@gmail.com>

diff --git a/docs/release/release-notes/Fraser-release-notes.rst b/docs/release/release-notes/Fraser-release-notes.rst
new file mode 100644 (file)
index 0000000..3e864fb
--- /dev/null
+++ b/docs/release/release-notes/Fraser-release-notes.rst
@@ -0,0 +1,100 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.\r
+.. http://creativecommons.org/licenses/by/4.0\r
+.. SPDX-License-Identifier CC-BY-4.0\r
+.. (c) optionally add copywriters name\r
+\r
+\r
+This document provides the release notes for Fraser of OPNFV Clover.\r
+\r
+.. contents::\r
+   :depth: 3\r
+   :local:\r
+\r
+\r
+Version history\r
+---------------\r
+\r
++--------------------+--------------------+--------------------+--------------------+\r
+| **Date**           | **Ver.**           | **Author**         | **Comment**        |\r
+|                    |                    |                    |                    |\r
++--------------------+--------------------+--------------------+--------------------+\r
+| 2018-03-14         | Fraser 1.0         | Stephen Wong       | First draft        |\r
+|                    |                    |                    |                    |\r
++--------------------+--------------------+--------------------+--------------------+\r
+\r
+Important notes\r
+===============\r
+\r
+The OPNFV Clover project for Fraser can ONLY be run on Kubernetes version 1.9.3 or\r
+above\r
+\r
+Summary\r
+=======\r
+\r
+Clover provides tools to help run cloud native virtual network functions. These\r
+tools include service-mesh and associated policy-based-routing config (via\r
+Istio), logging (via fluentd), monitoring (via Prometheus), and tracing (via\r
+OpenTracing and Jaeger).\r
+\r
+Release Data\r
+============\r
+\r
++--------------------------------------+--------------------------------------+\r
+| **Project**                          | Clover                               |\r
+|                                      |                                      |\r
++--------------------------------------+--------------------------------------+\r
+| **Repo/commit-ID**                   |                                      |\r
+|                                      |                                      |\r
++--------------------------------------+--------------------------------------+\r
+| **Release designation**              | Fraser                               |\r
+|                                      |                                      |\r
++--------------------------------------+--------------------------------------+\r
+| **Release date**                     | 2018-04-xx                           |\r
+|                                      |                                      |\r
++--------------------------------------+--------------------------------------+\r
+| **Purpose of the delivery**          | OPNFV Fraser release                 |\r
+|                                      |                                      |\r
++--------------------------------------+--------------------------------------+\r
+\r
+Version change\r
+^^^^^^^^^^^^^^^^\r
+\r
+Module version changes\r
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
+Fraser marks the first release of OPNFV Clover\r
+\r
+Document version changes\r
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
+Fraser marks the first release of OPNFV Clover\r
+\r
+Reason for version\r
+^^^^^^^^^^^^^^^^^^^^\r
+\r
+Feature additions\r
+~~~~~~~~~~~~~~~~~~~~~~~\r
+<None> (no backlog)\r
+\r
+Bug corrections\r
+~~~~~~~~~~~~~~~~~~~~~\r
+<None>\r
+\r
+Known Limitations, Issues and Workarounds\r
+=========================================\r
+\r
+System Limitations\r
+^^^^^^^^^^^^^^^^^^^^\r
+TBD\r
+\r
+Known issues\r
+^^^^^^^^^^^^^^^\r
+TBD\r
+\r
+Workarounds\r
+^^^^^^^^^^^^^^^^^\r
+\r
+Test Result\r
+===========\r
+\r
+\r
+References\r
+==========\r

diff --git a/docs/release/userguide/Fraser-userguide.rst b/docs/release/userguide/Fraser-userguide.rst
new file mode 100644 (file)
index 0000000..243c4e1
--- /dev/null
+++ b/docs/release/userguide/Fraser-userguide.rst
@@ -0,0 +1,81 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. SPDX-License-Identifier CC-BY-4.0
+.. (c) optionally add copywriters name
+
+
+================================================================
+Clover User Guide (Fraser Release)
+================================================================
+
+This document provides the user guide for Fraser release of Clover.
+
+.. contents::
+   :depth: 3
+   :local:
+
+
+Description
+===========
+
+Project Clover was established to investigate best practice to implement,
+build, deploy, and operate virtual network functions as cloud native
+applications. "Cloud native" has a ever evolving and expanding definition,
+and in Clover, the focus is effectively running and operating VNFs built
+in a micro-service design pattern running on Docker containers and
+orchestrated by Kubernetes.
+
+The strength of cloud native applications is their operablity and
+scalability. Essential to achieve these qualities is the use of service
+mesh. As such, in Fraser release, Clover's emphasis is on demonstrating
+running a sample micro-service composed VNF on Istio, the service mesh
+platform of Clover's choice in Fraser, and how to maximize visibility
+of this sample running in a service mesh.
+
+What is in Fraser?
+==================
+
+ * a sample micro-service composed VNF
+
+ * logging module: fluentd and elasticsearch Kubernetes manifests,
+   installation validation, log data correlation in datastore
+
+ * tracing module: jaeger Kubernetes manifest, installation validation,
+   jaegar tracing query tools, trace data correlation in datastore
+
+ * monitoring module: prometheus Kubernetes manifest, installation
+   validation, prometheous query tools for Istio related metrics,
+   metrics correlation in datastore
+
+ * Istio route-rules and circuit breaking sample yaml and validation
+   tools
+
+ * Test scripts
+
+ * Reference for a demo shown during ONS
+
+Usage
+=====
+
+ * each modules (service mesh, logging, tracing, monitoring) are Python
+   modules with their own set of library calls / API exposed. The descriptions
+   of these library calls are under doc/developer (TBD)
+
+ * tools directory contains Python tools for generic use
+   python clover_validate_route_rules.py -s <service name> -n <number of tests>
+   [more TBD]
+
+ * an example scenario:
+   - version 2 (v2) of a micro-service component is deployed
+   - Istio route rule is applied to send 50% traffic to v2
+   - Clover tool validates traffic conformance with route rules
+   - user specify via yaml the "success" expectation of v2 (latency,
+     performance, session loss...etc)
+   - Clover tool validates sessions conformance with user defined expectations
+   - The "commit" action is invoked to move 100% traffic to v2
+   - Clover tool validates traffic conformance with route rules
+   - A fault is injected for the path to the extra service of v2 which adds
+     a one second delay onto the path
+   - The same A-B testing script is invoked, this time, performance
+     test now fails
+   - The "rollback" action is invoked to move 100% traffic back to v1