Amended sphinx documents

  Updated from https://wiki.openstack.org/wiki/Rally

Change-Id: I520b08202910ad476447fa09ca0a5993fc1bffc5

doc/source/benchmark.rst → doc/source/concepts.rst

@@ -13,16 +13,16 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-.. _benchmark:
+.. _main_concepts:
 
-Benchmark
-=========
+Main concepts of Rally
+======================
 
 Benchmark Scenarios
 -------------------
 
-Notion of benchmark scenarios
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Concept
+^^^^^^^
 
 The concept of **benchmark scenarios** is a central one in Rally. Benchmark scenarios are what Rally actually uses to **test the performance of an OpenStack deployment**. They also play the role of main building blocks in the configurations of benchmark tasks. Each benchmark scenario performs a small **set of atomic operations**, thus testing some **simple use case**, usually that of a specific OpenStack project. For example, the **"NovaServers"** scenario group contains scenarios that use several basic operations available in **nova**. The **"boot_and_delete_server"** benchmark scenario from that group allows to benchmark the performance of a sequence of only **two simple operations**: it first **boots** a server (with customizable parameters) and then **deletes** it.
 
@@ -105,14 +105,11 @@ In a toy example below, we define a scenario class *MyScenario* with one benchma
 
 
 
-Benchmark engine
+Scenario runners
 ----------------
 
-The core classes responsible for the benchmarking mechanism, including
-the benchmark engine class, benchmark scenario runners and others.
-
-Notion of scenario runners
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+Concept
+^^^^^^^
 
 **Scenario Runners** in Rally are entities that control the execution type and order of benchmark scenarios. They support different running **strategies for creating load on the cloud**, including simulating *concurrent requests* from different users, periodic load, gradually growing load and so on.
 
@@ -214,8 +211,8 @@ It is possible to extend Rally with new Scenario Runner types, if needed. Basica
 Benchmark contexts
 ------------------
 
-Notion of contexts
-^^^^^^^^^^^^^^^^^^
+Concept
+^^^^^^^
 
 The notion of **contexts** in Rally is essentially used to define different types of **environments** in which benchmark scenarios can be launched. Those environments are usually specified by such parameters as the number of **tenants and users** that should be present in an OpenStack project, the **roles** granted to those users, extended or narrowed **quotas** and so on.
 

doc/source/deploy_engines.rst

