openstack/aetos
Code Issues Proposed changes

Add first iteration of documentation

Browse Source 
This is about the most of documentation I could come up with
at this moment. I tried to follow other telemetry component
documentation, to have similar structure.

Change-Id: Ic1e7fffad33f56f15122ec57cea565b7829c4693
This commit is contained in:
Jaromir Wysoglad
2025-06-13 04:31:23 -04:00
parent 9dcb65ec66
commit 7c89d7e213
29 changed files with 390 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@@ -52,6 +52,7 @@ output/*/index.html
# Sphinx
doc/build
doc/source/_static
# pbr generates these
AUTHORS

4
.zuul.yaml
View File

@@ -2,7 +2,7 @@
queue: telemetry
templates:
- openstack-python3-jobs
# TODO(tkajinm): Enable these once ready
#- publish-openstack-docs-pti
- publish-openstack-docs-pti
# TODO(tkajinm): Enable this once ready
#- release-notes-jobs-python3
- check-requirements

1
doc/requirements.txt
View File

@@ -2,3 +2,4 @@ sphinx>=2.0.0,!=2.1.0 # BSD
openstackdocstheme>=2.2.1 # Apache-2.0
# releasenotes
reno>=3.1.0 # Apache-2.0
sphinxcontrib-pecanwsme>=0.10.0 # BSD

5
doc/source/cli/index.rst
View File

@@ -1,5 +0,0 @@
================================
Command line interface reference
================================
CLI reference of aetos.

21
doc/source/conf.py
View File

@@ -14,6 +14,9 @@
import os
import sys
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.abspath(os.path.join(BASE_DIR, "..", ".."))
sys.path.insert(0, os.path.abspath('../..'))
# -- General configuration ----------------------------------------------------
@@ -22,9 +25,27 @@ sys.path.insert(0, os.path.abspath('../..'))
extensions = [
'sphinx.ext.autodoc',
'openstackdocstheme',
'oslo_config.sphinxconfiggen',
'oslo_config.sphinxext',
'oslo_policy.sphinxpolicygen',
'oslo_policy.sphinxext',
'wsmeext.sphinxext',
'sphinxcontrib.pecanwsme.rest',
'sphinxcontrib.httpdomain',
# 'sphinx.ext.intersphinx',
]
config_generator_config_file = os.path.join(
ROOT, 'etc/aetos/aetos-config-generator.conf')
sample_config_basename = '_static/aetos'
policy_generator_config_file = os.path.join(
ROOT, 'etc/aetos/aetos-policy-generator.conf'
)
sample_policy_basename = '_static/aetos'
# 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

22
doc/source/configuration/aetos-config-file.rst Normal file
View File

@@ -0,0 +1,22 @@
Aetos Sample Configuration File
===============================
Configure Aetos by editing /etc/aetos/aetos.conf.
No config file is provided with the source code, it will be created during
the installation. In case where no configuration file was installed, one
can be easily created by running::
oslo-config-generator \
--config-file=/etc/aetos/aetos-config-generator.conf \
--output-file=/etc/aetos/aetos.conf
.. only:: html
The following is a sample Aetos configuration for adaptation and use.
It is auto-generated from Aetos when this documentation is built, and
can also be viewed in `file form <../_static/aetos.conf.sample>`_.
.. literalinclude:: ../_static/aetos.conf.sample

7
doc/source/configuration/aetos-config-options.rst Normal file
View File

@@ -0,0 +1,7 @@
Aetos Configuration Options
===========================
.. show-options::
:split-namespaces:
aetos

6
doc/source/configuration/index.rst
View File

@@ -2,4 +2,8 @@
Configuration
=============
Configuration of aetos.
.. toctree::
aetos-config-file.rst
aetos-config-options.rst
policy.rst
sample-policy-yaml.rst

9
doc/source/configuration/policy.rst Normal file
View File

@@ -0,0 +1,9 @@
======================================
Aetos Sample Policy Configuration File
======================================
The following is an overview of all available policies in Aetos.
For a sample configuration file, refer to :doc:`sample-policy-yaml`.
.. show-policy::
:config-file: ../../etc/aetos/aetos-policy-generator.conf

8
doc/source/configuration/sample-policy-yaml.rst Normal file
View File

@@ -0,0 +1,8 @@
===========
policy.yaml
===========
Use the ``policy.yaml`` file to define additional access controls that will be
applied to Aetos:
.. literalinclude:: ../_static/aetos.policy.yaml.sample

40
doc/source/contributor/api.rst Normal file
View File

@@ -0,0 +1,40 @@
=========
Aetos API
=========
Aetos API is currently a minimal subset of `Prometheus API
<https://prometheus.io/docs/prometheus/latest/querying/api/>`_
as required by the observabilityclient and Watcher.
Regular API
===========
.. rest-controller:: aetos.controllers.api.v1.label:LabelController
:webprefix: /api/v1/label/<name>/values
.. rest-controller:: aetos.controllers.api.v1.labels:LabelsController
:webprefix: /api/v1/labels
.. rest-controller:: aetos.controllers.api.v1.query:QueryController
:webprefix: /api/v1/query
.. rest-controller:: aetos.controllers.api.v1.series:SeriesController
:webprefix: /api/v1/series
.. rest-controller:: aetos.controllers.api.v1.status:StatusController
:webprefix: /api/v1/status
.. rest-controller:: aetos.controllers.api.v1.targets:TargetsController
:webprefix: /api/v1/targets
Admin API
=========
.. rest-controller:: aetos.controllers.api.v1.admin.tsdb.clean_tombstones:CleanTombstonesController
:webprefix: /api/v1/admin/tsdb/clean_tombstones
.. rest-controller:: aetos.controllers.api.v1.admin.tsdb.delete_series:DeleteSeriesController
:webprefix: /api/v1/admin/tsdb/delete_series
.. rest-controller:: aetos.controllers.api.v1.admin.tsdb.snapshot:SnapshotController
:webprefix: /api/v1/admin/tsdb/snapshot

26
doc/source/contributor/architecture.rst Normal file
View File

@@ -0,0 +1,26 @@
===================
System Architecture
===================
Aetos is a reverse-proxy, which should be used together with Prometheus.
It implements a subset of Prometheus API to support observabilityclient's and
Watcher's access to Prometheus. Using Aetos provides OpenStack authentication
and multi-tenancy support to Prometheus.
On most endpoints Aetos recognizes 2 types of access:
- privileged
- nonprivileged
Privileged access is by default automatically allowed for admin and service
users and it allows sending requests without any restrictions. Privileged
users can retrieve any metric from any project at any time. These users can
also retrieve metrics coming from other sources than ceilometer, which
typically lack openstack project labels.
Nonprivileged access is allowed for users with the reader or member role.
These users cat retrieve metrics from their current project only. Aetos
will automatically modify each request to prevent access to metrics from
other projects.
Privileged and unprivileged access can be configured for each endpoint
separately by modifying policies.

51
doc/source/contributor/contributing.rst
View File

@@ -1,6 +1,6 @@
============================
So You Want to Contribute...
============================
=====================
Contributing to Aetos
=====================
For general information on contributing to OpenStack, please check out the
`contributor guide <https://docs.openstack.org/contributors/>`_ to get started.
@@ -13,36 +13,12 @@ with aetos.
Communication
~~~~~~~~~~~~~
.. This would be a good place to put the channel you chat in as a project; when/
where your meeting is, the tags you prepend to your ML threads, etc.
:Mailing list: http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss (prefix subjects with ``[Aetos]`` for faster responses)
:IRC: #openstack-telemetry
Contacting the Core Team
~~~~~~~~~~~~~~~~~~~~~~~~
.. This section should list the core team, their irc nicks, emails, timezones
etc. If all this info is maintained elsewhere (i.e. a wiki), you can link to
that instead of enumerating everyone here.
New Feature Planning
~~~~~~~~~~~~~~~~~~~~
.. This section is for talking about the process to get a new feature in. Some
projects use blueprints, some want specs, some want both! Some projects
stick to a strict schedule when selecting what new features will be reviewed
for a release.
Task Tracking
~~~~~~~~~~~~~
.. This section is about where you track tasks- launchpad? storyboard? is there
more than one launchpad project? what's the name of the project group in
storyboard?
We track our tasks in Launchpad
https://bugs.launchpad.net/aetos
If you're looking for some smaller, easier work item to pick up and get started
on, search for the 'low-hanging-fruit' tag.
.. NOTE: If your tag is not 'low-hanging-fruit' please change the text above.
:List of telemetry core members: https://review.opendev.org/admin/groups/7586a97d8db096591fa23b5632df561896dae55a,members
Reporting a Bug
~~~~~~~~~~~~~~~
@@ -52,18 +28,3 @@ Reporting a Bug
You found an issue and want to make sure we are aware of it? You can do so on
`Launchpad
<https://bugs.launchpad.net/aetos>`_.
Getting Your Patch Merged
~~~~~~~~~~~~~~~~~~~~~~~~~
.. This section should have info about what it takes to get something merged. Do
you require one or two +2's before +W? Do some of your repos require unit
test changes with all patches? etc.
Project Team Lead Duties
~~~~~~~~~~~~~~~~~~~~~~~~
.. this section is where you can put PTL specific duties not already listed in
the common PTL guide (linked below), or if you already have them written
up elsewhere you can link to that doc here.
All common PTL duties are enumerated in the `PTL guide
<https://docs.openstack.org/project-team-guide/ptl.html>`_.

4
doc/source/contributor/index.rst
View File

@@ -6,4 +6,6 @@
:maxdepth: 2
contributing
api
architecture
install/index

48
doc/source/contributor/install/development.rst Normal file
View File

@@ -0,0 +1,48 @@
==============================
Installing development sandbox
==============================
Configuring devstack
====================
.. index::
double: installing; devstack
1. Download devstack_.
2. Create a ``local.conf`` file as input to devstack.
.. note::
``local.conf`` replaces the former configuration file called ``localrc``.
If you used localrc before, remove it to switch to using the new file.
For further information see the `devstack configuration
<https://docs.openstack.org/devstack/latest/configuration.html>`_.
3. The aetos service is not enabled by default, so it must be
enabled in ``local.conf`` before running ``stack.sh``.
This example ``local.conf`` file shows all of the settings required for
aetos, as well as how to deploy ceilometer with prometheus, which is recommended::
[[local|localrc]]
# Configure Ceilometer to send metrics through sg-core to Prometheus
CEILOMETER_BACKEND=sg-core
# Configure Prometheus to scrape sg-core and itself
PROMETHEUS_CUSTOM_SCRAPE_TARGETS="localhost:3000,localhost:9090"
# Enable Ceilometer
enable_plugin ceilometer https://opendev.org/openstack/ceilometer
# Enable Prometheus
enable_plugin devstack-plugin-prometheus https://opendev.org/openstack/devstack-plugin-prometheus
# Enable sg-core for forwarding metrics from Ceilometer to Prometheus
enable_plugin sg-core https://github.com/infrawatch/sg-core
# Enable the Aetos
enable_plugin aetos https://opendev.org/openstack/aetos
.. _devstack: https://docs.openstack.org/devstack/latest/

9
doc/source/contributor/install/index.rst Normal file
View File

@@ -0,0 +1,9 @@
================
Installing Aetos
================
.. toctree::
:maxdepth: 2
development
manual

45
doc/source/contributor/install/manual.rst Normal file
View File

@@ -0,0 +1,45 @@
===========================
Installing Aetos with uwsgi
===========================
The module ``aetos.wsgi.api`` provides the function to set up the WSGI
application. The module is installed with the rest of the Aetos application
code, and should not need to be modified.
Install uwsgi.
On RHEL/CentOS/Fedora::
sudo dnf install uwsgi-plugin-python3
On Ubuntu/Debian::
sudo apt-get install uwsgi-plugin-python3
Create aetos-uwsgi.ini file::
[uwsgi]
chmod-socket = 666
socket = /var/run/uwsgi/aetos.socket
start-time = %t
lazy-apps = true
add-header = Connection: close
buffer-size = 65535
hook-master-start = unix_signal:15 gracefully_kill_them_all
thunder-lock = true
plugins = http,python3
enable-threads = true
worker-reload-mercy = 80
exit-on-reload = false
die-on-term = true
master = true
processes = 2
module = aetos.wsgi.api:application
Then start the uwsgi server::
uwsgi ./aetos-uwsgi.ini
Or start in background with::
uwsgi -d ./aetos-uwsgi.ini

3
doc/source/index.rst
View File

@@ -14,13 +14,10 @@ Contents:
readme
install/index
library/index
contributor/index
configuration/index
cli/index
user/index
admin/index
reference/index
Indices and tables
==================

25
doc/source/install/common_configure.rst
View File

@@ -7,3 +7,28 @@
[DEFAULT]
prometheus_host=localhost
prometheus_port=9090
* In the ``[DEFAULT]`` and ``[keystone_authtoken]`` sections,
configure Identity service access:
.. code-block:: ini
[DEFAULT]
...
auth_strategy = keystone
[keystone_authtoken]
...
www_authenticate_uri = http://controller:5000
auth_url = http://controller:5000
memcached_servers = controller:11211
auth_type = password
project_domain_id = default
user_domain_id = default
project_name = service
username = aetos
password = AETOS_PASS
Replace ``AETOS_PASS`` with the password you chose for
the ``aetos`` user in the Identity service.

107
doc/source/install/common_prerequisites.rst
View File

@@ -2,39 +2,7 @@ Prerequisites
-------------
Before you install and configure the aetos service,
you must create a database, service credentials, and API endpoints.
#. To create the database, complete these steps:
* Use the database access client to connect to the database
server as the ``root`` user:
.. code-block:: console
$ mysql -u root -p
* Create the ``aetos`` database:
.. code-block:: none
CREATE DATABASE aetos;
* Grant proper access to the ``aetos`` database:
.. code-block:: none
GRANT ALL PRIVILEGES ON aetos.* TO 'aetos'@'localhost' \
IDENTIFIED BY 'AETOS_DBPASS';
GRANT ALL PRIVILEGES ON aetos.* TO 'aetos'@'%' \
IDENTIFIED BY 'AETOS_DBPASS';
Replace ``AETOS_DBPASS`` with a suitable password.
* Exit the database access client.
.. code-block:: none
exit;
you must create service credentials, and API endpoints.
#. Source the ``admin`` credentials to gain access to
admin-only CLI commands:
@@ -50,6 +18,18 @@ you must create a database, service credentials, and API endpoints.
.. code-block:: console
$ openstack user create --domain default --password-prompt aetos
User Password:
Repeat User Password:
+---------------------+----------------------------------+
| Field | Value |
+---------------------+----------------------------------+
| domain_id | default |
| enabled | True |
| id | b7657c9ea07a4556aef5d34cf70713a3 |
| name | aetos |
| options | {} |
| password_expires_at | None |
+---------------------+----------------------------------+
* Add the ``admin`` role to the ``aetos`` user:
@@ -57,19 +37,72 @@ you must create a database, service credentials, and API endpoints.
$ openstack role add --project service --user aetos admin
.. note::
This command provides no output.
* Create the aetos service entities:
.. code-block:: console
$ openstack service create --name aetos --description "aetos" aetos
$ openstack service create --name aetos --description "OpenStack Aetos Service" prometheus
+-------------+----------------------------------+
| Field | Value |
+-------------+----------------------------------+
| description | OpenStack Aetos Service |
| enabled | True |
| id | 3405453b14da441ebb258edfeba96d83 |
| name | aetos |
| type | prometheus |
+-------------+----------------------------------+
#. Create the aetos service API endpoints:
.. code-block:: console
$ openstack endpoint create --region RegionOne \
aetos public http://controller:XXXX/vY/%\(tenant_id\)s
prometheus public http://controller/prometheus
+--------------+-----------------------------------+
| Field | Value |
+--------------+-----------------------------------+
| enabled | True |
| id | 1196727cc22a4a26a011688236c38da9 |
| interface | public |
| region | RegionOne |
| region_id | RegionOne |
| service_id | 3405453b14da441ebb258edfeba96d83 |
| service_name | aetos |
| service_type | prometheus |
| url | http://controller/prometheus |
+--------------+-----------------------------------+
$ openstack endpoint create --region RegionOne \
aetos internal http://controller:XXXX/vY/%\(tenant_id\)s
prometheus internal http://controller/prometheus
+--------------+-----------------------------------+
| Field | Value |
+--------------+-----------------------------------+
| enabled | True |
| id | 1196727cc22a4a26a011688236c38da9 |
| interface | internal |
| region | RegionOne |
| region_id | RegionOne |
| service_id | 3405453b14da441ebb258edfeba96d83 |
| service_name | aetos |
| service_type | prometheus |
| url | http://controller/prometheus |
+--------------+-----------------------------------+
$ openstack endpoint create --region RegionOne \
aetos admin http://controller:XXXX/vY/%\(tenant_id\)s
prometheus admin http://controller/prometheus
+--------------+-----------------------------------+
| Field | Value |
+--------------+-----------------------------------+
| enabled | True |
| id | 1196727cc22a4a26a011688236c38da9 |
| interface | admin |
| region | RegionOne |
| region_id | RegionOne |
| service_id | 3405453b14da441ebb258edfeba96d83 |
| service_name | aetos |
| service_type | prometheus |
| url | http://controller/prometheus |
+--------------+-----------------------------------+

14
doc/source/install/get_started.rst
View File

@@ -1,9 +1,15 @@
======================
aetos service overview
Aetos service overview
======================
The aetos service provides...
The aetos service provides a multi-tenancy layer and openstack authentication
for Prometheus.
The aetos service consists of the following components:
``aetos-api`` service
Accepts and responds to end user compute API calls...
``aetos``
A reverse-proxy, which runs on a central management server, preferably on
the same one which runs Prometheus. It provides a subset of Prometheus
API. For each request an authentication token is checked before forwarding
it to Prometheus. Two privilege levels are recognized. When accessing
with lower privilege, which typically means access by a non-admin user,
the request is restricted to metrics from the current project only.

10
doc/source/install/index.rst
View File

@@ -1,6 +1,6 @@
================================
aetos service installation guide
================================
==================
Installation Guide
==================
.. toctree::
:maxdepth: 2
@@ -10,8 +10,8 @@ aetos service installation guide
verify.rst
next-steps.rst
The aetos service (aetos) provides...
The aetos service (aetos) provides multi-tenancy layer for Prometheus.
This chapter assumes a working setup of OpenStack following the
`OpenStack Installation Tutorial
<https://docs.openstack.org/project-install-guide/ocata/>`_.
<https://docs.openstack.org/install-guide/>`_.

2
doc/source/install/install.rst
View File

@@ -8,7 +8,7 @@ aetos service, code-named aetos, on the controller node.
This section assumes that you already have a working OpenStack
environment with at least the following components installed:
.. (add the appropriate services here and further notes)
Prometheus
Note that installation and configuration vary by distribution.

2
doc/source/install/next-steps.rst
View File

@@ -6,4 +6,4 @@ Next steps
Your OpenStack environment now includes the aetos service.
To add additional services, see
https://docs.openstack.org/project-install-guide/ocata/.
`OpenStack Installation Tutorials and Guides <https://docs.openstack.org/latest/install>`_.

22
doc/source/install/verify.rst
View File

@@ -9,6 +9,14 @@ Verify operation of the aetos service.
Perform these commands on the controller node.
.. note::
The following assumes Ceilometer is installed and Prometheus is
configured to scrape metrics from Ceilometer. The
``ceilometer_image_size`` metric is used for the verification. A
working Image service with an image stored is required to get the
``ceilometer_image_size`` metric.
#. Source the ``admin`` project credentials to gain access to
admin-only CLI commands:
@@ -16,9 +24,17 @@ Verify operation of the aetos service.
$ . admin-openrc
#. List service components to verify successful launch and registration
of each process:
#. Query for the ceilometer_image_size metric and see if data is returned:
.. code-block:: console
$ openstack aetos service list
$ openstack metric query ceilometer_image_size
+----------+----------+----------+----------+---------+----------+-----------+----------+---------------+------+------+----------+
| __name__ | counter | image | instance | job | project | publisher | resource | resource_name | type | unit | value |
+----------+----------+----------+----------+---------+----------+-----------+----------+---------------+------+------+----------+
| ceilomet | image.si | 6b51fba6 | localhos | sg-core | 2dd8edd6 | localhost | 6b51fba6 | Fedora-Cloud- | size | B | 49283072 |
| er_image | ze | -8b74-4b | t:3000 | | c8c24f49 | .localdom | -8b74-4b | Base-37-1.7.x | | | 0 |
| _size | | d4-be53- | | | bf046705 | ain | d4-be53- | 86_64 | | | |
| | | 25e509ea | | | 34f6b357 | | 25e509ea | | | | |
| | | 0aaf | | | | | 0aaf | | | | |
+----------+----------+----------+----------+---------+----------+-----------+----------+---------------+------+------+----------+

7
doc/source/library/index.rst
View File

@@ -1,7 +0,0 @@
========
Usage
========
To use aetos in a project::
import aetos

5
doc/source/reference/index.rst
View File

@@ -1,5 +0,0 @@
==========
References
==========
References of aetos.

1
etc/aetos/aetos-config-generator.conf
View File

@@ -7,3 +7,4 @@ namespace = oslo.middleware.cors
namespace = oslo.middleware.healthcheck
namespace = oslo.middleware.http_proxy_to_wsgi
namespace = oslo.policy
namespace = keystonemiddleware.auth_token

7
tox.ini
View File

@@ -37,8 +37,11 @@ commands =
coverage xml -o cover/coverage.xml
[testenv:docs]
deps = -r{toxinidir}/doc/requirements.txt
commands = sphinx-build -W -b html doc/source doc/build/html
deps =
-c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master}
-r{toxinidir}/requirements.txt
-r{toxinidir}/doc/requirements.txt
commands = sphinx-build --keep-going -b html doc/source doc/build/html
[testenv:releasenotes]
deps = {[testenv:docs]deps}