Convert site to Hugo (#8316)
This commit converts content and layout to use Hugo.
This commit is contained in:
Bjørn Erik Pedersen
committed by
k8s-ci-robot
k8s-ci-robot
parent
7745f0e0c5
commit
7f3b633aa0
@@ -0,0 +1,339 @@
|
||||
---
|
||||
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.
|
||||
content_template: templates/task
|
||||
---
|
||||
|
||||
{{% 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.
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture prerequisites %}}
|
||||
|
||||
{{< include "task-tutorial-prereqs.md" >}} {{< version-check >}}
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
{{% 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:
|
||||
|
||||
{{< code file="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-containers.yaml` that has this content:
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- name: patch-demo-ctr-2
|
||||
image: redis
|
||||
```
|
||||
|
||||
Patch your Deployment:
|
||||
|
||||
```shell
|
||||
kubectl patch deployment patch-demo --patch "$(cat patch-file-containers.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: redis
|
||||
imagePullPolicy: Always
|
||||
name: patch-demo-ctr-2
|
||||
...
|
||||
- image: nginx
|
||||
imagePullPolicy: Always
|
||||
name: patch-demo-ctr
|
||||
...
|
||||
```
|
||||
|
||||
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: redis
|
||||
...
|
||||
- image: nginx
|
||||
...
|
||||
```
|
||||
|
||||
### Notes on the strategic merge patch
|
||||
|
||||
The patch you did in the preceding exercise is called a *strategic merge patch*.
|
||||
Notice that the patch did not replace the `containers` list. Instead it added a new
|
||||
Container to the list. In other words, the list in the patch was merged with the
|
||||
existing list. This is not always what happens when you use a strategic merge patch on a list.
|
||||
In some cases, the list is replaced, not merged.
|
||||
|
||||
With a strategic merge patch, a list is either replaced or merged depending on its
|
||||
patch strategy. The patch strategy is specified by the value of the `patchStrategy` key
|
||||
in a field tag in the Kubernetes source code. For example, the `Containers` field of `PodSpec`
|
||||
struct has a `patchStrategy` of `merge`:
|
||||
|
||||
```go
|
||||
type PodSpec struct {
|
||||
...
|
||||
Containers []Container `json:"containers" patchStrategy:"merge" patchMergeKey:"name" ...`
|
||||
```
|
||||
|
||||
You can also see the patch strategy in the
|
||||
[OpenApi spec](https://raw.githubusercontent.com/kubernetes/kubernetes/master/api/openapi-spec/swagger.json):
|
||||
|
||||
```json
|
||||
"io.k8s.api.core.v1.PodSpec": {
|
||||
...
|
||||
"containers": {
|
||||
"description": "List of containers belonging to the pod. ...
|
||||
},
|
||||
"x-kubernetes-patch-merge-key": "name",
|
||||
"x-kubernetes-patch-strategy": "merge"
|
||||
},
|
||||
```
|
||||
|
||||
And you can see the patch strategy in the
|
||||
[Kubernetes API documentation](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#podspec-v1-core).
|
||||
|
||||
Create a file named `patch-file-tolerations.yaml` that has this content:
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
tolerations:
|
||||
- effect: NoSchedule
|
||||
key: disktype
|
||||
value: ssd
|
||||
```
|
||||
|
||||
Patch your Deployment:
|
||||
|
||||
```shell
|
||||
kubectl patch deployment patch-demo --patch "$(cat patch-file-tolerations.yaml)"
|
||||
```
|
||||
|
||||
View the patched Deployment:
|
||||
|
||||
```shell
|
||||
kubectl get deployment patch-demo --output yaml
|
||||
```
|
||||
|
||||
The output shows that the PodSpec in the Deployment has only one Toleration:
|
||||
|
||||
```shell
|
||||
tolerations:
|
||||
- effect: NoSchedule
|
||||
key: disktype
|
||||
value: ssd
|
||||
```
|
||||
|
||||
Notice that the `tolerations` list in the PodSpec was replaced, not merged. This is because
|
||||
the Tolerations field of PodSpec does not have a `patchStrategy` key in its field tag. So the
|
||||
strategic merge patch uses the default patch strategy, which is `replace`.
|
||||
|
||||
```go
|
||||
type PodSpec struct {
|
||||
...
|
||||
Tolerations []Toleration `json:"tolerations,omitempty" protobuf:"bytes,22,opt,name=tolerations"`
|
||||
```
|
||||
|
||||
## 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/rfc7386).
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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 used `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/reference/generated/kubectl/kubectl-commands/#annotate),
|
||||
[kubectl edit](/docs/reference/generated/kubectl/kubectl-commands/#edit),
|
||||
[kubectl replace](/docs/reference/generated/kubectl/kubectl-commands/#replace),
|
||||
[kubectl scale](/docs/reference/generated/kubectl/kubectl-commands/#scale),
|
||||
and
|
||||
[kubectl apply](/docs/reference/generated/kubectl/kubectl-commands/#apply).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
* [Kubernetes Object Management](/docs/concepts/overview/object-management-kubectl/overview/)
|
||||
* [Managing Kubernetes Objects Using Imperative Commands](/docs/concepts/overview/object-management-kubectl/imperative-command/)
|
||||
* [Imperative Management of Kubernetes Objects Using Configuration Files](/docs/concepts/overview/object-management-kubectl/imperative-config/)
|
||||
* [Declarative Management of Kubernetes Objects Using Configuration Files](/docs/concepts/overview/object-management-kubectl/declarative-config/)
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user