Explained KEYSTONE_SERVICE_PROJECT_NAME variable

The objective is to make it more explicit that the 'service' project
is referring to the keystone service.
This changeset also updated the documentation to stay under the
limit of 80 per line.

Change-Id: I22430585e3e8999f27c2c2d48398a70298da9850

README.rst

@@ -2,13 +2,17 @@
 Watcher
 =======
 
-OpenStack Watcher provides a flexible and scalable resource optimization service for multi-tenant OpenStack-based clouds.
+OpenStack Watcher provides a flexible and scalable resource optimization
-Watcher provides a complete optimization loop—including everything from a metrics receiver, complex event processor and profiler,
+service for multi-tenant OpenStack-based clouds.
-optimization processor and an action plan applier. This provides a robust framework to realize a wide range of cloud optimization goals,
+Watcher provides a complete optimization loop—including everything from a
-including the reduction of data center operating costs, increased system performance via intelligent virtual machine migration, increased energy efficiency—and more!
+metrics receiver, complex event processor and profiler, optimization processor
+and an action plan applier. This provides a robust framework to realize a wide
+range of cloud optimization goals, including the reduction of data center
+operating costs, increased system performance via intelligent virtual machine
+migration, increased energy efficiency—and more!
 
 * Free software: Apache license
 * Wiki: http://wiki.openstack.org/wiki/Watcher
-* Source:  http://git.openstack.org/cgit/openstack/watcher
+* Source:  https://github.com/openstack/watcher
 * Bugs: http://bugs.launchpad.net/watcher
 * Documentation: https://factory.b-com.com/www/watcher/doc/watcher/index.html

doc/source/deploy/configuration.rst

@@ -10,37 +10,39 @@ available code of the Watcher service.
 Service overview
 ================
 
-The Watcher service is a collection of modules that provides support to
+The Watcher system is a collection of services that provides support to
-optimize your IAAS plateform. The Watcher service may, depending
+optimize your IAAS plateform. The Watcher service may, depending upon
-upon configuration, interact with several other OpenStack services. This
+configuration, interact with several other OpenStack services. This includes:
-includes:
 
-- the OpenStack Identity service (`keystone`_) for request authentication and to
+- the OpenStack Identity service (`keystone`_) for request authentication and
-  locate other OpenStack services
+  to locate other OpenStack services
-- the OpenStack Telemetry module (`ceilometer`_) for consuming the resources metrics
+- the OpenStack Telemetry service (`ceilometer`_) for consuming the resources
-- the OpenStack Compute service (`nova`_) works with the Watcher service and acts as
+  metrics
-  a user-facing API for instance migration.
+- the OpenStack Compute service (`nova`_) works with the Watcher service and
+  acts as a user-facing API for instance migration.
 
 The Watcher service includes the following components:
 
-- ``watcher-decision-engine``: runs audit on part of your IAAS and return an action plan in order to optimize resource placement.
+- ``watcher-decision-engine``: runs audit on part of your IAAS and return an
+  action plan in order to optimize resource placement.
 - ``watcher-api``: A RESTful API that processes application requests by sending
   them to the watcher-decision-engine over RPC.
 - ``watcher-applier``: applies the action plan.
 - `python-watcherclient`_: A command-line interface (CLI) for interacting with
   the Watcher service.
 
-Additionally, the Bare Metal service has certain external dependencies, which are
+Additionally, the Bare Metal service has certain external dependencies, which
-very similar to other OpenStack services:
+are very similar to other OpenStack services:
 
-- A database to store audit and action plan information and state. You can set the database
+- A database to store audit and action plan information and state. You can set
-  back-end type and location.
+  the database back-end type and location.
 - A queue. A central hub for passing messages, such as `RabbitMQ`_.
 
 Optionally, one may wish to utilize the following associated projects for
 additional functionality:
 
-- `watcher metering`_: an alternative of Ceilometer project to collect real-time metering data.
+- `watcher metering`_: an alternative to collect and push metrics to the
+  Telemetry service.
 
 .. _`keystone`: https://github.com/openstack/keystone
 .. _`ceilometer`: https://github.com/openstack/ceilometer
@@ -52,35 +54,42 @@ additional functionality:
 Install and configure prerequisites
 ===================================
 
