Debian Codegraph @

doc/patch_types.md

raw
1 # Introduction to Kubernetes Patch Types
2 In Kubernetes, patches are a way to make updates or changes to resources (like Pods, ConfigMaps, Deployments, etc.) without having to replace the entire resource. Patches allow you to modify specific parts of a resource while leaving the rest unchanged.
3
4 ## Types of Kubernetes Patches
5
6 There are several types of patches that Kubernetes supports:
7
8 1. JSON Merge Patch (Standard JSON Patch)
9 2. Strategic Merge Patch
10 3. JSON Patch
11 4. Apply Patch (Server-Side Apply)
12
13 ## 1. JSON Merge Patch
14 - JSON Merge Patch is based on the concept of merging JSON objects. When you apply a patch, you only need to specify the changes you want to make. Kubernetes will take your partial update and merge it with the existing resource.
15
16 - This patch type is simple and works well when you need to update fields, such as changing a value or adding a new key.
17
18
19 ### Example Scenario:
20 Imagine you have a Kubernetes Pod resource that looks like this:
21
22 ```
23 apiVersion: v1
24 kind: Pod
25 metadata:
26 name: mypod
27 spec:
28 containers:
29 - name: nginx
30 image: nginx:1.14
31 - name: redis
32 image: redis:5
33 ```
34 Now, you want to change the image of the nginx container from nginx:1.14 to nginx:1.16. Instead of sending the entire resource, you can send only the part you want to change, like this:
35 ```
36 {
37 "spec": {
38 "containers": [
39 {
40 "name": "nginx",
41 "image": "nginx:1.16"
42 }
43 ]
44 }
45 }
46 ```
47
48 When you send this patch to Kubernetes:
49
50 It will replace the image of the nginx container with the new one (nginx:1.16).
51 It will leave the redis container unchanged, because it's not included in the patch.
52
53 ### Example Code (Python):
54 ```
55 from kubernetes import client, config
56
57 def main():
58 config.load_kube_config()
59 v1 = client.CoreV1Api()
60
61 namespace = "default"
62 name = "mypod"
63
64 patch = {
65 "spec": {
66 "containers": [
67 {
68 "name": "nginx",
69 "image": "nginx:1.16"
70 }
71 ]
72 }
73 }
74
75 v1.patch_namespaced_pod(name=name, namespace=namespace, body=patch, content_type="application/merge-patch+json")
76
77 if __name__ == "__main__":
78 main()
79
80 ```
81
82 ### After the JSON Merge patch
83
84 ```
85 apiVersion: v1
86 kind: Pod
87 metadata:
88 name: mypod
89 spec:
90 containers:
91 - name: nginx
92 image: nginx:1.16 # Updated image version
93 - name: redis
94 image: redis:5 # Unchanged
95 ```
96
97
98 ## 2. Strategic Merge Patch
99 Strategic Merge Patch is another type of patching mechanism, mostly used in Kubernetes, that allows updates to objects in a way that is more aware of the structure and semantics of the resource being modified. It is strategic because it understands the structure of the object, rather than blindly replacing it, and applies the changes in a smart way.
100 - The patch itself is typically a JSON or YAML object, which contains the fields to be updated
101 - **Adds New Fields:** You can use it to add new fields or modify existing ones without affecting the rest of the object.
102 - **Handle Lists or Arrays:** When dealing with lists (e.g., arrays or dictionaries), Strategic Merge Patch handles merging and updates intelligently.
103
104 ### Example of Strategic Merge Patch:
105 let's suppose we have a yaml file Target Resource (Kubernetes ConfigMap):
106
107 ```
108 apiVersion: v1
109 kind: ConfigMap
110 metadata:
111 name: my-configmap
112 data:
113 key1: value1
114 key2: value2
115 list1:
116 - item1
117 - item2
118
119 ```
120
121 Strategic Merge Patch
122 ```
123 data:
124 key1: updated_value1 # Update key1
125 key3: value3 # Add new key3
126 list1:
127 - item1
128 - item2
129 - item3 # Add item3 to list1
130
131 ```
132
133 Result after Strategic Merge Patch
134
135 ```
136 apiVersion: v1
137 kind: ConfigMap
138 metadata:
139 name: my-configmap
140 data:
141 key1: updated_value1 # key1 is updated
142 key2: value2 # key2 is unchanged
143 key3: value3 # key3 is added
144 list1:
145 - item1
146 - item2
147 - item3 # item3 is added to list1
148
149
150 ```
151
152
153 ## 3. JSON Patch
154 - JSON Patch is a standard format that specifies a way to apply updates to a JSON document. Instead of sending a new or merged version of the object, JSON Patch describes how to modify the object step-by-step.
155 - Operation-Based: A JSON Patch is an array of operations that describe modifications to a target JSON object.
156 - Ideal when you need to perform multiple, specific operations on resource fields (e.g., replacing a value, adding new fields, or deleting specific values).
157
158 ### Patch Structure:
159 A JSON Patch is an array of operations. Each operation is an object with:
160 • op: The operation type (e.g., add, remove, replace, etc.).
161 • path: A JSON Pointer string (defined in RFC 6901) that specifies the location in the document to apply the operation.
162 • value: (Optional) The new value to apply (used with operations like add, replace, or test).
163 • from: (Optional) Used in operations like move and copy to specify the source path.
164
165 ### Supported Operations for JSON Patch
166
167 #### 1. **add**
168 - Adds a value to a specified path.
169 - If the path already exists, it adds the value to a list or object.
170
171 Example:
172 ```json
173 { "op": "add", "path": "/a/b/c", "value": "foo" }
174 ```
175
176 #### 2. **remove**
177 - Removes the value at the specified path.
178
179 Example:
180 ```json
181 { "op": "remove", "path": "/a/b/c" }
182 ```
183
184 #### 3. **replace**
185 - Replaces the value at the specified path.
186 - Functionally similar to remove followed by add.
187
188 Example:
189 ```json
190 { "op": "replace", "path": "/a/b/c", "value": "bar" }
191 ```
192
193 #### 4. **move**
194 - Moves a value from one path to another.
195
196 Example:
197 ```json
198 { "op": "move", "from": "/a/b/c", "path": "/x/y/z" }
199 ```
200
201 #### 5. **copy**
202 - Copies a value from one path to another.
203
204 Example:
205 ```json
206 { "op": "copy", "from": "/a/b/c", "path": "/x/y/z" }
207 ```
208
209 #### 6. **test**
210 - Tests whether a value at a specified path matches a given value.
211 - Used for validation in transactional updates.
212
213 Example:
214 ```json
215 { "op": "test", "path": "/a/b/c", "value": "foo" }
216 ```
217
218 ---
219
220 #### Example: Applying a JSON Patch
221
222 ##### Target JSON Document:
223 ```json
224 {
225 "a": {
226 "b": {
227 "c": "foo"
228 }
229 },
230 "x": {
231 "y": "bar"
232 }
233 }
234 ```
235
236 ##### JSON Patch:
237 ```json
238 [
239 { "op": "replace", "path": "/a/b/c", "value": "baz" },
240 { "op": "add", "path": "/a/d", "value": ["new", "value"] },
241 { "op": "remove", "path": "/x/y" }
242 ]
243 ```
244
245 ##### Result:
246 ```json
247 {
248 "a": {
249 "b": {
250 "c": "baz"
251 },
252 "d": ["new", "value"]
253 },
254 "x": {}
255 }
256 ```
257
258
259 ## 4. Apply Patch (Server-Side Apply)
260 Server-Side Apply is a feature in Kubernetes that allows you to declaratively update resources by specifying their desired state. It provides an intuitive and robust way to manage resources without having to manually modify every field. It tracks which fields belong to which manager, which helps prevent conflicts when multiple clients (such as different controllers or users) update the same resource.
261
262 Key Features:
263 - Declarative Management: You provide the desired final state, and Kubernetes ensures the actual state matches it.
264 - Conflict Detection: Ensures changes from different clients don’t conflict with each other.
265 - Field Ownership: Kubernetes tracks which client or manager owns which fields of a resource.
266
267 ##### Example Scenario:
268
269 You have a ConfigMap and want to update certain keys but leave others unchanged.
270 ```
271 apiVersion: v1
272 kind: ConfigMap
273 metadata:
274 name: example-config
275 namespace: default
276 data:
277 key1: value1
278 key2: value2
279 ```
280 **Goal:**
281 - You want to update key2 to new_value2 and
282 - add a new key key3 with a value value3.
283 - leave key1 unchanged
284
285 ##### Apply Patch YAML(Desired State):
286 ```
287 apiVersion: v1
288 kind: ConfigMap
289 metadata:
290 name: example-config
291 namespace: default
292 data:
293 key2: new_value2 # Update existing key
294 key3: value3 # Add new key
295
296 ```
297
298 ##### Resulting ConfigMap (after apply):
299 ```
300 apiVersion: v1
301 kind: ConfigMap
302 metadata:
303 name: example-config
304 namespace: default
305 data:
306 key1: value1 # Remains unchanged
307 key2: new_value2 # Updated value
308 key3: value3 # New key added
309
310 ```
311
312
313
314
315