Metadata-Version: 1.1
Name: almanach
Version: 3.2.1
Summary: Stores usage of OpenStack volumes and instances for each tenant
Home-page: https://github.com/internap/almanach
Author: Internap Hosting
Author-email: opensource@internap.com
License: Apache-2
Description: 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.
        
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 2.7
