Clean up heat-agents docs

Improve links, formatting, grammar.

Change-Id: I459b40f30ccd613e19d20e342948f19be1f01efd
This commit is contained in:
Zane Bitter 2017-11-30 10:01:31 -05:00
parent 6a29080987
commit 461013f01c
14 changed files with 89 additions and 114 deletions

View File

@ -1,8 +0,0 @@
===========================
Contributing to Heat Agents
===========================
This contains policies for developing with heat-agents.
.. toctree::
:maxdepth: 1

View File

@ -1,42 +1,27 @@
.. heat-agents documentation master file, created by
sphinx-quickstart on Thu Jul 20 08:52:00 2017.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Heat Agents
===========
Welcome to Heat Agents!
=======================
Overview
========
Heat Agents are python hooks for deploying software configurations using heat.
Heat Agents are python hooks for deploying software configurations using
`Heat`_.
This repository contains `diskimage-builder <https://github.com/openstack/diskimage-builder>`_
elements to build an image with the software configuration hooks
required to use your preferred configuration method.
This repository contains `diskimage-builder`_ elements to build an image with
the software configuration hooks required to use your preferred configuration
method.
These elements depend on some elements found in the
`tripleo-image-elements <https://github.com/openstack/tripleo-image-elements>`_
repository. These elements will build an image which uses
`os-collect-config <https://github.com/openstack/os-collect-config>`_,
`os-refresh-config <https://github.com/openstack/os-refresh-config>`_, and
`os-apply-config <https://github.com/openstack/os-apply-config>`_ together to
invoke a hook with the supplied configuration data, and return any outputs back
to heat.
These elements depend on some elements found in the `tripleo-image-elements`_
repository. These elements will build an image which uses `os-collect-config`_,
`os-refresh-config`_, and `os-apply-config`_ together to invoke a hook with the
supplied configuration data, and return any outputs back to Heat.
.. _Heat: https://docs.openstack.org/heat/latest
.. _diskimage-builder: https://docs.openstack.org/diskimage-builder/latest/
.. _tripleo-image-elements: https://git.openstackorg/cgit/openstack/tripleo-image-elements
.. _os-collect-config: https://git.openstackorg/cgit/openstack/os-collect-config
.. _os-refresh-config: https://git.openstackorg/cgit/openstack/os-refresh-config
.. _os-apply-config: https://git.openstackorg/cgit/openstack/os-apply-config
Index
=====
.. toctree::
:maxdepth: 1
:maxdepth: 3
install/index
contributor/index
Indices and tables
==================
* :ref:`genindex`
* :ref:`search`

View File

@ -1,14 +1,13 @@
=============================================
Build image with software configuration hooks
=============================================
================================================
Building an image with software deployment hooks
================================================
When building an image only the elements for the preferred configuration methods are required.
The heat-config element is automatically included as a dependency.
When building an image with `diskimage-builder`_ only the elements for the
preferred configuration methods are required. The heat-config element is
automatically included as a dependency.
An example fedora based image containing some hooks can be built and uploaded to glance
with the following:
::
An example fedora based image containing some hooks can be built and uploaded
to glance with the following::
sudo pip install git+https://git.openstack.org/openstack/diskimage-builder.git
git clone https://git.openstack.org/openstack/tripleo-image-elements.git
@ -30,3 +29,5 @@ with the following:
-o fedora-software-config.qcow2
openstack image create --disk-format qcow2 --container-format bare fedora-software-config < \
fedora-software-config.qcow2
.. _diskimage-builder: https://docs.openstack.org/diskimage-builder/latest/

View File

