Skip to content

Commit ec86b30

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #498 from Liujingfang1/doc
Add example for transformer configurations: crd
2 parents 18a2321 + a90c957 commit ec86b30

File tree

5 files changed

+315
-0
lines changed

5 files changed

+315
-0
lines changed

‎examples/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,6 @@ go get sigs.k8s.io/kustomize
4242
* [remote target](remoteBuild.md) - Building a kustomization from a github URL
4343

4444
* [json patch](jsonpatch.md) - Apply a json patch in a kustomization
45+
46+
* [transformer configs](transformerconfigs/README.md) - Customize transformer configurations
47+

‎examples/transformerconfigs/README.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# Transformer Configurations
2+
3+
Kustomize computes the resources by applying a series of transformers:
4+
- namespace transformer
5+
- prefix transformer
6+
- label transformer
7+
- annotation transformer
8+
- name reference transformer
9+
- variable reference transformer
10+
11+
Each transformer takes a list of resources and modifies certain fields. The modification is based on the transformer's rule.
12+
The fields to update is the transformer's configuration, which is a list of filedspec that can be represented in YAML format.
13+
14+
## fieldSpec
15+
FieldSpec is a type to represent a path to a field in one kind of resources. It has following format
16+
```
17+
group: some-group
18+
version: some-version
19+
kind: some-kind
20+
path: path/to/the/field
21+
create: false
22+
```
23+
If `create` is set to true, it indicates the transformer to create the path if it is not found in the resources. This is most useful for label and annotation transformers, where the path for labels or annotations may not be set before the transformation.
24+
25+
## prefix transformer
26+
Name prefix transformer adds prefix to the `metadata/name` field for all resources with following configuration:
27+
```
28+
namePrefix:
29+
- path: metadata/name
30+
```
31+
32+
## label transformer
33+
Label transformer adds labels to `metadata/labels` field for all resources. It also adds labels to `spec/selector` field in all Service and to `spec/selector/matchLabels` field in all Deployment.
34+
```
35+
commonLabels:
36+
- path: metadata/labels
37+
create: true
38+
39+
- path: spec/selector
40+
create: true
41+
version: v1
42+
kind: Service
43+
44+
- path: spec/selector/matchLabels
45+
create: true
46+
kind: Deployment
47+
(etc.)
48+
```
49+
50+
## name reference transformer
51+
Name reference transformer's configuration is different from all other transformers. It contains a list of namebackreferences, which represented all the possible fields that a type could be used as a reference in other types of resources. A namebackreference contains a type such as ConfigMap as well as a list of FieldSpecs where ConfigMap is referenced. Here is an example.
52+
```
53+
kind: ConfigMap
54+
version: v1
55+
FieldSpecs:
56+
- kind: Pod
57+
version: v1
58+
path: spec/volumes/configMap/name
59+
- kind: Deployment
60+
path: spec/template/spec/volumes/configMap/name
61+
- kind: Job
62+
path: spec/template/spec/volumes/configMap/name
63+
(etc.)
64+
```
65+
Name reference transformer configuration contains a list of such namebackreferences for ConfigMap, Secret, Service, Role, ServiceAccount and so on.
66+
```
67+
nameReference:
68+
- kind: ConfigMap
69+
version: v1
70+
fieldSpecs:
71+
- path: spec/volumes/configMap/name
72+
version: v1
73+
kind: Pod
74+
- path: spec/containers/env/valueFrom/configMapKeyRef/name
75+
version: v1
76+
kind: Pod
77+
(etc.)
78+
- kind: Secret
79+
version: v1
80+
fieldSpecs:
81+
- path: spec/volumes/secret/secretName
82+
version: v1
83+
kind: Pod
84+
- path: spec/containers/env/valueFrom/secretKeyRef/name
85+
version: v1
86+
kind: Pod
87+
(etc.)
88+
```
89+
90+
## cusotmizing transformer configurations
91+
92+
Kustomize has a default set of configurations. They can be saved to local directory through `kustomize config save -d`. kusotmize allows modifying those configuration files and using them in `kustomize build` through `-t`. This tutorial shows how to customize those configurations to
93+
- [support a crd type](crd/README.md)
94+
- disabling adding commonLabels to fields in some kind of resources
95+
- add extra fields for variable substitution
96+
- add extra fields for name reference

