From b829e19995fd9cf5b30896a61644f53833d9c30f Mon Sep 17 00:00:00 2001
From: Ilya Shakhat <shakhat@gmail.com>
Date: Fri, 3 Nov 2017 12:31:26 +0100
Subject: [PATCH] Add section describing OS-Faults and Rally integration

Change-Id: Ib0511064d29b2013a44691b30d4644042a508ca1
---
 doc/source/quickstart/api.rst   |  6 ++--
 doc/source/quickstart/index.rst |  1 +
 doc/source/quickstart/rally.rst | 62 +++++++++++++++++++++++++++++++++
 3 files changed, 66 insertions(+), 3 deletions(-)
 create mode 100644 doc/source/quickstart/rally.rst

diff --git a/doc/source/quickstart/api.rst b/doc/source/quickstart/api.rst
index 1d07c99..2cd0477 100644
--- a/doc/source/quickstart/api.rst
+++ b/doc/source/quickstart/api.rst
@@ -8,10 +8,10 @@ The library operates with 2 types of objects:
     * `nodes` - nodes that host the cloud, e.g. a hardware server with a hostname
 
 
-Simplified API
---------------
+Human API
+---------
 
-Simplified API is used to inject faults in a human-friendly form.
+Human API is used to specify faults as normal English sentences.
 
 .. code-block:: python
 
diff --git a/doc/source/quickstart/index.rst b/doc/source/quickstart/index.rst
index f481bd2..8831c68 100644
--- a/doc/source/quickstart/index.rst
+++ b/doc/source/quickstart/index.rst
@@ -11,3 +11,4 @@ This section describes how to start using os-faults.
    basics
    api
    config_spec
+   rally
diff --git a/doc/source/quickstart/rally.rst b/doc/source/quickstart/rally.rst
new file mode 100644
index 0000000..1a5394f
--- /dev/null
+++ b/doc/source/quickstart/rally.rst
@@ -0,0 +1,62 @@
+=================
+OS-Faults + Rally
+=================
+
+Combination of OS-Faults and `Rally`_ gives a powerful tool to test OpenStack high availability
+and fail-over under the load.
+
+Fault injection is implemented with help of Rally `Fault Injection Hook`_. Following
+is an example of Rally scenario performing Keystone authentication with restart of one of
+Memcached services:
+
+.. code-block:: yaml
+
+    ---
+      Authenticate.keystone:
+        -
+          runner:
+            type: "constant_for_duration"
+            duration: 30
+            concurrency: 5
+          context:
+            users:
+              tenants: 1
+              users_per_tenant: 1
+          hooks:
+            -
+              name: fault_injection
+              args:
+                action: restart memcached service on one node
+              trigger:
+                name: event
+                args:
+                  unit: iteration
+                  at: [100]
+
+The moment of fault injection can be specified as iteration number or in time relative
+to the beginning of the test:
+
+.. code-block:: yaml
+
+              trigger:
+                name: event
+                args:
+                  unit: time
+                  at: [10]
+
+Parameter `action` contains fault specification in human-friendly format, see
+:ref:`Human API` for details.
+
+More on reliability testing of OpenStack:
+
+ * `Reliability Test Plan`_ in OpenStack performance documentation
+ * `Keystone authentication with restart memcached report`_ collected in OpenStack deployed by Fuel
+ * `Introduction into reliability metrics`_ video cast
+
+
+.. references:
+.. _Rally: http://rally.readthedocs.io
+.. _Fault Injection Hook: http://docs.xrally.xyz/projects/openstack/en/0.10.0/plugins/plugin_reference.html?highlight=fault_injection#fault-injection-hook-action
+.. _Reliability Test Plan: https://docs.openstack.org/performance-docs/latest/test_plans/reliability/version_2/plan.html
+.. _Keystone authentication with restart memcached report: https://docs.openstack.org/performance-docs/latest/test_results/reliability/version_2/reports/keystone/authenticate_with_restart_memcached_service_on_one_node/index.html
+.. _Introduction into reliability metrics: https://www.youtube.com/watch?v=9puoDd14IxU