1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
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
appropriate file in the ``sample-env-generator/`` directory. The existing
entries in the files can be used as examples, and a more detailed
explanation of the different available keys is below:
Top-level:
- **environments**: This is the top-level key in the file. All other keys
below should appear in a list of dictionaries that define environments.
Environment-specific:
- **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.
- **children**: For environments that share a lot of common values but may
need minor variations for different use cases, sample environment entries
can be nested. ``children`` takes a list of environments with the same
structure as the top-level ``environments`` key. The main difference is
that all keys are optional, and any that are omitted will be inherited from
the parent environment definition.
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
|