‎examples/transformerconfigs/crd/README.md

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
## Transformer Configurations - CRD
2+
3+
This tutorial shows how to add transformer configurations to support a CRD type.
4+
5+
### Get Default Config
6+
Get the default transformer configurations by
7+
8+
<!-- @saveConfig @test -->
9+
```
10+
kustomize config save -d ~/.kustomize/config
11+
```
12+
The default configurations are save in directory `~/.kustomize/config` as several files
13+
14+
> ```
15+
> commonannotations.yaml commonlabels.yaml nameprefix.yaml namereference.yaml namespace.yaml varreference.yaml
16+
> ```
17+
18+
### Add Config for a CRD
19+
All transformers will be involved for a CRD type. The default configurations already include some common fieldSpec for all types:
20+
21+
- nameprefix is added to `.metadata.name`
22+
- namespace is added to `.metadata.namespace`
23+
- labels is added to `.metadata.labels`
24+
- annotations is added to `.metadata.annotations`
25+
26+
Thus those fieldSpec don't need to be added to support a CRD type.
27+
Consider a CRD type `MyKind` with fields
28+
- `.spec.secretRef.name` reference a Secret
29+
- `.spec.beeRef.name` reference an instance of CRD `Bee`
30+
- `.spec.containers.command` as the list of container commands
31+
- `.spec.selectors` as the label selectors
32+
33+
Add following file to configure the transformers for the above fields
34+
<!-- @addConfig @test -->
35+
```
36+
cat > ~/.kustomize/config/mykind.yaml << EOF
37+
38+
commonLabels:
39+
- path: spec/selectors
40+
create: true
41+
kind: MyKind
42+
43+
nameReference:
44+
- kind: Bee
45+
fieldSpecs:
46+
- path: spec/beeRef/name
47+
kind: MyKind
48+
- kind: Secret
49+
fieldSpecs:
50+
- path: spec/secretRef/name
51+
kind: MyKind
52+
53+
varReference:
54+
- path: spec/containers/command
55+
kind: MyKind
56+
- path: spec/beeRef/action
57+
kind: MyKind
58+
59+
EOF
60+
```
61+
62+
### Apply config
63+
Create a kustomization with a `MyKind` instance.
64+
65+
<!-- @createKustomization @test -->
66+
```
67+
DEMO_HOME=$(mktemp -d)
68+
69+
cat > $DEMO_HOME/kustomization.yaml << EOF
70+
resources:
71+
- resources.yaml
72+
73+
namePrefix: test-
74+
75+
commonLabels:
76+
foo: bar
77+
78+
vars:
79+
- name: BEE_ACTION
80+
objref:
81+
kind: Bee
82+
name: bee
83+
apiVersion: v1beta1
84+
fieldref:
85+
fieldpath: spec.action
86+
EOF
87+
88+
cat > $DEMO_HOME/resources.yaml << EOF
89+
apiVersion: v1
90+
kind: Secret
91+
metadata:
92+
name: crdsecret
93+
data:
94+
PATH: YmJiYmJiYmIK
95+
---
96+
apiVersion: v1beta1
97+
kind: Bee
98+
metadata:
99+
name: bee
100+
spec:
101+
action: fly
102+
---
103+
apiVersion: jingfang.example.com/v1beta1
104+
kind: MyKind
105+
metadata:
106+
name: mykind
107+
spec:
108+
secretRef:
109+
name: crdsecret
110+
beeRef:
111+
name: bee
112+
action: \$(BEE_ACTION)
113+
containers:
114+
- command:
115+
- "echo"
116+
- "\$(BEE_ACTION)"
117+
image: myapp
118+
EOF
119+
```
120+
121+
Run `kustomize build` with customized transformer configurations and verify that
122+
the namereference is correctly resolved.
123+
124+
<!-- @build @test -->
125+
```
126+
test 2 == \
127+
$(kustomize build $DEMO_HOME -t ~/.kustomize/config | grep -A 2 ".*Ref" | grep "test-" | wc -l); \
128+
echo $?
129+
```
130+
131+
Run `kustomize build` with customized transformer configurations and verify that
132+
the vars correctly resolved.
133+
134+
<!-- @verify @test -->
135+
```
136+
test 0 == \
137+
$(kustomize build $DEMO_HOME -t ~/.kustomize/config | grep "BEE_ACTION" | wc -l); \
138+
echo $?
139+
```
140+
141+
To understand this better, compare the output using default transformer configurations.
142+
143+
<!-- @compareOutput -->
144+
```
145+
diff \
146+
<(kustomize build $DEMO_HOME) \
147+
<(kustomize build $DEMO_HOME -t ~/.kustomize/config ) |\
148+
more
149+
```
150+
151+
The difference output should look something like
152+
> ```
153+
> 20,21c20,21
154+
> < action: $(BEE_ACTION)
155+
> < name: bee
156+
> ---
157+
> > action: fly
158+
> > name: test-bee
159+
> 25c25
160+
> < - $(BEE_ACTION)
161+
> ---
162+
> > - fly
163+
> 28c28,30
164+
> < name: crdsecret
165+
> ---
166+
> > name: test-crdsecret
167+
> > selectors:
168+
> > foo: bar
169+
> ```
170+
171+

‎examples/transformerconfigs/crd/kustomization.yaml

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
resources:
2+
- resources.yaml
3+
4+
namePrefix: test-
5+
6+
commonLabels:
7+
foo: bar
8+
9+
vars:
10+
- name: BEE_ACTION
11+
objref:
12+
kind: Bee
13+
name: bee
14+
apiVersion: v1beta1
15+
fieldref:
16+
fieldpath: spec.action

‎examples/transformerconfigs/crd/resources.yaml

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
apiVersion: v1
2+
kind: Secret
3+
metadata:
4+
name: crdsecret
5+
data:
6+
PATH: YmJiYmJiYmIK
7+
---
8+
apiVersion: v1beta1
9+
kind: Bee
10+
metadata:
11+
name: bee
12+
spec:
13+
action: fly
14+
---
15+
apiVersion: jingfang.example.com/v1beta1
16+
kind: MyKind
17+
metadata:
18+
name: mykind
19+
spec:
20+
secretRef:
21+
name: crdsecret
22+
beeRef:
23+
name: bee
24+
action: $(BEE_ACTION)
25+
containers:
26+
- command:
27+
- "echo"
28+
- "$(BEE_ACTION)"
29+
image: myapp

0 commit comments

Comments
 (0)