Skip to content

Commit 3b0a998

Browse files
anEXPerkcboyle
anEXPer
and
kcboyle
committedAug 28, 2020
Update docs with dual-pass interp info
Signed-off-by: Kira Boyle <kirab@vmware.com> Co-authored-by: Kira Boyle <kirab@vmware.com>
·
7.15.06.2.0
1 parent d85df9b commit 3b0a998

File tree

2 files changed

+102
-6
lines changed

2 files changed

+102
-6
lines changed
 

‎docs/interpolate/README.md

+51-3
Original file line numberDiff line numberDiff line change
@@ -47,15 +47,15 @@ Global Flags:
4747
```
4848

4949
## Interpolation
50-
5150
Given a template file with a variable reference:
5251

5352
```yaml
5453
# config.yml
5554
key: ((variable_name))
5655
```
5756
58-
Values can be provided from a separate variables yaml file (`--vars-file`) or from environment variables (`--vars-env`).
57+
Values can be provided from a separate variables yaml file (`--vars-file`)
58+
or from environment variables (`--vars-env`).
5959

6060
To load variables from a file use the `--vars-file` flag.
6161

@@ -81,4 +81,52 @@ OM_VAR_variable_name=some_value om interpolate \
8181
8282
The interpolation support is inspired by similar features in BOSH. You can
8383
[refer to the BOSH documentation](https://bosh.io/docs/cli-int/) for details on how interpolation
84-
is performed.
84+
is performed.
85+
86+
One significant difference from similar features in BOSH
87+
and Concourse `fly` is that `om` performs _dual-pass_ interpolation.
88+
That is, the template is interpolated (including applying ops files) once,
89+
and then the output of that interpolation is interpolated again,
90+
using the same arguments (except for Ops Files,
91+
which are not necessarily idempotent).
92+
93+
This allows the use of _mapping variables_,
94+
variables that contain a value that is a variable in turn.
95+
Mapping variables are useful for mapping
96+
between programmatically-generated variable names
97+
such as those created by `om config-template` and `om staged-director-config`,
98+
and credentials that may be used in multiple places,
99+
such as database passwords.
100+
101+
Such config might look something like this:
102+
103+
```
104+
cc:
105+
database-password: ((cc_database_password))
106+
uaa:
107+
database-password: ((uaa_database_password))
108+
```
109+
110+
In such cases, a vars-file like this can encode the relationship:
111+
112+
```
113+
---
114+
cc_database_password: ((sql_password))
115+
uaa_database_password: ((sql_password))
116+
```
117+
118+
Assuming the value of `sql_password` is available to the interpolation,
119+
it will be present in the final output,
120+
like so:
121+
122+
```
123+
cc:
124+
database-password: actualsqlpasswordverysecure
125+
uaa:
126+
database-password: actualsqlpasswordverysecure
127+
```
128+
129+
This feature generally shouldn't interfere with interpolation
130+
as it would normally work in BOSH.
131+
If you encounter any situation where this difference is an unwelcome surprise,
132+
please open an issue; we were unable to think of any.

‎docsgenerator/templates/interpolate/ADDITIONAL_INFO.md

+51-3
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
## Interpolation
2-
32
Given a template file with a variable reference:
43

54
```yaml
65
# config.yml
76
key: ((variable_name))
87
```
98
10-
Values can be provided from a separate variables yaml file (`--vars-file`) or from environment variables (`--vars-env`).
9+
Values can be provided from a separate variables yaml file (`--vars-file`)
10+
or from environment variables (`--vars-env`).
1111

1212
To load variables from a file use the `--vars-file` flag.
1313

@@ -33,4 +33,52 @@ OM_VAR_variable_name=some_value om interpolate \
3333
3434
The interpolation support is inspired by similar features in BOSH. You can
3535
[refer to the BOSH documentation](https://bosh.io/docs/cli-int/) for details on how interpolation
36-
is performed.
36+
is performed.
37+
38+
One significant difference from similar features in BOSH
39+
and Concourse `fly` is that `om` performs _dual-pass_ interpolation.
40+
That is, the template is interpolated (including applying ops files) once,
41+
and then the output of that interpolation is interpolated again,
42+
using the same arguments (except for Ops Files,
43+
which are not necessarily idempotent).
44+
45+
This allows the use of _mapping variables_,
46+
variables that contain a value that is a variable in turn.
47+
Mapping variables are useful for mapping
48+
between programmatically-generated variable names
49+
such as those created by `om config-template` and `om staged-director-config`,
50+
and credentials that may be used in multiple places,
51+
such as database passwords.
52+
53+
Such config might look something like this:
54+
55+
```
56+
cc:
57+
database-password: ((cc_database_password))
58+
uaa:
59+
database-password: ((uaa_database_password))
60+
```
61+
62+
In such cases, a vars-file like this can encode the relationship:
63+
64+
```
65+
---
66+
cc_database_password: ((sql_password))
67+
uaa_database_password: ((sql_password))
68+
```
69+
70+
Assuming the value of `sql_password` is available to the interpolation,
71+
it will be present in the final output,
72+
like so:
73+
74+
```
75+
cc:
76+
database-password: actualsqlpasswordverysecure
77+
uaa:
78+
database-password: actualsqlpasswordverysecure
79+
```
80+
81+
This feature generally shouldn't interfere with interpolation
82+
as it would normally work in BOSH.
83+
If you encounter any situation where this difference is an unwelcome surprise,
84+
please open an issue; we were unable to think of any.

0 commit comments

Comments
 (0)
Please sign in to comment.