<commit_before>..

===================
Configuring Watcher
===================

This document is continually updated and reflects the latest
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 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 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-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:

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

.. _`keystone`: https://github.com/openstack/keystone
.. _`ceilometer`: https://github.com/openstack/ceilometer
.. _`nova`: https://github.com/openstack/nova
.. _`python-watcherclient`: https://github.com/openstack/python-watcherclient
.. _`watcher metering`: https://github.com/b-com/watcher-metering
.. _`RabbitMQ`: https://www.rabbitmq.com/

Install and configure prerequisites
===================================

You can configure Watcher modules 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.

It assumes that the Identity, Image, Compute, and Networking services
have already been set up.



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:

    .. code-block:: bash

      $ keystone user-create --name=watcher --pass=<PASSWORD> --email=<EMAIL>
      $ keystone user-role-add --user=watcher --tenant=service --role=admin
      $ keystone user-role-add --user=watcher --tenant=admin --role=admin

   or

     .. code-block:: bash

      $ openstack user create  --password <PASSWORD> --enable --email <EMAIL> watcher
      $ openstack role add --project services --user watcher admin
      $ openstack role add --user watcher --project admin admin


#. You must register the Watcher Service with the Identity Service so that
   other OpenStack services can locate it. To register the service:

    .. code-block:: bash

      $ keystone service-create --name=watcher --type=infra-optim \
        --description="Infrastructure Optimization service"

   or

    .. code-block:: bash

      $ openstack service create --name watcher infra-optim

#. Create the endpoints by replacing YOUR_REGION and WATCHER_API_IP with your region and your
   Watcher Service's API node IP address (or FQDN):

    .. code-block:: bash

      $ keystone endpoint-create \
      --service-id=the_service_id_above \
      --publicurl=http://WATCHER_API_IP:9322 \
      --internalurl=http://WATCHER_API_IP:9322 \
      --adminurl=http://WATCHER_API_IP:9322

  or

    .. code-block:: bash

      $ openstack endpoint create --region YOUR_REGION watcher public http://WATCHER_API_IP:9322
      $ openstack endpoint create --region YOUR_REGION watcher admin http://WATCHER_API_IP:9322
      $ openstack endpoint create --region YOUR_REGION watcher internal http://WATCHER_API_IP:9322

Set up the database for Watcher
-------------------------------

The Watcher service stores information in a database. This guide uses the
MySQL database that is used by other OpenStack services.

#. In MySQL, create a ``watcher`` database that is accessible by the
   ``watcher`` user. Replace WATCHER_DBPASSWORD
   with the actual password::

    $ mysql -u root -p

    mysql> CREATE DATABASE watcher CHARACTER SET utf8;
    mysql> GRANT ALL PRIVILEGES ON watcher.* TO 'watcher'@'localhost' \
    IDENTIFIED BY 'WATCHER_DBPASSWORD';
    mysql> GRANT ALL PRIVILEGES ON watcher.* TO 'watcher'@'%' \
    IDENTIFIED BY 'WATCHER_DBPASSWORD';


Configure the Watcher service
=============================

The Watcher service is configured via its configuration file. This file
is typically located at ``/etc/watcher/watcher.conf``.

The configuration file is organized into the following sections:

