使用 kubectl patch 就地更新 API 对象

本任务介绍如何使用 kubectl patch 就地更新 API 对象。任务中的练习将演示策略性合并补丁和 JSON 合并补丁的使用。

准备工作

你需要拥有一个 Kubernetes 集群，并且 kubectl 命令行工具已经配置为与你的集群通信。建议在至少有两个非控制平面主机的节点的集群上运行本教程。如果你还没有集群，可以使用 minikube 创建一个，或者使用这些 Kubernetes 演练场之一

• Killercoda
• KodeKloud
• Play with Kubernetes

要检查版本，输入 kubectl version。

使用策略性合并补丁更新 Deployment

以下是包含两个副本的 Deployment 的配置文件。每个副本都是一个包含一个容器的 Pod。

application/deployment-patch.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: patch-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: patch-demo-ctr
        image: nginx
      tolerations:
      - effect: NoSchedule
        key: dedicated
        value: test-team

创建 Deployment

kubectl apply -f https://k8s.io/examples/application/deployment-patch.yaml

查看与你的 Deployment 相关联的 Pods

kubectl get pods

输出显示该 Deployment 有两个 Pod。1/1 表示每个 Pod 有一个容器。

NAME                        READY     STATUS    RESTARTS   AGE
patch-demo-28633765-670qr   1/1       Running   0          23s
patch-demo-28633765-j5qs3   1/1       Running   0          23s

记下正在运行的 Pod 的名称。稍后，你将看到这些 Pod 被终止并被新的 Pod 替换。

此时，每个 Pod 有一个运行 nginx 镜像的容器。现在假设你希望每个 Pod 有两个容器：一个运行 nginx，另一个运行 redis。

创建一个名为 patch-file.yaml 的文件，内容如下：

spec:
  template:
    spec:
      containers:
      - name: patch-demo-ctr-2
        image: redis

给你的 Deployment 打补丁

kubectl patch deployment patch-demo --patch-file patch-file.yaml

查看已打补丁的 Deployment

kubectl get deployment patch-demo --output yaml

输出显示 Deployment 中的 PodSpec 有两个容器。

containers:
- image: redis
  imagePullPolicy: Always
  name: patch-demo-ctr-2
  ...
- image: nginx
  imagePullPolicy: Always
  name: patch-demo-ctr
  ...

查看与你已打补丁的 Deployment 相关联的 Pods

kubectl get pods

输出显示正在运行的 Pod 的名称与之前运行的 Pod 不同。Deployment 终止了旧的 Pod，并创建了两个符合更新的 Deployment 规约的新 Pod。2/2 表示每个 Pod 有两个容器。

NAME                          READY     STATUS    RESTARTS   AGE
patch-demo-1081991389-2wrn5   2/2       Running   0          1m
patch-demo-1081991389-jmg7b   2/2       Running   0          1m

仔细查看一个 patch-demo Pod。

kubectl get pod <your-pod-name> --output yaml

输出显示 Pod 有两个容器：一个运行 nginx，一个运行 redis。

containers:
- image: redis
  ...
- image: nginx
  ...

关于策略性合并补丁的说明

前一个练习中使用的补丁称为策略性合并补丁。请注意，该补丁没有替换 containers 列表，而是向列表中添加了一个新容器。换句话说，补丁中的列表与现有列表合并了。当你对一个列表使用策略性合并补丁时，并非总是如此。在某些情况下，列表会被替换，而不是合并。

使用策略性合并补丁时，列表是替换还是合并取决于其补丁策略。补丁策略由 Kubernetes 源代码中字段标签里 patchStrategy 键的值指定。例如，PodSpec 结构体的 Containers 字段的 patchStrategy 为 merge。

type PodSpec struct {
  ...
  Containers []Container `json:"containers" patchStrategy:"merge" patchMergeKey:"name" ...`
  ...
}

你还可以在 OpenApi spec 中看到补丁策略。

"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"
}

并且可以在 Kubernetes API documentation 中看到补丁策略。

创建一个名为 patch-file-tolerations.yaml 的文件，内容如下：

spec:
  template:
    spec:
      tolerations:
      - effect: NoSchedule
        key: disktype
        value: ssd

给你的 Deployment 打补丁

kubectl patch deployment patch-demo --patch-file patch-file-tolerations.yaml

查看已打补丁的 Deployment

kubectl get deployment patch-demo --output yaml

输出显示 Deployment 中的 PodSpec 只有一个 Toleration。

