Browse Source

Organize heat-agents docs

This organizes the heat-agents docs as per the openstackdocs format.
Also adds the team and repository tags.

Change-Id: I997dd3f52c9cd9f8ea274520e033de3ef582401c
changes/49/490349/2 1.4.0
rabi 4 years ago
parent
commit
6e8e631d34
  1. 52
      README.rst
  2. 8
      doc/source/contributor/index.rst
  3. 19
      doc/source/index.rst
  4. 32
      doc/source/install/building_image.rst
  5. 24
      doc/source/install/hooks.rst
  6. 4
      doc/source/install/hooks/ansible.rst
  7. 4
      doc/source/install/hooks/apply-config.rst
  8. 6
      doc/source/install/hooks/cfn-init.rst
  9. 16
      doc/source/install/hooks/chef.rst
  10. 4
      doc/source/install/hooks/docker-cmd.rst
  11. 10
      doc/source/install/hooks/docker-compose.rst
  12. 28
      doc/source/install/hooks/hiera.rst
  13. 8
      doc/source/install/hooks/json-file.rst
  14. 6
      doc/source/install/hooks/kubelet.rst
  15. 21
      doc/source/install/hooks/puppet.rst
  16. 6
      doc/source/install/hooks/salt.rst
  17. 4
      doc/source/install/hooks/script.rst
  18. 9
      doc/source/install/index.rst
  19. 25
      heat-config-hiera/README.rst
  20. 16
      heat-config-puppet/README.rst

52
README.rst

@ -1,46 +1,14 @@
============================
Software configuration hooks
============================
========================
Team and repository tags
========================
This directory contains `diskimage-builder <https://github.com/openstack/diskimage-builder>`_
elements to build an image which contains the software configuration hook
required to use your preferred configuration method.
.. image:: https://governance.openstack.org/badges/heat-agents.svg
:target: https://governance.openstack.org/reference/tags/index.html
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.
.. Change things from this point on
When building an image only the elements for the preferred configuration methods are required. The heat-config element is automatically included as a dependency.
===========
Heat Agents
===========
An example fedora based image containing all hooks can be built and uploaded to glance
with the following:
::
git clone https://git.openstack.org/openstack/diskimage-builder.git
git clone https://git.openstack.org/openstack/tripleo-image-elements.git
git clone https://git.openstack.org/openstack/heat-agents.git
git clone https://git.openstack.org/openstack/dib-utils.git
export PATH="${PWD}/dib-utils/bin:$PATH"
export ELEMENTS_PATH=tripleo-image-elements/elements:heat-agents/
diskimage-builder/bin/disk-image-create vm \
fedora selinux-permissive \
os-collect-config \
os-refresh-config \
os-apply-config \
heat-config \
heat-config-ansible \
heat-config-cfn-init \
heat-config-docker-compose \
heat-config-kubelet \
heat-config-puppet \
heat-config-salt \
heat-config-script \
-o fedora-software-config.qcow2
openstack image create --disk-format qcow2 --container-format bare fedora-software-config < \
fedora-software-config.qcow2
Heat Agents are python hooks for deploying software configurations using heat.

8
doc/source/contributor/index.rst

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

19
doc/source/index.rst

@ -11,11 +11,30 @@ Overview
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.
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.
Index
=====
.. toctree::
:maxdepth: 1
install/index
contributor/index
Indices and tables
==================

32
doc/source/install/building_image.rst

@ -0,0 +1,32 @@
=============================================
Build image with software configuration 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.
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
git clone https://git.openstack.org/openstack/heat-agents.git
export ELEMENTS_PATH=tripleo-image-elements/elements:heat-agents/
disk-image-create vm \
fedora selinux-permissive \
os-collect-config \
os-refresh-config \
os-apply-config \
heat-config \
heat-config-ansible \
heat-config-cfn-init \
heat-config-docker-compose \
heat-config-kubelet \
heat-config-puppet \
heat-config-salt \
heat-config-script \
-o fedora-software-config.qcow2
openstack image create --disk-format qcow2 --container-format bare fedora-software-config < \
fedora-software-config.qcow2

24
doc/source/install/hooks.rst

@ -0,0 +1,24 @@
===============
Available Hooks
===============
Below listed are the available hooks.
.. toctree::
: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

4
heat-config-ansible/README.rst → doc/source/install/hooks/ansible.rst

@ -1,3 +1,7 @@
=======
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.

4
heat-config-apply-config/README.rst → doc/source/install/hooks/apply-config.rst

@ -1,3 +1,7 @@
============
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

6
heat-config-cfn-init/README.rst → doc/source/install/hooks/cfn-init.rst

@ -1,3 +1,7 @@
========
cfn-init
========
A hook which consumes configuration in the format of AWS::CloudFormation::Init
metadata. It is provided to enable migrating from CloudFormation metadata
configuration to configuration using config and deployment resources.
configuration to configuration using config and deployment resources.