-You can configure Watcher modules to run on separate nodes or the same node.
+You can configure Watcher services to run on separate nodes or the same node.
 In this guide, the components run on one node, typically the Controller node.
 
-This section shows you how to install and configure the modules.
+This section shows you how to install and configure the services.
 
 It assumes that the Identity, Image, Compute, and Networking services
 have already been set up.
 
-
+.. _identity-service_configuration:
 
 Configure the Identity service for the Watcher service
 ------------------------------------------------------
 
 #. Create the Watcher service user (eg ``watcher``). The service uses this to
-   authenticate with the Identity Service. Use the ``service`` project and
+   authenticate with the Identity Service. Use the
-   give the user the ``admin`` role:
+   ``KEYSTONE_SERVICE_PROJECT_NAME`` project (named ``service`` by default in
+   devstack) and give the user the ``admin`` role:
 
     .. code-block:: bash
 
-      $ keystone user-create --name=watcher --pass=WATCHER_PASSWORD --email=watcher@example.com
+      $ keystone user-create --name=watcher --pass=WATCHER_PASSWORD \
-      $ keystone user-role-add --user=watcher --tenant=service --role=admin
+        --email=watcher@example.com \
+        --tenant=KEYSTONE_SERVICE_PROJECT_NAME
+      $ keystone user-role-add --user=watcher \
+        --tenant=KEYSTONE_SERVICE_PROJECT_NAME --role=admin
       $ keystone user-role-add --user=watcher --tenant=admin --role=admin
 
    or (by using python-openstackclient 1.8.0+)
 
      .. code-block:: bash
 
-      $ openstack user create  --password WATCHER_PASSWORD --enable --email watcher@example.com watcher
+      $ openstack user create  --password WATCHER_PASSWORD --enable \
-      $ openstack role add --project service --user watcher admin
+        --email watcher@example.com watcher \
+        --project=KEYSTONE_SERVICE_PROJECT_NAME
+      $ openstack role add --project KEYSTONE_SERVICE_PROJECT_NAME \
+        --user watcher admin
       $ openstack role add --user watcher --project admin admin
 
 
@@ -96,10 +105,11 @@ Configure the Identity service for the Watcher service
 
     .. code-block:: bash
 
-      $ openstack service create --name watcher infra-optim
+      $ openstack service create --name watcher infra-optim \
+        --description="Infrastructure Optimization service"
 
 #. Create the endpoints by replacing YOUR_REGION and
-   WATCHER_API_[PUBLIC|ADMIN|INTERNAL]_IP with your region and your
+   ``WATCHER_API_[PUBLIC|ADMIN|INTERNAL]_IP`` with your region and your
    Watcher Service's API node IP addresses (or FQDN):
 
     .. code-block:: bash
@@ -119,6 +129,8 @@ Configure the Identity service for the Watcher service
         --internalurl http://WATCHER_API_INTERNAL_IP:9322 \
         --adminurl http://WATCHER_API_ADMIN_IP:9322
 
+.. _watcher-db_configuration:
+
 Set up the database for Watcher
 -------------------------------
 
@@ -153,10 +165,7 @@ The configuration file is organized into the following sections:
 * ``[watcher_applier]`` - Watcher Applier module configuration
 * ``[watcher_decision_engine]`` - Watcher Decision Engine module configuration
 * ``[watcher_goals]`` - Goals mapping configuration
-* ``[watcher_influxdb_collector]`` - influxDB driver configuration
 * ``[watcher_messaging]`` -Messaging driver configuration
-* ``[watcher_metrics_collector]`` - Metric collector driver configuration
-* ``[watcher_metrics_collector]`` - Metric collector driver configuration
 * ``[watcher_strategies]`` - Strategy configuration
 
 
@@ -173,8 +182,8 @@ configuration file, in order:
 
 
 Although some configuration options are mentioned here, it is recommended that
-you review all the
+you review all the `available options
-`available options <https://git.openstack.org/cgit/openstack/watcher/tree/etc/watcher/watcher.conf.sample>`_
+<https://git.openstack.org/cgit/openstack/watcher/tree/etc/watcher/watcher.conf.sample>`_
 so that the watcher service is configured for your needs.
 
 #. The Watcher Service stores information in a database. This guide uses the