tolerations:
- effect: NoSchedule
  key: disktype
  value: ssd

请注意，PodSpec 中的 tolerations 列表被替换了，而不是合并。这是因为 PodSpec 的 Tolerations 字段的字段标签中没有 patchStrategy 键。因此，策略性合并补丁使用了默认的补丁策略，即 replace。

type PodSpec struct {
  ...
  Tolerations []Toleration `json:"tolerations,omitempty" protobuf:"bytes,22,opt,name=tolerations"`
  ...
}

使用 JSON 合并补丁更新 Deployment

策略性合并补丁与 JSON 合并补丁 不同。使用 JSON 合并补丁时，如果要更新列表，必须指定整个新列表。新列表将完全替换现有列表。

kubectl patch 命令有一个 type 参数，你可以将其设置为以下值之一：

有关 JSON patch 和 JSON merge patch 的比较，请参阅 JSON Patch and JSON Merge Patch。

type 参数的默认值为 strategic。因此，在前面的练习中，你执行的是策略性合并补丁。

接下来，对同一个 Deployment 执行 JSON 合并补丁。创建一个名为 patch-file-2.yaml 的文件，内容如下：

spec:
  template:
    spec:
      containers:
      - name: patch-demo-ctr-3
        image: gcr.io/google-samples/hello-app:2.0

在你的补丁命令中，将 type 设置为 merge。

kubectl patch deployment patch-demo --type merge --patch-file patch-file-2.yaml

查看已打补丁的 Deployment

kubectl get deployment patch-demo --output yaml

你在补丁中指定的 containers 列表中只有一个容器。输出显示你的一个容器列表替换了现有的 containers 列表。

spec:
  containers:
  - image: gcr.io/google-samples/hello-app:2.0
    ...
    name: patch-demo-ctr-3

列出正在运行的 Pods

kubectl get pods

在输出中，你可以看到现有 Pods 被终止，并创建了新的 Pods。1/1 表示每个新 Pod 只运行一个容器。

NAME                          READY     STATUS    RESTARTS   AGE
patch-demo-1307768864-69308   1/1       Running   0          1m
patch-demo-1307768864-c86dc   1/1       Running   0          1m

使用带有 retainKeys 策略的策略性合并补丁更新 Deployment

以下是使用 RollingUpdate 策略的 Deployment 的配置文件：

application/deployment-retainkeys.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: retainkeys-demo
spec:
  selector:
    matchLabels:
      app: nginx
  strategy:
    rollingUpdate:
      maxSurge: 30%
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: retainkeys-demo-ctr
        image: nginx

创建 Deployment

kubectl apply -f https://k8s.io/examples/application/deployment-retainkeys.yaml

此时，Deployment 已创建并正在使用 RollingUpdate 策略。

创建一个名为 patch-file-no-retainkeys.yaml 的文件，内容如下：

spec:
  strategy:
    type: Recreate

给你的 Deployment 打补丁

kubectl patch deployment retainkeys-demo --type strategic --patch-file patch-file-no-retainkeys.yaml

在输出中，你可以看到当 spec.strategy.rollingUpdate 定义了值时，无法将 type 设置为 Recreate。

The Deployment "retainkeys-demo" is invalid: spec.strategy.rollingUpdate: Forbidden: may not be specified when strategy `type` is 'Recreate'

在更新 type 值时移除 spec.strategy.rollingUpdate 的值的方法是，对策略性合并使用 retainKeys 策略。

创建另一个名为 patch-file-retainkeys.yaml 的文件，内容如下：

spec:
  strategy:
    $retainKeys:
    - type
    type: Recreate

使用此补丁，我们表明我们只想保留 strategy 对象的 type 键。因此，在补丁操作期间将移除 rollingUpdate。

使用这个新补丁再次给你的 Deployment 打补丁。

kubectl patch deployment retainkeys-demo --type strategic --patch-file patch-file-retainkeys.yaml

检查 Deployment 的内容。

kubectl get deployment retainkeys-demo --output yaml

输出显示 Deployment 中的 strategy 对象不再包含 rollingUpdate 键。

spec:
  strategy:
    type: Recreate
  template:

关于使用 retainKeys 策略的策略性合并补丁的说明

前一个练习中使用的补丁称为带有 retainKeys 策略的策略性合并补丁。此方法引入了一个新的指令 $retainKeys，它包含以下策略：

• 它包含一个字符串列表。
• 需要保留的所有字段必须存在于 $retainKeys 列表中。
• 存在的字段将与实时对象合并。
• 所有缺失的字段将在打补丁时被清除。
• $retainKeys 列表中的所有字段必须是补丁中存在的字段的超集或相同。

