aboutsummaryrefslogtreecommitdiffstats
path: root/sample-env-generator/README.rst
diff options
context:
space:
mode:
authorBen Nemec <bnemec@redhat.com>2016-05-31 11:36:23 -0500
committerBen Nemec <bnemec@redhat.com>2017-06-12 15:02:50 -0500
commit4e24c8cb6a1f65b1e5c764febfe96c2c465cfed1 (patch)
treee1f5a72dfece465f72117db99114a2b4f11eabe7 /sample-env-generator/README.rst
parentea04e61094c65e9bf26b035aa7113128eb38f4f3 (diff)
Sample environment generator
This is a tool to automate the generation of our sample environment files. It takes a yaml file as input, and based on the environments defined in that file generates a number of sample environment files from the parameters in the Heat templates. A tox genconfig target is added that mirrors how the other OpenStack services generate their sample config files. A description of the available options for the input file is provided in a README file in the sample-env-generator directory. In this commit only a single sample config is provided as a basic example of how the tool works, but subsequent commits will add more generated sample configs. Change-Id: I855f33a61bba5337d844555a7c41b633b3327f7a bp: environment-generator
Diffstat (limited to 'sample-env-generator/README.rst')
-rw-r--r--sample-env-generator/README.rst149
1 files changed, 149 insertions, 0 deletions
diff --git a/sample-env-generator/README.rst b/sample-env-generator/README.rst
new file mode 100644
index 00000000..71e9810a
--- /dev/null
+++ b/sample-env-generator/README.rst
@@ -0,0 +1,149 @@
+Sample Environment Generator
+----------------------------
+
+This is a tool to automate the generation of our sample environment
+files. It takes a yaml file as input, and based on the environments
+defined in that file generates a number of sample environment files
+from the parameters in the Heat templates.
+
+Usage
+=====
+
+The simplest case is when an existing sample environment needs to be
+updated to reflect changes in the templates. Use the tox ``genconfig``
+target to do this::
+
+ tox -e genconfig
+
+.. note:: The tool should be run from the root directory of the
+ ``tripleo-heat-templates`` project.
+
+If a new sample environment is needed, it should be added to the
+``sample-env-generator/sample-environments.yaml`` file. The existing
+entries in the file can be used as examples, and a more detailed
+explanation of the different available keys is below:
+
+- **name**: the output file will be this name + .yaml, in the
+ ``environments`` directory.
+- **title**: a human-readable title for the environment.
+- **description**: A description of the environment. Will be included
+ as a comment at the top of the sample file.
+- **files**: The Heat templates containing the parameter definitions
+ for the environment. Should be specified as a path relative to the
+ root of the ``tripleo-heat-templates`` project. For example:
+ ``puppet/extraconfig/tls/tls-cert-inject.yaml:``. Each filename
+ should be a YAML dictionary that contains a ``parameters`` entry.
+- **parameters**: There should be one ``parameters`` entry per file in the
+ ``files`` section (see the example configuration below).
+ This can be either a list of parameters related to
+ the environment, which is necessary for templates like
+ overcloud.yaml, or the string 'all', which indicates that all
+ parameters from the file should be included.
+- **static**: Can be used to specify that certain parameters must
+ not be changed. Examples would be the EnableSomething params
+ in the templates. When writing a sample config for Something,
+ ``EnableSomething: True`` would be a static param, since it
+ would be nonsense to include the environment with it set to any other
+ value.
+- **sample_values**: Sometimes it is useful to include a sample value
+ for a parameter that is not the parameter's actual default.
+ An example of this is the SSLCertificate param in the enable-tls
+ environment file.
+- **resource_registry**: Many environments also need to pass
+ resource_registry entries when they are used. This can be used
+ to specify that in the configuration file.
+
+Some behavioral notes:
+
+- Parameters without default values will be marked as mandatory to indicate
+ that the user must set a value for them.
+- It is no longer recommended to set parameters using the ``parameters``
+ section. Instead, all parameters should be set as ``parameter_defaults``
+ which will work regardless of whether the parameter is top-level or nested.
+ Therefore, the tool will always set parameters in the ``parameter_defaults``
+ section.
+- Parameters whose name begins with the _ character are treated as private.
+ This indicates that the parameter value will be passed in from another
+ template and does not need to be exposed directly to the user.
+
+If adding a new environment, don't forget to add the new file to the
+git repository so it will be included with the review.
+
+Example
+=======
+
+Given a Heat template named ``example.yaml`` that looks like::
+
+ parameters:
+ EnableExample:
+ default: False
+ description: Enable the example feature
+ type: boolean
+ ParamOne:
+ default: one
+ description: First example param
+ type: string
+ ParamTwo:
+ description: Second example param
+ type: number
+ _PrivateParam:
+ default: does not matter
+ description: Will not show up
+ type: string
+
+And an environment generator entry that looks like::
+
+ environments:
+ -
+ name: example
+ title: Example Environment
+ description: |
+ An example environment demonstrating how to use the sample
+ environment generator. This text will be included at the top
+ of the generated file as a comment.
+ files:
+ example.yaml:
+ parameters: all
+ sample_values:
+ EnableExample: True
+ static:
+ - EnableExample
+ resource_registry:
+ OS::TripleO::ExampleData: ../extraconfig/example.yaml
+
+The generated environment file would look like::
+
+ # *******************************************************************
+ # This file was created automatically by the sample environment
+ # generator. Developers should use `tox -e genconfig` to update it.
+ # Users are recommended to make changes to a copy of the file instead
+ # of the original, if any customizations are needed.
+ # *******************************************************************
+ # title: Example Environment
+ # description: |
+ # An example environment demonstrating how to use the sample
+ # environment generator. This text will be included at the top
+ # of the generated file as a comment.
+ parameter_defaults:
+ # First example param
+ # Type: string
+ ParamOne: one
+
+ # Second example param
+ # Mandatory. This parameter must be set by the user.
+ # Type: number
+ ParamTwo: <None>
+
+ # ******************************************************
+ # Static parameters - these are values that must be
+ # included in the environment but should not be changed.
+ # ******************************************************
+ # Enable the example feature
+ # Type: boolean
+ EnableExample: True
+
+ # *********************
+ # End static parameters
+ # *********************
+ resource_registry:
+ OS::TripleO::ExampleData: ../extraconfig/example.yaml