stackforge/bufunfa
Code Issues Proposed changes

Fix documentation

Browse Source
This commit is contained in:
Endre Karlson 2012-11-03 00:46:29 +01:00
parent 61bc365d60
commit 7bc2c010e9
9 changed files with 659 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
doc/requirements.txt Normal file
View File

@ -0,0 +1,20 @@
Flask==0.9
iso8601>=0.1.4
eventlet
sqlalchemy>=0.7
jsonschema>=0.6
PasteDeploy
# Needed for Keystone Middleware
https://launchpad.net/keystone/folsom/2012.2/+download/keystone-2012.2.tar.gz#egg=keystone
python-keystoneclient
# Optional Stuff that is used by default
kombu
nose
mox
coverage
pep8==1.3.3
openstack.nose_plugin
sphinx
sphinxcontrib-httpdomain

39
doc/source/architecture.rst Normal file
View File

@ -0,0 +1,39 @@
..
Copyright 2012 Endre Karlson for Bouvet ASA
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _architecture:
============
Architecture
============
.. index::
double: architecture; brief
Brief overview
++++++++++++++
:term:`central` is the central component that stores data persistantly in
:term:`storage` which is a backend using typically SQLAlchemy, MongoDB or
others.
:term:`recorder` is the component that will fetch records from external
datasources. This can look a bit like Ceilometer's agents but it's not
quite. It loads difference "plugins" which it uses to poll data and
transforms the data into a :term:`record`.
:term:`api` standard OpenStack alike REST api service that communicates via
:term:`mq` to :term:`central` in order to do actions like adding
records and so on.

243
doc/source/conf.py Normal file
View File

