Add documentation

- Move README.rst documentation to doc/source
- Addd job to publish docs
- Update tox to run docs and pdf-docs

Change-Id: I967312ab8ba572adb3155c98b5511aa9600c0d03
(cherry picked from commit e2080d0862)
This commit is contained in:
Iury Gregory Melo Ferreira 2020-03-16 16:34:31 +01:00 committed by Iury Gregory Melo Ferreira
parent a952594c5b
commit ce5e422a75
9 changed files with 285 additions and 87 deletions

View File

@ -86,6 +86,7 @@
- openstack-python-jobs
- openstack-python3-train-jobs
- release-notes-jobs-python3
- publish-openstack-docs-pti
check:
jobs:
- ironic-prometheus-exporter-redfish

View File

@ -1,9 +1,8 @@
Ironic Prometheus Exporter
==========================
Overview
--------
Tool to expose hardware sensor data in the `Prometheus <https://prometheus.io/>`_ format through an HTTP endpoint.
Ironic Prometheus Exporter is a Tool to expose hardware sensor data in the
`Prometheus <https://prometheus.io/>`_ format through an HTTP endpoint.
The hardware sensor data come from bare metal machines deployed
using `OpenStack Bare Metal Service (ironic) <https://docs.openstack.org/ironic/latest/>`_.
@ -12,87 +11,3 @@ using `OpenStack Bare Metal Service (ironic) <https://docs.openstack.org/ironic/
* Documentation: https://docs.openstack.org/ironic-prometheus-exporter/
* Source: https://opendev.org/openstack/ironic-prometheus-exporter
* Bugs: https://storyboard.openstack.org/#!/project/openstack/ironic-prometheus-exporter
Installation
------------
1 - Install ironic-prometheus-exporter
::
$ pip install --user ironic-prometheus-exporter
2- Verify if the driver is installed
::
$ pip install entry_point_inspector --user <user>
$ epi group show oslo.messaging.notify.drivers
- Output in case of a successful instalation: `prometheus_exporter` is listed in the `Name` column and the `Error` column should be empty.
- Output in case of an unsuccessful instalation: `prometheus_exporter` is listed in the `Name` column and the `Error` column will have more information.
Configuration
-------------
After install the driver you will need to update the `ironic.conf` and add the following information:
::
[conductor]
send_sensor_data=true
[oslo_messaging_notifications]
driver = prometheus_exporter
transport_url = fake://
location=/tmp/ironic_prometheus_exporter
Running exporter application
----------------------------
The Flask Application is responsible to merge all the metrics files present in the directory
set in `[oslo_messaging_notifications]/location`.
.. note:: If you want to deploy in production please check the Flask `documentation <http://flask.pocoo.org/docs/dev/deploying/>`_
To run the Flask Application follow the steps listed below:
1 - open the repository directory
::
$ cd ironic-prometheus-exporter/
2- set the `FLASK_*` environment variables and the location of the `ironic.conf` file.
::
$ export IRONIC_CONFIG=/etc/ironic/ironic.conf
$ export FLASK_APP=ironic_prometheus_exporter/app/exporter.py
$ export FLASK_RUN_HOST=$HOST_IP
$ export FLASK_RUN_PORT=5000
3- run the Flask Application
::
$ python -m flask run &
**Running under uWSGI**
Reproduce the Steps 1 and 2 (You don't need to set `FLASK_APP` variable) and run the command below:
::
$ uwsgi --plugin python --http-socket ${FLASK_RUN_HOST}:${FLASK_RUN_PORT} --module ironic_prometheus_exporter.app.wsgi:application
Contributing
------------
* Pull requests: `Gerrit
<https://review.opendev.org/#/q/project:openstack/ironic-prometheus-exporter>`_
(see `developer's guide
<https://docs.openstack.org/infra/manual/developers.html>`_)
* Bugs and RFEs: `StoryBoard
<https://storyboard.openstack.org/#!/project/openstack/ironic-prometheus-exporter>`_
(please do NOT report bugs to Github)

74
doc/source/conf.py Normal file
View File

@ -0,0 +1,74 @@
# -*- coding: utf-8 -*-
# Copyright 2010-2020 OpenStack Foundation
#
# Licensed under the Apache License, Version 2.0 (the "License"); you may
# not use this file except in compliance with the License. You may obtain
# a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
import os
import sys
sys.path.insert(0, os.path.abspath('../..'))
# -- General configuration ----------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [
'sphinx.ext.autodoc',
'openstackdocstheme'
]
# autodoc generation is a bit aggressive and a nuisance when doing heavy
# text edit cycles.
# execute "export SPHINX_DEBUG=1" in your terminal to disable
# The suffix of source filenames.
source_suffix = '.rst'
# The master toctree document.
master_doc = 'index'
# General information about the project.
copyright = u'2020, Ironic Developers'
# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
add_module_names = True
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# -- Options for HTML output --------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
# html_theme_path = ["."]
html_theme = 'openstackdocs'
# html_static_path = ['static']
# Output file base name for HTML help builder.
htmlhelp_basename = 'ironic_prometheus_exporter_doc'
latex_use_xindy = False
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass
# [howto/manual]).
latex_documents = [
('index',
'doc-ipe.tex',
u'Ironic Prometheus Exporter Documentation',
u'Ironic Developers', 'manual'),
]

View File