16
heat-config-chef/README.rst → doc/source/install/hooks/chef.rst

@ -1,8 +1,12 @@
====
chef
====
A hook which invokes ``chef-client`` in local mode (chef zero) on the
provided configuration.
Inputs:
-------
Inputs
------
Inputs are attribute overrides. In order to format them correctly for
consumption, you need to explicitly declare each top-level section as an
input of type ``Json`` in your config resource.
@ -12,16 +16,16 @@ Additionally, there is a special input named ``environment`` of type
applying the config. You do not have to explicitly declare this input in
the config resource.
Outputs:
--------
Outputs
-------
If you need to capture specific outputs from your chef run, you should
specify the output name(s) as normal in your config. Then, your recipes
should write files to the directory specified by the ``heat_outputs_path``
environment variable. The file name should match the name of the output
you are trying to capture.
Options:
-------------
Options
-------
kitchen : optional
A URL for a Git repository containing the desired recipes, roles,

4
heat-config-docker-cmd/README.rst → doc/source/install/hooks/docker-cmd.rst

@ -1,3 +1,7 @@
==========
docker-cmd
==========
A hook which uses the `docker` command via
`paunch <https://docs.openstack.org/developer/paunch/>`_ to deploy containers.

10
heat-config-docker-compose/README.rst → doc/source/install/hooks/docker-compose.rst

@ -1,3 +1,7 @@
==============
docker-compose
==============
A hook which uses `docker-compose` to deploy containers.
A special input 'env_files' can be used with SoftwareConfig and
@ -9,10 +13,10 @@ error, as it can't find these files.
Also, `--parameter-file` option can be used to pass env files from client.
Example:
Example::
$ openstack stack create test_stack -t example-docker-compose-template.yaml \
$ openstack stack create test_stack -t example-docker-compose-template.yaml \
--parameter-file env_file_0=./common.env \
--parameter-file env_file_1=./apps/web.env \
--parameter-file env_file_2=./test.env \
--parameter-file env_file_3=./busybox.env
--parameter-file env_file_3=./busybox.env

28
doc/source/install/hooks/hiera.rst

@ -0,0 +1,28 @@
=====
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.
Example::
ComputeConfig:
type: OS::Heat::StructuredConfig
properties:
group: hiera
config:
hierarchy:
- compute
datafiles:
compute:
debug: true
db_connection: foo:/bar
# customized hiera goes here...
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
custom hiera data.

8
heat-config-json-file/README.rst → doc/source/install/hooks/json-file.rst

@ -1,10 +1,14 @@
=========
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'.
Multiple JSON files can be written out in this manner.
Example:
Example::
JsonConfig:
type: OS::Heat::StructuredConfig
@ -16,4 +20,4 @@ Example:
- bar2
This would write out a JSON files at
/tmp/foo containing a JSON representation of ['bar', 'bar2'].
/tmp/foo containing a JSON representation of ['bar', 'bar2'].

6
heat-config-kubelet/README.rst → doc/source/install/hooks/kubelet.rst

@ -1,3 +1,7 @@
=======
kubelet
=======
This hook uses the kubelet agent from the kubernetes project to provision
containers. The StructuredConfig resource data represents a pod of containers
to be provisioned.
@ -19,4 +23,4 @@ The files have the following purpose:
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
config changes

21
doc/source/install/hooks/puppet.rst

@ -0,0 +1,21 @@
======
puppet
======
A hook which invokes ``puppet apply`` on the provided configuration.
Config inputs are passed in as facts and/or using hiera, and output values
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
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

6
heat-config-salt/README.rst → doc/source/install/hooks/salt.rst

@ -1,3 +1,7 @@
====
salt
====
A hook which uses salt library to apply the provided configuration
as a state. Config inputs are passed as opts and output values are
read from the yaml returned.
read from the yaml returned.

4
heat-config-script/README.rst → doc/source/install/hooks/script.rst

@ -1,3 +1,7 @@
======
script
======
A hook which invokes the provided configuration as an executable script.
Config inputs are passed in as environment variables, and output values are
read from written-out files.

9
doc/source/install/index.rst

@ -0,0 +1,9 @@
======================
Installing Heat Agents
=====================
.. toctree::
:maxdepth: 1
building_image
hooks

25
heat-config-hiera/README.rst

@ -1,25 +0,0 @@
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.
Example:
ComputeConfig:
type: OS::Heat::StructuredConfig
properties:
group: hiera
config:
hierarchy:
- compute
datafiles:
compute:
debug: true
db_connection: foo:/bar
# customized hiera goes here...
This would write out:
1) An /etc/hiera.yaml config file with compute in the hierarchy.
2) An /etc/puppet/hieradata/compute.json file loaded with the
custom hiera data.

16
heat-config-puppet/README.rst

@ -1,16 +0,0 @@
A hook which invokes ``puppet apply`` on the provided configuration.
Config inputs are passed in as facts and/or using hiera, and output values
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
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
Loading…
Cancel
Save