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:
parent
a952594c5b
commit
ce5e422a75
|
@ -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
|
||||
|
|
89
README.rst
89
README.rst
|
@ -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)
|
||||
|
|
|
@ -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'),
|
||||
]
|
|
@ -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
|
|
@ -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`
|
|
@ -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.
|
|
@ -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.
|
|
@ -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
14
tox.ini
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue