diff --git a/Makefile b/Makefile index 7d85e7f..1400172 100644 --- a/Makefile +++ b/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 diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..33a23b3 --- /dev/null +++ b/doc/source/conf.py @@ -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} diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst new file mode 100644 index 0000000..37f4615 --- /dev/null +++ b/doc/source/configuration.rst @@ -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. diff --git a/doc/source/faq.rst b/doc/source/faq.rst new file mode 100644 index 0000000..deea8b8 --- /dev/null +++ b/doc/source/faq.rst @@ -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. diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..4096687 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,12 @@ +Welcome to the novajoin documentation! +====================================== + +Table of Contents +================= + +.. toctree:: + :maxdepth: 2 + + Frequently asked questions + Installation + Configuration diff --git a/doc/source/installation.rst b/doc/source/installation.rst new file mode 100644 index 0000000..7949bdd --- /dev/null +++ b/doc/source/installation.rst @@ -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. diff --git a/test-requirements.txt b/test-requirements.txt index a3b0312..4da918f 100644 --- a/test-requirements.txt +++ b/test-requirements.txt @@ -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 diff --git a/tox.ini b/tox.ini index 4ed0a1b..1bd3ef3 100644 --- a/tox.ini +++ b/tox.ini @@ -50,3 +50,6 @@ commands = bandit -r novajoin -n5 -x tests -ll -s B104 ignore = E251,D100,D101,D102,D202,D208 exclude = .git,.venv,.tox,dist,tools,doc,*egg,build max-complexity=30 + +[testenv:docs] +commands = sphinx-build -W -b html doc/source doc/build/html