update documentation
Change-Id: I0a3dd67587ac0c78cd9f2a77aee1fe1b917c5f4a
This commit is contained in:
Jean-Emile DARTOIS
170
doc/source/deploy/install-devstack-docker.rst
Normal file
170
doc/source/deploy/install-devstack-docker.rst
Normal file
@@ -0,0 +1,170 @@
|
||||
.. _install-devstack-docker:
|
||||
|
||||
Watcher Installation
|
||||
====================
|
||||
|
||||
To test Watcher, you can deploy it next to DevStack and run Watcher in a Docker environment. Watcher image containers integrate automatic provisioning scripts to simplify installation and configuration. You can install DevStack and Docker tools on the same machine.
|
||||
|
||||
You have to be familiar with Docker and its *docker-compose* orchestration tool.
|
||||
|
||||
|
||||
Install devstack
|
||||
----------------
|
||||
|
||||
If you need to install DevStack, you can refer to this page :
|
||||
`DevStack - an OpenStack Community Production <http://docs.openstack.org/developer/devstack/>`_
|
||||
|
||||
::
|
||||
|
||||
$ git clone clone https://git.openstack.org/openstack-dev/devstack
|
||||
$ cd devstack; ./stack.sh
|
||||
|
||||
Install docker & docker compose
|
||||
-------------------------------
|
||||
|
||||
To install Docker, you can refer to this page : `Supported installation <https://docs.docker.com/installation/>`_ and choose your distribution.
|
||||
|
||||
1. On Ubuntu simply do::
|
||||
|
||||
$ sudo apt-get install curl
|
||||
$ curl -sSL https://get.docker.com | sh
|
||||
|
||||
2. To test your installation::
|
||||
|
||||
$ sudo docker run hello-world
|
||||
|
||||
|
||||
To install Docker compose, you can refer to this page: `Install Docker Compose <https://docs.docker.com/compose/install/>`_
|
||||
|
||||
::
|
||||
|
||||
$ curl -L https://github.com/docker/compose/releases/download/1.4.0/docker-compose-)\`uname -s\`-\`uname -m\` \> /usr/local/bin/docker-compose
|
||||
$ chmod +x /usr/local/bin/docker-compose
|
||||
|
||||
|
||||
Watcher containers
|
||||
------------------
|
||||
|
||||
Containers orchestration templating is composed of 3 groups of containers, each group are independent:
|
||||
|
||||
- SERVICE_DISCOVERY : containers providing an automatic service discovery tool, based on
|
||||
- `consul <https://github.com/hashicorp/consul>`_
|
||||
- `registrator <https://github.com/gliderlabs/registrator>`_
|
||||
|
||||
- WATCHER : containers providing a basic OpenStack identity Service and the Watcher modules (including Horizon plugin)
|
||||
- mariadb,
|
||||
- rabbitmq,
|
||||
- keystone,
|
||||
- console,
|
||||
- watcher-api,
|
||||
- watcher-decision-engine,
|
||||
- watcher-applier,
|
||||
- horizon
|
||||
|
||||
- METERING: containers providing a complete metering chain for Watcher.
|
||||
- riemann,
|
||||
- influxdb,
|
||||
- nanoconfig-server,
|
||||
- watcher-metering-publisher,
|
||||
- watcher-metering-agent,
|
||||
- grafana
|
||||
|
||||
|
||||
Install the Service Discovery tool
|
||||
----------------------------------
|
||||
|
||||
1. Upload the Watcher orchestration template files::
|
||||
|
||||
$ git clone https://github.com/b-com/watcher-tools.git
|
||||
|
||||
|
||||
2. Deploy the containers::
|
||||
|
||||
$ cd docker/service-discovery
|
||||
$ docker-compose up -d
|
||||
|
||||
Install the Watcher module
|
||||
--------------------------
|
||||
|
||||
1. Customize the template file *docker-compose.yml*:
|
||||
- comment the *keystone* service (you will use the DevStack one)
|
||||
- comment the *mariadb* service if you want to use the DevStack db
|
||||
- comment the *rabbitmq* service if you want to use the DevStack RabbitMQ service
|
||||
- comment the *horizon* service if you don't want to use Horizon with the Watcher UI plugin
|
||||
|
||||
2. For all non commented services, don't forget to set environment variables in the template file *docker-compose.yml*:
|
||||
|
||||
- DevStack modules settings:
|
||||
|
||||
- **KEYSTONE_NODE**: DevStack Keystone IP address
|
||||
- **KEYSTONE_ADMIN_TOKEN**: DevStack Keystone admin token (default is *ADMIN_TOKEN*)
|
||||
- **KEYSTONE_SERVICE_TENANT_NAME**: DevStack service project name (default is *service*)
|
||||
- **MARIADB_NODE**: DevStack MySQL server IP address, if used.
|
||||
- **RABBITMQ_NODE**: DevStack RabbitMQ server IP address, if used
|
||||
|
||||
- Watcher modules:
|
||||
|
||||
- **DEBUG_MODE**: Debug mode (true|false, default is *false*)
|
||||
- **VERBOSE_MODE**: Verbose mode (true|false, default is *false*)
|
||||
|
||||
- Watcher console:
|
||||
|
||||
- **WATCHER_API_URL**: Watcher API endpoint (default is *http://watcher.service.watcher.b-com.com:9322*)
|
||||
- **EXIT_AFTER_INIT**: Watcher API endpoint (default is *http://watcher.service.watcher.b-com.com:9322*)
|
||||
|
||||
- *admin* user's credentials :
|
||||
|
||||
- **OS_AUTH_URL**: DevStack Keystone Identity Auth URL (default is *http://keystone.service.watcher.b-com.com:5000/v3*)
|
||||
- **OS_IDENTITY_API_VERSION**: DevStack Keystone Identity API Version (2.0|3, default is *3*)
|
||||
- **OS_PROJECT_DOMAIN_ID**: DevStack Project Domain ID (default is *default*)
|
||||
- **OS_USER_DOMAIN_ID**: DevStack User Domain ID (default is *default*)
|
||||
- **OS_USERNAME**: DevStack User name (default is *admin*)
|
||||
- **OS_PASSWORD**: DevStack User password (default is *1234*)
|
||||
- **OS_PROJECT_NAME**: DevStack Project name (default is *admin*)
|
||||
|
||||
|
||||
3. Deploy the containers::
|
||||
|
||||
$ cd docker/watcher
|
||||
$ docker-compose up -d
|
||||
|
||||
At startup the *console* container will automatically declare the watcher service into the DevStack Keystone Identity Service.
|
||||
|
||||
|
||||
4. Deploy the metering chain containers::
|
||||
|
||||
$ cd docker/metering
|
||||
$ docker-compose up -d
|
||||
|
||||
Note: you can deploy complete metering chain for development purpose within containers, but reminder that the Watcher Metering Agent should be deployed on real Compute Node to collect real metric data.
|
||||
|
||||
Run Watcher commands
|
||||
--------------------
|
||||
|
||||
You can use the *console* container to play with Watcher.
|
||||
|
||||
1. Connect to the Watcher console container::
|
||||
|
||||
$ docker ps
|
||||
|
||||
Get the *console* container ID and attach to it::
|
||||
|
||||
$ docker exec -it <watcher_console_container_ID> bash
|
||||
|
||||
::
|
||||
|
||||
root@console:/# cd /root
|
||||
root@console:/# source creds
|
||||
root@console:~# watcher audit-list
|
||||
+------+------+---------------------+-------+
|
||||
| UUID | Type | Audit Template Name | State |
|
||||
+------+------+---------------------+-------+
|
||||
+------+------+---------------------+-------+
|
||||
|
||||
|
||||
Important notes
|
||||
===============
|
||||
|
||||
Please check your Compute's hypervisor configuration to handle correctly instance migration:
|
||||
|
||||
`OpenStack - Configure Migrations <http://docs.openstack.org/admin-guide-cloud/compute-configuring-migrations.html>`_
|
||||
@@ -1,96 +1,68 @@
|
||||
.. _installation:
|
||||
|
||||
========================
|
||||
Development Installation
|
||||
========================
|
||||
Quick installation
|
||||
==================
|
||||
|
||||
Watcher development uses virtualenv to track and manage Python dependencies while in development and testing. This allows you to install all of the Python package dependencies in a virtual environment or “virtualenv”, instead of installing the packages at the system level.
|
||||
#. Install the prerequisite packages.
|
||||
|
||||
On Ubuntu (tested on 14.04-64)::
|
||||
|
||||
sudo apt-get install python-dev libssl-dev python-pip git-core libmysqlclient-dev libffi-dev
|
||||
|
||||
On Fedora-based distributions e.g., Fedora/RHEL/CentOS/Scientific Linux (tested on CentOS 6.5)::
|
||||
|
||||
sudo yum install python-virtualenv openssl-devel python-pip git gcc libffi-devel mysql-devel postgresql-devel
|
||||
|
||||
On openSUSE-based distributions (SLES 12, openSUSE 13.1, Factory or Tumbleweed)::
|
||||
|
||||
sudo zypper install gcc git libmysqlclient-devel libopenssl-devel postgresql-devel python-devel python-pip
|
||||
|
||||
Linux Systems
|
||||
-------------
|
||||
#. Install watcher modules from pip::
|
||||
|
||||
Install the prerequisite packages.
|
||||
|
||||
On Ubuntu (tested on 12.04-64 and 14.04-64)::
|
||||
|
||||
sudo apt-get install python-dev libssl-dev python-pip git-core libmysqlclient-dev libffi-dev
|
||||
|
||||
On Fedora-based distributions e.g., Fedora/RHEL/CentOS/Scientific Linux (tested on CentOS 6.5)::
|
||||
|
||||
sudo yum install python-virtualenv openssl-devel python-pip git gcc libffi-devel mysql-devel postgresql-devel
|
||||
|
||||
On openSUSE-based distributions (SLES 12, openSUSE 13.1, Factory or Tumbleweed)::
|
||||
|
||||
sudo zypper install gcc git libmysqlclient-devel libopenssl-devel postgresql-devel python-devel python-pip
|
||||
|
||||
|
||||
Manually installing and using the virtualenv
|
||||
--------------------------------------------
|
||||
|
||||
If you have `virtualenvwrapper <https://virtualenvwrapper.readthedocs.org/en/latest/install.html>`_ installed::
|
||||
|
||||
$ mkvirtualenv watcher
|
||||
$ git clone https://git.openstack.org/openstack/stackforge/watcher
|
||||
$ cd watcher && python setup.py install
|
||||
$ pip install -r ./requirements.txt
|
||||
|
||||
To run a specific test, use a positional argument for the unit tests::
|
||||
|
||||
# run a specific test for Python 2.7
|
||||
tox -epy27 -- tests.api
|
||||
|
||||
You may pass options to the test programs using positional arguments::
|
||||
|
||||
# run all the Python 2.7 unit tests (in parallel!)
|
||||
tox -epy27 -- --parallel
|
||||
|
||||
To run only the pep8/flake8 syntax and style checks::
|
||||
|
||||
tox -epep8
|
||||
sudo pip install python-watcher
|
||||
|
||||
Configure Watcher
|
||||
=================
|
||||
|
||||
Configure Identity Service for Watcher
|
||||
--------------------------------------
|
||||
|
||||
#. Create the Watcher service user (eg ``watcher``). The service uses this to
|
||||
authenticate with the Identity Service. Use the ``service`` project and
|
||||
#. Create the Watcher service user (eg ``watcher``) and set a password. The service uses it to
|
||||
authenticate with the Identity Service. Set KEYSTONE_SERVICE_PROJECT_NAME, your Keystone `service project name`_ and
|
||||
give the user the ``admin`` role::
|
||||
|
||||
keystone user-create --name=watcher --pass=WATCHER_PASSWORD --email=watcher@example.com
|
||||
keystone user-role-add --user=watcher --tenant=service --role=admin
|
||||
keystone user-role-add --user=watcher --tenant=KEYSTONE_SERVICE_PROJECT_NAME --role=admin
|
||||
|
||||
or
|
||||
or::
|
||||
|
||||
openstack user create --password WATCHER_PASSWORD --enable --email watcher@example.com watcher
|
||||
openstack role add --project services --user watcher admin
|
||||
|
||||
|
||||
#. You must register the Watcher Service with the Identity Service so that
|
||||
other OpenStack services can locate it. To register the service::
|
||||
|
||||
keystone service-create --name=watcher --type=infra-optim \
|
||||
--description="Infrastructure Optimization service"
|
||||
keystone service-create --name=watcher --type=infra-optim --description="Infrastructure Optimization service"
|
||||
|
||||
or::
|
||||
|
||||
openstack service create --name watcher infra-optim
|
||||
|
||||
or
|
||||
|
||||
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::
|
||||
#. Create the endpoints by replacing YOUR_REGION and WATCHER_API_IP with your region and your Watcher Service's API node URLs::
|
||||
|
||||
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
|
||||
--adminurl=http://WATCHER_API_IP:9322
|
||||
|
||||
or::
|
||||
|
||||
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
|
||||
|
||||
|
||||
.. _`service project name`: http://docs.openstack.org/developer/keystone/configuringservices.html
|
||||
|
||||
Set up the Database for Watcher
|
||||
-------------------------------
|
||||
@@ -98,9 +70,9 @@ 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 an ``watcher`` database that is accessible by the
|
||||
#. In MySQL, create a ``watcher`` database that is accessible by the
|
||||
``watcher`` user. Replace WATCHER_DBPASSWORD
|
||||
with the actual password::
|
||||
with the real password::
|
||||
|
||||
# mysql -u root -p
|
||||
mysql> CREATE DATABASE watcher CHARACTER SET utf8;
|
||||
@@ -111,7 +83,7 @@ MySQL database that is used by other OpenStack services.
|
||||
|
||||
|
||||
Configure the Watcher Service
|
||||
=============================
|
||||
-----------------------------
|
||||
|
||||
The Watcher Service is configured via its configuration file. This file
|
||||
is typically located at ``/etc/watcher/watcher.conf``. You can copy the file ``etc/watcher/watcher.conf.sample`` from the GIT repo to your server and update it.
|
||||
@@ -137,7 +109,7 @@ configured for your needs.
|
||||
|
||||
#. Configure the Watcher Service to use the RabbitMQ message broker by
|
||||
setting one or more of these options. Replace RABBIT_HOST with the
|
||||
address of the RabbitMQ server.::
|
||||
address of the RabbitMQ server::
|
||||
|
||||
[DEFAULT]
|
||||
...
|
||||
@@ -154,9 +126,9 @@ configured for your needs.
|
||||
# The RabbitMQ virtual host (string value)
|
||||
#rabbit_virtual_host=/
|
||||
|
||||
#. Configure the Watcher Service to use these credentials with the Identity
|
||||
Service. Replace IDENTITY_IP with the IP of the Identity server, and
|
||||
replace WATCHER_PASSWORD with the password you chose for the ``watcher``
|
||||
#. Configure the Watcher Service to use these credentials with the Identity Service.
|
||||
|
||||
Replace IDENTITY_IP with the address of the Keystone Identity server, KEYSTONE_SERVICE_PROJECT_NAME by the Keystone service project name, and WATCHER_PASSWORD with the password you chose for the ``watcher``
|
||||
user in the Identity Service::
|
||||
|
||||
[DEFAULT]
|
||||
@@ -184,7 +156,7 @@ configured for your needs.
|
||||
|
||||
# Keystone account password (string value)
|
||||
#admin_password=<None>
|
||||
admin_password=WATCHER_DBPASSWORD
|
||||
admin_password=WATCHER_PASSWORD
|
||||
|
||||
# Keystone service account tenant name to validate user tokens
|
||||
# (string value)
|
||||
@@ -200,23 +172,13 @@ configured for your needs.
|
||||
|
||||
watcher-db-manage --config-file /etc/watcher/watcher.conf create_schema
|
||||
|
||||
#. Start the Watcher Service::
|
||||
Development installation
|
||||
========================
|
||||
|
||||
watcher-api && watcher-decision-engine && watcher-applier
|
||||
We propose different ways to quickly install Watcher for development:
|
||||
|
||||
===============
|
||||
Important notes
|
||||
===============
|
||||
* `DevStack and Docker`_
|
||||
* `Virtualenv`_
|
||||
|
||||
|
||||
#. Watcher must have admin role on supervized users' projects created on your IAAS, in order to be able to migrate project's instances if required by Watcher audits:
|
||||
|
||||
keystone user-role-add --user=watcher --tenant=<USER_PROJECT_NAME> --role=admin
|
||||
|
||||
or
|
||||
|
||||
openstack role add --project <USER_PROJECT_NAME> --user watcher admin
|
||||
|
||||
#. Please check also your hypervisor configuration to handle correctly instance migration:
|
||||
|
||||
`OpenStack - Configure Migrations <http://docs.openstack.org/admin-guide-cloud/content/section_configuring-compute-migrations.html>`_
|
||||
.. _DevStack and Docker: ./install-devstack-docker.rst
|
||||
.. _Virtualenv: ./virtualenv.rst
|
||||
|
||||
@@ -10,66 +10,86 @@ 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 "*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.
|
||||
I you need help on a specific command, you can use "watcher help COMMAND"
|
||||
If you need help on a specific command, you can use:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ watcher help COMMAND
|
||||
|
||||
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.
|
||||
|
||||
``watcher``
|
||||
.. code:: bash
|
||||
|
||||
$ 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.
|
||||
This goal should be declared in the Watcher service configuration file.
|
||||
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**.
|
||||
|
||||
``$ watcher audit-template-create my_first_audit SERVERS_CONSOLIDATION``
|
||||
.. code:: bash
|
||||
|
||||
If you get "You must provide a username via either --os-username or via env[OS_USERNAME]" you may have to verify your credentials
|
||||
$ 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
|
||||
|
||||
Then, you can create an audit. An audit is a request for optimizing your cluster depending on the specified goal.
|
||||
|
||||
You can launch an audit on your cluster by referencing the audit template (i.e. the goal) that you want to use.
|
||||
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.
|
||||
|
||||
- Get the audit template UUID::
|
||||
``$ watcher audit-template-list``
|
||||
- Start an audit based on this audit template settings::
|
||||
``$ watcher audit-create -a <your_audit_template_uuid>``
|
||||
- Get the audit template UUID:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ watcher audit-template-list
|
||||
|
||||
- Start an audit based on this audit template 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 according to the goal to achieve.
|
||||
You can see all of the goals available in the Watcher service configuration file, section ``[watcher_strategies]``.
|
||||
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.
|
||||
|
||||
- Wait until the Watcher audit has produced a new action plan, and get it::
|
||||
``$ watcher action-plan-list --audit <the_audit_uuid>``
|
||||
- Wait until the Watcher audit has produced a new action plan, and get it:
|
||||
|
||||
- Have a look on the list of optimization of this new action plan::
|
||||
``$ watcher action-list --action-plan <the_action_plan_uuid>``
|
||||
.. 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:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ watcher action-list --action-plan <the_action_plan_uuid>
|
||||
|
||||
|
||||
Once you've learnt how to create an Action Plan it's time to go further by applying it to your cluster :
|
||||
Once you've learned how to create an Action Plan, it's time to go further by applying it to your cluster:
|
||||
|
||||
- Execute the action plan::
|
||||
``$ watcher action-plan-start <the_action_plan_uuid>``
|
||||
- Execute the action plan:
|
||||
|
||||
You can follow the states of the actions by calling periodically ``watcher action-list``
|
||||
.. code:: bash
|
||||
|
||||
Frequently Asked Questions
|
||||
--------------------------
|
||||
$ watcher action-plan-start <the_action_plan_uuid>
|
||||
|
||||
Under specific circumstances, you may encounter the following errors :
|
||||
You can follow the states of the actions by calling periodically:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ watcher action-list
|
||||
|
||||
You can also obtain more detailed information about a specific action:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
$ watcher action-show <the_action_uuid>
|
||||
|
||||
- Why do I get a 'Unable to establish connection to ....' error message ?
|
||||
|
||||
You typically get this error when one of the watcher services is not running.
|
||||
You can make sure every Watcher service is running by launching the following command :
|
||||
``
|
||||
initctl list | grep watcher
|
||||
watcher-api start/running, process 33062
|
||||
watcher-decision-engine start/running, process 35511
|
||||
watcher-applier start/running, process 47359
|
||||
``
|
||||
222
doc/source/deploy/virtualenv.rst
Normal file
222
doc/source/deploy/virtualenv.rst
Normal file
@@ -0,0 +1,222 @@
|
||||
.. _virtualenv:
|
||||
|
||||
========================
|
||||
Development Installation
|
||||
========================
|
||||
|
||||
Watcher development uses virtualenv to track and manage Python dependencies while in development and testing. This allows you to install all of the Python package dependencies in a virtual environment or “virtualenv”, instead of installing the packages at the system level.
|
||||
|
||||
|
||||
Linux Systems
|
||||
-------------
|
||||
|
||||
Install the prerequisite packages.
|
||||
|
||||
On Ubuntu (tested on 12.04-64 and 14.04-64)::
|
||||
|
||||
sudo apt-get install python-dev libssl-dev python-pip git-core libmysqlclient-dev libffi-dev
|
||||
|
||||
On Fedora-based distributions e.g., Fedora/RHEL/CentOS/Scientific Linux (tested on CentOS 6.5)::
|
||||
|
||||
sudo yum install python-virtualenv openssl-devel python-pip git gcc libffi-devel mysql-devel postgresql-devel
|
||||
|
||||
On openSUSE-based distributions (SLES 12, openSUSE 13.1, Factory or Tumbleweed)::
|
||||
|
||||
sudo zypper install gcc git libmysqlclient-devel libopenssl-devel postgresql-devel python-devel python-pip
|
||||
|
||||
|
||||
Manually installing and using the virtualenv
|
||||
--------------------------------------------
|
||||
|
||||
If you have `virtualenvwrapper <https://virtualenvwrapper.readthedocs.org/en/latest/install.html>`_ installed::
|
||||
|
||||
$ mkvirtualenv watcher
|
||||
$ git clone https://git.openstack.org/openstack/stackforge/watcher
|
||||
$ cd watcher && python setup.py install
|
||||
$ pip install -r ./requirements.txt
|
||||
|
||||
To run a specific test, use a positional argument for the unit tests::
|
||||
|
||||
# run a specific test for Python 2.7
|
||||
tox -epy27 -- tests.api
|
||||
|
||||
You may pass options to the test programs using positional arguments::
|
||||
|
||||
# run all the Python 2.7 unit tests (in parallel!)
|
||||
tox -epy27 -- --parallel
|
||||
|
||||
To run only the pep8/flake8 syntax and style checks::
|
||||
|
||||
tox -epep8
|
||||
|
||||
|
||||
Configure Identity Service for Watcher
|
||||
--------------------------------------
|
||||
|
||||
#. 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::
|
||||
|
||||
keystone user-create --name=watcher --pass=WATCHER_PASSWORD --email=watcher@example.com
|
||||
keystone user-role-add --user=watcher --tenant=service --role=admin
|
||||
|
||||
or
|
||||
|
||||
openstack user create --password WATCHER_PASSWORD --enable --email watcher@example.com watcher
|
||||
openstack role add --project services --user watcher admin
|
||||
|
||||
|
||||
#. You must register the Watcher Service with the Identity Service so that
|
||||
other OpenStack services can locate it. To register the service::
|
||||
|
||||
keystone service-create --name=watcher --type=infra-optim \
|
||||
--description="Infrastructure Optimization service"
|
||||
|
||||
or
|
||||
|
||||
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::
|
||||
|
||||
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
|
||||
|
||||
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 an ``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``. You can copy the file ``etc/watcher/watcher.conf.sample`` from the GIT repo to your server and update it.
|
||||
|
||||
Although some configuration options are mentioned here, it is recommended that
|
||||
you review all the available options so that the Watcher Service is
|
||||
configured for your needs.
|
||||
|
||||
#. The Watcher Service stores information in a database. This guide uses the
|
||||
MySQL database that is used by other OpenStack services.
|
||||
|
||||
Configure the location of the database via the ``connection`` option. In the
|
||||
following, replace WATCHER_DBPASSWORD with the password of your ``watcher``
|
||||
user, and replace DB_IP with the IP address where the DB server is located::
|
||||
|
||||
[database]
|
||||
...
|
||||
|
||||
# The SQLAlchemy connection string used to connect to the
|
||||
# database (string value)
|
||||
#connection=<None>
|
||||
connection = mysql://watcher:WATCHER_DBPASSWORD@DB_IP/watcher?charset=utf8
|
||||
|
||||
#. Configure the Watcher Service to use the RabbitMQ message broker by
|
||||
setting one or more of these options. Replace RABBIT_HOST with the
|
||||
address of the RabbitMQ server.::
|
||||
|
||||
[DEFAULT]
|
||||
...
|
||||
# The RabbitMQ broker address where a single node is used
|
||||
# (string value)
|
||||
rabbit_host=RABBIT_HOST
|
||||
|
||||
# The RabbitMQ userid (string value)
|
||||
#rabbit_userid=guest
|
||||
|
||||
# The RabbitMQ password (string value)
|
||||
#rabbit_password=guest
|
||||
|
||||
# The RabbitMQ virtual host (string value)
|
||||
#rabbit_virtual_host=/
|
||||
|
||||
#. Configure the Watcher Service to use these credentials with the Identity
|
||||
Service. Replace IDENTITY_IP with the IP of the Identity server, and
|
||||
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)
|
||||
#auth_uri=<None>
|
||||
auth_uri=http://IDENTITY_IP:5000/v3
|
||||
|
||||
# Complete admin Identity API endpoint. This should specify the
|
||||
# unversioned root endpoint e.g. https://localhost:35357/ (string
|
||||
# value)
|
||||
#identity_uri = <None>
|
||||
identity_uri = http://IDENTITY_IP:5000
|
||||
|
||||
# Keystone account username (string value)
|
||||
#admin_user=<None>
|
||||
admin_user=watcher
|
||||
|
||||
# Keystone account password (string value)
|
||||
#admin_password=<None>
|
||||
admin_password=WATCHER_DBPASSWORD
|
||||
|
||||
# Keystone service account tenant name to validate user tokens
|
||||
# (string value)
|
||||
#admin_tenant_name=admin
|
||||
admin_tenant_name=KEYSTONE_SERVICE_PROJECT_NAME
|
||||
|
||||
# Directory used to cache files related to PKI tokens (string
|
||||
# value)
|
||||
#signing_dir=<None>
|
||||
|
||||
|
||||
#. Create the Watcher Service database tables::
|
||||
|
||||
watcher-db-manage --config-file /etc/watcher/watcher.conf create_schema
|
||||
|
||||
#. Start the Watcher Service::
|
||||
|
||||
watcher-api && watcher-decision-engine && watcher-applier
|
||||
|
||||
===============
|
||||
Important notes
|
||||
===============
|
||||
|
||||
|
||||
#. Watcher must have admin role on supervized users' projects created on your IAAS, in order to be able to migrate project's instances if required by Watcher audits:
|
||||
|
||||
keystone user-role-add --user=watcher --tenant=<USER_PROJECT_NAME> --role=admin
|
||||
|
||||
or
|
||||
|
||||
openstack role add --project <USER_PROJECT_NAME> --user watcher admin
|
||||
|
||||
#. Please check also your hypervisor configuration to handle correctly instance migration:
|
||||
|
||||
`OpenStack - Configure Migrations <http://docs.openstack.org/admin-guide-cloud/content/section_configuring-compute-migrations.html>`_
|
||||
@@ -49,7 +49,7 @@ Wiki
|
||||
http://wiki.openstack.org/Watcher
|
||||
|
||||
Code Hosting
|
||||
https://github.com/openstack/watcher
|
||||
https://git.openstack.org/cgit/stackforge/watcher
|
||||
|
||||
Code Review
|
||||
https://review.openstack.org/#/q/status:open+project:stackforge/watcher,n,z
|
||||
|
||||
@@ -2,10 +2,10 @@
|
||||
Welcome to Watcher's developer documentation
|
||||
============================================
|
||||
|
||||
Introduction
|
||||
============
|
||||
Mission
|
||||
=======
|
||||
|
||||
Watcher is an OpenStack project ...
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user