@@ -202,7 +211,7 @@ so that the watcher service is configured for your needs.
     # The name of the driver used by oslo messaging (string value)
     #notifier_driver = messaging
 
-    # The name of a message executor, forexample: eventlet, blocking
+    # The name of a message executor, for example: eventlet, blocking
     # (string value)
     #executor = blocking
 
@@ -230,13 +239,6 @@ so that the watcher service is configured for your needs.
    replace WATCHER_PASSWORD with the password you chose for the ``watcher``
    user in the Identity Service::
 
-    [DEFAULT]
-    ...
-    # Method to use for authentication: noauth or keystone.
-    # (string value)
-    auth_strategy=keystone
-
-    ...
     [keystone_authtoken]
 
     # Complete public Identity API endpoint (string value)
@@ -277,7 +279,8 @@ so that the watcher service is configured for your needs.
 Configure Nova compute
 ======================
 
-Please check your hypervisor configuration to correctly handle `instance migration`_.
+Please check your hypervisor configuration to correctly handle
+`instance migration`_.
 
 .. _`instance migration`: http://docs.openstack.org/admin-guide-cloud/compute-configuring-migrations.html
 

doc/source/deploy/installation.rst

@@ -14,7 +14,8 @@ packages, instead using the source for the code and the Python Package Index
 
 .. _PyPi: http://pypi.python.org/pypi
 
-It's expected that your system already has python2.7_, latest version of pip_, and git_ available.
+It's expected that your system already has python2.7_, latest version of pip_,
+and git_ available.
 
 .. _python2.7: http://www.python.org
 .. _pip: http://www.pip-installer.org/en/latest/installing.html
@@ -28,7 +29,8 @@ Your system shall also have some additional system libraries:
 
     $ sudo apt-get install python-dev libssl-dev libmysqlclient-dev libffi-dev
 
-  On Fedora-based distributions e.g., Fedora/RHEL/CentOS/Scientific Linux (tested on CentOS 7.1):
+  On Fedora-based distributions e.g., Fedora/RHEL/CentOS/Scientific Linux
+  (tested on CentOS 7.1):
 
   .. code-block:: bash
 
@@ -54,11 +56,12 @@ Install the Watcher modules:
 The following commands should be available on the command-line path:
 
 * ``watcher-api`` the Watcher Web service used to handle RESTful requests
-* ``watcher-decision-engine`` the Watcher Decision Engine used to build action plans, according to optimization goals to achieve.
+* ``watcher-decision-engine`` the Watcher Decision Engine used to build action
+  plans, according to optimization goals to achieve.
 * ``watcher-applier`` the Watcher Applier module, used to apply action plan
 * ``watcher-db-manage`` used to bootstrap Watcher data
 
-You will find sample configuration files in ``etc/``:
+You will find sample configuration files in ``etc/watcher``:
 
 * ``watcher.conf.sample``
 
@@ -68,7 +71,9 @@ Install the Watcher modules dependencies:
 
     # pip install -r requirements.txt
 
-From here, refer to :doc:`configuration` to declare Watcher as a new service into Keystone and to configure its different modules. Once configured, you should be able to run Watcher by issuing these commands:
+From here, refer to :doc:`configuration` to declare Watcher as a new service
+into Keystone and to configure its different modules. Once configured, you
+should be able to run the Watcher services by issuing these commands:
 
 .. code-block:: bash
 
@@ -84,13 +89,16 @@ Once started, you can use the `Watcher Client`_ to play with Watcher service.
 Installing from packages: PyPI
 --------------------------------
 
-Watcher package is available on PyPI repository. To install Watcher on your system
+Watcher package is available on PyPI repository. To install Watcher on your
-:
+system:
 
 .. code-block:: bash
 
     $ sudo pip install python-watcher
 
-Watcher modules and its dependencies will be automatically installed on your system.
+The Watcher services along with its dependencies should then be automatically
+installed on your system.
 
-Once installed, you still need to declare Watcher as a new service into Keystone and to configure its different modules, which you can find described in :doc:`configuration`.
+Once installed, you still need to declare Watcher as a new service into
+Keystone and to configure its different modules, which you can find described
+in :doc:`configuration`.

