blob: 1444dd4912497986c1c012e4578dcb2300361490 (
plain) (
blame)
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
161
162
163
164
165
166
167
168
169
170
|
Resource Sets
================
Resource sets are collections of Kubernetes resources that should be passed to `kubectl` together.
Technically a resource set is simply a folder with a few YAML and/or JSON templates in it.
<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->
**Table of Contents**
- [Resource Sets](#resource-sets)
- [Creating resource sets](#creating-resource-sets)
- [Default variables](#default-variables)
- [Including resource sets](#including-resource-sets)
- [Fields](#fields)
- [`name`](#name)
- [`path`](#path)
- [`values`](#values)
- [`args`](#args)
- [`include`](#include)
- [Multiple includes](#multiple-includes)
- [Nesting resource sets](#nesting-resource-sets)
- [Caveats](#caveats)
<!-- markdown-toc end -->
# Creating resource sets
Simply create a folder in your Kontemplate repository and place a YAML or JSON file in it. These
files get interpreted as [templates][] during Kontemplate runs and variables (as well as template
logic or functions) will be interpolated.
Refer to the template documentation for information on how to write templates.
## Default variables
Sometimes it is useful to specify default values for variables that should be interpolated during
a run if the [cluster configuration][] does not specify a variable explicitly.
This can be done simply by placing a `default.yaml` or `default.json` file in the resource set
folder and filling it with key/value pairs of the intended default variables.
Kontemplate will error during interpolation if any variables are left unspecified.
# Including resource sets
Under the cluster configuration `include` key resource sets are included and required variables
are specified. For example:
```yaml
include:
- name: some-api
values:
version: 1.2-SNAPSHOT
```
This will include a resource set from a folder called `some-api` and set the specified `version` variable.
## Fields
The available fields when including a resource set are these:
### `name`
The `name` field contains the name of the resource set. This name can be used to refer to the resource set
when specifying explicit includes or excludes during a run.
By default it is assumed that the `name` is the path to the resource set folder, but this can be overridden.
This field is **required**.
### `path`
The `path` field specifies an explicit path to a resource set folder in the case that it should differ from
the resource set's `name`.
This field is **optional**.
### `values`
The `values` field specifies key/values pairs of variables that should be available during templating.
This field is **optional**.
### `args`
The `args` field specifies a list of arguments that should be passed to `kubectl`.
This field is **optional**.
### `include`
The `include` field specifies additional resource sets that should be included and that should inherit the
variables of this resource set.
The fully qualified names of "nested" resource sets are set to `${PARENT_NAME}/${CHILD_NAME}` and paths are
merged in the same way.
This makes it easy to organise different resource sets as "groups" to include / exclude them collectively
during runs.
This field is **optional**.
## Multiple includes
Resource sets can be included multiple times with different configurations. In this case it is recommended
to set the `path` and `name` fields explicitly. For example:
```yaml
include:
- name: forwarder-europe
path: tools/forwarder
values:
source: europe
- name: forwarder-asia
path: tools/forwarder
values:
source: asia
```
The two different configurations can be referred to by their set names, but will use the same resource
templates with different configurations.
## Nesting resource sets
As mentioned above for the `include` field, resource sets can be nested. This lets users group resource
sets in logical ways using simple folder structures.
Assuming a folder structure like:
```
├── backend
│ ├── auth-api
│ ├── message-api
│ └── order-api
└── frontend
├── app-page
└── login-page
```
With each of these folders being a resource set, they could be included in a cluster configuration like so:
```yaml
include:
- name: backend
include:
- name: auth-api
- name: message-api
- name: order-api
- name: frontend:
include:
- name: app-page
- name: login-page
```
Kontemplate could then be run with, for example, `--include backend` to only include the resource sets nested
in the backend group. Specific resource sets can also be targeted, for example as `--include backend/order-api`.
Variables specified in the parent resource set are inherited by the children.
### Caveats
Two caveats apply that users should be aware of:
1. The parent resource set can not contain any resource templates itself.
2. Only one level of nesting is supported. Specifying `include` again on a nested resource set will be ignored.
[templates]: templates.md
[cluster configuration]: cluster-config.md
|
