Skip to content

Commit 11bc9b3

Browse files
karlkfikarlkfi
authored
Add annotation reference docs (#2636)
1 parent 839fb52 commit 11bc9b3

File tree

7 files changed

+459
-0
lines changed

7 files changed

+459
-0
lines changed

‎site/book/06-deploying-packages/03-handling-dependencies.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,3 +79,8 @@ statefulset.apps/wordpress-mysql deleted
7979
service/wordpress-mysql deleted
8080
2 resource(s) deleted, 0 skipped
8181
```
82+
83+
See [depends-on] for more information.
84+
85+
[depends-on]:
86+
/reference/annotations/depends-on

‎site/reference/README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@
22

33
- [CLI Reference](/reference/cli/)
44
- [Schema Reference](/reference/schema/)
5+
- [Annotations Reference](/reference/annotations/)

‎site/reference/annotations/README.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Annotations Reference
2+
3+
The following annotations are used to configure kpt features:
4+
5+
| Annotation | Description |
6+
| ---------- | ----------- |
7+
| [config.kubernetes.io/depends-on] | specifies one or more resource dependencies |
8+
| [config.kubernetes.io/apply-time-mutation] | specifies one or more substitutions to make at apply time using dependencies as input |
9+
| [config.kubernetes.io/local-config] | specifies a resource to be skipped when applying |
10+
11+
The following annotations are used by kpt internally:
12+
13+
| Annotation | Description |
14+
| ---------- | ----------- |
15+
| `internal.config.kubernetes.io/path` | specifies the resource's file path when formatted as a ResourceList |
16+
| `internal.config.kubernetes.io/index` | specifies the index of the resource in a file when formatted as a ResourceList |
17+
| `config.kubernetes.io/merge-source` | specifies the source of the resource during a three way merge |
18+
19+
[config.kubernetes.io/depends-on]: /reference/annotations/depends-on/
20+
[config.kubernetes.io/apply-time-mutation]: /reference/annotations/apply-time-mutation/
21+
[config.kubernetes.io/local-config]: /reference/annotations/local-config/

‎site/reference/annotations/apply-time-mutation/README.md

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
---
2+
title: "`apply-time-mutation`"
3+
linkTitle: "apply-time-mutation"
4+
type: docs
5+
description: >
6+
Specify one or more substitutions to make at apply time using dependencies as input.
7+
---
8+
9+
The `config.kubernetes.io/apply-time-mutation` annotation specifies one or more
10+
substitutions to make at apply time using dependencies as input.
11+
12+
### Schema
13+
14+
The annotation value accepts a list of substitutions, formatted as a YAML string.
15+
16+
- (\[\][Substitution]), required
17+
18+
A list of one or more substitutions to perform on the annotated object.
19+
20+
#### Substitution
21+
22+
A substitution is a modification to a specific target field.
23+
24+
- **sourceRef**: ([ObjectReference]), required
25+
26+
Reference to the source resource, the dependency for this substitution.
27+
28+
- **sourcePath**: (string), required
29+
30+
The source resource field to read from as input, specified with [JSONPath].
31+
32+
- **targetPath**: (string), required
33+
34+
The target resource field to write to as output, specified with [JSONPath].
35+
36+
- **token**: (string)
37+
38+
The substring to replace in the target resource field.
39+
40+
If the token is unspecified, the whole target field value will be replaced,
41+
allowing for replacement of non-string values using the source field type.
42+
43+
#### ObjectReference
44+
45+
A reference to a specific resource object.
46+
47+
- **apiVersion**: (string)
48+
49+
The group and version of the object resource.
50+
51+
One of the following is required: apiVersion or group.
52+
53+
- **group**: (string)
54+
55+
The group of the object resource.
56+
57+
Group is accepted as a version-less alternative to APIVersion.
58+
59+
Group must be empty for resources in the "core" group.
60+
61+
One of the following is required: apiVersion or group.
62+
63+
- **kind**: (string), required
64+
65+
The kind of the object resource.
66+
67+
- **name**: (string), required
68+
69+
The name of the object.
70+
71+
- **namespace**: (string)
72+
73+
The namespace of the object.
74+
75+
Namespace is required for namespaced resources.
76+
77+
### Behavior
78+
79+
Like the `depends-on` feature, `apply-time-mutation` waits for dependencies
80+
(source resources) to be applied and reconciled before applying the resource
81+
with the annotation.
82+
83+
Unlike the `depends-on` feature, `apply-time-mutation` modifies the annotated
84+
resource before applying it.
85+
86+
#### Special cases
87+
88+
If the source resource is not part of the package being applied, the apply of
89+
the target resource will fail with an error.
90+
91+
The `apply-time-mutation` annotation is only enforced by `kpt live apply` and
92+
`kpt live destroy`. Modifying or deleting these resources with other mechanisms
93+
will not follow the rules specified by these annotations.
94+
95+
### JSONPath syntax
96+
97+
Since there is no formal specification for JSONPath, the supported syntax
98+
depends on the chosen implimentation. In this case, kpt uses the
99+
[ajson](https://github.com/spyzhov/ajson) library. For details about what
100+
language features are supported, see the
101+
[json-path-comparison table](https://cburgmer.github.io/json-path-comparison/).
102+
103+
### Example
104+
105+
In this example, pod-b depends on pod-a with two substitutions that replace
106+
tokens in the same target field. The value of the SERVICE_HOST environment
107+
variable of a container in pod-b will be updated to represent the host and port
108+
from pod-a.
109+
110+
Create a new kpt package:
111+
112+
```shell
113+
mkdir my-pkg
114+
cd my-pkg
115+
kpt pkg init
116+
```
117+
118+
Configure two pods, with one that depends on the other:
119+
120+
```shell
121+
cat > pods.yaml << EOF
122+
kind: Pod
123+
apiVersion: v1
124+
metadata:
125+
name: pod-a
126+
namespace: test
127+
spec:
128+
containers:
129+
- name: nginx
130+
image: nginx:1.21
131+
ports:
132+
- name: tcp
133+
containerPort: 80
134+
---
135+
apiVersion: v1
136+
kind: Pod
137+
metadata:
138+
name: pod-b
139+
namespace: test
140+
annotations:
141+
config.kubernetes.io/apply-time-mutation: |
142+
- sourceRef:
143+
kind: Pod
144+
name: pod-a
145+
sourcePath: $.status.podIP
146+
targetPath: $.spec.containers[?(@.name=="nginx")].env[?(@.name=="SERVICE_HOST")].value
147+
token: ${pod-a-ip}
148+
- sourceRef:
149+
kind: Pod
150+
name: pod-a
151+
sourcePath: $.spec.containers[?(@.name=="nginx")].ports[?(@.name=="tcp")].containerPort
152+
targetPath: $.spec.containers[?(@.name=="nginx")].env[?(@.name=="SERVICE_HOST")].value
153+
token: ${pod-a-port}
154+
spec:
155+
containers:
156+
- name: nginx
157+
image: nginx:1.21
158+
ports:
159+
- name: tcp
160+
containerPort: 80
161+
env:
162+
- name: SERVICE_HOST
163+
value: "${pod-a-ip}:${pod-a-port}"
164+
EOF
165+
```
166+
167+
Create a namespace for your package:
168+
169+
```shell
170+
kubectl create namespace test
171+
```
172+
173+
Initialize the package inventory:
174+
175+
```shell
176+
kpt live init
177+
```
178+
179+
Apply the package to your Kubernetes cluster:
180+
181+
```shell
182+
kpt live apply
183+
```
184+
185+
If all goes well, the output should look like this:
186+
187+
```
188+
pod/pod-a created
189+
1 resource(s) applied. 1 created, 0 unchanged, 0 configured, 0 failed
190+
pod/pod-b created
191+
1 resource(s) applied. 1 created, 0 unchanged, 0 configured, 0 failed
192+
```
193+
194+
To verify that the SERVICE_HOST was mutated correctly:
195+
196+
```shell
197+
# Read the IP of pod-a
198+
kubectl get pod pod-a -n test \
199+
-o jsonpath='{.status.podIP}'
200+
```
201+
202+
```shell
203+
# Read the SERVICE_HOST of pod-b
204+
kubectl get pod pod-b -n test \
205+
-o jsonpath='{.spec.containers[?(@.name=="nginx")].env[?(@.name=="SERVICE_HOST")].value}'
206+
```
207+
208+
Delete the package from your Kubernetes cluster:
209+
210+
```shell
211+
kpt live destroy
212+
```
213+
214+
If all goes well, the output should look like this:
215+
216+
```
217+
pod/pod-b deleted
218+
1 resource(s) deleted, 0 skipped
219+
pod/pod-a deleted
220+
1 resource(s) deleted, 0 skipped
221+
```
222+
223+
[Substitution]: /reference/annotations/apply-time-mutation/#substitution
224+
[ObjectReference]: /reference/annotations/apply-time-mutation/#objectreference
225+
[JSONPath]: /reference/annotations/apply-time-mutation/#jsonpath-syntax

‎site/reference/annotations/depends-on/README.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: "`depends-on`"
3+
linkTitle: "depends-on"
4+
type: docs
5+
description: >
6+
Specify one or more resource dependencies.
7+
---
8+
9+
The `config.kubernetes.io/depends-on` annotation specifies one or more resource
10+
dependencies.
11+
12+
### Schema
13+
14+
The annotation value accepts a list of resource references, delimited by commas.
15+
16+
#### Resource reference
17+
18+
A resource reference is a string that uniquely identifies a resource.
19+
20+
It consists of the group, kind, name, and optionally the namespace, delimited by
21+
forward slashes.
22+
23+
| Resource Scope | Format |
24+
| -------------- | ------ |
25+
| namespace-scoped | `<group>/namespaces/<namespace>/<kind>/<name>` |
26+
| cluster-scoped | `<group>/<kind>/<name>` |
27+
28+
For resources in the "core" group, the empty string is used instead
29+
(for example: `/namespaces/test/Pod/pod-a`).
30+
31+
### Example
32+
33+
In this example, pod-b depends on pod-a.
34+
35+
Create a new kpt package:
36+
37+
```shell
38+
mkdir my-pkg
39+
cd my-pkg
40+
kpt pkg init
41+
```
42+
43+
Configure two pods, with one that depends on the other:
44+
45+
```shell
46+
cat > pods.yaml << EOF
47+
kind: Pod
48+
apiVersion: v1
49+
metadata:
50+
name: pod-a
51+
namespace: test
52+
spec:
53+
containers:
54+
- name: nginx
55+
image: nginx:1.21
56+
ports:
57+
- containerPort: 80
58+
---
59+
kind: Pod
60+
apiVersion: v1
61+
metadata:
62+
name: pod-b
63+
namespace: test
64+
annotations:
65+
config.kubernetes.io/depends-on: /namespaces/test/Pod/pod-a
66+
spec:
67+
containers:
68+
- name: nginx
69+
image: nginx:1.21
70+
ports:
71+
- containerPort: 80
72+
EOF
73+
```
74+
75+
Create a namespace for your package:
76+
77+
```shell
78+
kubectl create namespace test
79+
```
80+
81+
Initialize the package inventory:
82+
83+
```shell
84+
kpt live init
85+
```
86+
87+
Apply the package to your Kubernetes cluster:
88+
89+
```shell
90+
kpt live apply
91+
```
92+
93+
If all goes well, the output should look like this:
94+
95+
```
96+
pod/pod-a created
97+
1 resource(s) applied. 1 created, 0 unchanged, 0 configured, 0 failed
98+
pod/pod-b created
99+
1 resource(s) applied. 1 created, 0 unchanged, 0 configured, 0 failed
100+
```
101+
102+
Delete the package from your Kubernetes cluster:
103+
104+
```shell
105+
kpt live destroy
106+
```
107+
108+
If all goes well, the output should look like this:
109+
110+
```
111+
pod/pod-b deleted
112+
1 resource(s) deleted, 0 skipped
113+
pod/pod-a deleted
114+
1 resource(s) deleted, 0 skipped
115+
```

0 commit comments

Comments
 (0)