Skip to content

Commit a3103f1

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #1534 from monopole/configExample
Example of configuring builtin plugin.
2 parents 32be1cf + 74ed0b3 commit a3103f1

15 files changed

+1223
-455
lines changed

‎docs/fields.md

Lines changed: 27 additions & 304 deletions
Large diffs are not rendered by default.

‎docs/plugins/builtins.md

Lines changed: 683 additions & 0 deletions
Large diffs are not rendered by default.

‎examples/configureBuiltinPlugin.md

Lines changed: 333 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,333 @@
1+
[builtin operations]: ../docs/plugins/builtins.md
2+
[builtin plugins]: ../docs/plugins/builtins.md
3+
[plugins]: ../docs/plugins
4+
[plugin]: ../docs/plugins
5+
[fields]: ../docs/fields.md
6+
[fields in a kustomization file]: ../docs/fields.md
7+
[TransformerConfig]: ../pkg/transformers/config/transformerconfig.go
8+
[kustomization]: ../docs/glossary.md#kustomization
9+
10+
# Customizing kustomize
11+
12+
The [fields in a kustomization file] allow the user to
13+
specify which resource files to use as input, how to
14+
_generate_ new resources, and how to _transform_ those
15+
resources - add labels, patch them, etc.
16+
17+
These fields are simple (low argument count) directives.
18+
For example, the `commonAnnotations` field demands only a
19+
list of _name:value_ pairs.
20+
21+
If using a field triggers behavior that pleases the user,
22+
everyone's happy.
23+
24+
If not, the user can ask for new behavior to be implemented
25+
in kustomize proper (and wait), or the user can write a
26+
transformer or generator [plugin]. This latter option
27+
generally means writing code; a Go plugin, a Go binary,
28+
a C++ binary, a `bash` script - something.
29+
30+
There's a third option. If one merely wants to tweak
31+
behavior that already exists in kustomize, one may be able
32+
to do so by just writing some YAML.
33+
34+
## Configure the builtin plugins
35+
36+
All of kustomize's [builtin operations] are implemented
37+
and usable as plugins.
38+
39+
Using the fields is convenient and brief, but necessarily
40+
specifies only part of the entire plugin specification. The
41+
unspecified part is defaulted to what are hopefully
42+
generally appealing values.
43+
44+
If, instead, one invokes the plugins directly using the
45+
`transformers` or `generators` field, one can (indeed
46+
_must_) specify the entire plugin configuration.
47+
48+
## Example: field vs plugin
49+
50+
Define a place to work:
51+
52+
<!-- @makeWorkplace @testAgainstLatestRelease -->
53+
```
54+
DEMO_HOME=$(mktemp -d)
55+
```
56+
57+
### Using the `commonLabels` and `commonAnnotations` fields
58+
59+
In this simple example, we'll use just two resources: a deployment and a service.
60+
61+
Define them:
62+
63+
<!-- @makeRes1 @testAgainstLatestRelease -->
64+
```
65+
cat <<EOF >$DEMO_HOME/deployment.yaml
66+
apiVersion: apps/v1
67+
kind: Deployment
68+
metadata:
69+
name: deployment
70+
spec:
71+
replicas: 10
72+
template:
73+
spec:
74+
containers:
75+
- name: the-container
76+
image: monopole/hello:1
77+
EOF
78+
```
79+
80+
<!-- @makeRes2 @testAgainstLatestRelease -->
81+
```
82+
cat <<EOF >$DEMO_HOME/service.yaml
83+
apiVersion: v1
84+
kind: Service
85+
metadata:
86+
name: service
87+
spec:
88+
type: LoadBalancer
89+
ports:
90+
- protocol: TCP
91+
port: 8666
92+
targetPort: 8080
93+
EOF
94+
```
95+
96+
Now make a kustomization file that causes them
97+
to be read and transformed:
98+
99+
<!-- @makeKustomization @testAgainstLatestRelease -->
100+
```
101+
cat <<'EOF' >$DEMO_HOME/kustomization.yaml
102+
namePrefix: hello-
103+
commonLabels:
104+
app: hello
105+
commonAnnotations:
106+
area: "51"
107+
greeting: Take me to your leader
108+
resources:
109+
- deployment.yaml
110+
- service.yaml
111+
EOF
112+
```
113+
114+
And run kustomize:
115+
116+
<!-- @checkLabel @testAgainstLatestRelease -->
117+
```
118+
kustomize build $DEMO_HOME
119+
```
120+
121+
The output will be something like
122+
123+
> ```
124+
> apiVersion: v1
125+
> kind: Service
126+
> metadata:
127+
> annotations:
128+
> area: "51"
129+
> greeting: Take me to your leader
130+
> labels:
131+
> app: hello
132+
> name: hello-service
133+
> spec:
134+
> ports:
135+
> - port: 8666
136+
> protocol: TCP
137+
> targetPort: 8080
138+
> selector:
139+
> app: hello
140+
> type: LoadBalancer
141+
> ---
142+
> apiVersion: apps/v1
143+
> kind: Deployment
144+
> metadata:
145+
> annotations:
146+
> area: "51"
147+
> greeting: Take me to your leader
148+
> labels:
149+
> app: hello
150+
> name: hello-deployment
151+
> spec:
152+
> replicas: 10
153+
> selector:
154+
> matchLabels:
155+
> app: hello
156+
> template:
157+
> metadata:
158+
> annotations:
159+
> area: "51"
160+
> greeting: Take me to your leader
161+
> labels:
162+
> app: hello
163+
> spec:
164+
> containers:
165+
> - image: monopole/hello:1
166+
> name: the-container
167+
> ```
168+
169+
Let's say we are unhappy with this result.
170+
171+
We only want the annotations
172+
to be applied down in the pod templates,
173+
and don't want to see them in the metadata
174+
for Service or Deployment.
175+
176+
We like that the label _app: hello_ ended up in
177+
178+
- Service `spec.selector`
179+
- Deployment `spec.selector.matchLabels`
180+
- Deployment `spec.template.metadata.labels`
181+
182+
as this binds the Service (load balancer) to the pods,
183+
and the Deployment itself to its own pods -
184+
but we again don't care to see these labels in
185+
the metadata for the Service and the Deployment.
186+
187+
188+
### Configuring the builtin plugins instead
189+
190+
To fine tune this, invoke the same transformations
191+
using the plugin approach.
192+
193+
Change the kustomization file:
194+
195+
<!-- @makeKustomization @testAgainstLatestRelease -->
196+
```
197+
cat <<'EOF' >$DEMO_HOME/kustomization.yaml
198+
namePrefix: hello-
199+
transformers:
200+
- myAnnotator.yaml
201+
- myLabeller.yaml
202+
resources:
203+
- deployment.yaml
204+
- service.yaml
205+
EOF
206+
```
207+
208+
Then make the two plugin configuration files
209+
(`myAnnotator.yaml`, `myLabeller.yaml`)
210+
referred to by the `transformers` field above.
211+
For details about the fields to specify, see
212+
the documentation for the [builtin plugins].
213+
214+
<!-- @makeAnnotatorPluginConfig @testAgainstLatestRelease -->
215+
```
216+
cat <<EOF >$DEMO_HOME/myAnnotator.yaml
217+
apiVersion: builtin
218+
kind: AnnotationsTransformer
219+
metadata:
220+
name: notImportantHere
221+
annotations:
222+
area: 51
223+
greeting: take me to your leader
224+
fieldSpecs:
225+
- kind: Deployment
226+
path: spec/template/metadata/annotations
227+
create: true
228+
EOF
229+
```
230+
231+
<!-- @makeLabelPluginConfig @testAgainstLatestRelease -->
232+
```
233+
cat <<EOF >$DEMO_HOME/myLabeller.yaml
234+
apiVersion: builtin
235+
kind: LabelTransformer
236+
metadata:
237+
name: notImportantHere
238+
labels:
239+
app: hello
240+
fieldSpecs:
241+
- kind: Service
242+
path: spec/selector
243+
create: true
244+
- kind: Deployment
245+
path: spec/selector/matchLabels
246+
create: true
247+
- kind: Deployment
248+
path: spec/template/metadata/labels
249+
create: true
250+
EOF
251+
```
252+
253+
Finally, run kustomize again:
254+
255+
<!-- @checkLabel @testAgainstLatestRelease -->
256+
```
257+
kustomize build $DEMO_HOME
258+
```
259+
260+
The output should resemble the following,
261+
with fewer labels and annotations.
262+
263+
> ```
264+
> apiVersion: v1
265+
> kind: Service
266+
> metadata:
267+
> name: hello-service
268+
> spec:
269+
> ports:
270+
> - port: 8666
271+
> protocol: TCP
272+
> targetPort: 8080
273+
> selector:
274+
> app: hello
275+
> type: LoadBalancer
276+
> ---
277+
> apiVersion: apps/v1
278+
> kind: Deployment
279+
> metadata:
280+
> name: hello-deployment
281+
> spec:
282+
> replicas: 10
283+
> selector:
284+
> matchLabels:
285+
> app: hello
286+
> template:
287+
> metadata:
288+
> annotations:
289+
> area: "51"
290+
> greeting: take me to your leader
291+
> labels:
292+
> app: hello
293+
> spec:
294+
> containers:
295+
> - image: monopole/hello:1
296+
> name: the-container
297+
> ```
298+
299+
300+
## The old way to do this
301+
302+
The original (and still functional) way to customize
303+
kustomize is to specify a `configurations` field in the
304+
kustomization file.
305+
306+
This field, normally omitted because it overrides hardcoded
307+
data, accepts a list of file path arguments. The files, in
308+
turn, specify which fields in which k8s objects should be
309+
affected by particular builtin transformations. It's a
310+
global configuration cutting across transformations, and
311+
doesn't effect generators at all.
312+
313+
At `build` time, the configuration files are unmarshalled
314+
into one instance of [TransformerConfig]. This
315+
object, _plus_ the field values for `namePrefix`, etc. are
316+
fed into the transformation code to build the output.
317+
318+
The best way to write these custom configuration files is to
319+
generate the files from the hardcoded values built into
320+
kustomize via these commands:
321+
322+
> ```
323+
> mkdir /tmp/junk
324+
> kustomize config save -d /tmp/junk
325+
> ```
326+
327+
One can then edit those file or files, and specify the
328+
resulting edited files in a `configurations:`
329+
field in a kustomization file used in a `build`.
330+
331+
Using plugins _completely ignores_ both hard coded
332+
tranformer configuration, and any configuration loaded by
333+
the `configuration` field.

‎pkg/image/image.go

Lines changed: 2 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,5 @@
1-
/*
2-
Copyright 2019 The Kubernetes Authors.
3-
4-
Licensed under the Apache License, Version 2.0 (the "License");
5-
you may not use this file except in compliance with the License.
6-
You may obtain a copy of the License at
7-
8-
http://www.apache.org/licenses/LICENSE-2.0
9-
10-
Unless required by applicable law or agreed to in writing, software
11-
distributed under the License is distributed on an "AS IS" BASIS,
12-
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13-
See the License for the specific language governing permissions and
14-
limitations under the License.
15-
*/
1+
// Copyright 2019 The Kubernetes Authors.
2+
// SPDX-License-Identifier: Apache-2.0
163

174
// Package image provides struct definitions and libraries
185
// for image overwriting of names, tags and digest.

‎pkg/types/configmapargs.go

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
// Copyright 2019 The Kubernetes Authors.
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
package types
5+
6+
// ConfigMapArgs contains the metadata of how to generate a configmap.
7+
type ConfigMapArgs struct {
8+
// GeneratorArgs for the configmap.
9+
GeneratorArgs `json:",inline,omitempty" yaml:",inline,omitempty"`
10+
}

0 commit comments

Comments
 (0)