@ -2,23 +2,11 @@
Available Hooks
===============
Below listed are the available hooks.
The available hooks are:
.. toctree::
:glob:
:maxdepth: 1
hooks/ansible
hooks/apply-config
hooks/cfn-init
hooks/chef
hooks/docker-cmd
hooks/docker-compose
hooks/hiera
hooks/json-file
hooks/kubelet
hooks/puppet
hooks/salt
hooks/script
hooks/*

View File

@ -3,6 +3,6 @@ ansible
=======
A hook which invokes ``ansible-playbook -i "localhost,"`` on the provided
configuration. Config inputs are written to a 'variables.json' file and
then passed to ansible via the '--extra-vars @json_file' parameter.
configuration. Config inputs are written to a ``variables.json`` file and
then passed to ansible via the ``--extra-vars @json_file`` flag.
Config output values are read from written-out files.

View File

@ -2,17 +2,21 @@
apply-config
============
A hook which invokes os-apply-config.
A hook which invokes `os-apply-config`_.
The intent is for this element (hook script) to be used in place of the one in
tripleo-image-elements which relies on an external signal handling
shell script at the end of the os-refresh-config run (99-refresh-completed).
This version will run os-apply-config and return a signal immediately. Because
it uses the heat-hook mechanisms it also supports a broader set of signal
handling capabilities... which 99-refresh-completed doesn't fully support.
`tripleo-image-elements`_ which relies on an external signal handling shell
script at the end of the `os-refresh-config`_ run (99-refresh-completed). This
version will run `os-apply-config`_ and return a signal immediately. Because it
uses the heat-hook mechanisms it also supports a broader set of signal handling
capabilities... which 99-refresh-completed doesn't fully support.
It is worth noting that this hook runs os-apply-config against all the
accumulated metadata, not just data supplied to an individual hook.
To use this hook set group: to 'apply-config' instead of 'os-apply-config'
in your Heat software configuration resources.
To use this hook set the ``group`` property to `apply-config` instead of
`os-apply-config` in your Heat software configuration resources.
.. _os-apply-config: https://git.openstackorg/cgit/openstack/os-apply-config
.. _tripleo-image-elements: https://git.openstackorg/cgit/openstack/tripleo-image-elements
.. _os-refresh-config: https://git.openstackorg/cgit/openstack/os-refresh-config

View File

@ -2,13 +2,15 @@
docker-cmd
==========
A hook which uses the `docker` command via
`paunch <https://docs.openstack.org/developer/paunch/>`_ to deploy containers.
A hook which uses the ``docker`` command via `paunch`_ to deploy containers.
The hook currently supports specifying containers in the `docker-compose v1
format <https://docs.docker.com/compose/compose-file/#/version-1>`_. The
intention is for this hook to also support the kubernetes pod format.
format`_. The intention is for this hook to also support the kubernetes pod
format.
A dedicated os-refresh-config script will remove running containers if a
deployment is removed or changed, then the docker-cmd hook will run any
containers in new or updated deployments.
.. _paunch: https://docs.openstack.org/paunch/latest/
.. _docker-compose v1 format: https://docs.docker.com/compose/compose-file/#/version-1

View File

@ -2,16 +2,15 @@
docker-compose
==============
A hook which uses `docker-compose` to deploy containers.
A hook which uses ``docker-compose`` to deploy containers.
A special input 'env_files' can be used with SoftwareConfig and
StructuredConfig for docker-compose `env_file` key(s).
A special input ``env_files`` can be used with SoftwareConfig and
StructuredConfig for docker-compose env_file key(s). If any env_file
keys specified in ``docker-compose.yml`` do not exist in the ``input_values``
supplied, docker-compose will throw an error, as it can't find these files.
if env_file keys specified in the `docker-compose.yml`, do not
exist in input_values supplied, docker-compose will throw an
error, as it can't find these files.
Also, `--parameter-file` option can be used to pass env files from client.
Also, the ``--parameter-file`` option can be used to pass env files from the
client.
Example::

View File

@ -2,9 +2,9 @@
hiera
=====
A hook which helps write hiera files to disk and creates
the hiera.yaml to order them. This is typically used alongside
of the puppet hook to generate Hiera in a more composable manner.
A hook which helps write `hiera`_ files to disk and creates the ``hiera.yaml``
to order them. This is typically used alongside the puppet hook to generate
Hiera in a more composable manner.
Example::
@ -21,8 +21,10 @@ Example::
db_connection: foo:/bar
# customized hiera goes here...
This would write out
This would write out:
- An /etc/hiera.yaml config file with compute in the hierarchy.
- An /etc/puppet/hieradata/compute.json file loaded with the
- An ``/etc/hiera.yaml`` config file with compute in the hierarchy.
- An ``/etc/puppet/hieradata/compute.json`` file loaded with the
custom hiera data.
.. _hiera: https://docs.puppet.com/hiera/

View File

@ -4,7 +4,7 @@ json-file
A hook which helps write JSON files to disk for configuration or use
with ad-hoc scripts. The data files are written to the named file
location for each section listed under 'config'.
location for each section listed under `config`.
Multiple JSON files can be written out in this manner.
@ -19,5 +19,5 @@ Example::
- bar
- bar2
This would write out a JSON files at
/tmp/foo containing a JSON representation of ['bar', 'bar2'].
This would write out a JSON files at ``/tmp/foo`` containing a JSON
representation of ``["bar", "bar2"]``.

View File

@ -8,19 +8,19 @@ to be provisioned.
The files have the following purpose:
- extra-data.d/50-docker-images allows an archive file of docker images to
- ``extra-data.d/50-docker-images`` allows an archive file of docker images to
be included in the dib image
- install.d/50-heat-config-kubelet installs kubernetes for redhat based
- ``install.d/50-heat-config-kubelet`` installs kubernetes for redhat based
distros during dib image build, along with the required systemd and config
files required to enable a working kubelet service on the host
- install.d/hook-kubelet.py polls docker images and containers until the
- ``install.d/hook-kubelet.py`` polls docker images and containers until the
expected kubelet-provisioned containers are running (or a timeout occurs)
- os-refresh-config/configure.d/50-heat-config-kubelet runs before
55-heat-config (and the kubelet hook it triggers). This orc script writes
- ``os-refresh-config/configure.d/50-heat-config-kubelet`` runs before
``55-heat-config`` (and the kubelet hook it triggers). This orc script writes
out all pod definition files for the pods that should currently be running.
Kubelet is configured to monitor the directory containing these files, so
the current running containers will change when kubelet acts on these
config changes
Kubelet is configured to monitor the directory containing these files, so the
current running containers will change when kubelet acts on these config
changes

View File

@ -10,12 +10,14 @@ are read from written-out files.
Hook Options
------------
- use_facter: default True. Set to True to pass puppet inputs via Facter
- use_hiera: default False. Set to True to pass puppet inputs via Hiera
- modulepath: If set, puppet will use this filesystem path to load modules
- tags: If set, puppet will use the specified value(s) to apply only a
- ``use_facter``: default `True`. Set to True to pass puppet inputs via Facter
- ``use_hiera``: default `False`. Set to True to pass puppet inputs via Hiera
- ``modulepath``: If set, puppet will use this filesystem path to load modules
- ``tags``: If set, puppet will use the specified value(s) to apply only a
subset of the catalog for a given manifest.
- enable_debug: default False. Set to True to run puppet apply in debug mode
and have it captured on the node to /var/log/puppet/heat-debug.log
- enable_verbose: default False. Set to True to run puppet apply in verbose mode
and have it captured on the node to /var/log/puppet/heat-verbose.log
- ``enable_debug``: default `False`. Set to True to run puppet apply in debug
mode and have it captured on the node to /var/log/puppet/heat-debug.log
- ``enable_verbose``: default `False`. Set to True to run puppet apply in
verbose mode and have it captured on the node to
/var/log/puppet/heat-verbose.log

View File

@ -1,6 +1,6 @@
======================
Installing Heat Agents
=====================
======================
.. toctree::
:maxdepth: 1

View File

@ -16,7 +16,7 @@ commands = flake8
[testenv:docs]
deps = -r{toxinidir}/doc/requirements.txt
commands = python setup.py build_sphinx
commands = sphinx-build -W -b html doc/source doc/build/html
[testenv:venv]
commands = {posargs}