doc/source/deploy/user-guide.rst

@@ -4,15 +4,19 @@
 Welcome to the Watcher User Guide
 =================================
 
-In the `architecture <https://wiki.openstack.org/wiki/WatcherArchitecture>`_ you got information about how it works.
+In the `architecture <https://wiki.openstack.org/wiki/WatcherArchitecture>`_
-In this guide we're going to take you through the fundamentals of using Watcher.
+you got information about how it works.
+In this guide we're going to take you through the fundamentals of using
+Watcher.
 
 
 Getting started with Watcher
 ----------------------------
-This guide assumes you have a working installation of Watcher. If you get "*watcher: command not found*" you may have to verify your installation.
+This guide assumes you have a working installation of Watcher. If you get
-Please refer to installation guide.
+"*watcher: command not found*" you may have to verify your installation.
-In order to use Watcher, you have to configure your credentials suitable for watcher command-line tools.
+Please refer to the :doc:`installation guide <installation>`.
+In order to use Watcher, you have to configure your credentials suitable for
+watcher command-line tools.
 If you need help on a specific command, you can use:
 
 .. code:: bash
@@ -21,7 +25,8 @@ If you need help on a specific command, you can use:
 
 Seeing what the Watcher CLI can do ?
 ------------------------------------
-We can see all of the commands available with Watcher CLI by running the watcher binary without options.
+We can see all of the commands available with Watcher CLI by running the
+watcher binary without options.
 
 .. code:: bash
 
@@ -30,57 +35,74 @@ We can see all of the commands available with Watcher CLI by running the watcher
 How do I run an audit of my cluster ?
 -------------------------------------
 
-First, you need to create an audit template. An audit template defines an optimization goal to achieve (i.e. the settings of your audit).
+First, you need to create an :ref:`audit template <audit_template_definition>`.
-This goal should be declared in the Watcher service configuration file **/etc/watcher/watcher.conf**.
+An :ref:`audit template <audit_template_definition>` defines an optimization
+:ref:`goal <goal_definition>` to achieve (i.e. the settings of your audit).
+This goal should be declared in the Watcher service configuration file
+**/etc/watcher/watcher.conf**.
 
 .. code:: bash
 
   $ watcher audit-template-create my_first_audit SERVERS_CONSOLIDATION
 
-If you get "*You must provide a username via either --os-username or via env[OS_USERNAME]*" you may have to verify your credentials
+If you get "*You must provide a username via either --os-username or via
+env[OS_USERNAME]*" you may have to verify your credentials.
 
-Then, you can create an audit. An audit is a request for optimizing your cluster depending on the specified goal.
+Then, you can create an audit. An audit is a request for optimizing your
+cluster depending on the specified :ref:`goal <goal_definition>`.
 
-You can launch an audit on your cluster by referencing the audit template (i.e. the settings of your audit) that you want to use.
+You can launch an audit on your cluster by referencing the
+:ref:`audit template <audit_template_definition>` (i.e. the settings of your
+audit) that you want to use.
 
-- Get the audit template UUID:
+- Get the :ref:`audit template <audit_template_definition>` UUID:
 
 .. code:: bash
 
   $ watcher audit-template-list
 
-- Start an audit based on this audit template settings:
+- Start an audit based on this :ref:`audit template
+  <audit_template_definition>` settings:
 
 .. code:: bash
 
   $ watcher audit-create -a <your_audit_template_uuid>
 
 
-Watcher service will compute an Action Plan composed of a list of potential optimization actions (instance migration, disabling of an hypervisor, ...) according to the goal to achieve.
+Watcher service will compute an :ref:`Action Plan <action_plan_definition>`
-You can see all of the goals available in section ``[watcher_strategies]`` of the Watcher service configuration file.
+composed of a list of potential optimization :ref:`actions <action_definition>`
+(instance migration, disabling of an hypervisor, ...) according to the
+:ref:`goal <goal_definition>` to achieve. You can see all of the goals
+available in section ``[watcher_strategies]`` of the Watcher service
+configuration file.
 