@ -0,0 +1,74 @@
Configuration
=============
To enable the ironic-prometheus-exporter to collect the sensor data from Ironic,
it's necessary to enable some configuration parameters in the ``ironic.conf``.
Below you can see an example of the required configuration, the table
:ref:`ipe_conf` shows all the available configuration options.
Example of configuration
.. code-block:: ini
[conductor]
send_sensor_data = true
send_sensor_data_interval = 300
[oslo_messaging_notifications]
driver = prometheus_exporter
transport_url = fake://
location = /opt/stack/node_metrics
.. _ipe_conf:
.. list-table:: Configuration options for the ironic-prometheus-exporter in Ironic
:widths: 15 15 10 50 10
:header-rows: 1
* - Section
- Setting
- Value
- Description
- Required
* - conductor
- send_sensor_data
- true
- Enable sending sensor data message via the notification bus.
- ``Yes``
* - conductor
- send_sensor_data_interval
- 600 (`default`)
- Seconds between conductor sending sensor data message via the
notification bus.
- ``Yes``
* - conductor
- send_sensor_data_for_undeployed_nodes
- false (`default`)
- When set to true, the conductor will collect sensor information from
all nodes when sensor data collection is enabled via the
``send_sensor_data`` setting.
- No
* - oslo_messaging_notifications
- driver
- prometheus_exporter
- The Drivers(s) to handle sending notifications.
- ``Yes``
* - oslo_messaging_notifications
- transport_url
- fake://
- A URL representing the messaging driver to use for notifications.
If not set, we fall back to the same configuration used for RPC.
- ``Yes``
* - oslo_messaging_notifications
- location
- <dir_path>
- Directory where the files will be written.
- ``Yes``
.. note::
After doing the modifications in the ``ironic.conf`` don't forget to re-start
the ironic-conductor service

17
doc/source/index.rst Normal file
View File

@ -0,0 +1,17 @@
Welcome to Ironic Prometheus Exporter's documentation!
======================================================
.. toctree::
:maxdepth: 2
:caption: Contents:
install
configuration
run
limitations
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

39
doc/source/install.rst Normal file
View File

@ -0,0 +1,39 @@
Installation
============
Pre-Requisites
--------------
Before installing the exporter you need to have Ironic already installed,
to know about the limitations check :doc:`limitations`
Supported OS:
* CentOS/RHEL 8
* Ubuntu Bionic
Ironic Prometheus Exporter Installation
---------------------------------------
The ironic-prometheus-exporter is available as pip package and as rpm package
on RDO.
#. Package Installation
#. Using pip::
$ pip install --user ironic-prometheus-exporter
#. Using rpm from RDO::
$ dnf install -y python3-ironic-prometheus-exporter
#. Verify the Installation::
$ pip install entry_point_inspector --user <user>
$ epi group show oslo.messaging.notify.drivers
- Output in case of a successful installation: `prometheus_exporter` is listed in the `Name` column and the `Error` column should be empty.
- Output in case of an unsuccessful installation: `prometheus_exporter` is listed in the `Name` column and the `Error` column will have more information.

View File

@ -0,0 +1,9 @@
Limitations
===========
* The only hardware types that have support for sensor data are `ipmi` and
`redfish` (If a new hardware type adds support we need to add a parser for
it).
* We can only deal with `Gauge metrics
<https://prometheus.io/docs/practices/instrumentation/#counter-vs-gauge-summary-vs-histogram>`_.
* The set of metrics that will be available depends on the hardware type.

55
doc/source/run.rst Normal file
View File

@ -0,0 +1,55 @@
Running the exporter Application
================================
The exporter application is a Flask Application responsible to merge
all the metrics files present in the directory set in
``[oslo_messaging_notifications]/location``.
The prometheus community defined the port of the Ironic Prometheus Exporter
application as ``9608`` (see `Default port allocations
<https://github.com/prometheus/prometheus/wiki/Default-port-allocations>`_),
but you can choose any port for your deployment.
The application needs to have access to the ``ironic.conf``, you need to set
the ``IRONIC_CONFIG`` environment variable to the absolute path of the file.
We will explain how you can run the application in a development environment
and in production environment.
Development Environment
-----------------------
To run the Flask Application follow the steps listed below:
#. Set the ``FLASK_*`` environment variables and the location of the
``ironic.conf`` file.::
$ export IRONIC_CONFIG=/etc/ironic/ironic.conf
$ export FLASK_APP=ironic_prometheus_exporter/app/exporter.py
$ export FLASK_RUN_HOST=<ip address>
$ export FLASK_RUN_PORT=9608
#. Run the Flask Application::
$ python -m flask run
Production Environment
----------------------
To deploy the application in production you can use any application server, we
will be using `gunicorn <https://gunicorn.org/#docs>`_ since it's what we use
in our CI.
The command to execute the application using gunicorn is:
::
$ gunicorn3 -b <ip_address>:9608 \
--env IRONIC_CONFIG=$IRONIC_CONFIG \
--env FLASK_DEBUG=1 -w 4 \
--access-logfile=ipe_access.log \
--error-logfile=ipe_errors.log \
-D ironic_prometheus_exporter.app.wsgi:application
You can find more information about how to deploy a Flask application in
production in the `Flask documentation
<http://flask.pocoo.org/docs/dev/deploying/>`_.

14
tox.ini
View File

@ -30,6 +30,20 @@ deps =
commands =
sphinx-build -a -E -W -d releasenotes/build/doctrees -b html releasenotes/source releasenotes/build/html
[testenv:docs]
deps =
-c{env:UPPER_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
-r{toxinidir}/requirements.txt
-r{toxinidir}/doc/requirements.txt
commands = sphinx-build -W -b html doc/source doc/build/html
[testenv:pdf-docs]
deps = {[testenv:docs]deps}
whitelist_externals = make
commands =
sphinx-build -W -b latex doc/source doc/build/pdf
make -C doc/build/pdf
[testenv:venv]
basepython = python3
setenv = PYTHONHASHSEED=0