Document deployment of Python monasca-persister

Add documentation of how to deploy and use the Python implementation of the
monasca-persister, including notes on how to ensure the persister will
resume operation under certain failure scenarios which will cause it to
exit, such as Kafka becoming unavailable.

Change-Id: I7fec0bbe730ed49b1eb6ec8b4efb808abf810828
Closes-Bug: #1644867
This commit is contained in:
Steve Simpson 2016-12-09 16:46:38 +00:00 committed by Tomasz Trębski
parent de9efed226
commit a9090a655a
1 changed files with 183 additions and 0 deletions

View File

@ -5,6 +5,189 @@ A Monasca Persister written in Python.
Reads alarms and metrics from a Kafka queue and stores them in an InfluxDB
database.
## Deployment
Note that this document refers to the Python implementation of the persister.
For information regarding the Java implementation, see the README.md in the
root of this repository.
### Package Installation
Monasca Persister should be installed from PyPI via pip. Use your distribution
package manager, or other preferred method, to ensure that you have pip
installed, it is typically called python-pip.
e.g. For Debian/Ubuntu:
```
sudo apt-get install python-pip
```
Alternately, you may want to follow the official instructions available at:
https://pip.pypa.io/en/stable/installing/
Now, to install a particular released version:
```
sudo pip install monasca-persister==<version>
```
If using InfluxDB, the persister requires the necessary Python library
to be installed. This can also be achieved via pip:
```
sudo pip install influxdb
```
Alternatively, pip can be used to install the latest development version
or a specific revision. This requires you have git installed in addition
to pip.
```
sudo apt-get install git
sudo pip install git+https://git.openstack.org/openstack/monasca-persister@<revision>#egg=monasca-persister
```
The installation will not cause the persister to run - it should first
be configured.
### Environment
Using the persister requires that the following components of the Monasca
system are deployed and available:
* Kafka
* Zookeeper (Required by Kafka)
* InfluxDB
If running the persister as a daemon, it is good practice to create a
dedicated system user for the purpose, for example:
```
sudo groupadd --system monasca
sudo useradd --system --gid monasca mon-persister
```
Additionally, it is good practice to give the daemon a dedicated working
directory, in the event it ever needs to write any files.
```
sudo mkdir -p /var/lib/monasca-persister
sudo chown mon-persister:monasca /var/lib/monasca-persister
```
The persister will write a log file in a location which can be changed
via the configuration, but by default requires that a suitable directory
be created as follows:
```
sudo mkdir -p /var/log/monasca/persister
sudo chown mon-persister:monasca /var/log/monasca/persister
```
Make sure to allow the user who will be running the persister to have
write access to the log directory.
### Configuration
There is minimum amount of configuration which must be performed before
running the persister. A template configuration file is installed in the
default location of /etc/monasca/persister.conf.
Note that the configuration will contain authentication information for
the database being used, so depending on your environment it may be
desirable to inhibit read access except for the monasca-persister group.
```
sudo chown root:monasca /etc/monasca/persister.conf
sudo chmod 640 /etc/monasca/persister.conf
```
Most of the configuration options should be left at default, but at a
minimum, the following should be changed:
```
[zookeeper]
uri = <host1>:<port1>,<host2>:<port2>,...
[kafka_alarm_history]
uri = <host1>:<port1>,<host2>:<port2>,...
[kafka_metrics]
uri = <host1>:<port1>,<host2>:<port2>,...
[influxdb]
database_name =
ip_address =
port =
user =
password =
```
### Running
The installation does not provide scripts for starting the persister, it
is up to the user how the persister is run. To run the persister manually,
which may be useful for troubleshooting:
```
sudo -u mon-persister \
monasca-persister \
--config-file /etc/monasca/persister.conf
```
Note that it is important to deploy the daemon in a manner such that the daemon
will be restarted if it exits (fails). There are a number of situations in which
the persister will fail-fast, such as all Kafka endpoints becoming unreachable.
For an example of this, see the systemd deployment section below.
### Running (systemd)
To run the persister as a daemon, the following systemd unit file can be used
and placed in ``/etc/systemd/system/monasca-persister.service``:
```
[Unit]
Description=OpenStack Monasca Persister
Documentation=https://github.com/openstack/monasca-persister/monasca-persister/README.md
Requires=network.target remote-fs.target
After=network.target remote-fs.target
ConditionPathExists=/etc/monasca/persister.conf
ConditionPathExists=/var/lib/monasca-persister
ConditionPathExists=/var/log/monasca/persister
[Service]
Type=simple
PIDFile=/var/run/monasca-persister.pid
User=mon-persister
Group=monasca
WorkingDirectory=/var/lib/monasca-persister
ExecStart=/usr/local/bin/monasca-persister --config-file /etc/monasca/persister.conf
Restart=on-failure
RestartSec=5
SyslogIdentifier=monasca-persister
[Install]
WantedBy=multi-user.target
```
After creating or modifying the service file, you should run:
```
sudo systemctl daemon-reload
```
The service can then be managed as normal, e.g.
```
sudo systemctl start monasca-persister
```
For a production deployment, it will almost always be desirable to use the
*Restart* clause in the service file. The *RestartSec* clause is also
important as by default, systemd assumes a delay of 100ms. A number of
failures in quick succession will cause the unit to enter a failed state,
therefore extending this period is critical.
# License