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
rabi 1 year ago
parent
commit
6e8e631d34

+ 10
- 42
README.rst View File

@@ -1,46 +1,14 @@
1
-============================
2
-Software configuration hooks
3
-============================
1
+========================
2
+Team and repository tags
3
+========================
4 4
 
5
-This directory contains `diskimage-builder <https://github.com/openstack/diskimage-builder>`_
6
-elements to build an image which contains the software configuration hook
7
-required to use your preferred configuration method.
5
+.. image:: https://governance.openstack.org/badges/heat-agents.svg
6
+    :target: https://governance.openstack.org/reference/tags/index.html
8 7
 
9
-These elements depend on some elements found in the
10
-`tripleo-image-elements <https://github.com/openstack/tripleo-image-elements>`_
11
-repository. These elements will build an image which uses
12
-`os-collect-config <https://github.com/openstack/os-collect-config>`_,
13
-`os-refresh-config <https://github.com/openstack/os-refresh-config>`_, and
14
-`os-apply-config <https://github.com/openstack/os-apply-config>`_ together to
15
-invoke a hook with the supplied configuration data, and return any outputs back
16
-to heat.
8
+.. Change things from this point on
17 9
 
18
-When building an image only the elements for the preferred configuration methods are required. The heat-config element is automatically included as a dependency.
10
+===========
11
+Heat Agents
12
+===========
19 13
 
20
-An example fedora based image containing all hooks can be built and uploaded to glance
21
-with the following:
22
-
23
-::
24
-
25
-  git clone https://git.openstack.org/openstack/diskimage-builder.git
26
-  git clone https://git.openstack.org/openstack/tripleo-image-elements.git
27
-  git clone https://git.openstack.org/openstack/heat-agents.git
28
-  git clone https://git.openstack.org/openstack/dib-utils.git
29
-  export PATH="${PWD}/dib-utils/bin:$PATH"
30
-  export ELEMENTS_PATH=tripleo-image-elements/elements:heat-agents/
31
-  diskimage-builder/bin/disk-image-create vm \
32
-    fedora selinux-permissive \
33
-    os-collect-config \
34
-    os-refresh-config \
35
-    os-apply-config \
36
-    heat-config \
37
-    heat-config-ansible \
38
-    heat-config-cfn-init \
39
-    heat-config-docker-compose \
40
-    heat-config-kubelet \
41
-    heat-config-puppet \
42
-    heat-config-salt \
43
-    heat-config-script \
44
-    -o fedora-software-config.qcow2
45
-  openstack image create --disk-format qcow2 --container-format bare fedora-software-config < \
46
-    fedora-software-config.qcow2
14
+Heat Agents are python hooks for deploying software configurations using heat.

+ 8
- 0
doc/source/contributor/index.rst View File

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

+ 19
- 0
doc/source/index.rst View File

@@ -11,11 +11,30 @@ Overview
11 11
 
12 12
 Heat Agents are python hooks for deploying software configurations using heat.
13 13
 
14
+
15
+This repository contains `diskimage-builder <https://github.com/openstack/diskimage-builder>`_
16
+elements to build an image with the software configuration hooks
17
+required to use your preferred configuration method.
18
+
19
+These elements depend on some elements found in the
20
+`tripleo-image-elements <https://github.com/openstack/tripleo-image-elements>`_
21
+repository. These elements will build an image which uses
22
+`os-collect-config <https://github.com/openstack/os-collect-config>`_,
23
+`os-refresh-config <https://github.com/openstack/os-refresh-config>`_, and
24
+`os-apply-config <https://github.com/openstack/os-apply-config>`_ together to
25
+invoke a hook with the supplied configuration data, and return any outputs back
26
+to heat.
27
+
28
+
14 29
 Index
15 30
 =====
16 31
 .. toctree::
17 32
    :maxdepth: 1
18 33
 
34
+   install/index
35
+   contributor/index
36
+
37
+
19 38
 Indices and tables
20 39
 ==================
21 40
 

+ 32
- 0
doc/source/install/building_image.rst View File

