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
parent
bd91db747d
commit
6e8e631d34
52
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
Normal file
8
doc/source/contributor/index.rst
Normal file
@ -0,0 +1,8 @@
|
||||
===========================
|
||||
Contributing to Heat Agents
|
||||
===========================
|
||||
|
||||
This contains policies for developing with heat-agents.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
@ -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
Normal file
32
doc/source/install/building_image.rst
Normal 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
|
||||
24
doc/source/install/hooks.rst
Normal file
24
doc/source/install/hooks.rst
Normal 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
|
||||
|
||||
|
||||
@ -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.
|
||||
@ -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
|
||||
@ -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.
|
||||
@ -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,
|
||||
@ -1,3 +1,7 @@
|
||||
==========
|
||||
docker-cmd
|
||||
==========
|
||||
|
||||
A hook which uses the `docker` command via
|
||||
`paunch <https://docs.openstack.org/developer/paunch/>`_ to deploy containers.
|
||||
|
||||
@ -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 \
|
||||
28
doc/source/install/hooks/hiera.rst
Normal file
28
doc/source/install/hooks/hiera.rst
Normal 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.
|
||||
@ -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'].
|
||||
@ -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.
|
||||
21
doc/source/install/hooks/puppet.rst
Normal file
21
doc/source/install/hooks/puppet.rst
Normal 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
|
||||
@ -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.
|
||||
@ -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
Normal file
9
doc/source/install/index.rst
Normal file
@ -0,0 +1,9 @@
|
||||
======================
|
||||
Installing Heat Agents
|
||||
=====================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
building_image
|
||||
hooks
|
||||
@ -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.
|
||||
@ -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…
Reference in New Issue
Block a user