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,
you must follow the steps in this page:
If you're interested in contributing to the Bilean project,
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
should be submitted for review via the Gerrit tool, following
the workflow documented at:
In order to contribute to the Bilean project, you need to have
signed OpenStack's contributor's agreement:
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.
The team is using the #openstack-bilean channel on freenode.net.
* Wiki
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

15
devstack/README.rst
View File

@ -2,25 +2,32 @@
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::
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
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::
4. Then run devstack normally.
::
cd /opt/stack/devstack
./stack.sh

56
doc/source/conf.py
View File

@ -15,8 +15,6 @@
import os
import sys
import openstackdocstheme
sys.path.insert(0, os.path.abspath('../..'))
# -- 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 = [
'sphinx.ext.autodoc',
# 'sphinx.ext.todo'
'sphinx.ext.intersphinx',
# 'sphinx.ext.intersphinx',
'oslosphinx'
]
@ -33,9 +30,6 @@ extensions = [
# text edit cycles.
# 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.
source_suffix = '.rst'
@ -46,40 +40,6 @@ master_doc = 'index'
project = u'bilean'
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.
add_function_parentheses = True
@ -92,15 +52,12 @@ pygments_style = 'sphinx'
# -- 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']
# 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.
htmlhelp_basename = '%sdoc' % project
@ -116,6 +73,3 @@ latex_documents = [
# Example configuration for intersphinx: refer to the Python standard library.
# 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

113
doc/source/install.rst
View File

@ -17,14 +17,59 @@
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
~~~~~~~~~~~~~~~~~~~~
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
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
2. Install Bilean with required packages.
::
@ -34,9 +79,7 @@ Installation
3. Register Bilean service with keystone.
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
@ -47,17 +90,17 @@ Installation
::
$ cd /opt/stack/bilean
$ tools/gen-config
$ 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
Edit file :file:`/etc/bilean/bilean.conf` according to your system settings.
The most common options to be customized include:
5. Modify configuration file.
::
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
@ -82,21 +125,57 @@ The most common options to be customized include:
rabbit_hosts = <HOST>
rabbit_password = <RABBIT PASSWORD>
5. Create Bilean Database
6. Create Bilean Database
Create Bilean database using the :command:`bilean-db-recreate` script under
the :file:`tools` subdirectory.
::
the :file:`tools` subdirectory::
$ cd /opt/stack/bilean/tools
$ ./bilean-db-recreate <DB PASSWORD>
6. Start bilean engine and api service.
7. Start bilean services.
You may need two consoles for the services each.
::
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.
::
$ 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 |
+----------------------------------+--------------------+---------+--------+------+--------+

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
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
provided by other OpenStack components such as Nova, then converts notifications
into billing resources and sends to :program:`bilean-engine` over AMQP.
The :program:`bilean-scheduler` manages jobs related to users and scheduler job
to engine to execute it.
bilean-engine
-------------
@ -54,6 +53,13 @@ bilean-engine
The :program:`bilean-engine` does the main billing work, operates all users,
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
~~~~~~~~~~~~