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

README.rst

@@ -1,46 +1,14 @@
-============================
+========================
-Software configuration hooks
+Team and repository tags
-============================
+========================
 
-This directory contains `diskimage-builder <https://github.com/openstack/diskimage-builder>`_
+.. image:: https://governance.openstack.org/badges/heat-agents.svg
-elements to build an image which contains the software configuration hook
+    :target: https://governance.openstack.org/reference/tags/index.html
-required to use your preferred configuration method.
 
-These elements depend on some elements found in the
+.. Change things from this point on
-`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.
 
-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
+Heat Agents are python hooks for deploying software configurations using heat.
-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

doc/source/contributor/index.rst

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

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

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

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

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.

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

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.

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,

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.
 

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

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.

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

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

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

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.

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.

doc/source/install/index.rst

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

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.

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