@@ -0,0 +1,128 @@
+..
+      Copyright 2014 Mirantis Inc. All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+.. _deploy_engines:
+
+Deploy engines
+==============
+
+
+Introduction
+------------
+
+One of the core entities in Rally architecture are the Deploy engines. The task of a deploy engine is to control the process of deploying some OpenStack distribution like DevStack or FUEL before any benchmarking procedures take place. Every deploy engine should implement the following fairly simple interface:
+
+..
+
+    **constuctor**, which takes a deployment entity as its only parameter;
+
+..
+
+    **deploy()**, which should deploy the appropriate OpenStack distribution given the cloud config from the deployment object the engine was initialized with (possibly using one of available :ref:`server providers <server_providers>`). The method should also return a dictionary with endpoints of the deployed OpenStack distribution;
+
+..
+
+    **cleanup()**, which should clean up the OpenStack deployment (again, possibly using one of available :ref:`server providers <server_providers>`).
+
+
+Below you will find a short but informative description of deploy engines implemented in Rally.
+
+
+Available Deploy engines
+------------------------
+
+
+ExistingCloud
+^^^^^^^^^^^^^
+
+**Description**
+
+This engine in fact does not deploy anything, but uses an existing OpenStack installation. It may be useful in case you have a preconfigured OpenStack deployment ready to launch benchmark scenarios.
+
+**Configuration Example**
+
+.. code-block:: none
+
+   {
+       "type": "ExistingCloud",
+       "endpoint": {
+            "auth_url": "http://192.168.122.22:5000/v2.0/",
+            "username": "admin",
+            "password": "password",
+            "tenant_name": "admin",
+            "use_public_urls": True
+       }
+   }
+
+Or using keystone v3 API endpoint:
+
+.. code-block:: none
+
+    {
+        "type": "ExistingCloud,
+        "endpoint": {
+            "auth_url": "http://localhost:5000/v3/,
+            "username": "engineer1,
+            "user_domain_name": "qa,
+            "project_name": "qa_admin_project,
+            "project_domain_name": "qa,
+            "password": "password,
+            "region_name": "RegionOne,
+            "use_public_urls": False,
+            "admin_port": 35357
+        }
+    }
+..
+
+  *use_public_urls*  option will be used later for switching access method to the cloud.
+    Because in some use-cases cloud may be accessible only by public endpoints.
+
+
+
+All you should specify in the config is the OpenStack cloud endpoint: the auth_url and also admin credentials, including tenant name. Rally will use the specified admin account to manage temporary non-admin tenants and users exploited while launching benchmark scenarios.
+
+
+DevstackEngine
+^^^^^^^^^^^^^^
+
+**Description**
+
+This engine deploys a Devstack cloud using the given Devstack repository.
+
+**Configuration Example**
+
+.. code-block:: none
+
+   {
+       "type": "DevstackEngine",
+       "localrc": {
+           "ADMIN_PASSWORD": "secret",
+           "NOVA_REPO": "git://example.com/nova/",
+           ...
+       },
+       "devstack_repo": "git://example.com/devstack/",
+       "type": {
+           "name": "${PROVIDER_NAME}",
+           ...
+       }
+   }
+
+
+The localrc field of the Devstack engine configuration will be used to initialize the Devstack's localrc file. As this deploy engine does not use an existing cloud, it also needs a concrete :ref:`server provider <server_providers>` specification: the type of the used provider *(${PROVIDER_NAME})*, followed by provider-specific fields configuration.
+
+
+**Note**
+
+More Deploy engines are to come in future releases, namely deploy engines for FUEL, Tripple-O etc. Stay tuned.

doc/source/improve_rally.rst