retainKeys 策略并非适用于所有对象。它仅在 Kubernetes 源代码中字段标签里 patchStrategy 键的值包含 retainKeys 时才起作用。例如，DeploymentSpec 结构体的 Strategy 字段的 patchStrategy 为 retainKeys。

type DeploymentSpec struct {
  ...
  // +patchStrategy=retainKeys
  Strategy DeploymentStrategy `json:"strategy,omitempty" patchStrategy:"retainKeys" ...`
  ...
}

你还可以在 OpenApi spec 中看到 retainKeys 策略。

"io.k8s.api.apps.v1.DeploymentSpec": {
    ...,
    "strategy": {
        "$ref": "#/definitions/io.k8s.api.apps.v1.DeploymentStrategy",
        "description": "The deployment strategy to use to replace existing pods with new ones.",
        "x-kubernetes-patch-strategy": "retainKeys"
    },
    ....
}

并且可以在 Kubernetes API documentation 中看到 retainKeys 策略。

kubectl patch 命令的替代形式

kubectl patch 命令接受 YAML 或 JSON。它可以通过文件或直接在命令行上接受补丁。

创建一个名为 patch-file.json 的文件，内容如下：

{
   "spec": {
      "template": {
         "spec": {
            "containers": [
               {
                  "name": "patch-demo-ctr-2",
                  "image": "redis"
               }
            ]
         }
      }
   }
}

以下命令是等效的：

kubectl patch deployment patch-demo --patch-file 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-file patch-file.json
kubectl patch deployment patch-demo --patch '{"spec": {"template": {"spec": {"containers": [{"name": "patch-demo-ctr-2","image": "redis"}]}}}}'

使用带有 --subresource 的 kubectl patch 更新对象的副本数

标志 --subresource=[subresource-name] 用于 kubectl 命令（如 get、patch、edit、apply 和 replace），以获取和更新你指定的资源的 status、scale 和 resize 子资源。对于任何具有 status、scale 或 resize 子资源的 Kubernetes API 资源（内置和 CR），你都可以指定一个子资源。

例如，Deployment 有一个 status 子资源和一个 scale 子资源，因此你可以使用 kubectl 仅获取或修改 Deployment 的 status 子资源。

以下是包含两个副本的 Deployment 的清单：

application/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 2 # tells deployment to run 2 pods matching the template
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

创建 Deployment

kubectl apply -f https://k8s.io/examples/application/deployment.yaml

查看与你的 Deployment 相关联的 Pods

kubectl get pods -l app=nginx

在输出中，你可以看到 Deployment 有两个 Pod。例如：

NAME                                READY   STATUS    RESTARTS   AGE
nginx-deployment-7fb96c846b-22567   1/1     Running   0          47s
nginx-deployment-7fb96c846b-mlgns   1/1     Running   0          47s

现在，使用 --subresource=[subresource-name] 标志给该 Deployment 打补丁。

kubectl patch deployment nginx-deployment --subresource='scale' --type='merge' -p '{"spec":{"replicas":3}}'

输出为：

scale.autoscaling/nginx-deployment patched

查看与你已打补丁的 Deployment 相关联的 Pods

kubectl get pods -l app=nginx

在输出中，你可以看到创建了一个新 Pod，因此现在有 3 个正在运行的 Pod。

NAME                                READY   STATUS    RESTARTS   AGE
nginx-deployment-7fb96c846b-22567   1/1     Running   0          107s
nginx-deployment-7fb96c846b-lxfr2   1/1     Running   0          14s
nginx-deployment-7fb96c846b-mlgns   1/1     Running   0          107s

查看已打补丁的 Deployment

kubectl get deployment nginx-deployment -o yaml

...
spec:
  replicas: 3
  ...
status:
  ...
  availableReplicas: 3
  readyReplicas: 3
  replicas: 3

总结

在本练习中，你使用 kubectl patch 改变了 Deployment 对象的实时配置。你没有更改最初用于创建 Deployment 对象的配置文件。更新 API 对象的其他命令包括 kubectl annotate、kubectl edit、kubectl replace、kubectl scale 和 kubectl apply。

下一步

• Kubernetes 对象管理
• 使用命令式命令管理 Kubernetes 对象
• 使用配置文件以命令式方法管理 Kubernetes 对象
• 使用配置文件以声明式方法管理 Kubernetes 对象