@@ -0,0 +1,32 @@
1
+=============================================
2
+Build image with software configuration hooks
3
+=============================================
4
+
5
+When building an image only the elements for the preferred configuration methods are required.
6
+The heat-config element is automatically included as a dependency.
7
+
8
+An example fedora based image containing some hooks can be built and uploaded to glance
9
+with the following:
10
+
11
+::
12
+
13
+  sudo pip install git+https://git.openstack.org/openstack/diskimage-builder.git
14
+  git clone https://git.openstack.org/openstack/tripleo-image-elements.git
15
+  git clone https://git.openstack.org/openstack/heat-agents.git
16
+  export ELEMENTS_PATH=tripleo-image-elements/elements:heat-agents/
17
+  disk-image-create vm \
18
+    fedora selinux-permissive \
19
+    os-collect-config \
20
+    os-refresh-config \
21
+    os-apply-config \
22
+    heat-config \
23
+    heat-config-ansible \
24
+    heat-config-cfn-init \
25
+    heat-config-docker-compose \
26
+    heat-config-kubelet \
27
+    heat-config-puppet \
28
+    heat-config-salt \
29
+    heat-config-script \
30
+    -o fedora-software-config.qcow2
31
+  openstack image create --disk-format qcow2 --container-format bare fedora-software-config < \
32
+    fedora-software-config.qcow2

+ 24
- 0
doc/source/install/hooks.rst View File

@@ -0,0 +1,24 @@
1
+===============
2
+Available Hooks
3
+===============
4
+
5
+Below listed are the available hooks.
6
+
7
+
8
+.. toctree::
9
+   :maxdepth: 1
10
+
11
+   hooks/ansible
12
+   hooks/apply-config
13
+   hooks/cfn-init
14
+   hooks/chef
15
+   hooks/docker-cmd
16
+   hooks/docker-compose
17
+   hooks/hiera
18
+   hooks/json-file
19
+   hooks/kubelet
20
+   hooks/puppet
21
+   hooks/salt
22
+   hooks/script
23
+
24
+

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

@@ -1,3 +1,7 @@
1
+=======
2
+ansible
3
+=======
4
+
1 5
 A hook which invokes ``ansible-playbook -i "localhost,"`` on the provided
2 6
 configuration. Config inputs are written to a 'variables.json' file and
3 7
 then passed to ansible via the '--extra-vars @json_file' parameter.

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

@@ -1,3 +1,7 @@
1
+============
2
+apply-config
3
+============
4
+
1 5
 A hook which invokes os-apply-config.
2 6
 
3 7
 The intent is for this element (hook script) to be used in place of the one in

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

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

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

@@ -1,8 +1,12 @@
1
+====
2
+chef
3
+====
4
+
1 5
 A hook which invokes ``chef-client`` in local mode (chef zero) on the
2 6
 provided configuration.
3 7
 
4
-Inputs:
5
--------
8
+Inputs
9
+------
6 10
 Inputs are attribute overrides. In order to format them correctly for
7 11
 consumption, you need to explicitly declare each top-level section as an
8 12
 input of type ``Json`` in your config resource.
@@ -12,16 +16,16 @@ Additionally, there is a special input named ``environment`` of type
12 16
 applying the config. You do not have to explicitly declare this input in
13 17
 the config resource.
14 18
 
15
-Outputs:
16
---------
19
+Outputs
20
+-------
17 21
 If you need to capture specific outputs from your chef run, you should
18 22
 specify the output name(s) as normal in your config. Then, your recipes
19 23
 should write files to the directory specified by the ``heat_outputs_path``
20 24
 environment variable. The file name should match the name of the output
21 25
 you are trying to capture.
22 26
 
23
-Options:
24
--------------
27
+Options
28
+-------
25 29
 
26 30
 kitchen : optional
27 31
     A URL for a Git repository containing the desired recipes, roles,

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

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

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

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

+ 28
- 0
doc/source/install/hooks/hiera.rst View File

@@ -0,0 +1,28 @@
1
+=====
2
+hiera
3
+=====
4
+
5
+A hook which helps write hiera files to disk and creates
6
+the hiera.yaml to order them. This is typically used alongside
7
+of the puppet hook to generate Hiera in a more composable manner.
8
+
9
+Example::
10
+
11
+    ComputeConfig:
12
+      type: OS::Heat::StructuredConfig
13
+      properties:
14
+        group: hiera
15
+        config:
16
+          hierarchy:
17
+            - compute
18
+          datafiles:
19
+            compute:
20
+              debug: true
21
+              db_connection: foo:/bar
22
+              # customized hiera goes here...
23
+
24
+This would write out
25
+
26
+- An /etc/hiera.yaml config file with compute in the hierarchy.
27
+- An /etc/puppet/hieradata/compute.json file loaded with the
28
+  custom hiera data.

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

@@ -1,10 +1,14 @@
1
+=========
2
+json-file
3
+=========
4
+
1 5
 A hook which helps write JSON files to disk for configuration or use
