Welcome to the Bilean documentation!

Bilean is a billing service for OpenStack cloud, it provides trigger-type billing based on other OpenStack services’ notification.

This documentation offers information on how Bilean works and how to contribute to the project.

Overview

The mission for Bilean project is to provide a generic billing service for an OpenStack cloud, it implements trigger-type billing based on other OpenStack services’ notification.

Components

The developers are focusing on creating an OpenStack style project using OpenStack design tenets, implemented in Python. We have started with a close interaction with Heat project.

bilean

The bilean tool is A CLI communicates with the bilean-api to manage rules, policies, users, resources, jobs and events. End developers could also use the Bilean REST API directly.

bilean-api

The bilean-api component provides an OpenStack-native REST API that processes API requests by sending them to the bilean-engine over RPC.

bilean-scheduler

The bilean-scheduler manages jobs related to users and scheduler job to engine to execute it.

bilean-engine

The bilean-engine does the main billing work, operates all users, rules, policies, resources, jobs and events.

bilean-notification

The bilean-notification component monitors the message bus for data provided by other OpenStack components such as Nova, then converts notifications into billing resources and sends to bilean-engine over AMQP.

Installation

You will need to make sure you have a suitable environment for deploying Bilean. Please refer to Installation for detailed instructions on setting up an environment to use the Bilean service.

Installation

There are in general two ways to isntall Bilean service: install via DevStack or install manually.

Install via DevStack

This is the recommended way to install the Bilean service. Please refer to following detailed instructions.

  1. Download DevStack.
git clone https://git.openstack.org/openstack-dev/devstack
cd devstack
  1. Add this repo as an external repository.
cat > /opt/stack/devstack/local.conf << END
[[local|localrc]]
enable_plugin bilean https://github.com/openstack/bilean master
END

  1. Add Plugin Configuration Hooks.

    Bilean service is driven using a plugin mechanism for integrating to other services. Each integrated service may require additional configuration settings. For example, typically, you will need to add the billing_notifications notification topic to each service’s configuration.

  2. Then run devstack normally.

cd /opt/stack/devstack
./stack.sh

Manual Installation

Install Bilean Server

  1. Get Bilean source code from Github.
$ cd /opt/stack
$ git clone https://github.com/lvdongbing/bilean.git
  1. Install Bilean with required packages.
$ cd /opt/stack/bilean
$ sudo pip install -e .

  1. Register Bilean service with keystone.

    This can be done using the setup-service script under the tools folder:

    $ source ~/devstack/openrc admin
$ cd /opt/stack/bilean/tools
$ ./setup-service <HOST IP> <SERVICE_PASSWORD>

  2. Generate configuration file for the Bilean service.

$ cd /opt/stack/bilean
$ tox -e genconfig
$ sudo mkdir /etc/bilean
$ sudo cp etc/bilean/api-paste.ini /etc/bilean
$ sudo cp etc/bilean/policy.json /etc/bilean
$ sudo cp etc/bilean/resource_definitions.yaml /etc/bilean
$ sudo cp etc/bilean/bilean.conf.sample /etc/bilean/bilean.conf

  1. Modify configuration file.

    Edit file /etc/bilean/bilean.conf according to your system settings. The most common options to be customized include:

    [database]
connection = mysql://root:<DB PASSWORD>@127.0.0.1/bilean?charset=utf8

[keystone_authtoken]
auth_uri = http://<HOST>:5000/v3
auth_version = 3
cafile = /opt/stack/data/ca-bundle.pem
identity_uri = http://<HOST>:35357
admin_user = bilean
admin_password = <BILEAN PASSWORD>
admin_tenant_name = service

[authentication]
auth_url = http://<HOST>:5000/v3
service_username = bilean
service_password = <BILEAN PASSWORD>
service_project_name = service

[oslo_messaging_rabbit]
rabbit_userid = <RABBIT USER ID>
rabbit_hosts = <HOST>
rabbit_password = <RABBIT PASSWORD>

  2. Create Bilean Database

    Create Bilean database using the bilean-db-recreate script under the tools subdirectory:

    $ cd /opt/stack/bilean/tools
$ ./bilean-db-recreate <DB PASSWORD>

  3. Start bilean services.

    You may need four consoles for the services each:

    $ bilean-engine --config-file /etc/bilean/bilean.conf
$ bilean-api --config-file /etc/bilean/bilean.conf
$ bilean-scheduler --config-file /etc/bilean/bilean.conf
$ bilean-notification --config-file /etc/bilean/bilean.conf

Install Bilean Client

  1. Get Bilean client code from OpenStack git repository.
$ cd /opt/stack
$ git clone https://git.openstack.org/openstack/python-bileanclient.git
  1. Install Bilean client.
$ cd python-bileanclient
$ sudo pip install -e .

Verify Installation

To check whether Bilean server and Bilean client have been installed successfully, run command bilean user-list in a console. The installation is successful if the command output looks similar to the following.

$ bilean user-list
+----------------------------------+--------------------+---------+--------+------+--------+
| id                               | name               | balance | credit | rate | status |
+----------------------------------+--------------------+---------+--------+------+--------+
| 675f42b2dd3a456c9890350403bce8cf | admin              | 0.0     | 0      | 0.0  | INIT   |
| 927fef3da8194718a9179f4775f5f5ce | service            | 0.0     | 0      | 0.0  | INIT   |
| c688c64711a64d06b90c2b3c5d513dde | demo               | 0.0     | 0      | 0.0  | INIT   |
| e0504e51bd0d4e8886d06bb3cc3e6e80 | alt_demo           | 0.0     | 0      | 0.0  | INIT   |
| e9950cf337be47e68a21c9b20b291142 | invisible_to_admin | 0.0     | 0      | 0.0  | INIT   |
+----------------------------------+--------------------+---------+--------+------+--------+

Contributing to Bilean

If you’re interested in contributing to the Bilean project, the following will help get you started.

Contributor License Agreement

In order to contribute to the Bilean project, you need to have signed OpenStack’s contributor’s agreement:

Indices and tables