Convert Markdown to reStructuredText format
Change-Id: I8094a23cc6d32c6fc280b89a2633dd80b001398a
This commit is contained in:
Frédéric Guillot
parent
3ace712f06
commit
4f9fe41f51
231
README.md
231
README.md
@ -1,231 +0,0 @@
|
||||
Almanach
|
||||
========
|
||||
|
||||
[](https://travis-ci.org/internap/almanach)
|
||||
[](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.
|
||||
42
README.rst
Normal file
42
README.rst
Normal file
@ -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.
|
||||
@ -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`
|
||||
|
||||
@ -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
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user