From 6e8e631d3458259ef0d8b87ddd7b558b0f1f6116 Mon Sep 17 00:00:00 2001 From: rabi Date: Thu, 3 Aug 2017 12:05:16 +0530 Subject: [PATCH] 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 | 52 ++++--------------- doc/source/contributor/index.rst | 8 +++ doc/source/index.rst | 19 +++++++ doc/source/install/building_image.rst | 32 ++++++++++++ doc/source/install/hooks.rst | 24 +++++++++ .../source/install/hooks/ansible.rst | 4 ++ .../source/install/hooks/apply-config.rst | 4 ++ .../source/install/hooks/cfn-init.rst | 6 ++- .../source/install/hooks/chef.rst | 16 +++--- .../source/install/hooks/docker-cmd.rst | 4 ++ .../source/install/hooks/docker-compose.rst | 10 ++-- doc/source/install/hooks/hiera.rst | 28 ++++++++++ .../source/install/hooks/json-file.rst | 8 ++- .../source/install/hooks/kubelet.rst | 6 ++- doc/source/install/hooks/puppet.rst | 21 ++++++++ .../source/install/hooks/salt.rst | 6 ++- .../source/install/hooks/script.rst | 4 ++ doc/source/install/index.rst | 9 ++++ heat-config-hiera/README.rst | 25 --------- heat-config-puppet/README.rst | 16 ------ 20 files changed, 205 insertions(+), 97 deletions(-) create mode 100644 doc/source/contributor/index.rst create mode 100644 doc/source/install/building_image.rst create mode 100644 doc/source/install/hooks.rst rename heat-config-ansible/README.rst => doc/source/install/hooks/ansible.rst (91%) rename heat-config-apply-config/README.rst => doc/source/install/hooks/apply-config.rst (94%) rename heat-config-cfn-init/README.rst => doc/source/install/hooks/cfn-init.rst (86%) rename heat-config-chef/README.rst => doc/source/install/hooks/chef.rst (96%) rename heat-config-docker-cmd/README.rst => doc/source/install/hooks/docker-cmd.rst (93%) rename heat-config-docker-compose/README.rst => doc/source/install/hooks/docker-compose.rst (75%) create mode 100644 doc/source/install/hooks/hiera.rst rename heat-config-json-file/README.rst => doc/source/install/hooks/json-file.rst (80%) rename heat-config-kubelet/README.rst => doc/source/install/hooks/kubelet.rst (96%) create mode 100644 doc/source/install/hooks/puppet.rst rename heat-config-salt/README.rst => doc/source/install/hooks/salt.rst (74%) rename heat-config-script/README.rst => doc/source/install/hooks/script.rst (89%) create mode 100644 doc/source/install/index.rst delete mode 100644 heat-config-hiera/README.rst delete mode 100644 heat-config-puppet/README.rst diff --git a/README.rst b/README.rst index b114915..1729f08 100644 --- a/README.rst +++ b/README.rst @@ -1,46 +1,14 @@ -============================ -Software configuration hooks -============================ +======================== +Team and repository tags +======================== -This directory contains `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 `_ -repository. These elements will build an image which uses -`os-collect-config `_, -`os-refresh-config `_, and -`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. diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst new file mode 100644 index 0000000..029422b --- /dev/null +++ b/doc/source/contributor/index.rst @@ -0,0 +1,8 @@ +=========================== +Contributing to Heat Agents +=========================== + +This contains policies for developing with heat-agents. + +.. toctree:: + :maxdepth: 1 diff --git a/doc/source/index.rst b/doc/source/index.rst index 7d81868..ab79331 100644 --- a/doc/source/index.rst +++ b/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 `_ +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 `_ +repository. These elements will build an image which uses +`os-collect-config `_, +`os-refresh-config `_, and +`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 ================== diff --git a/doc/source/install/building_image.rst b/doc/source/install/building_image.rst new file mode 100644 index 0000000..9697fe8 --- /dev/null +++ b/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 diff --git a/doc/source/install/hooks.rst b/doc/source/install/hooks.rst new file mode 100644 index 0000000..4bc39f5 --- /dev/null +++ b/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 + + diff --git a/heat-config-ansible/README.rst b/doc/source/install/hooks/ansible.rst similarity index 91% rename from heat-config-ansible/README.rst rename to doc/source/install/hooks/ansible.rst index 0be5b62..a76bb4b 100644 --- a/heat-config-ansible/README.rst +++ b/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. diff --git a/heat-config-apply-config/README.rst b/doc/source/install/hooks/apply-config.rst similarity index 94% rename from heat-config-apply-config/README.rst rename to doc/source/install/hooks/apply-config.rst index 444d36a..2c92afd 100644 --- a/heat-config-apply-config/README.rst +++ b/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 diff --git a/heat-config-cfn-init/README.rst b/doc/source/install/hooks/cfn-init.rst similarity index 86% rename from heat-config-cfn-init/README.rst rename to doc/source/install/hooks/cfn-init.rst index 53f489e..474de42 100644 --- a/heat-config-cfn-init/README.rst +++ b/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. \ No newline at end of file +configuration to configuration using config and deployment resources. diff --git a/heat-config-chef/README.rst b/doc/source/install/hooks/chef.rst similarity index 96% rename from heat-config-chef/README.rst rename to doc/source/install/hooks/chef.rst index bc77177..a7e140c 100644 --- a/heat-config-chef/README.rst +++ b/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, diff --git a/heat-config-docker-cmd/README.rst b/doc/source/install/hooks/docker-cmd.rst similarity index 93% rename from heat-config-docker-cmd/README.rst rename to doc/source/install/hooks/docker-cmd.rst index 45e549a..63cbd83 100644 --- a/heat-config-docker-cmd/README.rst +++ b/doc/source/install/hooks/docker-cmd.rst @@ -1,3 +1,7 @@ +========== +docker-cmd +========== + A hook which uses the `docker` command via `paunch `_ to deploy containers. diff --git a/heat-config-docker-compose/README.rst b/doc/source/install/hooks/docker-compose.rst similarity index 75% rename from heat-config-docker-compose/README.rst rename to doc/source/install/hooks/docker-compose.rst index 1aab252..2f4a7bc 100644 --- a/heat-config-docker-compose/README.rst +++ b/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 \ No newline at end of file + --parameter-file env_file_3=./busybox.env diff --git a/doc/source/install/hooks/hiera.rst b/doc/source/install/hooks/hiera.rst new file mode 100644 index 0000000..21f1955 --- /dev/null +++ b/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. diff --git a/heat-config-json-file/README.rst b/doc/source/install/hooks/json-file.rst similarity index 80% rename from heat-config-json-file/README.rst rename to doc/source/install/hooks/json-file.rst index 33efa5f..2275168 100644 --- a/heat-config-json-file/README.rst +++ b/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']. diff --git a/heat-config-kubelet/README.rst b/doc/source/install/hooks/kubelet.rst similarity index 96% rename from heat-config-kubelet/README.rst rename to doc/source/install/hooks/kubelet.rst index da824c5..b2a063f 100644 --- a/heat-config-kubelet/README.rst +++ b/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 \ No newline at end of file + config changes diff --git a/doc/source/install/hooks/puppet.rst b/doc/source/install/hooks/puppet.rst new file mode 100644 index 0000000..122f46c --- /dev/null +++ b/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 diff --git a/heat-config-salt/README.rst b/doc/source/install/hooks/salt.rst similarity index 74% rename from heat-config-salt/README.rst rename to doc/source/install/hooks/salt.rst index 129cf6d..367b846 100644 --- a/heat-config-salt/README.rst +++ b/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. \ No newline at end of file +read from the yaml returned. diff --git a/heat-config-script/README.rst b/doc/source/install/hooks/script.rst similarity index 89% rename from heat-config-script/README.rst rename to doc/source/install/hooks/script.rst index 63c8c03..837cc53 100644 --- a/heat-config-script/README.rst +++ b/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. diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 0000000..e4f9cd9 --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,9 @@ +====================== +Installing Heat Agents +===================== + +.. toctree:: + :maxdepth: 1 + + building_image + hooks diff --git a/heat-config-hiera/README.rst b/heat-config-hiera/README.rst deleted file mode 100644 index 89e9c83..0000000 --- a/heat-config-hiera/README.rst +++ /dev/null @@ -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. diff --git a/heat-config-puppet/README.rst b/heat-config-puppet/README.rst deleted file mode 100644 index 58fa59e..0000000 --- a/heat-config-puppet/README.rst +++ /dev/null @@ -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