You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
`tgen` is a simple CLI application that allows you to write a template file and then use the power of Go Templates to generate an output (which is) outputted to `stdout`. Besides the Go Template engine itself, `tgen` contains a few extra utility functions to assist you when writing templates. See below for a description of each.
7
6
8
7
You can also use the `--help` (or `-h`) to see the available set of options. The only flag required is the file to process, and everything else is optional.
@@ -15,7 +14,7 @@ Usage:
15
14
16
15
Flags:
17
16
-e, --environment string an optional environment file to use (key=value formatted) to perform replacements
18
-
-f, --file string the template file to process
17
+
-f, --file string the template file to process, or "-" to read from stdin
-x, --execute string a raw template to execute directly, without providing --file
21
20
-v, --values string a file containing values to use for the template, a la Helm
@@ -25,132 +24,68 @@ Flags:
25
24
--version version for tgen
26
25
```
27
26
28
-
### Environment file
27
+
##Usage
29
28
30
-
`tgen` supports an optional environment variable collection in a file but it's a pretty basic implementation of a simple key/value pair. The environment file works by finding lines that aren't empty or preceded by a pound `#` -- since they're treated as comments -- and then tries to find at least one equal (`=`) sign. If it can find at least one, all values on the left side of the equal sign become the key and the contents on the right side become the value. If the same line has more than one equal, only the first one is honored and all remaining ones become part of the value.
29
+
You can use `tgen`:
31
30
32
-
There's no support for Bash interpolation or multiline values. If this is needed, consider using a YAML values file instead.
31
+
* By reading environment variables from the environment or a key-value file
32
+
* By reading variables from a YAML values file
33
33
34
-
#### Example
34
+
While working with it, `tgen` supports a "strict" mode, where if a variable (either environment or from a values file) is used in the template but not set, it will fail the template generation.
35
35
36
-
Consider the following template, named `template.txt`:
36
+
## Examples
37
37
38
-
```handlebars
39
-
The dog licked the {{ env "element" }} and everyone laughed.
40
-
```
38
+
### Simple template
41
39
42
-
And the following environment file, named `contents.env`:
40
+
Using a template file and an environment file, you can generate a template as follows:
43
41
44
42
```bash
45
-
element=Oil
46
-
```
43
+
$ cat template.txt
44
+
The dog licked the {{ env "element" }} and everyone laughed.
47
45
48
-
After being passed to `tgen`, the output becomes:
46
+
$ cat contents.env
47
+
element=Oil
49
48
50
-
```bash
51
49
$ tgen -e contents.env -f template.txt
52
50
The dog licked the Oil and everyone laughed.
53
51
```
54
52
55
-
Using the inline mode to execute a template, you can also call the program as such (note the use of single-quotes since in Go, strings are always double-quoted) which will yield the same result:
56
-
57
-
```bash
58
-
$ tgen -x '{{ env "element" }}' -e contents.env
59
-
The dog licked the Oil and everyone laughed.
60
-
```
61
-
62
-
Do note as well that using single quotes for the template allows you to prevent any bash special parsing logic that your terminal might have.
63
-
64
-
### Helm-style values
65
-
66
-
`tgen` can be used to generate templates, in a very similar way as `helm` can be used. However, do note that `tgen`'s intention is not to replace `helm` since it can't handle application lifecycle the way `helm` does, however, it can do a great job generating resources with very similar code.
67
-
68
-
Consider the following example of creating a Kubernetes secret for a `tls.crt` file -- in real environments, you'll also need the key, but for the sake of this example, it has been omitted.
69
-
70
-
Checking the files in the folder:
71
-
72
-
```bash
73
-
tree .
74
-
```
75
-
76
-
```text
77
-
.
78
-
├── secret.yaml
79
-
└── tls.crt
80
-
81
-
0 directories, 2 files
82
-
```
53
+
### Inline mode
83
54
84
-
We have a `secret.yaml` which includes `tgen` templating notation:
55
+
You can skip the template file altogether and use the inline mode to execute a template directly:
$ tgen -e contents.env -x 'The dog licked the {{ env "element" }} and everyone laughed.'
62
+
The dog licked the Oil and everyone laughed.
98
63
```
99
64
100
-
The last line includes the following logic:
101
-
102
-
* Reads the `tls.crt` file from the current directory where `tgen` is run
103
-
* Takes the contents of the file and converts it to `base64` -- required by Kubernetes secrets
104
-
* Then indents with 4 spaces, starting with a new line
65
+
### Helm-style values
105
66
106
-
To generate the output, we can now run `tgen`:
67
+
While `tgen` Helm-like support is currently limited to values, it allows for a powerful way to generate templates. Consider the following example:
107
68
108
69
```bash
109
-
tgen -f secret.yaml
110
-
```
111
-
112
-
And the output looks like this:
113
-
114
-
```yaml
115
-
apiVersion: v1
116
-
kind: Secret
117
-
metadata:
118
-
name: secret-tls
119
-
type: kubernetes.io/tls
120
-
data:
121
-
tls.crt: |
122
-
Rk9PQkFSQkFaCg==
123
-
```
70
+
$ cat template.txt
71
+
The dog licked the {{ .element }} and everyone laughed.
124
72
125
-
This output can be then passed to Kubernetes as follows:
73
+
$ cat values.yaml
74
+
element: Oil
126
75
127
-
```
128
-
tgen -f secret.yaml | kubectl apply -f -
129
-
```
130
-
131
-
Do keep in mind though your DevOps requirements in terms of keeping a copy of your YAML files, rendered. Additionally, the `readfile` function is akin to `helm`'s `.Files`, with the exception that **you can read any file the `tgen` binary has access**, including potentially sensitive files such as `/etc/passwd`. If this is a concern, please run `tgen` in a CI/CD environment or where access to these resources is limited.
132
-
133
-
You can also use a `values.yaml` file like Helm. `tgen` will allow you to read values from the values file as `.variable` or `.Values.variable`. The latter is the same as Helm's `.Values.variable` and the former is a shortcut to `.Values.variable` for convenience. Consider the following YAML values file:
134
-
135
-
```yaml
136
-
name: Patrick
137
-
```
138
-
139
-
And the following template:
140
-
141
-
```handlebars
142
-
Hello, my name is {{ .name }}.
76
+
$ tgen -v values.yaml -f template.txt
77
+
The dog licked the Oil and everyone laughed.
143
78
```
144
79
145
-
Running `tgen` with the values file will yield the following output:
80
+
In the last function call, if your file is named `values.yaml`, you can omit it calling it directly and instead use:
146
81
147
82
```bash
148
-
$ tgen -f template.yaml -v values.yaml
149
-
Hello, my name is Patrick.
83
+
$ tgen --with-values -f template.txt
84
+
The dog licked the Oil and everyone laughed.
150
85
```
151
86
152
-
If your values file is called `values.yaml`, you also have the handy shortcut of simply specifying `--with-values` and `tgen` will automatically include the values file from the current working directory.
87
+
For more details, see the ["Kubernetes and Helm-style values" documentation page](docs/helm-style-values.md).
153
88
154
-
### Template functions
89
+
## Template functions
155
90
156
91
See [template functions](docs/functions.md) for a list of all the functions available.
All examples below have been generated using `-x` -- or `--execute`, which allows passing a template as argument rather than reading a file. In either case, whether the template file -- with `-f` or `--file` -- or the template argument is used, all functions are available.
18
19
@@ -91,6 +92,8 @@ Both `env` and `envdefault` are case insensitive -- either `"home"` or `"HOME"`
91
92
92
93
When `--strict` mode is enabled, if `env` is called with a environment variable name with no value set or set to empty, the application will exit with error. Useful if you must receive a value or fail a CI build, for example.
93
94
95
+
Consider the following example reading these environment variables:
96
+
94
97
```bash
95
98
$ tgen -x '{{ env "user" }}'
96
99
patrick
@@ -99,16 +102,22 @@ $ tgen -x '{{ env "USER" }}'
99
102
patrick
100
103
```
101
104
105
+
Then trying to read a nonexistent environment variable with `--strict` mode enabled:
106
+
102
107
```bash
103
-
$ tgen -x '{{ env "foobar" }}' -s
104
-
Error: strict mode on: environment variable not found: $FOOBAR
108
+
$ tgen -x '{{ env "foobar" }}' --strict
109
+
Error: evaluating /dev/stdin:1:3: strict mode on: environment variable not found: $FOOBAR
105
110
```
106
111
112
+
And bypassing strict mode by setting a default value:
Error: evaluating /dev/stdin:1:15: environment variable "foo" is required
219
+
```
220
+
221
+
Note that you can also use `--strict` mode to achieve a similar result. The difference between `--strict` and `required` is that `required` works anywhere: not just on missing YAML value keys or environment variables. Here's another example:
222
+
223
+
```bash
224
+
$ tgen -x '{{ "" | required "Value must be set" }}'
225
+
Error: evaluating /dev/stdin:1:8: Value must be set
Consider the following example of creating a Kubernetes secret for a `tls.crt` file -- in real environments, you'll also need the key, but for the sake of this example, it has been omitted.
4
+
5
+
Checking the files in the folder:
6
+
7
+
```bash
8
+
tree .
9
+
```
10
+
11
+
```text
12
+
.
13
+
├── secret.yaml
14
+
└── tls.crt
15
+
16
+
0 directories, 2 files
17
+
```
18
+
19
+
We have a `secret.yaml` which includes `tgen` templating notation:
* Reads the `tls.crt` file from the current directory where `tgen` is run
38
+
* Takes the contents of the file and converts it to `base64` -- required by Kubernetes secrets
39
+
* Then indents with 4 spaces, starting with a new line
40
+
41
+
To generate the output, we can now run `tgen`:
42
+
43
+
```bash
44
+
tgen -f secret.yaml
45
+
```
46
+
47
+
And the output looks like this:
48
+
49
+
```yaml
50
+
apiVersion: v1
51
+
kind: Secret
52
+
metadata:
53
+
name: secret-tls
54
+
type: kubernetes.io/tls
55
+
data:
56
+
tls.crt: |
57
+
Rk9PQkFSQkFaCg==
58
+
```
59
+
60
+
This output can be then passed to Kubernetes as follows:
61
+
62
+
```
63
+
tgen -f secret.yaml | kubectl apply -f -
64
+
```
65
+
66
+
Do keep in mind though your DevOps requirements in terms of keeping a copy of your YAML files, rendered. Additionally, the `readfile` function is akin to `helm`'s `.Files`, with the exception that **you can read any file the `tgen` binary has access**, including potentially sensitive files such as `/etc/passwd`. If this is a concern, please run `tgen` in a CI/CD environment or where access to these resources is limited.
67
+
68
+
You can also use a `values.yaml` file like Helm. `tgen` will allow you to read values from the values file as `.variable` or `.Values.variable`. The latter is the same as Helm's `.Values.variable` and the former is a shortcut to `.Values.variable` for convenience. Consider the following YAML values file:
69
+
70
+
```yaml
71
+
name: Patrick
72
+
```
73
+
74
+
And the following template:
75
+
76
+
```handlebars
77
+
Hello, my name is {{ .name }}.
78
+
```
79
+
80
+
Running `tgen` with the values file will yield the following output:
81
+
82
+
```bash
83
+
$ tgen -f template.yaml -v values.yaml
84
+
Hello, my name is Patrick.
85
+
```
86
+
87
+
If your values file is called `values.yaml`, you also have the handy shortcut of simply specifying `--with-values` and `tgen` will automatically include the values file from the current working directory.
0 commit comments