-- Wait until the Watcher audit has produced a new action plan, and get it:
+- Wait until the Watcher audit has produced a new :ref:`action plan
+  <action_plan_definition>`, and get it:
 
 .. code:: bash
 
   $ watcher action-plan-list --audit <the_audit_uuid>
 
-- Have a look on the list of optimization actions contained in this new action plan:
+- Have a look on the list of optimization :ref:`actions <action_definition>`
+contained in this new :ref:`action plan <action_plan_definition>`:
 
 .. code:: bash
 
   $ watcher action-list --action-plan <the_action_plan_uuid>
 
 
-Once you've learned how to create an Action Plan, it's time to go further by applying it to your cluster:
+Once you have learned how to create an :ref:`Action Plan
+<action_plan_definition>`, it's time to go further by applying it to your
+cluster:
 
-- Execute the action plan:
+- Execute the :ref:`action plan <action_plan_definition>`:
 
 .. code:: bash
 
   $ watcher action-plan-start <the_action_plan_uuid>
 
-You can follow the states of the actions by calling periodically:
+You can follow the states of the :ref:`actions <action_definition>` by
+periodically calling:
 
 .. code:: bash
 
@@ -91,5 +113,3 @@ You can also obtain more detailed information about a specific action:
 .. code:: bash
 
   $ watcher action-show <the_action_uuid>
-
-

doc/source/dev/environment.rst

@@ -16,7 +16,8 @@ Documentation`_.
 Prerequisites
 =============
 
-This document assumes you are using Ubuntu or Fedora, and that you have the following tools available on your system:
+This document assumes you are using Ubuntu or Fedora, and that you have the
+following tools available on your system:
 
 - Python_ 2.7 and 3.4
 - git_
@@ -56,7 +57,9 @@ Watcher maintains two lists of dependencies::
     requirements.txt
     test-requirements.txt
 
-The first is the list of dependencies needed for running Watcher, the second list includes dependencies used for active development and testing of Watcher itself.
+The first is the list of dependencies needed for running Watcher, the second
+list includes dependencies used for active development and testing of Watcher
+itself.
 
 These dependencies can be installed from PyPi_ using the Python tool pip_.
 
@@ -142,7 +145,9 @@ If you can import watcher without a traceback, you should be ready to develop.
 
 Run Watcher unit tests
 ======================
-All unit tests should be run using tox. To run the unit tests under py27 and also run the pep8 tests:
+
+All unit tests should be run using tox. To run the unit tests under py27 and
+also run the pep8 tests:
 
 .. code-block:: bash
 
@@ -152,7 +157,9 @@ All unit tests should be run using tox. To run the unit tests under py27 and als
     (watcher) $ cd watcher
     (watcher) $ tox -epep8 -epy27
 
-You may pass options to the test programs using positional arguments. To run a specific unit test, this passes the -r option and desired test (regex string) to os-testr:
+You may pass options to the test programs using positional arguments. To run a
+specific unit test, this passes the -r option and desired test (regex string)
+to os-testr:
 
 .. code-block:: bash
 
@@ -167,7 +174,9 @@ When you're done, deactivate the virtualenv:
 
 Build the Watcher documentation
 ===============================
-you can easily build the HTML documentation from ``doc/source`` files, by using tox:
+
+You can easily build the HTML documentation from ``doc/source`` files, by using
+``tox``:
 
 .. code-block:: bash
 
@@ -179,19 +188,37 @@ you can easily build the HTML documentation from ``doc/source`` files, by using
 The HTML files are available into ``doc/build`` directory.
 
 
-Configure the Watcher modules
+Configure the Watcher services
-=============================
+==============================
-Watcher modules requires a configuration file. There is a sample configuration file that can be used to get started:
+
+Watcher services require a configuration file. There is a sample configuration
+file that can be used to get started:
 
 .. code-block:: bash
 
   $ cp etc/watcher.conf.sample etc/watcher.conf
 
-The defaults are enough to get you going, but you can make any changes if needed.
+Most of the default configuration should be enough to get you going, but you
+still need to configure the following sections:
+
+- The ``[database]`` section to configure the
+  :ref:`Watcher database <watcher-db_configuration>`
+- The  ``[keystone_authtoken]`` section to configure the
+  :ref:`Identity service <identity-service_configuration>` i.e. Keystone
+- The ``[watcher_messaging]`` section to configure the OpenStack AMQP-based
+  message bus
+
+So if you need some more details on how to configure one or more of these
+sections, please do have a look at :doc:`../deploy/configuration` before
+continuing.
+
 
 Create Watcher SQL database
 ===========================
-When initially getting set up, after you've configured which databases to use, you're probably going to need to run the following to your database schema in place:
+
+When initially getting set up, after you've configured which databases to use,
+you're probably going to need to run the following to your database schema in
+place:
 
 .. code-block:: bash
 
@@ -199,9 +226,11 @@ When initially getting set up, after you've configured which databases to use, y
 
     (watcher) $ watcher-db-manage --create_schema
 
-Running Watcher modules
+
-=======================
+Running Watcher services
-To run Watcher API server instance, use:
+========================
+
+To run the Watcher API service, use:
 
 .. code-block:: bash
 
@@ -209,7 +238,7 @@ To run Watcher API server instance, use:
 
     (watcher) $ watcher-api
 
-To run Watcher Decision Engine instance, use:
+To run the Watcher Decision Engine service, use:
 
 .. code-block:: bash
 
@@ -217,7 +246,7 @@ To run Watcher Decision Engine instance, use:
 
     (watcher) $ watcher-decision-engine
 
-To run Watcher Applier instance, use:
+To run the Watcher Applier service, use:
 
 .. code-block:: bash
 
@@ -225,24 +254,33 @@ To run Watcher Applier instance, use:
 
     (watcher) $ watcher-applier
 
-Default configuration of these modules are available into ``/etc/watcher`` directory. See :doc:`../deploy/configuration` for details on how Watcher is configured. By default, Watcher is configured with SQL backends.
+Default configuration of these services are available into ``/etc/watcher``
+directory. See :doc:`../deploy/configuration` for details on how Watcher is
+configured. By default, Watcher is configured with SQL backends.
 
 
 Interact with Watcher
 =====================
 
-You can also interact with Watcher through its REST API. There is a Python Watcher client library `python-watcherclient`_ which interacts exclusively through the REST API, and which Watcher itself uses to provide its command-line interface.
+You can also interact with Watcher through its REST API. There is a Python
-
+Watcher client library `python-watcherclient`_ which interacts exclusively
-When initially getting set up, after you've configured which databases to use, you're probably going to need to run the following to your database schema in place:
+through the REST API, and which Watcher itself uses to provide its command-line
+interface.
 
 .. _`python-watcherclient`: https://github.com/openstack/python-watcherclient
 
-Exercising the Watcher Services Locally
+
+Exercising the Watcher Services locally
 =======================================
 
-If you would like to exercise the Watcher services in isolation within a local virtual environment, you can do this without starting any other OpenStack services. For example, this is useful for rapidly prototyping and debugging interactions over the RPC channel, testing database migrations, and so forth.
+If you would like to exercise the Watcher services in isolation within a local
+virtual environment, you can do this without starting any other OpenStack
+services. For example, this is useful for rapidly prototyping and debugging
+interactions over the RPC channel, testing database migrations, and so forth.
 
-You will find in the `watcher-tools`_ project, Ansible playbooks and Docker template files to easily play with Watcher modules within a minimal OpenStack isolated environment (Identity, Message Bus, SQL database, Horizon, ...).
+You will find in the `watcher-tools`_ project, Ansible playbooks and Docker
+template files to easily play with Watcher services within a minimal OpenStack
+isolated environment (Identity, Message Bus, SQL database, Horizon, ...).
 
 .. _`watcher-tools`: https://github.com/b-com/watcher-tools
 

doc/source/index.rst

@@ -5,7 +5,8 @@ Welcome to Watcher's developer documentation
 Mission
 =======
 
-Provide an auditing service for OpenStack to improve workload placement on-the-go.
+Provide an auditing service for OpenStack to improve workload placement
+on-the-go.
 
 The developer documentation provided here is continually kept up-to-date based
 on the latest code, and may not represent the state of the project at any
@@ -21,6 +22,7 @@ Introduction
   :maxdepth: 1
 
   dev/architecture
+  dev/environment
   dev/contributing
   dev/plugins