Add sphinx documentation
This commit is contained in:
Rob Crittenden
parent
91499c11f7
commit
01463ed19d
2
Makefile
2
Makefile
|
|
@ -1,5 +1,5 @@
|
|||
clean:
|
||||
-rm -rf build dist MANIFEST novajoin.egg-info
|
||||
-rm -rf doc/build build dist MANIFEST novajoin.egg-info
|
||||
-find . -name '*.py[oc]' -exec rm {} \;
|
||||
.PHONY: clean
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,81 @@
|
|||
# -*- coding: utf-8 -*-
|
||||
# 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.
|
||||
|
||||
import os
|
||||
import sys
|
||||
import sphinx_rtd_theme
|
||||
import pbr.version
|
||||
version_info = pbr.version.VersionInfo('ara')
|
||||
|
||||
sys.path.insert(0, os.path.abspath('../..'))
|
||||
# -- General configuration ----------------------------------------------------
|
||||
|
||||
# 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',
|
||||
]
|
||||
|
||||
# autodoc generation is a bit aggressive and a nuisance when doing heavy
|
||||
# text edit cycles.
|
||||
# execute "export SPHINX_DEBUG=1" in your terminal to disable
|
||||
|
||||
# The suffix of source filenames.
|
||||
source_suffix = '.rst'
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'ara'
|
||||
copyright = u'2016, Red Hat'
|
||||
author = 'RDO Community'
|
||||
|
||||
# The short X.Y version.
|
||||
version = version_info.version_string()
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = version_info.release_string()
|
||||
|
||||
# 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
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
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 = 'sphinx_rtd_theme'
|
||||
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = '%sdoc' % project
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title, author, documentclass
|
||||
# [howto/manual]).
|
||||
latex_documents = [
|
||||
('index',
|
||||
'%s.tex' % project,
|
||||
u'%s Documentation' % project,
|
||||
u'Red Hat', 'manual'),
|
||||
]
|
||||
|
||||
# Example configuration for intersphinx: refer to the Python standard library.
|
||||
#intersphinx_mapping = {'http://docs.python.org/': None}
|
||||
|
|
@ -0,0 +1,55 @@
|
|||
Configuration
|
||||
=============
|
||||
|
||||
novajoin is configured via /etc/join/join.conf and consists of two
|
||||
configuration sections, DEFAULT and service_credentials.
|
||||
|
||||
DEFAULT
|
||||
-------
|
||||
|
||||
join_listen_port
|
||||
~~~~~~~~~~~~~~~~
|
||||
Port that the REST service listens on. Default 9999.
|
||||
|
||||
api_paste_config
|
||||
~~~~~~~~~~~~~~~~
|
||||
Pointer to the paste configuration.
|
||||
|
||||
debug
|
||||
~~~~~
|
||||
Enables additional debug logging.
|
||||
|
||||
keytab
|
||||
~~~~~~
|
||||
Kerberos keytab containing the IPA credentials used to add/delete hosts.
|
||||
|
||||
url
|
||||
~~~
|
||||
URL pointing to the IPA master JSON endpoint.
|
||||
|
||||
domain
|
||||
~~~~~~
|
||||
The domain name to add to instances names to create a FQDN.
|
||||
|
||||
connect_retries
|
||||
~~~~~~~~~~~~~~~
|
||||
The number of times to attempt to contact the IPA server before failing.
|
||||
|
||||
service_credentials
|
||||
-------------------
|
||||
|
||||
auth_url
|
||||
~~~~~~~~
|
||||
URL of the keystone service.
|
||||
|
||||
auth_type
|
||||
~~~~~~~~~
|
||||
Keystone authentication method.
|
||||
|
||||
password
|
||||
~~~~~~~~
|
||||
Password of the novajoin service user.
|
||||
|
||||
username
|
||||
~~~~~~~~
|
||||
The service username.
|
||||
|
|
@ -0,0 +1,52 @@
|
|||
FAQ
|
||||
===
|
||||
What is novajoin?
|
||||
-----------------
|
||||
_novajoin is nova vendordata plugin for the OpenStack nova metadata service
|
||||
to manage host instantiation in an IPA server.
|
||||
|
||||
novajoin has two parts:
|
||||
|
||||
1. A REST service which handles adding new IPA hosts
|
||||
2. A notification listener which handles removing hosts
|
||||
|
||||
The REST service will respond to dynamic requests from the nova metadata
|
||||
server. This is used to add hosts into IPA.
|
||||
|
||||
The notification listener will handle instance delete requests and remove
|
||||
the appropriate host from IPA as well as floating IP associate and
|
||||
disassociate requests and update IPA DNS.
|
||||
|
||||
.. _novajoin: https://github.com/rcritten/novajoin
|
||||
|
||||
How does it work?
|
||||
-----------------
|
||||
|
||||
The REST service waits for POST requests which includes the requested
|
||||
instance name (hostname), instance_id, OpenStack image_id, project_id
|
||||
and user metadata.
|
||||
|
||||
Only those requests which include the metadata ipa_enroll=True
|
||||
will result in a host being added. The metadata can be specified in
|
||||
the user metadata or in the associated image.
|
||||
|
||||
The image_id is used to return the image metadata from glance.
|
||||
|
||||
The domain name configured in join.conf is appended to the instance
|
||||
name to generate the FQDN that will be used to enroll the host into
|
||||
IPA.
|
||||
|
||||
The host is added along with a randomly generated One-Time Password (OTP)
|
||||
and the hostname are returned. This is then passed into the instance either
|
||||
via a config drive or by a metadata call from within the instance.
|
||||
|
||||
A cloud-init script is used to pass these values to ipa-client-install
|
||||
to enroll the host.
|
||||
|
||||
The notification service listens on the AMQP notifications queue for
|
||||
instance delete requests. When one is found the equivalent IPA host,
|
||||
if any, will be removed.
|
||||
|
||||
Can novajoin be used outside the context of OpenStack?
|
||||
----------------------------------------------------------------------------
|
||||
Not likely. It is pretty tightly integrated with nova and glance.
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
Welcome to the novajoin documentation!
|
||||
======================================
|
||||
|
||||
Table of Contents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
Frequently asked questions <faq>
|
||||
Installation <installation>
|
||||
Configuration <configuration>
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
Installing novajoin
|
||||
===================
|
||||
Installing novajoin is easy.
|
||||
|
||||
RHEL, CentOS, Fedora packages
|
||||
-----------------------------
|
||||
Required dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
::
|
||||
|
||||
yum -y install {free}ipa-client
|
||||
|
||||
Development or integration testing dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
::
|
||||
|
||||
yum -y install python-setuptools
|
||||
easy_install pip
|
||||
pip install tox
|
||||
|
||||
Ubuntu, Debian packages
|
||||
-----------------------
|
||||
Required dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
::
|
||||
|
||||
apt-get -y install freeipa-client
|
||||
|
||||
Development or integration testing dependencies
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
::
|
||||
|
||||
apt-get -y install python-pip
|
||||
pip install tox
|
||||
|
||||
Installing novajoin from trunk source
|
||||
-------------------------------------
|
||||
::
|
||||
|
||||
pip install git+https://github.com/rcritten/novajoin
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
The machine must first be configured as an IPA client. It is not
|
||||
mandatory to be run on the nova controller but it is recommended.
|
||||
|
||||
The installer novajoin-install configures nova to use the novajoin service
|
||||
as a dynamic metadata provider, configures the novajoin notification and
|
||||
REST services and configures IPA to grant access to a role that allows
|
||||
management of hosts.
|
||||
|
||||
There are four ways to provide authentication for the IPA integration:
|
||||
|
||||
1. kinit before running the script and use the --no-kinit option.
|
||||
2. Set the Kerberos principal with --principal and pass the password
|
||||
on the command-line using --password.
|
||||
3. Set the Kerberos principal with --principal and pass the password in
|
||||
a file using --password-file.
|
||||
4. Let the installer prompt the user for the password.
|
||||
|
|
@ -17,3 +17,5 @@ testscenarios>=0.4 # Apache-2.0/BSD
|
|||
os-testr>=0.7.0 # Apache-2.0
|
||||
tempest-lib>=0.14.0 # Apache-2.0
|
||||
bandit>=1.0.1 # Apache-2.0
|
||||
sphinx!=1.2.0,!=1.3b1,<1.3,>=1.1.2
|
||||
sphinx-rtd-theme
|
||||
|
|
|
|||
Loading…
Reference in New Issue