From 4f9fe41f5105ee8be03a6efd51a92e7a624176f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Guillot?= Date: Wed, 17 Aug 2016 17:11:32 -0400 Subject: [PATCH] Convert Markdown to reStructuredText format Change-Id: I8094a23cc6d32c6fc280b89a2633dd80b001398a --- README.md | 231 ------------------------------------------- README.rst | 42 ++++++++ doc/source/index.rst | 222 +++++++++++++++++++++++++++++++++++++++++ setup.cfg | 2 +- 4 files changed, 265 insertions(+), 232 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/README.md b/README.md deleted file mode 100644 index 7fac4ff..0000000 --- a/README.md +++ /dev/null @@ -1,231 +0,0 @@ -Almanach -======== - -[![Build Status](https://travis-ci.org/internap/almanach.svg?branch=master)](https://travis-ci.org/internap/almanach) -[![PyPI version](https://badge.fury.io/py/almanach.svg)](https://badge.fury.io/py/almanach) - -Almanach stores the utilization of OpenStack resources (instances and volumes) for each tenant. - -What is Almanach? ------------------ - -The main purpose of this software is to bill customers based on their usage of the cloud infrastructure. - -Almanach is composed of two parts: - -- **Collector**: Listen for OpenStack events and store the relevant information in the database. -- **REST API**: Expose the information collected to external systems. - -Resources ---------- - -### Launchpad Projects - -- https://launchpad.net/almanach - -### Blueprints - -- https://blueprints.launchpad.net/almanach - -### Bug Tracking - -- https://bugs.launchpad.net/almanach - -Requirements ------------- - -- OpenStack infrastructure installed (Nova, Cinder...) -- MongoDB -- Python 2.7 - -Command line usage ------------------- - -Usage: - -```bash -usage: almanach [-h] [--logging LOGGING] {api,collector} config_file -``` - -Start the API daemon: - -```bash -almanach api /path/to/almanach.cfg -``` - -Start the collector: - -```bash -almanach collector /path/to/almanach.cfg -``` - -Custom logging configuration: - -```bash -almanach collector /path/to/almanach.cfg --logging /path/to/logging.cfg -``` - -The syntax of the logging configuration file is available in the official [Python documentation](https://docs.python.org/2/library/logging.config.html). - -Authentication --------------- - -### Protocol - -The authentication mechanism use the HTTP header `X-Auth-Token` to send a token. -This token is validated through Keystone or with the config file (private secret key). - -``` -GET /volume_types HTTP/1.1 -X-Auth-Token: secret -Content-Type: application/json - -{} -``` - -If the token is not valid, you will receive a `401 Not Authorized` response. - -### Private Key Authentication - -The private secret key authentication is the default method. -In your config file, you have to define your private key in the field `auth_token`: - -``` -[ALMANACH] -auth_token=my secret token -``` - -### Keystone Authentication - -The token will be validated with Keystone. -To use this authentication backend you have to define the authentication strategy to `keystone`. - -``` -[ALMANACH] -auth_strategy=keystone - -[KEYSTONE] -username=my_service_username -password=my_service_password -tenant_name=my_service_tenant_name -auth_url=http://keystone_url:5000/v2.0 -``` - -Environment variables ---------------------- - -You can override the configuration parameters by using environment variables: - -```bash -export RABBITMQ_URL="amqp://openstack:openstack@hostname:5672" -almanach collector /path/to/almanach.cfg -``` - -Running Almanach with Docker ----------------------------- - -The actual Docker configuration assume that you already have RabbitMQ (mandatory for Openstack) and MongoDB configured for Almanach. - -```bash -export RABBITMQ_URL="amqp://guest:guest@messaging:5672/" -export MONGODB_URL="mongodb://almanach:almanach@database:27017/almanach" - -docker-compose build -docker-compose up -``` - -The command `docker-compose up` starts 2 containers: the collector and the API server. -The environment variables `RABBITMQ_URL` and `MONGODB_URL` are mandatory. - -RabbitMQ configuration ----------------------- - -Each OpenStack services (Nova, Cinder, Neutron) need to be configured to send notifications to the Almanach queue. - -For example with Nova, add the topic "almanach" in the config file `/etc/nova.conf`: - -```bash -notification_topics=almanach -``` - -Database configuration ----------------------- - -Almanach requires a specific user to connect to the database. -To create a new user, open a new MongoDB shell: - -```javascript -m = new Mongo() -m.getDB("almanach").createUser({user: "almanach", pwd: "almanach", roles: [{role: "readWrite", db: "almanach"}]}) -``` - -Database entities ------------------ - -Each entity have at least these properties: - -- `entity_id`: Unique id for the entity (UUID) -- `entity_type`: "instance" or "volume" -- `project_id`: Tenant unique ID (UUID) -- `start`: Start date of the resource usage -- `end`: End date of the resource usage or `null` if the resource still in use by the tenant -- `name`: Resource name - -### Compute Object - -```json -{ - "entity_id": "UUID", - "entity_type": "instance", - "project_id": "UUID", - "start": "2014-01-01T06:00:00.000Z", - "end": null, - "last_event": "2014-01-01T06:00:00.000Z", - "flavor": "MyFlavor1", - "os": { - "distro": "ubuntu", - "version": "14.04" - }, - "name": "my-virtual-machine.domain.tld" -} -``` - -### Block Storage Object - -```json -{ - "entity_id": "UUID", - "entity_type": "volume", - "project_id": "UUID", - "start": "2014-01-01T06:00:00.000Z", - "end": null, - "last_event": "2014-01-01T06:00:00.000Z", - "volume_type": "MyVolumeType", - "size": 50, - "name": "my-virtual-machine.domain.tld-volume", - "attached_to": "UUID" -} -``` - -List of events handled ----------------------- - -Almanach will process those events: - -- `compute.instance.create.end` -- `compute.instance.delete.end` -- `compute.instance.resize.confirm.end` -- `compute.instance.rebuild.end` -- `volume.create.end` -- `volume.delete.end` -- `volume.resize.end` -- `volume.attach.end` -- `volume.detach.end` -- `volume.update.end` -- `volume.exists` -- `volume_type.create` - -License -------- - -Almanach is distributed under Apache 2.0 LICENSE. diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..e4332ef --- /dev/null +++ b/README.rst @@ -0,0 +1,42 @@ +======== +Almanach +======== + + +.. image:: https://badge.fury.io/py/almanach.svg + :target: https://badge.fury.io/py/almanach + +Almanach stores the utilization of OpenStack resources (instances and volumes) for each tenant. + +What is Almanach? +----------------- + +The main purpose of this software is to bill customers based on their usage of the cloud infrastructure. + +Almanach is composed of two parts: + +- **Collector**: Listen for OpenStack events and store the relevant information in the database. +- **REST API**: Expose the information collected to external systems. + +Resources +--------- + +Launchpad Projects +~~~~~~~~~~~~~~~~~~ + +- https://launchpad.net/almanach + +Blueprints +~~~~~~~~~~ + +- https://blueprints.launchpad.net/almanach + +Bug Tracking +~~~~~~~~~~~~ + +- https://bugs.launchpad.net/almanach + +License +------- + +Almanach is distributed under Apache 2.0 LICENSE. diff --git a/doc/source/index.rst b/doc/source/index.rst index 2ead5d3..ede8e66 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -16,3 +16,225 @@ Welcome to the Almanach documentation! ====================================== Almanach stores the utilization of OpenStack resources (instances and volumes) for each tenant. + +What is Almanach? +----------------- + +The main purpose of this software is to bill customers based on their usage of the cloud infrastructure. + +Almanach is composed of two parts: + +- **Collector**: Listen for OpenStack events and store the relevant information in the database. +- **REST API**: Expose the information collected to external systems. + +Requirements +------------ + +- OpenStack infrastructure installed (Nova, Cinder...) +- MongoDB +- Python 2.7 + +Command line usage +------------------ + +Usage: + +.. code:: bash + + usage: almanach [-h] [--logging LOGGING] {api,collector} config_file + + +Start the API daemon: + +.. code:: bash + + almanach api /path/to/almanach.cfg + + +Start the collector: + +.. code:: bash + + almanach collector /path/to/almanach.cfg + + +Custom logging configuration: + +.. code:: bash + + almanach collector /path/to/almanach.cfg --logging /path/to/logging.cfg + + +The syntax of the logging configuration file is available in the official [Python documentation](https://docs.python.org/2/library/logging.config.html). + +Authentication +-------------- + +Protocol +~~~~~~~~ + +The authentication mechanism use the HTTP header :code:`X-Auth-Token` to send a token. +This token is validated through Keystone or with the config file (private secret key). + +:: + + GET /volume_types HTTP/1.1 + X-Auth-Token: secret + Content-Type: application/json + + {} + + +If the token is not valid, you will receive a :code:`401 Not Authorized` response. + +Private Key Authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The private secret key authentication is the default method. +In your config file, you have to define your private key in the field :code:`auth_token`: + +:: + + [ALMANACH] + auth_token=my secret token + + +Keystone Authentication +~~~~~~~~~~~~~~~~~~~~~~~ + +The token will be validated with Keystone. +To use this authentication backend you have to define the authentication strategy to :code:`keystone`. + +:: + + [ALMANACH] + auth_strategy=keystone + + [KEYSTONE] + username=my_service_username + password=my_service_password + tenant_name=my_service_tenant_name + auth_url=http://keystone_url:5000/v2.0 + + +Environment variables +--------------------- + +You can override the configuration parameters by using environment variables: + +.. code:: bash + + export RABBITMQ_URL="amqp://openstack:openstack@hostname:5672" + almanach collector /path/to/almanach.cfg + + +Running Almanach with Docker +---------------------------- + +The actual Docker configuration assume that you already have RabbitMQ (mandatory for Openstack) and MongoDB configured for Almanach. + +.. code:: bash + + export RABBITMQ_URL="amqp://guest:guest@messaging:5672/" + export MONGODB_URL="mongodb://almanach:almanach@database:27017/almanach" + + docker-compose build + docker-compose up + + +The command :code:`docker-compose up` starts 2 containers: the collector and the API server. +The environment variables :code:`RABBITMQ_URL` and :code:`MONGODB_URL` are mandatory. + +RabbitMQ configuration +---------------------- + +Each OpenStack services (Nova, Cinder, Neutron) need to be configured to send notifications to the Almanach queue. + +For example with Nova, add the topic "almanach" in the config file :code:`/etc/nova.conf`: + +.. code:: bash + + notification_topics=almanach + + +Database configuration +---------------------- + +Almanach requires a specific user to connect to the database. +To create a new user, open a new MongoDB shell: + +.. code:: javascript + + m = new Mongo() + m.getDB("almanach").createUser({user: "almanach", pwd: "almanach", roles: [{role: "readWrite", db: "almanach"}]}) + + +Database entities +----------------- + +Each entity have at least these properties: + +- :code:`entity_id`: Unique id for the entity (UUID) +- :code:`entity_type`: "instance" or "volume" +- :code:`project_id`: Tenant unique ID (UUID) +- :code:`start`: Start date of the resource usage +- :code:`end`: End date of the resource usage or :code:`null` if the resource still in use by the tenant +- :code:`name`: Resource name + +Compute Object +~~~~~~~~~~~~~~ + +.. code:: json + + { + "entity_id": "UUID", + "entity_type": "instance", + "project_id": "UUID", + "start": "2014-01-01T06:00:00.000Z", + "end": null, + "last_event": "2014-01-01T06:00:00.000Z", + "flavor": "MyFlavor1", + "os": { + "distro": "ubuntu", + "version": "14.04" + }, + "name": "my-virtual-machine.domain.tld" + } + + +Block Storage Object +~~~~~~~~~~~~~~~~~~~~ + +.. code:: json + + { + "entity_id": "UUID", + "entity_type": "volume", + "project_id": "UUID", + "start": "2014-01-01T06:00:00.000Z", + "end": null, + "last_event": "2014-01-01T06:00:00.000Z", + "volume_type": "MyVolumeType", + "size": 50, + "name": "my-virtual-machine.domain.tld-volume", + "attached_to": "UUID" + } + + +List of events handled +---------------------- + +Almanach will process those events: + +- :code:`compute.instance.create.end` +- :code:`compute.instance.delete.end` +- :code:`compute.instance.resize.confirm.end` +- :code:`compute.instance.rebuild.end` +- :code:`volume.create.end` +- :code:`volume.delete.end` +- :code:`volume.resize.end` +- :code:`volume.attach.end` +- :code:`volume.detach.end` +- :code:`volume.update.end` +- :code:`volume.exists` +- :code:`volume_type.create` diff --git a/setup.cfg b/setup.cfg index 130e974..fd43717 100644 --- a/setup.cfg +++ b/setup.cfg @@ -7,7 +7,7 @@ home-page = https://github.com/internap/almanach license = Apache-2 summary = Stores usage of OpenStack volumes and instances for each tenant description-file = - README.md + README.rst classifier = Development Status :: 5 - Production/Stable Intended Audience :: Developers