x/bilean
Code Issues Proposed changes

Revise install doc

Browse Source 
As devstack plugin is added, this commit revises install doc about
installing bilean via devstack.

Change-Id: I6052e83a3d503b941e8fc44a0db9f1f0d73b5816
This commit is contained in:
lvdongbing 2016-05-23 05:06:34 -04:00
parent 3274078d80
commit dd679bba81
6 changed files with 213 additions and 155 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
CONTRIBUTING.rst
View File

@ -1,28 +1,43 @@
Before You Start ======================
================ Contributing to Bilean
======================
If you would like to contribute to the development of OpenStack, If you're interested in contributing to the Bilean project,
you must follow the steps in this page: the following will help get you started.
http://docs.openstack.org/infra/manual/developers.html Contributor License Agreement
=============================
Once those steps have been completed, changes to OpenStack In order to contribute to the Bilean project, you need to have
should be submitted for review via the Gerrit tool, following signed OpenStack's contributor's agreement:
the workflow documented at:
http://docs.openstack.org/infra/manual/developers.html#development-workflow * http://docs.openstack.org/infra/manual/developers.html
* http://wiki.openstack.org/CLA
Reporting Bugs
==============
Pull requests submitted through Github will be ignored. Project Hosting Details
=======================
Bugs should be filed on Launchpad, not Github: * Bug trackers
* General bilean tracker: https://launchpad.net/bilean
https://bugs.launchpad.net/bilean * Python client tracker: https://launchpad.net/python-bileanclient
Meet the Developers * Mailing list (prefix subjects with ``[Bilean]`` for faster responses)
=================== http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Real-time communication among developers are mostly done via IRC. * Wiki
The team is using the #openstack-bilean channel on freenode.net. https://wiki.openstack.org/wiki/Bilean
* IRC channel
* #openstack-bilean at FreeNode
* Code Hosting
* https://git.openstack.org/cgit/openstack/bilean
* https://git.openstack.org/cgit/openstack/python-bileanclient
* Code Review
* https://review.openstack.org/#/q/bilean+AND+status:+open,n,z
* http://docs.openstack.org/infra/manual/developers.html#development-workflow

35
devstack/README.rst
View File

@ -2,25 +2,32 @@
Enabling Bilean in DevStack Enabling Bilean in DevStack
=========================== ===========================
1. Download DevStack: 1. Download DevStack.
git clone https://git.openstack.org/openstack-dev/devstack
cd devstack
2. Add this repo as an external repository:: ::
cat > /opt/stack/devstack/local.conf << END git clone https://git.openstack.org/openstack-dev/devstack
[[local|localrc]] cd devstack
enable_plugin bilean https://github.com/openstack/bilean master
END
3. Add Plugin Configuration Hooks 2. Add this repo as an external repository.
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.
4. Then run devstack normally:: cat > /opt/stack/devstack/local.conf << END
[[local|localrc]]
enable_plugin bilean https://github.com/openstack/bilean master
END
3. 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.
4. Then run devstack normally.
::
cd /opt/stack/devstack cd /opt/stack/devstack
./stack.sh ./stack.sh

56
doc/source/conf.py
View File