@ -0,0 +1,243 @@
# -*- coding: utf-8 -*-
#
# bufunfa documentation build configuration file, created by
# sphinx-quickstart on Wed Oct 31 18:58:17 2012.
#
# This file is execfile()d with the current directory set to its containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys, os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinxcontrib.httpdomain']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'bufunfa'
copyright = u'2012, Bouvet ASA'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
from bufunfa.version import version_info as bufunfa_version
version = bufunfa_version.canonical_version_string()
# The full version, including alpha/beta/rc tags.
release = bufunfa_version.version_string_with_vcs()
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# -- Options for HTML output ---------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
#html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'bufunfadoc'
# -- Options for LaTeX output --------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'bufunfa.tex', u'bufunfa Documentation',
u'Bouvet ASA', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output --------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'bufunfa', u'bufunfa Documentation',
[u'Bouvet ASA'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output ------------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'bufunfa', u'bufunfa Documentation',
u'Bouvet ASA', 'bufunfa', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'

131
doc/source/configuration.rst Normal file
View File

@ -0,0 +1,131 @@
..
Copyright 2012 Endre Karlson for Bouvet ASA
Copyright 2012 New Dream Network, LLC (DreamHost)
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _configuration:
=======================
Configuration Options
=======================
Bufunfa specific
================
=============================== ==================================== ==============================================================
Parameter Default Note
=============================== ==================================== ==============================================================
api_host 0.0.0.0 API listen host
api_port 0.0.0.0 API listen port
control_exchange bufunfa The MQ Control exchange
worker_topic worker The topic that the Recorder(s) should use
central_topic central The topic that the Central should use
os-username glance Username to use for openstack service access
os-password admin Password to use for openstack service access
os-tenant-id Tenant ID to use for openstack service access
os-tenant-name admin Tenant name to use for openstack service access
os-auth-url http://localhost:5000/v2.0 Auth URL to use for openstack service access
database_connection sqlite:///$pystatepath/bufunfa.db Database connection string
=============================== ==================================== ==============================================================
SQL Alchemy
===========
========================== ==================================== ==============================================================
Parameter Default Note
========================== ==================================== ==============================================================
sql_connection_debug 0 Verbosity of SQL debugging information. 0=None, 100=Everything
sql_connection_trace False Add python stack traces to SQL as comment strings
sql_idle_timeout 3600 timeout before idle sql connections are reaped
sql_max_retries 10 maximum db connection retries during startup.
(setting -1 implies an infinite retry count)
sql_retry_interval 10 interval between retries of opening a sql connection
mysql_engine InnoDB MySQL engine to use
sqlite_synchronous True If passed, use synchronous mode for sqlite
========================== ==================================== ==============================================================
General options
===============
The following is the list of openstack-common options that we use:
=========================== ==================================== ==============================================================
Parameter Default Note
=========================== ==================================== ==============================================================
default_notification_level INFO Default notification level for outgoing notifications
default_publisher_id $host Default publisher_id for outgoing notifications
bind_host 0.0.0.0 IP address to listen on
bind_port 9001 Port numver to listen on
port 5672 Rabbit MQ port to liste on
fake_rabbit False If passed, use a fake RabbitMQ provider
publish_errors False publish error events
use_stderr True Log output to standard error
logfile_mode 0644 Default file mode used when creating log files
logdir Log output to a per-service log file in named directory
logfile Log output to a named file
default_log_levels ['amqplib=WARN',sqlalchemy=WARN,...] Default log level per components
notification_topics ['notifications', ] AMQP topic used for openstack notifications
enabled_apis ['ec2', 'osapi_compute'] List of APIs to enable by default
verbose False Print more verbose output
debug False Print debugging output
state_path currentdir Top-level directory for maintaining nova state
sqlite_db nova.sqlite file name for sqlite
matchmaker_ringfile /etc/bufunfa/matchmaker_ring.json Matchmaker ring file (JSON)
rpc_zmq_bind_address '*' ZeroMQ bind address
rpc_zmq_matchmaker bufunfa.openstack.common.rpc. MatchMaker drivers
matchmaker.MatchMakerLocalhost
rpc_zmq_port 9501 ZeroMQ receiver listening port
rpc_zmq_port_pub 9502 ZeroMQ fanout publisher port
rpc_zmq_contexts 1 Number of ZeroMQ contexts
rpc_zmq_ipc_dir /var/run/openstack Directory for holding IPC sockets
rabbit_port 5672 The RabbitMQ broker port where a single node is used
rabbit_host localhost The RabbitMQ broker address where a single node is used
rabbit_hosts ['$rabbit_host:$rabbit_port'] The list of rabbit hosts to listen to
rabbit_userid guest the RabbitMQ userid
rabbit_password guest the RabbitMQ password
rabbit_virtual_host / the RabbitMQ virtual host
rabbit_retry_interval 1 how frequently to retry connecting with RabbitMQ
rabbit_retry_backoff 2 how long to backoff for between retries when connecting
rabbit_max_retries 0 maximum retries with trying to connect to RabbitMQ
(the default of 0 implies an infinite retry count)
rabbit_durable_queues False use durable queues in RabbitMQ
rabbit_use_ssl False connect over SSL for RabbitMQ
rabbit_durable_queues False use durable queues in RabbitMQ
rabbit_ha_queues False use H/A queues in RabbitMQ (x-ha-policy: all).
kombu_ssl_version SSL version to use (valid only if SSL enabled)
kombu_ssl_keyfile SSL key file (valid only if SSL enabled)
kombu_ssl_certfile SSL cert file (valid only if SSL enabled)
kombu_ssl_ca_certs SSL certification authority file
qpid_hostname localhost Qpid broker hostname
qpid_port 5672 Qpid broker port
qpid_username Username for qpid connection
qpid_password Password for qpid connection
qpid_sasl_mechanisms Space separated list of SASL mechanisms to use for auth
qpid_reconnect_timeout 0 Reconnection timeout in seconds
qpid_reconnect_limit 0 Max reconnections before giving up
qpid_reconnect_interval_min 0 Minimum seconds between reconnection attempts
qpid_reconnect_interval_max 0 Maximum seconds between reconnection attempts
qpid_reconnect_interval 0 Equivalent to setting max and min to the same value
qpid_heartbeat 60 Seconds between connection keepalive heartbeats
qpid_protocol tcp Transport to use, either 'tcp' or 'ssl'
qpid_reconnect True Automatically reconnect
qpid_tcp_nodelay True Disable Nagle algorithm
rpc_backend kombu The messaging module to use, defaults to kombu.
rpc_thread_pool_size 64 Size of RPC thread pool
rpc_conn_pool_size 30 Size of RPC connection pool
rpc_response_timeout 60 Seconds to wait for a response from call or multicall
rpc_cast_timeout 30 Seconds to wait before a cast expires (TTL).
Only supported by impl_zmq.
=========================== ==================================== ==============================================================

42
doc/source/glossary.rst Normal file
View File

@ -0,0 +1,42 @@
..
Copyright 2012 Endre Karlson for Bouvet ASA
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _architecture:
============
Glossary
============
.. glossary::
recorder
Agent that polls or receives data, generalizes it according to
:term:`record` and sends it to :term:`central` for storage.
central
Software service running on a central management node that stores
information persistantly in a backend storage using a configurable driver
like SQLAlchemy or other.
api
HTTP REST API service for Bufunfa
mq
A message queue, typically something like RabbitMQ or ZeroMQ
storage
A backend for storing data/information persistantly. Typically MongoDB or
a SQL based server software.
record
A Record is typically something that's been metered, the record is a
simple piece of information that holds general info that's needed to
process billing info + extra if wanted.

26
doc/source/index.rst Normal file
View File

@ -0,0 +1,26 @@
.. bufunfa documentation master file, created by
sphinx-quickstart on Wed Oct 31 18:58:17 2012.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Bufunfa's documentation!
===================================
Contents:
.. toctree::
:maxdepth: 2
architecture
configuration
install
glossary
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

145
doc/source/install.rst Normal file
View File

@ -0,0 +1,145 @@
..
Copyright 2012 Endre Karlson for Bouvet ASA
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _install:
========================
Install
========================
bufunfa is comprised of three components for more info on these please
consolidate :architecture:.
.. note::
bufunfa makes extensive use of the messaging bus, but has not
yet been tested with ZeroMQ. We recommend using Rabbit or qpid
for now.
From Packages
+++++++++++++
From Source / GIT
+++++++++++++++++
Common steps
================
.. index::
double: installing; rename_configs
.. note::
The below operations should take place underneath your <project>/etc folder.
** Renaming configuration files is easy if you want to do it one by one then
do::
$ mv bufunfa-central.conf.sample bufunfa-central.conf
** You can also do it in one swoop::
$ rename 's/\.sample$//' *.sample
Installing the Central
======================
.. index::
double: installing; central
1. Clone the bufunfa repo off of github::
$ cd /opt/stack
$ git clone https://github.com/ekarlso/bufunfa.git
2. As a user with ``root`` permissions or ``sudo`` privileges, run the
bufunfa installer::
$ cd bufunfa
$ sudo python setup.py install
3. See :rename_configs:
4. Configure the :term:`central` service
Change the wanted configuration settings to match your environment
::
$ vi bufunfa-central.conf
Refer to :doc:`configuration` details on configuring the service.
5. Start the central service::
$ bufunfa-central
Installing the Recorder
====================
.. index::
double: installing; recorder
1. Clone the bufunfa repo off of github::
$ cd /opt/stack
$ git clone https://github.com/ekarlso/bufunfa.git
2. As a user with ``root`` permissions or ``sudo`` privileges, run the
bufunfa installer::
$ cd bufunfa
$ sudo python setup.py install
3. See :rename_configs:
4. Configure the :term:`recorder` service
Change the wanted configuration settings to match your environment
::
$ vi bufunfa-recorder.conf
Refer to :doc:`configuration` details on configuring the service.
5. Start the Recorder service::
$ bufunfa-recorder
Installing the API
====================
.. index::
double: installing; api
.. note::
The API Server needs to able to talk to Keystone for AuthN + Z and
communicates via MQ to other services.
1. Clone the bufunfa repo off of github::
$ cd /opt/stack
$ git clone https://github.com/ekarlso/bufunfa.git
2. As a user with ``root`` permissions or ``sudo`` privileges, run the
bufunfa installer::
$ cd bufunfa
$ sudo python setup.py install
3. See :rename_configs:
4. Configure the :term:`api` service
Change the wanted configuration settings to match your environment
::
$ vi bufunfa-api.conf
$ vi bufunfa-api-paste.ini
Refer to :doc:`configuration` details on configuring the service.
5. Start the API service::
$ bufunfa-api

8
setup.cfg
View File

@ -6,3 +6,11 @@ cover-inclusive=true
verbosity=2
detailed-errors=1
where=bufunfa/tests
[build_sphinx]
source-dir = doc/source
build-dir = doc/build
all_files = 1
[upload_docs]
upload-dir = doc/build/html

6
setup.py
View File

@ -21,6 +21,7 @@ from bufunfa.openstack.common import setup as common_setup
from bufunfa.version import version_info as version
install_requires = common_setup.parse_requirements(['tools/pip-requires'])
install_options = common_setup.parse_requirements(['tools/pip-options'])
tests_require = common_setup.parse_requirements(['tools/test-requires'])
setup_require = common_setup.parse_requirements(['tools/setup-requires'])
dependency_links = common_setup.parse_dependency_links([
@ -42,7 +43,10 @@ setup(
setup_requires=setup_require,
install_requires=install_requires,
tests_require=tests_require,
extras_require={'test': tests_require},
extras_require={
'test': tests_require,
'optional': install_options,
},
dependency_links=dependency_links,
scripts=[
'bin/bufunfa-api',