kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

New Task topic for kubectl patch. (#4519)

This commit is contained in:
Steve Perry 2017-08-14 09:43:56 -07:00 committed by GitHub
parent 52fd55d372
commit 176b91d558
5 changed files with 305 additions and 45 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
_data/tasks.yml
View File

@ -46,6 +46,7 @@ toc:
- docs/tasks/run-application/run-stateless-application-deployment.md
- docs/tasks/run-application/run-single-instance-stateful-application.md
- docs/tasks/run-application/run-replicated-stateful-application.md
- docs/tasks/run-application/update-api-object-kubectl-patch.md
- docs/tasks/run-application/upgrade-pet-set-to-stateful-set.md
- docs/tasks/run-application/scale-stateful-set.md
- docs/tasks/run-application/delete-stateful-set.md

50
docs/concepts/cluster-administration/manage-deployment.md
View File

@ -354,51 +354,11 @@ For more information, please see [kubectl edit](/docs/user-guide/kubectl/{{page.
### kubectl patch
Suppose you want to fix a typo of the container's image of a Deployment. One way to do that is with `kubectl patch`:
```shell
# Suppose you have a Deployment with a container named "nginx" and its image "nignx" (typo),
# use container name "nginx" as a key to update the image from "nignx" (typo) to "nginx"
$ kubectl get deployment my-nginx -o yaml
```
```yaml
apiVersion: apps/v1beta1
kind: Deployment
...
spec:
template:
spec:
containers:
- image: nignx
name: nginx
...
```
```shell
$ kubectl patch deployment my-nginx -p'{"spec":{"template":{"spec":{"containers":[{"name":"nginx","image":"nginx"}]}}}}'
"my-nginx" patched
$ kubectl get pod my-nginx-1jgkf -o yaml
```
```yaml
apiVersion: apps/v1beta1
kind: Deployment
...
spec:
template:
spec:
containers:
- image: nginx
name: nginx
...
```
The patch is specified using json.
The system ensures that you don't clobber changes made by other users or components by confirming that the `resourceVersion` doesn't differ from the version you edited. If you want to update regardless of other changes, remove the `resourceVersion` field when you edit the resource. However, if you do this, don't use your original configuration file as the source since additional fields most likely were set in the live state.
For more information, please see [kubectl patch](/docs/user-guide/kubectl/{{page.version}}/#patch) document.
You can use `kubectl patch` to update API objects in place. This command supports JSON patch,
JSON merge patch, and strategic merge patch. See
[Update API Objects in Place Using kubectl patch](/docs/tasks/run-application/update-api-object-kubectl-patch/)
and
[kubectl patch](/docs/user-guide/kubectl/{{page.version}}/#patch).
## Disruptive updates

14
docs/tasks/run-application/deployment-patch-demo.yaml Normal file
View File

@ -0,0 +1,14 @@
apiVersion: apps/v1beta1
kind: Deployment
metadata:
name: patch-demo
spec:
replicas: 2
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: patch-demo-ctr
image: nginx

14
docs/tasks/run-application/patch-file.json Normal file
View File

@ -0,0 +1,14 @@
{
"spec": {
"template": {
"spec": {
"containers": [
{
"name": "patch-demo-ctr-2",
"image": "redis"
}
]
}
}
}
}

271
docs/tasks/run-application/update-api-object-kubectl-patch.md Normal file
View File

@ -0,0 +1,271 @@
---
title: Update API Objects in Place Using kubectl patch
description: Use kubectl patch to update Kubernetes API objects in place. Do a strategic merge patch or a JSON merge patch.
---
{% capture overview %}
This task shows how to use `kubectl patch` to update an API object in place. The exercises
in this task demonstrate a strategic merge patch and a JSON merge patch.
{% endcapture %}
{% capture prerequisites %}
{% include task-tutorial-prereqs.md %}
{% endcapture %}
{% capture steps %}
## Use a strategic merge patch to update a Deployment
Here's the configuration file for a Deployment that has two replicas. Each replica
is a Pod that has one container:
{% include code.html language="yaml" file="deployment-patch-demo.yaml" ghlink="/docs/tasks/run-application/deployment-patch-demo.yaml" %}
Create the Deployment:
```shell
kubectl create -f https://k8s.io/docs/tasks/run-application/deployment-patch-demo.yaml
```
View the Pods associated with your Deployment:
```shell
kubectl get pods
```
The output shows that the Deployment has two Pods. The `1/1` indicates that
each Pod has one container:
```
NAME READY STATUS RESTARTS AGE
patch-demo-28633765-670qr 1/1 Running 0 23s
patch-demo-28633765-j5qs3 1/1 Running 0 23s
```
Make a note of the names of the running Pods. Later, you will see that these Pods
get terminated and replaced by new ones.
At this point, each Pod has one Container that runs the nginx image. Now suppose
you want each Pod to have two containers: one that runs nginx and one that runs redis.
Create a file named `patch-file.yaml` that has this content:
```shell
spec:
template:
spec:
containers:
- name: patch-demo-ctr-2
image: redis
```
Patch your Deployment:
```shell
kubectl patch deployment patch-demo --patch "$(cat patch-file.yaml)"
```
View the patched Deployment:
```shell
kubectl get deployment patch-demo --output yaml
```
The output shows that the PodSpec in the Deployment has two Containers:
```shell
containers:
- image: nginx
imagePullPolicy: Always
name: patch-demo-ctr
...
- image: redis
imagePullPolicy: Always
name: patch-demo-ctr-2
...
```
View the Pods associated with your patched Deployment:
```shell
kubectl get pods
```
The output shows that the running Pods have different names from the Pods that
were running previously. The Deployment terminated the old Pods and created two
new Pods that comply with the updated Deployment spec. The `2/2` indicates that
each Pod has two Containers:
```
NAME READY STATUS RESTARTS AGE
patch-demo-1081991389-2wrn5 2/2 Running 0 1m
patch-demo-1081991389-jmg7b 2/2 Running 0 1m
```
Take a closer look at one of the patch-demo Pods:
```shell
kubectl get pod <your-pod-name> --output yaml
```
The output shows that the Pod has two Containers: one running nginx and one running redis:
```
containers:
- image: nginx
...
- image: redis
...
```
### Notes on the strategic merge patch
With a patch, you do not have to specify an entire object; you specify only the portion
of the object that you want to change. For example, in the preceding exercise, you specified
one Container in the `containers` list in a `PodSpec`.
The patch you did in the preceding exercise is called a *strategic merge patch*.
With a strategic merge patch, you can update a list by specifying only the elements
that you want to add to the list. The existing list elements remain, and the new elements
are merged with the existing elements. In the preceding exercise, the resulting `containers`
list has both the original nginx Container and the new redis Container.
## Use a JSON merge patch to update a Deployment
A strategic merge patch is different from a
[JSON merge patch](https://tools.ietf.org/html/rfc6902).
With a JSON merge patch, if you
want to update a list, you have to specify the entire new list. And the new list completely
replaces the existing list.
The `kubectl patch` command has a `type` parameter that you can set to one of these values:
<table>
<tr><th>Parameter value</th><th>Merge type</th></tr>
<tr><td>json</td><td><a href="https://tools.ietf.org/html/rfc6902">JSON Patch, RFC 6902</a></td></tr>
<tr><td>merge</td><td><a href="https://tools.ietf.org/html/rfc7386">JSON Merge Patch, RFC 7386</a></td></tr>
<tr><td>strategic</td><td>Strategic merge patch</td></tr>
</table>
For a comparison of JSON patch and JSON merge patch, see
[JSON Patch and JSON Merge Patch](http://erosb.github.io/post/json-patch-vs-merge-patch/).
The default value for the `type` parameter is `strategic`. So in the preceding exercise, you
did a strategic merge patch.
Next, do a JSON merge patch on your same Deployment. Create a file named `patch-file-2.yaml`
that has this content:
```shell
spec:
template:
spec:
containers:
- name: patch-demo-ctr-3
image: gcr.io/google-samples/node-hello:1.0
```
In your patch command, set `type` to `merge`:
```shell
kubectl patch deployment patch-demo --type merge --patch "$(cat patch-file-2.yaml)"
```
View the patched Deployment:
```shell
kubectl get deployment patch-demo --output yaml
```
The `containers` list that you specified in the patch has only one Container.
The output shows that your list of one Container replaced the existing `containers` list.
```shell
spec:
containers:
- image: gcr.io/google-samples/node-hello:1.0
...
name: patch-demo-ctr-3
```
List the running Pods:
```shell
kubectl get pods
```
In the output, you can see that the existing Pods were terminated, and new Pods
were created. The `1/1` indicates that each new Pod is running only one Container.
```shell
NAME READY STATUS RESTARTS AGE
patch-demo-1307768864-69308 1/1 Running 0 1m
patch-demo-1307768864-c86dc 1/1 Running 0 1m
```
## Alternate forms of the kubectl patch command
The `kubectl patch` command takes YAML or JSON. It can take the patch as a file or
directly on the command line.
Create a file named `patch-file.json` that has this content:
```shell
{
"spec": {
"template": {
"spec": {
"containers": [
{
"name": "patch-demo-ctr-2",
"image": "redis"
}
]
}
}
}
}
```
The following commands are equivalent:
```shell
kubectl patch deployment patch-demo --patch "$(cat patch-file.yaml)"
kubectl patch deployment patch-demo --patch $'spec:\n template:\n spec:\n containers:\n - name: patch-demo-ctr-2\n image: redis'
kubectl patch deployment patch-demo --patch "$(cat patch-file.json)"
kubectl patch deployment patch-demo --patch '{"spec": {"template": {"spec": {"containers": [{"name": "patch-demo-ctr-2","image": "redis"}]}}}}'
```
## Summary
In this exercise, you `kubectl patch` to change the live configuration
of a Deployment object. You did not change the configuration file that you originally used to
create the Deployment object. Other commands for updating API objects include
[kubectl annotate](/docs/user-guide/kubectl/{{page.version}}/#annotate),
[kubectl edit](/docs/user-guide/kubectl/v1.7/#edit),
[kubectl replace](/docs/user-guide/kubectl/v1.7/#replace),
[kubectl scale](/docs/user-guide/kubectl/v1.7/#scale),
[kubectl update](/docs/user-guide/kubectl/v1.7/#update). and
[kubectl apply](/docs/user-guide/kubectl/v1.7/#apply).
{% endcapture %}
{% capture whatsnext %}
* [Kubernetes Object Management](/docs/tutorials/object-management-kubectl/object-management/)
* [Managing Kubernetes Objects Using Imperative Commands](/docs/tutorials/object-management-kubectl/imperative-object-management-command/)
* [Imperative Management of Kubernetes Objects Using Configuration Files](/docs/tutorials/object-management-kubectl/imperative-object-management-configuration/)
* [Declarative Management of Kubernetes Objects Using Configuration Files](/docs/tutorials/object-management-kubectl/declarative-object-management-configuration/)
{% endcapture %}
{% include templates/task.md %}