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