Arnike/watcher
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Explained KEYSTONE_SERVICE_PROJECT_NAME variable

Browse Source 
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
This commit is contained in:
Vincent Françoise
2015-11-17 17:40:55 +01:00
parent a809b8d52c
commit 5107345c93
6 changed files with 174 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
doc/source/deploy/configuration.rst
View File

@@ -10,37 +10,39 @@ available code of the Watcher service.
Service overview
================
The Watcher service is a collection of modules that provides support to
optimize your IAAS plateform. The Watcher service may, depending
upon configuration, interact with several other OpenStack services. This
includes:
The Watcher system is a collection of services that provides support to
optimize your IAAS plateform. The Watcher service may, depending upon
configuration, interact with several other OpenStack services. This includes:
- the OpenStack Identity service (`keystone`_) for request authentication and to
locate other OpenStack services
- the OpenStack Telemetry module (`ceilometer`_) for consuming the resources metrics
- the OpenStack Compute service (`nova`_) works with the Watcher service and acts as
a user-facing API for instance migration.
- the OpenStack Identity service (`keystone`_) for request authentication and
to locate other OpenStack services
- the OpenStack Telemetry service (`ceilometer`_) for consuming the resources
metrics
- 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
very similar to other OpenStack services:
Additionally, the Bare Metal service has certain external dependencies, which
are very similar to other OpenStack services:
- A database to store audit and action plan information and state. You can set the database
back-end type and location.
- A database to store audit and action plan information and state. You can set
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
give the user the ``admin`` role:
authenticate with the Identity Service. Use the
``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-role-add --user=watcher --tenant=service --role=admin
$ keystone user-create --name=watcher --pass=WATCHER_PASSWORD \
--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 role add --project service --user watcher admin
$ openstack user create --password WATCHER_PASSWORD --enable \
--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
`available options <https://git.openstack.org/cgit/openstack/watcher/tree/etc/watcher/watcher.conf.sample>`_
you review all the `available options
<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

26
doc/source/deploy/installation.rst
View File

@@ -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`.

64
doc/source/deploy/user-guide.rst
View File

@@ -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 this guide we're going to take you through the fundamentals of using Watcher.
In the `architecture <https://wiki.openstack.org/wiki/WatcherArchitecture>`_
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.
Please refer to installation guide.
In order to use Watcher, you have to configure your credentials suitable for watcher command-line tools.
This guide assumes you have a working installation of Watcher. If you get
"*watcher: command not found*" you may have to verify your installation.
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).
This goal should be declared in the Watcher service configuration file **/etc/watcher/watcher.conf**.
First, you need to create an :ref:`audit template <audit_template_definition>`.
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.
You can see all of the goals available in section ``[watcher_strategies]`` of the Watcher service configuration file.
Watcher service will compute an :ref:`Action Plan <action_plan_definition>`
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>