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
This commit is contained in:
rabi 2017-08-03 12:05:16 +05:30
parent bd91db747d
commit 6e8e631d34
20 changed files with 205 additions and 97 deletions

View File

@ -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.

View File

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

View File

@ -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
==================

View File

@ -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

View File

@ -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

View File

@ -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.

View File

@ -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

View File

@ -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.

View File

@ -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,

View File

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

View File

@ -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,9 +13,9 @@ 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 \

View File

@ -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.

View File

@ -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'].

View File

@ -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.

View File

@ -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

View File

@ -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.

View File

@ -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.

View File

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

View File

@ -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.

View File

@ -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