* ``[DEFAULT]`` - General configuration
* ``[api]`` - API server configuration
* ``[database]`` - SQL driver configuration
* ``[keystone_authtoken]`` - Keystone Authentication plugin configuration
* ``[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


The Watcher configuration file is expected to be named
``watcher.conf``. When starting Watcher, you can specify a different
configuration file to use with ``--config-file``. If you do **not** specify a
configuration file, Watcher will look in the following directories for a
configuration file, in order:

* ``~/.watcher/``
* ``~/``
* ``/etc/watcher/``
* ``/etc/``


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>`_<commit_msg>Use a single command to create the 3 watcher endpoints.<commit_after>..

===================
Configuring Watcher
===================

This document is continually updated and reflects the latest
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 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 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-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:

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

.. _`keystone`: https://github.com/openstack/keystone
.. _`ceilometer`: https://github.com/openstack/ceilometer
.. _`nova`: https://github.com/openstack/nova
.. _`python-watcherclient`: https://github.com/openstack/python-watcherclient
.. _`watcher metering`: https://github.com/b-com/watcher-metering
.. _`RabbitMQ`: https://www.rabbitmq.com/

Install and configure prerequisites
===================================

You can configure Watcher modules 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.

It assumes that the Identity, Image, Compute, and Networking services
have already been set up.



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:

    .. code-block:: bash

      $ keystone user-create --name=watcher --pass=<PASSWORD> --email=<EMAIL>
      $ keystone user-role-add --user=watcher --tenant=service --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 <PASSWORD> --enable --email <EMAIL> watcher
      $ openstack role add --project services --user watcher admin
      $ openstack role add --user watcher --project admin admin


#. You must register the Watcher Service with the Identity Service so that
   other OpenStack services can locate it. To register the service:

    .. code-block:: bash

      $ keystone service-create --name=watcher --type=infra-optim \
        --description="Infrastructure Optimization service"

   or (by using python-openstackclient 1.8.0+)

    .. code-block:: bash

      $ openstack service create --name watcher infra-optim

#. Create the endpoints by replacing YOUR_REGION and
   WATCHER_API_[PUBLIC|ADMIN|INTERNAL]_IP with your region and your
   Watcher Service's API node IP addresses (or FQDN):

    .. code-block:: bash

      $ keystone endpoint-create \
      --service-id=the_service_id_above \
      --publicurl=http://WATCHER_API_PUBLIC_IP:9322 \
      --internalurl=http://WATCHER_API_INTERNAL_IP:9322 \
      --adminurl=http://WATCHER_API_ADMIN_IP:9322

   or (by using python-openstackclient 1.8.0+)

    .. code-block:: bash

      $ openstack endpoint create --region YOUR_REGION watcher \
        --publicurl http://WATCHER_API_PUBLIC_IP:9322 \
        --internalurl http://WATCHER_API_INTERNAL_IP:9322 \
        --adminurl http://WATCHER_API_ADMIN_IP:9322

Set up the database for Watcher
-------------------------------

The Watcher service stores information in a database. This guide uses the
MySQL database that is used by other OpenStack services.

#. In MySQL, create a ``watcher`` database that is accessible by the
   ``watcher`` user. Replace WATCHER_DBPASSWORD
   with the actual password::

    $ mysql -u root -p

    mysql> CREATE DATABASE watcher CHARACTER SET utf8;
    mysql> GRANT ALL PRIVILEGES ON watcher.* TO 'watcher'@'localhost' \
    IDENTIFIED BY 'WATCHER_DBPASSWORD';
    mysql> GRANT ALL PRIVILEGES ON watcher.* TO 'watcher'@'%' \
    IDENTIFIED BY 'WATCHER_DBPASSWORD';


Configure the Watcher service
=============================

The Watcher service is configured via its configuration file. This file
is typically located at ``/etc/watcher/watcher.conf``.

The configuration file is organized into the following sections:

* ``[DEFAULT]`` - General configuration
* ``[api]`` - API server configuration
* ``[database]`` - SQL driver configuration
* ``[keystone_authtoken]`` - Keystone Authentication plugin configuration
* ``[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


The Watcher configuration file is expected to be named
``watcher.conf``. When starting Watcher, you can specify a different
configuration file to use with ``--config-file``. If you do **not** specify a
configuration file, Watcher will look in the following directories for a
configuration file, in order:

* ``~/.watcher/``
* ``~/``
* ``/etc/watcher/``
* ``/etc/``


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>`_
{'fraction_non_alphanumeric': 0.11910818494688015, 'fraction_numerical': 0.004489001945234176, 'mean_word_length': 3.864264919941776, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 19, 'https://': 14, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5812961', 'n_tokens_mistral': 3784, 'n_tokens_neox': 3547, 'n_words': 1404}