From dd679bba8157ca6df02651f780ec1549734eb096 Mon Sep 17 00:00:00 2001 From: lvdongbing Date: Mon, 23 May 2016 05:06:34 -0400 Subject: [PATCH] Revise install doc As devstack plugin is added, this commit revises install doc about installing bilean via devstack. Change-Id: I6052e83a3d503b941e8fc44a0db9f1f0d73b5816 --- CONTRIBUTING.rst | 51 +++++---- devstack/README.rst | 35 +++--- doc/source/conf.py | 56 +--------- doc/source/contributing.rst | 3 - doc/source/install.rst | 207 +++++++++++++++++++++++++----------- doc/source/overview.rst | 16 ++- 6 files changed, 213 insertions(+), 155 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index ca85fdf..7cc54e1 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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 diff --git a/devstack/README.rst b/devstack/README.rst index 3325f09..7c99755 100644 --- a/devstack/README.rst +++ b/devstack/README.rst @@ -2,25 +2,32 @@ Enabling Bilean in DevStack =========================== -1. Download DevStack: - git clone https://git.openstack.org/openstack-dev/devstack - cd devstack +1. Download 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 + git clone https://git.openstack.org/openstack-dev/devstack + cd devstack -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 ./stack.sh diff --git a/doc/source/conf.py b/doc/source/conf.py index f04f8ee..dce3bd2 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -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 diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 1728a61..ac7b6bc 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1,4 +1 @@ -============ -Contributing -============ .. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/install.rst b/doc/source/install.rst index 76c56a9..6439155 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -17,86 +17,165 @@ 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 - $ git clone https://github.com/lvdongbing/bilean.git +This is the recommended way to install the Bilean service. Please refer to +following detailed instructions. -2. Install Bilean with required packages +1. Download DevStack. -:: + :: - $ cd /opt/stack/bilean - $ sudo pip install -e . + 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. + + :: + + $ cd /opt/stack/bilean + $ sudo pip install -e . 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 - $ ./setup-service + $ source ~/devstack/openrc admin + $ cd /opt/stack/bilean/tools + $ ./setup-service 4. Generate configuration file for the Bilean service. -:: + :: - $ cd /opt/stack/bilean - $ tools/gen-config - $ 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 + $ 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 -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:@127.0.0.1/bilean?charset=utf8 + + [keystone_authtoken] + auth_uri = http://:5000/v3 + auth_version = 3 + cafile = /opt/stack/data/ca-bundle.pem + identity_uri = http://:35357 + admin_user = bilean + admin_password = + admin_tenant_name = service + + [authentication] + auth_url = http://:5000/v3 + service_username = bilean + service_password = + service_project_name = service + + [oslo_messaging_rabbit] + rabbit_userid = + rabbit_hosts = + 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 + +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] - connection = mysql://root:@127.0.0.1/bilean?charset=utf8 + $ 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 | + +----------------------------------+--------------------+---------+--------+------+--------+ - [keystone_authtoken] - auth_uri = http://:5000/v3 - auth_version = 3 - cafile = /opt/stack/data/ca-bundle.pem - identity_uri = http://:35357 - admin_user = bilean - admin_password = - admin_tenant_name = service - - [authentication] - auth_url = http://:5000/v3 - service_username = bilean - service_password = - service_project_name = service - - [oslo_messaging_rabbit] - rabbit_userid = - rabbit_hosts = - 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 - -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 diff --git a/doc/source/overview.rst b/doc/source/overview.rst index 7d367f2..3aa20cc 100644 --- a/doc/source/overview.rst +++ b/doc/source/overview.rst @@ -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 ~~~~~~~~~~~~