Kubernetes 中使用 kubectl patch 更新 API 对象详解

计金勇Louise

于 2025-06-10 09:04:56 发布

阅读量237

点赞数 5

CC 4.0 BY-SA版权

本文链接：https://blog.youkuaiyun.com/gitblog_00438/article/details/148549773

Kubernetes 中使用 kubectl patch 更新 API 对象详解

website Kubernetes website and documentation repo: 项目地址: https://gitcode.com/gh_mirrors/webs/website

概述

在 Kubernetes 集群管理中，我们经常需要对已部署的资源进行修改。kubectl patch 命令提供了一种灵活的方式来对 API 对象进行部分更新，而无需替换整个资源配置。本文将深入探讨如何使用 kubectl patch 命令进行策略合并 patch 和 JSON 合并 patch 操作。

准备工作

在开始之前，请确保：

已安装 Kubernetes 集群
配置了 kubectl 命令行工具
对 Kubernetes 基本概念有了解

策略合并 patch 操作

策略合并 patch（Strategic Merge Patch）是 Kubernetes 特有的一种 patch 方式，它能够智能地合并而非简单地替换字段。

示例：向 Deployment 添加容器

假设我们有一个运行 nginx 的 Deployment：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: patch-demo
spec:
  replicas: 2
  template:
    spec:
      containers:
      - name: patch-demo-ctr
        image: nginx

当我们想添加一个 redis 容器时，可以创建如下 patch 文件：

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

应用 patch：

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

这个操作会保留原有容器并添加新容器，而不是替换整个容器列表。

合并策略原理

Kubernetes 中每个字段的合并行为由源码中的 patchStrategy 标记决定。例如：

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

patchStrategy:"merge" 表示列表应该合并
patchMergeKey:"name" 表示使用 name 字段作为合并键

JSON 合并 patch 操作

JSON 合并 patch（RFC 7386）与策略合并 patch 不同，它会完全替换指定的列表。

示例：替换 Deployment 的容器

使用 JSON 合并 patch 类型：

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

其中 patch-file-2.yaml 内容为：

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

这将完全替换原有的 containers 列表。

使用 retainKeys 策略

某些情况下，我们需要在更新字段时清除其他相关字段。这时可以使用 retainKeys 策略。

示例：更改 Deployment 更新策略

假设我们要将更新策略从 RollingUpdate 改为 Recreate：

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

这个 patch 会：

保留 strategy 下的 type 字段
清除其他字段（如 rollingUpdate）

实用技巧

多种输入方式：
- 可以直接在命令行提供 patch 内容
- 也可以使用文件作为输入
格式选择：
- 支持 YAML 和 JSON 格式
- 根据场景选择合适格式
子资源更新：
- 从 Kubernetes 1.24 开始支持直接更新子资源（如 status、scale）
- 例如：kubectl patch deployment --subresource=scale