diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst deleted file mode 100644 index 029422b..0000000 --- a/doc/source/contributor/index.rst +++ /dev/null @@ -1,8 +0,0 @@ -=========================== -Contributing to Heat Agents -=========================== - -This contains policies for developing with heat-agents. - -.. toctree:: - :maxdepth: 1 diff --git a/doc/source/index.rst b/doc/source/index.rst index ab79331..d326629 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 `_ -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 `_ -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. +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` diff --git a/doc/source/install/building_image.rst b/doc/source/install/building_image.rst index 9697fe8..3205604 100644 --- a/doc/source/install/building_image.rst +++ b/doc/source/install/building_image.rst @@ -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/ diff --git a/doc/source/install/hooks.rst b/doc/source/install/hooks.rst index 4bc39f5..e35cd43 100644 --- a/doc/source/install/hooks.rst +++ b/doc/source/install/hooks.rst @@ -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/* diff --git a/doc/source/install/hooks/ansible.rst b/doc/source/install/hooks/ansible.rst index a76bb4b..b457424 100644 --- a/doc/source/install/hooks/ansible.rst +++ b/doc/source/install/hooks/ansible.rst @@ -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. diff --git a/doc/source/install/hooks/apply-config.rst b/doc/source/install/hooks/apply-config.rst index 2c92afd..4b54203 100644 --- a/doc/source/install/hooks/apply-config.rst +++ b/doc/source/install/hooks/apply-config.rst @@ -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 diff --git a/doc/source/install/hooks/docker-cmd.rst b/doc/source/install/hooks/docker-cmd.rst index 63cbd83..ab0f8e4 100644 --- a/doc/source/install/hooks/docker-cmd.rst +++ b/doc/source/install/hooks/docker-cmd.rst @@ -2,13 +2,15 @@ docker-cmd ========== -A hook which uses the `docker` command via -`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 `_. 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 diff --git a/doc/source/install/hooks/docker-compose.rst b/doc/source/install/hooks/docker-compose.rst index 2f4a7bc..a12bd36 100644 --- a/doc/source/install/hooks/docker-compose.rst +++ b/doc/source/install/hooks/docker-compose.rst @@ -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:: diff --git a/doc/source/install/hooks/hiera.rst b/doc/source/install/hooks/hiera.rst index 21f1955..4667467 100644 --- a/doc/source/install/hooks/hiera.rst +++ b/doc/source/install/hooks/hiera.rst @@ -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/ diff --git a/doc/source/install/hooks/json-file.rst b/doc/source/install/hooks/json-file.rst index 2275168..09a9646 100644 --- a/doc/source/install/hooks/json-file.rst +++ b/doc/source/install/hooks/json-file.rst @@ -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"]``. diff --git a/doc/source/install/hooks/kubelet.rst b/doc/source/install/hooks/kubelet.rst index b2a063f..d9b4d33 100644 --- a/doc/source/install/hooks/kubelet.rst +++ b/doc/source/install/hooks/kubelet.rst @@ -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 diff --git a/doc/source/install/hooks/puppet.rst b/doc/source/install/hooks/puppet.rst index 122f46c..0060dd4 100644 --- a/doc/source/install/hooks/puppet.rst +++ b/doc/source/install/hooks/puppet.rst @@ -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 diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index e4f9cd9..ebf8bec 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -1,6 +1,6 @@ ====================== Installing Heat Agents -===================== +====================== .. toctree:: :maxdepth: 1 diff --git a/tox.ini b/tox.ini index dfcc794..41a2ed2 100644 --- a/tox.ini +++ b/tox.ini @@ -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}