@ -15,8 +15,6 @@
import os import os
import sys import sys
import openstackdocstheme
sys.path.insert(0, os.path.abspath('../..')) sys.path.insert(0, os.path.abspath('../..'))
# -- General configuration ---------------------------------------------------- # -- General configuration ----------------------------------------------------
@ -24,8 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = [ extensions = [
'sphinx.ext.autodoc', 'sphinx.ext.autodoc',
# 'sphinx.ext.todo' # 'sphinx.ext.intersphinx',
'sphinx.ext.intersphinx',
'oslosphinx' 'oslosphinx'
] ]
@ -33,9 +30,6 @@ extensions = [
# text edit cycles. # text edit cycles.
# execute "export SPHINX_DEBUG=1" in your terminal to disable # execute "export SPHINX_DEBUG=1" in your terminal to disable
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames. # The suffix of source filenames.
source_suffix = '.rst' source_suffix = '.rst'
@ -46,40 +40,6 @@ master_doc = 'index'
project = u'bilean' project = u'bilean'
copyright = u'2015, OpenStack Foundation' copyright = u'2015, OpenStack Foundation'
# The version infor for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents
#
# "version" and "release" are used by the "log-a-bug" feature
#
# The short X.Y version.
version = '1.0'
# The full version, including alpha/beta/rc tags.
release = '1.0'
# A few variables have to be set for the log-a-bug feature.
# giturl: The location of conf.py on Git. Must be set manually.
# gitsha: The SHA checksum of the bug description. Extracted from git log.
# bug_tag: Tag for categorizing the bug. Must be set manually.
# bug_project: Launchpad project to file bugs against.
# These variables are passed to the logabug code via html_context.
giturl = u'http://git.openstack.org/cgit/openstack/bilean/tree/doc/source'
git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '"
gitsha = os.popen(git_cmd).read().strip('\n')
bug_tag = "docs"
# source tree
pwd = os.getcwd()
# html_context allows us to pass arbitrary values into the html template
html_context = {"pwd": pwd,
"gitsha": gitsha,
"bug_tag": bug_tag,
"giturl": giturl,
"bug_project": "bilean"}
# If true, '()' will be appended to :func: etc. cross-reference text. # If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = True add_function_parentheses = True
@ -92,15 +52,12 @@ pygments_style = 'sphinx'
# -- Options for HTML output -------------------------------------------------- # -- Options for HTML output --------------------------------------------------
# The theme to use for HTML and HTML Help pages. Major themes that come with
# Sphinx are currently 'default' and 'sphinxdoc'.
# html_theme_path = ["."]
# html_theme = '_theme'
# html_static_path = ['static'] # html_static_path = ['static']
# The theme to use for HTML and HTML Help pages. See the documentation for a
# list of builtin themes.
html_theme = 'openstackdocs'
# Add any paths that contain custom themes here, relative to this directory
html_theme_path = [openstackdocstheme.get_html_theme_path()]
# Output file base name for HTML help builder. # Output file base name for HTML help builder.
htmlhelp_basename = '%sdoc' % project htmlhelp_basename = '%sdoc' % project
@ -116,6 +73,3 @@ latex_documents = [
# Example configuration for intersphinx: refer to the Python standard library. # Example configuration for intersphinx: refer to the Python standard library.
# intersphinx_mapping = {'http://docs.python.org/': None} # intersphinx_mapping = {'http://docs.python.org/': None}
[extensions]
# todo_include_todos = True

3
doc/source/contributing.rst
View File

@ -1,4 +1 @@
============
Contributing
============
.. include:: ../../CONTRIBUTING.rst .. include:: ../../CONTRIBUTING.rst

207
doc/source/install.rst
View File

@ -17,86 +17,165 @@
Installation Installation
============ ============
1. Get Bilean source code from Github There are in general two ways to isntall Bilean service: install via DevStack
or install manually.
:: Install via DevStack
~~~~~~~~~~~~~~~~~~~~
$ cd /opt/stack This is the recommended way to install the Bilean service. Please refer to
$ git clone https://github.com/lvdongbing/bilean.git following detailed instructions.
2. Install Bilean with required packages 1. Download DevStack.
:: ::
$ cd /opt/stack/bilean git clone https://git.openstack.org/openstack-dev/devstack
$ sudo pip install -e . cd devstack
2. 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
3. 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.
4. 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
2. Install Bilean with required packages.
::
$ cd /opt/stack/bilean
$ sudo pip install -e .
3. Register Bilean service with keystone. 3. Register Bilean service with keystone.
This can be done using the :command:`setup-service` script under the This can be done using the :command:`setup-service` script under the
:file:`tools` folder. :file:`tools` folder::
:: $ source ~/devstack/openrc admin
$ cd /opt/stack/bilean/tools
$ source ~/devstack/openrc admin $ ./setup-service <HOST IP> <SERVICE_PASSWORD>
$ cd /opt/stack/bilean/tools
$ ./setup-service <HOST IP> <SERVICE_PASSWORD>
4. Generate configuration file for the Bilean service. 4. Generate configuration file for the Bilean service.
:: ::
$ cd /opt/stack/bilean $ cd /opt/stack/bilean
$ tools/gen-config $ tox -e genconfig
$ sudo mkdir /etc/bilean $ sudo mkdir /etc/bilean
$ sudo cp etc/bilean/api-paste.ini /etc/bilean $ sudo cp etc/bilean/api-paste.ini /etc/bilean
$ sudo cp etc/bilean/policy.json /etc/bilean $ sudo cp etc/bilean/policy.json /etc/bilean
$ sudo cp etc/bilean/resource_definitions.yaml /etc/bilean $ sudo cp etc/bilean/resource_definitions.yaml /etc/bilean
$ sudo cp etc/bilean/bilean.conf.sample /etc/bilean/bilean.conf $ sudo cp etc/bilean/bilean.conf.sample /etc/bilean/bilean.conf
Edit file :file:`/etc/bilean/bilean.conf` according to your system settings. 5. Modify configuration file.
The most common options to be customized include:
Edit file :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>
6. Create Bilean Database
Create Bilean database using the :command:`bilean-db-recreate` script under
the :file:`tools` subdirectory::
$ cd /opt/stack/bilean/tools
$ ./bilean-db-recreate <DB PASSWORD>
7. 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
2. 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.
:: ::
[database] $ bilean user-list
connection = mysql://root:<DB PASSWORD>@127.0.0.1/bilean?charset=utf8 +----------------------------------+--------------------+---------+--------+------+--------+
| 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 |
+----------------------------------+--------------------+---------+--------+------+--------+
[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>
5. Create Bilean Database
Create Bilean database using the :command:`bilean-db-recreate` script under
the :file:`tools` subdirectory.
::
$ cd /opt/stack/bilean/tools
$ ./bilean-db-recreate <DB PASSWORD>
6. Start bilean engine and api service.
You may need two consoles for the services each.
::
$ bilean-engine --config-file /etc/bilean/bilean.conf
$ bilean-api --config-file /etc/bilean/bilean.conf

16
doc/source/overview.rst
View File

@ -41,12 +41,11 @@ bilean-api
The :program:`bilean-api` component provides an OpenStack-native REST API that The :program:`bilean-api` component provides an OpenStack-native REST API that
processes API requests by sending them to the :program:`bilean-engine` over RPC. processes API requests by sending them to the :program:`bilean-engine` over RPC.
bilean-notification bilean-scheduler
------------------- ----------------
The :program:`bilean-notification` component monitors the message bus for data The :program:`bilean-scheduler` manages jobs related to users and scheduler job
provided by other OpenStack components such as Nova, then converts notifications to engine to execute it.
into billing resources and sends to :program:`bilean-engine` over AMQP.
bilean-engine bilean-engine
------------- -------------
@ -54,6 +53,13 @@ bilean-engine
The :program:`bilean-engine` does the main billing work, operates all users, The :program:`bilean-engine` does the main billing work, operates all users,
rules, policies, resources, jobs and events. rules, policies, resources, jobs and events.
bilean-notification
-------------------
The :program:`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 :program:`bilean-engine` over AMQP.
Installation Installation
~~~~~~~~~~~~ ~~~~~~~~~~~~