2 6
 with ad-hoc scripts. The data files are written to the named file
3 7
 location for each section listed under 'config'.
4 8
 
5 9
 Multiple JSON files can be written out in this manner.
6 10
 
7
-Example:
11
+Example::
8 12
 
9 13
   JsonConfig:
10 14
     type: OS::Heat::StructuredConfig
@@ -16,4 +20,4 @@ Example:
16 20
            - bar2
17 21
 
18 22
 This would write out a JSON files at
19
- /tmp/foo containing a JSON representation of ['bar', 'bar2'].
23
+/tmp/foo containing a JSON representation of ['bar', 'bar2'].

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

@@ -1,3 +1,7 @@
1
+=======
2
+kubelet
3
+=======
4
+
1 5
 This hook uses the kubelet agent from the kubernetes project to provision
2 6
 containers. The StructuredConfig resource data represents a pod of containers
3 7
 to be provisioned.
@@ -19,4 +23,4 @@ The files have the following purpose:
19 23
   out all pod definition files for the pods that should currently be running.
20 24
   Kubelet is configured to monitor the directory containing these files, so
21 25
   the current running containers will change when kubelet acts on these
22
-  config changes
26
+  config changes

+ 21
- 0
doc/source/install/hooks/puppet.rst View File

@@ -0,0 +1,21 @@
1
+======
2
+puppet
3
+======
4
+
5
+A hook which invokes ``puppet apply`` on the provided configuration.
6
+
7
+Config inputs are passed in as facts and/or using hiera, and output values
8
+are read from written-out files.
9
+
10
+Hook Options
11
+------------
12
+
13
+- use_facter: default True. Set to True to pass puppet inputs via Facter
14
+- use_hiera: default False. Set to True to pass puppet inputs via Hiera
15
+- modulepath: If set, puppet will use this filesystem path to load modules
16
+- tags: If set, puppet will use the specified value(s) to apply only a
17
+  subset of the catalog for a given manifest.
18
+- enable_debug: default False. Set to True to run puppet apply in debug mode
19
+  and have it captured on the node to /var/log/puppet/heat-debug.log
20
+- enable_verbose: default False. Set to True to run puppet apply in verbose mode
21
+  and have it captured on the node to /var/log/puppet/heat-verbose.log

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

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

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

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

+ 9
- 0
doc/source/install/index.rst View File

@@ -0,0 +1,9 @@
1
+======================
2
+Installing Heat Agents
3
+=====================
4
+
5
+.. toctree::
6
+   :maxdepth: 1
7
+
8
+   building_image
9
+   hooks

+ 0
- 25
heat-config-hiera/README.rst View File

@@ -1,25 +0,0 @@
1
-A hook which helps write hiera files to disk and creates
2
-the hiera.yaml to order them. This is typically used alongside
3
-of the puppet hook to generate Hiera in a more composable manner.
4
-
5
-Example:
6
-
7
-  ComputeConfig:
8
-    type: OS::Heat::StructuredConfig
9
-    properties:
10
-      group: hiera
11
-      config:
12
-        hierarchy:
13
-          - compute
14
-        datafiles:
15
-          compute:
16
-            debug: true
17
-            db_connection: foo:/bar
18
-            # customized hiera goes here...
19
-
20
-This would write out:
21
-
22
- 1) An /etc/hiera.yaml config file with compute in the hierarchy.
23
-
24
- 2) An /etc/puppet/hieradata/compute.json file loaded with the
25
-    custom hiera data.

+ 0
- 16
heat-config-puppet/README.rst View File

@@ -1,16 +0,0 @@
1
-A hook which invokes ``puppet apply`` on the provided configuration.
2
-
3
-Config inputs are passed in as facts and/or using hiera, and output values
4
-are read from written-out files.
5
-
6
-Hook Options:
7
--------------
8
-  use_facter: default True. Set to True to pass puppet inputs via Facter
9
-  use_hiera: default False. Set to True to pass puppet inputs via Hiera
10
-  modulepath: If set, puppet will use this filesystem path to load modules
11
-  tags: If set, puppet will use the specified value(s) to apply only a
12
-        subset of the catalog for a given manifest.
13
-  enable_debug: default False. Set to True to run puppet apply in debug mode
14
-                and have it captured on the node to /var/log/puppet/heat-debug.log
15
-  enable_verbose: default False. Set to True to run puppet apply in verbose mode
16
-                and have it captured on the node to /var/log/puppet/heat-verbose.log

Loading…
Cancel
Save