Update the "admin/configuration" section of the documentation
This replaces the out-of-date "admin/configuration" section of the documentation with a step-by-step configuration guide. Change-Id: I2268ead54d0c0651c364bf790f1f17a16f28ab39 Story: 2004179 Task: 29063
This commit is contained in:
Luka Peschke
@@ -1,56 +1,57 @@
|
|||||||
###################
|
================================
|
||||||
Configuration Guide
|
Step by step configuration guide
|
||||||
###################
|
================================
|
||||||
|
|
||||||
Configure Cloudkitty
|
Edit ``/etc/cloudkitty/cloudkitty.conf`` to configure cloudkitty.
|
||||||
====================
|
|
||||||
|
|
||||||
Edit :file:`/etc/cloudkitty/cloudkitty.conf` to configure cloudkitty.
|
Common options
|
||||||
|
--------------
|
||||||
|
|
||||||
Then you need to know which keystone API version you use (which can be
|
Options supported by most OpenStack projects are also supported by cloudkitty:
|
||||||
determined using ``openstack endpoint list``)
|
|
||||||
|
|
||||||
|
|
||||||
The first thing to set is the authentication method wished to reach Cloudkitty
|
|
||||||
API endpoints.
|
|
||||||
|
|
||||||
|
|
||||||
Without authentication
|
|
||||||
----------------------
|
|
||||||
|
|
||||||
If wanted, you can choose to not set any authentication method.
|
|
||||||
This should be set in the ``DEFAULT`` block of the configuration file owing to
|
|
||||||
the ``auth_strategy`` field:
|
|
||||||
|
|
||||||
.. code-block:: ini
|
.. code-block:: ini
|
||||||
|
|
||||||
[DEFAULT]
|
[DEFAULT]
|
||||||
verbose = True
|
verbose = true
|
||||||
|
debug = false
|
||||||
log_dir = /var/log/cloudkitty
|
log_dir = /var/log/cloudkitty
|
||||||
# oslo_messaging_rabbit is deprecated
|
|
||||||
transport_url = rabbit://RABBIT_USER:RABBIT_PASSWORD@RABBIT_HOST
|
transport_url = rabbit://RABBIT_USER:RABBIT_PASSWORD@RABBIT_HOST
|
||||||
|
|
||||||
|
|
||||||
|
API authentication method
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
The authentication method is defined through the ``auth_strategy`` option in
|
||||||
|
the ``[DEFAULT]`` section.
|
||||||
|
|
||||||
|
Standalone mode
|
||||||
|
+++++++++++++++
|
||||||
|
|
||||||
|
If you're using CloudKitty in standalone mode, you'll have to use noauth:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[DEFAULT]
|
||||||
auth_strategy = noauth
|
auth_strategy = noauth
|
||||||
|
|
||||||
|
Keystone integration
|
||||||
|
++++++++++++++++++++
|
||||||
|
|
||||||
Otherwise, the only other officially implemented authentication method is
|
If you're using CloudKitty with OpenStack, you'll want to use Keystone
|
||||||
keystone. More methods will be implemented soon. It should be set in the
|
authentication:
|
||||||
``DEFAULT`` configuration block too, with the ``auth_stategy`` field.
|
|
||||||
|
|
||||||
|
|
||||||
For keystone (identity) API v3
|
|
||||||
------------------------------
|
|
||||||
|
|
||||||
The following shows the basic configuration items:
|
|
||||||
|
|
||||||
.. code-block:: ini
|
.. code-block:: ini
|
||||||
|
|
||||||
[DEFAULT]
|
[DEFAULT]
|
||||||
verbose = True
|
|
||||||
log_dir = /var/log/cloudkitty
|
|
||||||
# oslo_messaging_rabbit is deprecated
|
|
||||||
transport_url = rabbit://RABBIT_USER:RABBIT_PASSWORD@RABBIT_HOST/
|
|
||||||
auth_strategy = keystone
|
auth_strategy = keystone
|
||||||
|
|
||||||
|
When using Keystone, you'll have to provide the CloudKitty credentials for
|
||||||
|
Keystone. These must be specified in the ``[keystone_authtoken]`` section.
|
||||||
|
Since these credentials will be used in multiple places, it is convenient to
|
||||||
|
use a common section:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
[ks_auth]
|
[ks_auth]
|
||||||
auth_type = v3password
|
auth_type = v3password
|
||||||
auth_protocol = http
|
auth_protocol = http
|
||||||
@@ -61,178 +62,135 @@ The following shows the basic configuration items:
|
|||||||
project_name = service
|
project_name = service
|
||||||
user_domain_name = default
|
user_domain_name = default
|
||||||
project_domain_name = default
|
project_domain_name = default
|
||||||
debug = True
|
|
||||||
|
|
||||||
[keystone_authtoken]
|
[keystone_authtoken]
|
||||||
auth_section = ks_auth
|
auth_section = ks_auth
|
||||||
|
|
||||||
[database]
|
.. note:: The ``service`` project may also be called ``services``.
|
||||||
connection = mysql+pymysql://CK_DBUSER:CK_DBPASSWORD@DB_HOST/cloudkitty
|
|
||||||
|
|
||||||
[fetcher_keystone]
|
CloudKitty provides the ``rating`` OpenStack service.
|
||||||
auth_section = ks_auth
|
|
||||||
keystone_version = 3
|
|
||||||
|
|
||||||
[tenant_fetcher]
|
To integrate cloudkitty to Keystone, run the following commands (as OpenStack
|
||||||
backend = keystone
|
administrator):
|
||||||
|
|
||||||
.. note::
|
.. code-block:: shell
|
||||||
|
|
||||||
The tenant named ``service`` is also commonly called ``services``
|
openstack user create cloudkitty --password CK_PASSWORD
|
||||||
|
|
||||||
It is now time to configure the storage backend. Two storage backends are
|
openstack role add --project service --user cloudkitty admin
|
||||||
available: ``sqlalchemy`` and ``hybrid`` (SQLalchemy being the recommended one).
|
|
||||||
|
|
||||||
.. warning:: A v2 influxdb backend storage is also available. Its API is
|
openstack service create rating --name cloudkitty \
|
||||||
considered stable but its implementation may still evolve.
|
--description "OpenStack Rating Service"
|
||||||
|
|
||||||
.. code-block:: ini
|
openstack endpoint create rating --region RegionOne \
|
||||||
|
public http://localhost:8889
|
||||||
|
|
||||||
[storage]
|
openstack endpoint create rating --region RegionOne \
|
||||||
backend = sqlalchemy
|
admin http://localhost:8889
|
||||||
version = 1
|
|
||||||
|
|
||||||
As you will see in the following example, collector and storage backends
|
openstack endpoint create rating --region RegionOne \
|
||||||
sometimes need additional configuration sections. (The tenant fetcher works the
|
internal http://localhost:8889
|
||||||
same way). The section's name has the following format:
|
|
||||||
``{backend_type}_{backend_name}`` (``collector_gnocchi`` for example).
|
|
||||||
|
|
||||||
If you want to use the hybrid storage with a gnocchi backend, add the following
|
Storage
|
||||||
entry:
|
-------
|
||||||
|
|
||||||
.. code-block:: ini
|
The next step is to configure the storage. Start with the SQL and create the
|
||||||
|
``cloudkitty`` table and user:
|
||||||
|
|
||||||
[storage_gnocchi]
|
.. code-block:: shell
|
||||||
auth_section = ks_auth
|
|
||||||
|
|
||||||
Two collectors are available: Gnocchi and Monasca. The Monasca collector
|
|
||||||
collects metrics published by the Ceilometer agent to Monasca using Ceilosca_.
|
|
||||||
|
|
||||||
The collect information, is separated from the Cloudkitty configuration file,
|
|
||||||
in a yaml one.
|
|
||||||
|
|
||||||
This allows Cloudkitty users to change metrology configuration,
|
|
||||||
without modifying source code or Cloudkitty configuration file.
|
|
||||||
|
|
||||||
.. code-block:: ini
|
|
||||||
|
|
||||||
[collect]
|
|
||||||
metrics_conf = /etc/cloudkitty/metrics.yml
|
|
||||||
|
|
||||||
[collector_gnocchi]
|
|
||||||
auth_section = ks_auth
|
|
||||||
|
|
||||||
The ``/etc/cloudkitty/metrics.yml`` file looks like this:
|
|
||||||
|
|
||||||
.. literalinclude:: ../../../../etc/cloudkitty/metrics.yml
|
|
||||||
:language: yaml
|
|
||||||
|
|
||||||
Conversion information is included in the yaml file.
|
|
||||||
It allows operators to change metrics units for rating
|
|
||||||
and so to not stay stuck with the original unit.
|
|
||||||
|
|
||||||
The conversion information must be set for each metric.
|
|
||||||
It includes optionals factor and offset,
|
|
||||||
plus a mandatory final unit (used once the conversion is done).
|
|
||||||
By default, factor and offset are 1 and 0 respectively.
|
|
||||||
All type of linear conversions are so covered.
|
|
||||||
The complete formula looks like:
|
|
||||||
|
|
||||||
``new_value = (value * factor) + offset``
|
|
||||||
|
|
||||||
|
|
||||||
Setup the database and storage backend
|
|
||||||
--------------------------------------
|
|
||||||
|
|
||||||
MySQL/MariaDB is the recommended database engine. To setup the database, use
|
|
||||||
the ``mysql`` client::
|
|
||||||
|
|
||||||
mysql -uroot -p << EOF
|
mysql -uroot -p << EOF
|
||||||
CREATE DATABASE cloudkitty;
|
CREATE DATABASE cloudkitty;
|
||||||
GRANT ALL PRIVILEGES ON cloudkitty.* TO 'CK_DBUSER'@'localhost' IDENTIFIED BY 'CK_DBPASSWORD';
|
GRANT ALL PRIVILEGES ON cloudkitty.* TO 'CK_DBUSER'@'localhost' IDENTIFIED BY 'CK_DBPASSWORD';
|
||||||
EOF
|
EOF
|
||||||
|
|
||||||
If you need to authorize the mysql user associated to cloudkitty from another
|
Specify the SQL credentials in the ``[database]`` section of the configuration
|
||||||
host you have to change the line accordingly.
|
file:
|
||||||
|
|
||||||
Run the database synchronisation scripts::
|
.. code-block:: ini
|
||||||
|
|
||||||
cloudkitty-dbsync upgrade
|
[database]
|
||||||
|
connection = mysql+pymysql://CK_DBUSER:CK_DBPASSWORD@DB_HOST/cloudkitty
|
||||||
|
|
||||||
|
Once you have set up the SQL database service, the storage backend for rated
|
||||||
|
data can be configured. A complete configuration reference can be found in the
|
||||||
|
`storage backend configuration guide`_. We'll use a v2 storage backend, which
|
||||||
|
enables the v2 API. The storage version and driver to use must be specified in
|
||||||
|
the ``[storage]`` section of the documentation:
|
||||||
|
|
||||||
Init the storage backend::
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[storage]
|
||||||
|
version = 2
|
||||||
|
backend = influxdb
|
||||||
|
|
||||||
|
Driver-specific options are then specified in the ``[storage_{drivername}]``
|
||||||
|
section:
|
||||||
|
|
||||||
|
.. code-block:: ini
|
||||||
|
|
||||||
|
[storage_influxdb]
|
||||||
|
username = cloudkitty
|
||||||
|
password = cloudkitty
|
||||||
|
database = cloudkitty
|
||||||
|
host = influxdb
|
||||||
|
|
||||||
|
Once you have configured the SQL and rated data storage backends, initalize
|
||||||
|
the storage::
|
||||||
|
|
||||||
cloudkitty-storage-init
|
cloudkitty-storage-init
|
||||||
|
|
||||||
|
Then, run the database migrations::
|
||||||
|
|
||||||
Integration with Keystone
|
cloudkitty-dbsync upgrade
|
||||||
-------------------------
|
|
||||||
|
|
||||||
cloudkitty uses Keystone for authentication, and provides a ``rating`` service.
|
.. _storage backend configuration guide: ./storage.html
|
||||||
|
|
||||||
To integrate cloudkitty to Keystone, run the following commands (as OpenStack
|
Fetcher
|
||||||
administrator)::
|
-------
|
||||||
|
|
||||||
openstack user create cloudkitty --password CK_PASSWORD \
|
The fetcher retrieves the list of scopes to rate, which will then be passed
|
||||||
--email cloudkitty@localhost
|
to the collector. A complete configuration reference can be found in the
|
||||||
openstack role add --project service --user cloudkitty admin
|
`fetcher configuration guide`_. For this example, we'll use the ``gnocchi``
|
||||||
|
fetcher, which will discover scopes (in this case OpenStack projects) to rate.
|
||||||
|
The fetcher to use is specified through the ``backend`` option of the
|
||||||
|
``[fetcher]`` section:
|
||||||
|
|
||||||
Give the ``rating`` role to ``cloudkitty`` for each project that should be
|
.. code-block:: ini
|
||||||
handled by cloudkitty::
|
|
||||||
|
|
||||||
openstack role create rating
|
[fetcher]
|
||||||
openstack role add --project XXX --user cloudkitty rating
|
backend = gnocchi
|
||||||
|
|
||||||
Create the ``rating`` service and its endpoints::
|
Fetcher-specific options are then specified in the ``[fetcher_{fetchername}]``
|
||||||
|
section:
|
||||||
|
|
||||||
openstack service create rating --name cloudkitty \
|
.. code-block:: ini
|
||||||
--description "OpenStack Rating Service"
|
|
||||||
openstack endpoint create rating --region RegionOne \
|
|
||||||
public http://localhost:8889
|
|
||||||
openstack endpoint create rating --region RegionOne \
|
|
||||||
admin http://localhost:8889
|
|
||||||
openstack endpoint create rating --region RegionOne \
|
|
||||||
internal http://localhost:8889
|
|
||||||
|
|
||||||
.. note::
|
[fetcher_gnocchi]
|
||||||
|
auth_section = ks_auth
|
||||||
|
region_name = MyRegion
|
||||||
|
|
||||||
The default port for the API service changed from 8888 to 8889
|
.. _fetcher configuration guide: ./fetcher.html
|
||||||
in the Newton release. If you installed Cloudkitty in an
|
|
||||||
earlier version, make sure to either explicitly define the
|
|
||||||
``[api]/port`` setting to 8888 in ``cloudkitty.conf``, or update
|
|
||||||
your keystone endpoints to use the 8889 port.
|
|
||||||
|
|
||||||
Start cloudkitty
|
Collector
|
||||||
================
|
---------
|
||||||
|
|
||||||
If you installed cloudkitty from packages
|
The collector will retrieve data for the scopes provided by the fetcher and
|
||||||
-----------------------------------------
|
pass them to the rating modules. The collector to use is specified in
|
||||||
|
the ``[collect]`` section, and the collector-specific options are specified
|
||||||
|
in the ``[collector_{collectorname}]`` section:
|
||||||
|
|
||||||
Start the processing services::
|
.. code-block:: ini
|
||||||
|
|
||||||
systemctl start cloudkitty-processor.service
|
[collect]
|
||||||
|
collector = gnocchi
|
||||||
|
|
||||||
If you installed cloudkitty from sources
|
[collector_gnocchi]
|
||||||
-----------------------------------------
|
auth_section = ks_auth
|
||||||
|
region_name = MyRegion
|
||||||
|
|
||||||
Start the processing services::
|
Note that you'll also have to configure what metrics the collector should
|
||||||
|
collect, and how they should be collected. Have a look at the
|
||||||
|
`collector configuration guide`_ for this:
|
||||||
|
|
||||||
cloudkitty-processor --config-file /etc/cloudkitty/cloudkitty.conf
|
.. _collector configuration guide: ./collector.html
|
||||||
|
|
||||||
Choose and start the API server
|
|
||||||
-------------------------------
|
|
||||||
|
|
||||||
Cloudkitty includes the ``cloudkitty-api`` command. It can be
|
|
||||||
used to run the API server. For smaller or proof-of-concept
|
|
||||||
installations this is a reasonable choice. For larger installations it
|
|
||||||
is strongly recommended to install the API server in a WSGI host
|
|
||||||
such as mod_wsgi (see :ref:`mod_wsgi`). Doing so will provide better
|
|
||||||
performance and more options for making adjustments specific to the
|
|
||||||
installation environment.
|
|
||||||
|
|
||||||
If you are using the ``cloudkitty-api`` command it can be started as::
|
|
||||||
|
|
||||||
$ cloudkitty-api -p 8889
|
|
||||||
|
|
||||||
|
|
||||||
.. _Ceilosca: https://github.com/openstack/monasca-ceilometer
|
|
||||||
|
|||||||
Reference in New Issue
Block a user