Clean up heat-agents docs
Improve links, formatting, grammar. Change-Id: I459b40f30ccd613e19d20e342948f19be1f01efd
This commit is contained in:
Zane Bitter
parent
6a29080987
commit
461013f01c
@ -1,8 +0,0 @@
|
||||
===========================
|
||||
Contributing to Heat Agents
|
||||
===========================
|
||||
|
||||
This contains policies for developing with heat-agents.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
@ -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`
|
||||
|
||||
@ -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/
|
||||
|
||||
@ -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/*
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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::
|
||||
|
||||
|
||||
@ -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/
|
||||
|
||||
@ -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"]``.
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
======================
|
||||
Installing Heat Agents
|
||||
=====================
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
Loading…
Reference in New Issue
Block a user