sample-env-generator/README.rst

   1 Sample Environment Generator
   2 ----------------------------
   3
   4 This is a tool to automate the generation of our sample environment
   5 files.  It takes a yaml file as input, and based on the environments
   6 defined in that file generates a number of sample environment files
   7 from the parameters in the Heat templates.
   8
   9 Usage
  10 =====
  11
  12 The simplest case is when an existing sample environment needs to be
  13 updated to reflect changes in the templates.  Use the tox ``genconfig``
  14 target to do this::
  15
  16     tox -e genconfig
  17
  18 .. note:: The tool should be run from the root directory of the
  19           ``tripleo-heat-templates`` project.
  20
  21 If a new sample environment is needed, it should be added to the
  22 appropriate file in the ``sample-env-generator/`` directory.  The existing
  23 entries in the files can be used as examples, and a more detailed
  24 explanation of the different available keys is below:
  25
  26 Top-level:
  27 - **environments**: This is the top-level key in the file.  All other keys
  28   below should appear in a list of dictionaries that define environments.
  29
  30 Environment-specific:
  31 - **name**: the output file will be this name + .yaml, in the
  32   ``environments`` directory.
  33 - **title**: a human-readable title for the environment.
  34 - **description**: A description of the environment.  Will be included
  35   as a comment at the top of the sample file.
  36 - **files**: The Heat templates containing the parameter definitions
  37   for the environment.  Should be specified as a path relative to the
  38   root of the ``tripleo-heat-templates`` project.  For example:
  39   ``puppet/extraconfig/tls/tls-cert-inject.yaml:``.  Each filename
  40   should be a YAML dictionary that contains a ``parameters`` entry.
  41 - **parameters**: There should be one ``parameters`` entry per file in the
  42   ``files`` section (see the example configuration below).
  43   This can be either a list of parameters related to
  44   the environment, which is necessary for templates like
  45   overcloud.yaml, or the string 'all', which indicates that all
  46   parameters from the file should be included.
  47 - **static**: Can be used to specify that certain parameters must
  48   not be changed.  Examples would be the EnableSomething params
  49   in the templates.  When writing a sample config for Something,
  50   ``EnableSomething: True`` would be a static param, since it
  51   would be nonsense to include the environment with it set to any other
  52   value.
  53 - **sample_values**: Sometimes it is useful to include a sample value
  54   for a parameter that is not the parameter's actual default.
  55   An example of this is the SSLCertificate param in the enable-tls
  56   environment file.
  57 - **resource_registry**: Many environments also need to pass
  58   resource_registry entries when they are used.  This can be used
  59   to specify that in the configuration file.
  60 - **children**: For environments that share a lot of common values but may
  61   need minor variations for different use cases, sample environment entries
  62   can be nested.  ``children`` takes a list of environments with the same
  63   structure as the top-level ``environments`` key.  The main difference is
  64   that all keys are optional, and any that are omitted will be inherited from
  65   the parent environment definition.
  66
  67 Some behavioral notes:
  68
  69 - Parameters without default values will be marked as mandatory to indicate
  70   that the user must set a value for them.
  71 - It is no longer recommended to set parameters using the ``parameters``
  72   section.  Instead, all parameters should be set as ``parameter_defaults``
  73   which will work regardless of whether the parameter is top-level or nested.
  74   Therefore, the tool will always set parameters in the ``parameter_defaults``
  75   section.
  76 - Parameters whose name begins with the _ character are treated as private.
  77   This indicates that the parameter value will be passed in from another
  78   template and does not need to be exposed directly to the user.
  79
  80 If adding a new environment, don't forget to add the new file to the
  81 git repository so it will be included with the review.
  82
  83 Example
  84 =======
  85
  86 Given a Heat template named ``example.yaml`` that looks like::
  87
  88     parameters:
  89       EnableExample:
  90         default: False
  91         description: Enable the example feature
  92         type: boolean
  93       ParamOne:
  94         default: one
  95         description: First example param
  96         type: string
  97       ParamTwo:
  98         description: Second example param
  99         type: number
 100       _PrivateParam:
 101         default: does not matter
 102         description: Will not show up
 103         type: string
 104
 105 And an environment generator entry that looks like::
 106
 107     environments:
 108       -
 109         name: example
 110         title: Example Environment
 111         description: |
 112           An example environment demonstrating how to use the sample
 113           environment generator.  This text will be included at the top
 114           of the generated file as a comment.
 115         files:
 116           example.yaml:
 117             parameters: all
 118         sample_values:
 119           EnableExample: True
 120         static:
 121           - EnableExample
 122         resource_registry:
 123           OS::TripleO::ExampleData: ../extraconfig/example.yaml
 124
 125 The generated environment file would look like::
 126
 127     # *******************************************************************
 128     # This file was created automatically by the sample environment
 129     # generator. Developers should use `tox -e genconfig` to update it.
 130     # Users are recommended to make changes to a copy of the file instead
 131     # of the original, if any customizations are needed.
 132     # *******************************************************************
 133     # title: Example Environment
 134     # description: |
 135     #   An example environment demonstrating how to use the sample
 136     #   environment generator.  This text will be included at the top
 137     #   of the generated file as a comment.
 138     parameter_defaults:
 139       # First example param
 140       # Type: string
 141       ParamOne: one
 142
 143       # Second example param
 144       # Mandatory. This parameter must be set by the user.
 145       # Type: number
 146       ParamTwo: <None>
 147
 148       # ******************************************************
 149       # Static parameters - these are values that must be
 150       # included in the environment but should not be changed.
 151       # ******************************************************
 152       # Enable the example feature
 153       # Type: boolean
 154       EnableExample: True
 155
 156       # *********************
 157       # End static parameters
 158       # *********************
 159     resource_registry:
 160       OS::TripleO::ExampleData: ../extraconfig/example.yaml