From ce5e422a75e094349617c028be396b202e235945 Mon Sep 17 00:00:00 2001 From: Iury Gregory Melo Ferreira Date: Mon, 16 Mar 2020 16:34:31 +0100 Subject: [PATCH] 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 e2080d0862488bf869a115c264bc8a399545a62f) --- .zuul.yaml | 1 + README.rst | 89 +----------------------------------- doc/source/conf.py | 74 ++++++++++++++++++++++++++++++ doc/source/configuration.rst | 74 ++++++++++++++++++++++++++++++ doc/source/index.rst | 17 +++++++ doc/source/install.rst | 39 ++++++++++++++++ doc/source/limitations.rst | 9 ++++ doc/source/run.rst | 55 ++++++++++++++++++++++ tox.ini | 14 ++++++ 9 files changed, 285 insertions(+), 87 deletions(-) create mode 100644 doc/source/conf.py create mode 100644 doc/source/configuration.rst create mode 100644 doc/source/index.rst create mode 100644 doc/source/install.rst create mode 100644 doc/source/limitations.rst create mode 100644 doc/source/run.rst diff --git a/.zuul.yaml b/.zuul.yaml index 582d873..9c0c641 100644 --- a/.zuul.yaml +++ b/.zuul.yaml @@ -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 diff --git a/README.rst b/README.rst index 84786f7..67d3fc2 100644 --- a/README.rst +++ b/README.rst @@ -1,9 +1,8 @@ Ironic Prometheus Exporter ========================== -Overview --------- -Tool to expose hardware sensor data in the `Prometheus `_ format through an HTTP endpoint. +Ironic Prometheus Exporter is a Tool to expose hardware sensor data in the +`Prometheus `_ format through an HTTP endpoint. The hardware sensor data come from bare metal machines deployed using `OpenStack Bare Metal Service (ironic) `_. @@ -12,87 +11,3 @@ using `OpenStack Bare Metal Service (ironic) - $ 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 `_ - -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 - `_ - (see `developer's guide - `_) -* Bugs and RFEs: `StoryBoard - `_ - (please do NOT report bugs to Github) diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..3535503 --- /dev/null +++ b/doc/source/conf.py @@ -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'), +] diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst new file mode 100644 index 0000000..2787198 --- /dev/null +++ b/doc/source/configuration.rst @@ -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 + - + - 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 diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..cf49dcf --- /dev/null +++ b/doc/source/index.rst @@ -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` diff --git a/doc/source/install.rst b/doc/source/install.rst new file mode 100644 index 0000000..9290cc0 --- /dev/null +++ b/doc/source/install.rst @@ -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 + $ 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. diff --git a/doc/source/limitations.rst b/doc/source/limitations.rst new file mode 100644 index 0000000..b660335 --- /dev/null +++ b/doc/source/limitations.rst @@ -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 + `_. +* The set of metrics that will be available depends on the hardware type. diff --git a/doc/source/run.rst b/doc/source/run.rst new file mode 100644 index 0000000..3ebcb44 --- /dev/null +++ b/doc/source/run.rst @@ -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 +`_), +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= + $ 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 `_ since it's what we use +in our CI. + +The command to execute the application using gunicorn is: +:: + + $ gunicorn3 -b :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 +`_. diff --git a/tox.ini b/tox.ini index 30daf61..33d3673 100644 --- a/tox.ini +++ b/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