@@ -0,0 +1,113 @@
+..
+      Copyright 2014 Mirantis Inc. All Rights Reserved.
+
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+
+.. _improve_rally:
+
+Improve Rally
+=============
+
+Main directions of work
+-----------------------
+
+    * **Benchmarks**. Improvements in the benchmarking engine & developing new benchmark scenarios.
+    * **Deployments**. Making Rally able to support multiple cloud deployment facilities, e.g. Fuel.
+    * **CLI**. Enriching the command line interface for Rally.
+    * **API**. Work around making Rally to be a Benchmark-as-a-Service system & developing rally-pythonclient.
+    * **Incubation**. Efforts to make Rally an integrated project in OpenStack.
+    * **Share system**. Benchmark results visualization and paste.openstack.org-like sharing system.
+    * **Tempest**. Integration of Tempest tests in Rally for deployment verification.
+
+
+Where to begin
+--------------
+
+It is extremetly simple to participate in different Rally development lines mentioned above. The **Good for start** section of our `Trello board <https://trello.com/b/DoD8aeZy/rally>`_ contains a wide range of tasks perfectly suited for you to quickly and smoothly start contributing to Rally. As soon as you have chosen a task, just log in to Trello, join the corresponding card and move it to the **In progress** section.
+
+The most Trello cards contain basic descriptions of what is to be done there; in case you have questions or want to share your ideas, be sure to contanct us at the ``#openstack-rally`` IRC channel on **irc.freenode.net**.
+
+If you want to grasp a better understanding of several main design concepts used throughout the Rally code (such as **benchmark scenarios**, **contexts** etc.), please read this :ref:`article <main_concepts>`.
+
+
+How to contribute
+-----------------
+
+1. You need a `Launchpad <https://launchpad.net/>`_ account and need to be joined to the `Openstack team <https://launchpad.net/openstack>`_. You can also join the `Rally team <https://launchpad.net/rally>`_ if you want to. Make sure Launchpad has your SSH key, Gerrit (the code review system) uses this.
+
+2. Sign the CLA as outlined in section 3 of the `How To Contribute wiki page <https://wiki.openstack.org/wiki/HowToContribute#If_you.27re_a_developer>`_.
+
+3. Tell git your details:
+
+.. code-block:: none
+
+    git config --global user.name "Firstname Lastname"
+    git config --global user.email "your_email@youremail.com"
+
+4. Install git-review. This tool takes a lot of the pain out of remembering commands to push code up to Gerrit for review and to pull it back down to edit it. It is installed using:
+
+.. code-block:: none
+
+    pip install git-review
+
+Several Linux distributions (notably Fedora 16 and Ubuntu 12.04) are also starting to include git-review in their repositories so it can also be installed using the standard package manager.
+
+5. Grab the Rally repository:
+
+.. code-block:: none
+
+    git clone git@github.com:stackforge/rally.git
+
+6. Checkout a new branch to hack on:
+
+.. code-block:: none
+
+    git checkout -b TOPIC-BRANCH
+
+7. Start coding
+
+8. Run the test suite locally to make sure nothing broke, e.g.:
+
+.. code-block:: none
+
+    tox
+
+**(NOTE you should have installed tox<=1.6.1 )**
+
+If you extend Rally with new functionality, make sure you also have provided unit tests for it.
+
+9. Commit your work using:
+
+.. code-block:: none
+
+    git commit -a
+
+
+Make sure you have supplied your commit with a neat commit message, containing a link to the corresponding blueprint / bug, if appropriate.
+
+10. Push the commit up for code review using:
+
+.. code-block:: none
+
+    git review -R
+
+That is the awesome tool we installed earlier that does a lot of hard work for you.
+
+11. Watch your email or `review site <http://review.openstack.org/>`_, it will automatically send your code for a battery of tests on our `Jenkins setup <http://jenkins.openstack.org/>`_ and the core team for the project will review your code. If there are any changes that should be made they will let you know.
+
+12. When all is good the review site  will automatically merge your code.
+
+
+(This tutorial is based on: http://www.linuxjedi.co.uk/2012/03/real-way-to-start-hacking-on-openstack.html)

doc/source/index.rst

@@ -13,27 +13,46 @@
       License for the specific language governing permissions and limitations
       under the License.
 
-Welcome to Rally's documentation!
+What is Rally?
 =================================
 
-Rally is a benchmarking tool for the community that is capable of performing
-specific, complex and reproducible tests for real deployment scenarios.
+If you are here, you are probably familiar with OpenStack and you also know that it's a really huge ecosystem of cooperative services. When something fails, performs slowly or doesn't scale, it's really hard to answer different questions on "what", "why" and "where" has happened. Another reason why you could be here is that you would like to build an OpenStack CI/CD system that will allow you to improve SLA, performance and stability of OpenStack continuously.
 
+The OpenStack QA team mostly works on CI/CD that ensures that new patches don't break some specific single node installation of OpenStack. On the other hand it's clear that such CI/CD is only an indication and does not cover all cases (e.g. if a cloud works well on a single node installation it doesn't mean that it will continue to do so on a 1k servers installation under high load as well). Rally aims to fix this and help us to answer the question "How does OpenStack work at scale?". To make it possible, we are going to automate and unify all steps that are required for benchmarking OpenStack at scale: multi-node OS deployment, verification, benchmarking & profiling.
 
-Source Documentation
---------------------
 
-Contents:
+.. image:: ./images/Rally-Actions.png
+   :width: 50%
+   :align: center
 
+* Deploy engine is not yet another deployer of OpenStack, but just a pluggable mechanism that allows to unify & simplify work with different deployers like: DevStack, Fuel, Anvil on hardware/VMs that you have.
+* Verification - (work in progress) uses tempest to verify the functionality of a deployed OpenStack cloud. In future Rally will support other OS verifiers.
+* Benchmark engine - allows to create parameterized load on the cloud based on a big repository of benchmarks.
+
+
+Deeper in Rally:
+----------------
 .. toctree::
    :maxdepth: 3
 
-   deploy
+   overview
+   concepts
+   deploy_engines
+   server_providers
    verify
-   benchmark
+   installation
+   usage
+
+Development information:
+------------------------
+
+.. toctree::
+   :maxdepth: 3
+
    cmds
    implementation
-
+   improve_rally
+   rally_gatejob
 
 Indices and tables
 ------------------