使用配置文件声明式管理 Kubernetes 对象

可以通过将多个对象配置文件存储在目录中，并使用 kubectl apply 根据需要递归地创建和更新这些对象，从而实现对 Kubernetes 对象的创建、更新和删除。这种方法保留了对存活对象所做的写入，而不会将这些更改合并回对象配置文件中。kubectl diff 还可以让你预览 apply 将进行的更改。

开始之前

安装 kubectl。

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

要检查版本，请输入 kubectl version。

权衡

kubectl 工具支持三种对象管理方式

  • 命令式命令
  • 命令式对象配置
  • 声明式对象配置

有关每种对象管理的优缺点，请参阅 Kubernetes 对象管理。

概述

声明式对象配置需要深入了解 Kubernetes 对象定义和配置。如果你还没有阅读并完成以下文档，请先进行阅读

以下是本文档所用术语的定义

  • 对象配置文件 / 配置文件：定义 Kubernetes 对象配置的文件。本主题展示如何将配置文件传递给 kubectl apply。配置文件通常存储在版本控制系统（如 Git）中。
  • 存活对象配置 / 存活配置：Kubernetes 集群所观察到的对象的存活配置值。这些值保存在 Kubernetes 集群存储中（通常为 etcd）。
  • 声明式配置写入者 / 声明式写入者：对存活对象进行更新的人员或软件组件。本主题中提到的存活写入者会对对象配置文件进行更改，并运行 kubectl apply 来写入这些更改。

如何创建对象

使用 kubectl apply 创建指定目录下的配置文件定义的所有对象（已存在的除外）

kubectl apply -f <directory>

这会在每个对象上设置 kubectl.kubernetes.io/last-applied-configuration: '{...}' 注解。该注解包含了用于创建对象的对象配置文件的内容。

说明

添加 -R 标志以递归方式处理目录。

这是一个对象配置文件的示例

application/simple_deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  minReadySeconds: 5
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

运行 kubectl diff 以打印将要创建的对象

kubectl diff -f https://k8s.io/examples/application/simple_deployment.yaml

说明

diff 使用服务端试运行（dry-run），这需要在 kube-apiserver 上启用。

由于 diff 在试运行模式下执行服务端 apply 请求，因此需要授予 PATCH、CREATE 和 UPDATE 权限。详情请参见试运行授权。

使用 kubectl apply 创建对象

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

使用 kubectl get 打印存活配置

kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml

输出显示 kubectl.kubernetes.io/last-applied-configuration 注解已写入存活配置，并且与配置文件匹配

kind: Deployment
metadata:
  annotations:
    # ...
    # This is the json representation of simple_deployment.yaml
    # It was written by kubectl apply when the object was created
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}      
  # ...
spec:
  # ...
  minReadySeconds: 5
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        # ...
        name: nginx
        ports:
        - containerPort: 80
        # ...
      # ...
    # ...
  # ...

如何更新对象

你也可以使用 kubectl apply 更新目录中定义的所有对象，即使这些对象已经存在。这种方法可以实现以下功能

  1. 在存活配置中设置配置文件中出现的字段。
  2. 在存活配置中清除配置文件中已删除的字段。
kubectl diff -f <directory>
kubectl apply -f <directory>

说明

添加 -R 标志以递归方式处理目录。

这是一个示例配置文件

application/simple_deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  minReadySeconds: 5
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

使用 kubectl apply 创建对象

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

说明

为了演示目的，上述命令指的是单个配置文件而不是目录。

使用 kubectl get 打印存活配置

kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml

输出显示 kubectl.kubernetes.io/last-applied-configuration 注解已写入存活配置，并且与配置文件匹配

kind: Deployment
metadata:
  annotations:
    # ...
    # This is the json representation of simple_deployment.yaml
    # It was written by kubectl apply when the object was created
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}      
  # ...
spec:
  # ...
  minReadySeconds: 5
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        # ...
        name: nginx
        ports:
        - containerPort: 80
        # ...
      # ...
    # ...
  # ...

通过使用 kubectl scale 直接更新存活配置中的 replicas 字段。这不会使用 kubectl apply

kubectl scale deployment/nginx-deployment --replicas=2

使用 kubectl get 打印存活配置

kubectl get deployment nginx-deployment -o yaml

输出显示 replicas 字段已被设置为 2，且 last-applied-configuration 注解不包含 replicas 字段

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # ...
    # note that the annotation does not contain replicas
    # because it was not updated through apply
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}      
  # ...
spec:
  replicas: 2 # written by scale
  # ...
  minReadySeconds: 5
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        # ...
        name: nginx
        ports:
        - containerPort: 80
      # ...

更新 simple_deployment.yaml 配置文件，将镜像从 nginx:1.14.2 更改为 nginx:1.16.1，并删除 minReadySeconds 字段

application/update_deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.16.1 # update the image
        ports:
        - containerPort: 80

应用对配置文件所做的更改

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

使用 kubectl get 打印存活配置

kubectl get -f https://k8s.io/examples/application/update_deployment.yaml -o yaml

输出显示存活配置发生了以下更改

  • replicas 字段保留了由 kubectl scale 设置的值 2。这是因为该字段在配置文件中被省略了。
  • image 字段已从 nginx:1.14.2 更新为 nginx:1.16.1。
  • last-applied-configuration 注解已更新为新镜像。
  • minReadySeconds 字段已被清除。
  • last-applied-configuration 注解不再包含 minReadySeconds 字段。
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # ...
    # The annotation contains the updated image to nginx 1.16.1,
    # but does not contain the updated replicas to 2
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.16.1","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}      
    # ...
spec:
  replicas: 2 # Set by `kubectl scale`.  Ignored by `kubectl apply`.
  # minReadySeconds cleared by `kubectl apply`
  # ...
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.16.1 # Set by `kubectl apply`
        # ...
        name: nginx
        ports:
        - containerPort: 80
        # ...
      # ...
    # ...
  # ...

警告

不支持将 kubectl apply 与命令式对象配置命令 create 和 replace 混合使用。这是因为 create 和 replace 不会保留 kubectl apply 用来计算更新的 kubectl.kubernetes.io/last-applied-configuration。

如何删除对象

有两种方法可以删除由 kubectl apply 管理的对象。

手动使用命令式命令删除对象是推荐的方法，因为它对于删除的内容更加明确，且不太可能导致用户无意中删除某些内容

kubectl delete -f <filename>

备选：kubectl apply -f <directory> --prune

作为 kubectl delete 的替代方案，你可以在清单文件从本地文件系统的目录中移除后，使用 kubectl apply 来识别要删除的对象。

在 Kubernetes 1.36 中，kubectl apply 有两种可用修剪（pruning）模式

  • 基于允许列表（Allowlist）的修剪：此模式自 kubectl v1.5 起就已存在，但由于其设计在可用性、正确性和性能方面存在问题，仍处于 Alpha 阶段。基于 ApplySet 的模式旨在替代它。
  • 基于 ApplySet 的修剪：apply set 是一个服务端对象（默认是一个 Secret），kubectl 可以使用它在 apply 操作中准确高效地跟踪集合成员关系。此模式作为基于允许列表的修剪的替代方案，在 kubectl v1.27 中作为 Alpha 功能引入。

特性状态： Kubernetes v1.5 [alpha]

警告

在允许列表模式下使用 kubectl apply 的 --prune 时请务必小心。哪些对象会被修剪取决于 --prune-allowlist、--selector 和 --namespace 标志的值，并依赖于作用域内对象的动态发现。特别是在调用之间更改标志值时，这可能导致对象意外被删除或保留。

要使用基于允许列表的修剪，请在 kubectl apply 调用中添加以下标志

  • --prune：删除先前已应用但不在当前调用传递的集合中的对象。
  • --prune-allowlist：考虑用于修剪的组-版本-资源（GVK）列表。此标志是可选的，但强烈建议使用，因为其默认值是命名空间作用域和集群作用域类型的局部列表，这可能导致意想不到的结果。
  • --selector/-l：使用标签选择器来约束修剪的对象集合。此标志是可选的，但强烈建议使用。
  • --all：代替 --selector/-l 使用，显式选择所有先前应用过的符合允许列表类型的对象。

基于允许列表的修剪会查询 API 服务器以获取匹配给定标签（如果有）的所有允许列表 GVK 对象，并尝试将返回的存活对象配置与对象清单文件进行匹配。如果一个对象匹配查询，且该目录中没有其对应的清单，并且它具有 kubectl.kubernetes.io/last-applied-configuration 注解，则该对象会被删除。

kubectl apply -f <directory> --prune -l <labels> --prune-allowlist=<gvk-list>

警告

带有修剪功能的 apply 仅应在包含对象清单的根目录上运行。在子目录上运行可能导致对象被无意中删除，如果它们之前被应用过、具有给定的标签（如果有），且未出现在该子目录中。

特性状态： Kubernetes v1.27 [alpha]

注意

kubectl apply --prune --applyset 处于 Alpha 阶段，后续版本可能会引入不向后兼容的更改。

要使用基于 ApplySet 的修剪，请设置 KUBECTL_APPLYSET=true 环境变量，并在 kubectl apply 调用中添加以下标志

  • --prune：删除先前已应用但不在当前调用传递的集合中的对象。
  • --applyset：kubectl 可用于在 apply 操作中准确高效地跟踪集合成员关系的对象名称。
KUBECTL_APPLYSET=true kubectl apply -f <directory> --prune --applyset=<name>

默认情况下，使用的 ApplySet 父对象类型为 Secret。但是，ConfigMap 也可以按以下格式使用：--applyset=configmaps/<name>。使用 Secret 或 ConfigMap 时，如果对象不存在，kubectl 会自动创建它。

也可以将自定义资源用作 ApplySet 父对象。要启用此功能，请使用以下标签标记定义所需资源的自定义资源定义（CRD）：applyset.kubernetes.io/is-parent-type: true。然后，创建要用作 ApplySet 父级的对象（kubectl 不会自动为自定义资源执行此操作）。最后，在 applyset 标志中引用该对象，例如：--applyset=<resource>.<group>/<name>（例如，widgets.custom.example.com/widget-name）。

使用基于 ApplySet 的修剪时，kubectl 会在将对象发送到服务器之前，为集合中的每个对象添加 applyset.kubernetes.io/part-of=<parentID> 标签。出于性能考虑，它还会收集集合包含的资源类型和命名空间列表，并将其作为注解添加到存活的父对象上。最后，在 apply 操作结束时，它会根据 applyset.kubernetes.io/part-of=<parentID> 标签的定义，查询 API 服务器以获取属于该集合的这些类型和命名空间（或集群作用域）的对象。

注意事项和限制

  • 每个对象最多只能属于一个集合。
  • 使用任何命名空间作用域的父对象（包括默认的 Secret）时，必须使用 --namespace 标志。这意味着跨多个命名空间的 ApplySet 必须使用集群作用域的自定义资源作为父对象。
  • 要安全地在多个目录中使用基于 ApplySet 的修剪，请为每个目录使用唯一的 ApplySet 名称。

如何查看对象

你可以使用带有 -o yaml 的 kubectl get 来查看存活对象的配置

kubectl get -f <filename|url> -o yaml

Apply 如何计算差异并合并更改

注意

补丁（patch）是一种针对对象特定字段而非整个对象的更新操作。这使得无需先读取整个对象即可更新对象上的一组特定字段。

当 kubectl apply 更新对象的存活配置时，它通过向 API 服务器发送补丁请求来实现。补丁定义了针对存活对象配置中特定字段的更新。kubectl apply 命令使用配置文件、存活配置以及存储在存活配置中的 last-applied-configuration 注解来计算此补丁请求。

合并补丁计算

kubectl apply 命令将配置文件的内容写入 kubectl.kubernetes.io/last-applied-configuration 注解。这用于识别已从配置文件中移除并需要从存活配置中清除的字段。以下是计算应删除或设置哪些字段的步骤

  1. 计算要删除的字段。这些是在 last-applied-configuration 中存在但配置文件中缺失的字段。
  2. 计算要添加或设置的字段。这些是配置文件中存在但其值与存活配置不匹配的字段。

这是一个例子。假设这是 Deployment 对象的配置文件

application/update_deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.16.1 # update the image
        ports:
        - containerPort: 80

此外，假设这是同一个 Deployment 对象的存活配置

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # ...
    # note that the annotation does not contain replicas
    # because it was not updated through apply
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"minReadySeconds":5,"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.14.2","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}      
  # ...
spec:
  replicas: 2 # written by scale
  # ...
  minReadySeconds: 5
  selector:
    matchLabels:
      # ...
      app: nginx
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        # ...
        name: nginx
        ports:
        - containerPort: 80
      # ...

以下是 kubectl apply 将执行的合并计算

  1. 通过读取 last-applied-configuration 中的值并将其与配置文件中的值进行比较，计算要删除的字段。无论本地对象配置文件中是否出现，显式设置为 null 的字段都会被清除。在此示例中，minReadySeconds 出现在 last-applied-configuration 注解中，但未出现在配置文件中。操作：从存活配置中清除 minReadySeconds。
  2. 通过读取配置文件中的值并将其与存活配置中的值进行比较，计算要设置的字段。在此示例中，配置文件中 image 的值与存活配置中的值不匹配。操作：设置存活配置中 image 的值。
  3. 将 last-applied-configuration 注解设置为匹配配置文件的值。
  4. 将 1、2、3 的结果合并为一个发送给 API 服务器的补丁请求。

这是合并后的存活配置

apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    # ...
    # The annotation contains the updated image to nginx 1.16.1,
    # but does not contain the updated replicas to 2
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"apps/v1","kind":"Deployment",
      "metadata":{"annotations":{},"name":"nginx-deployment","namespace":"default"},
      "spec":{"selector":{"matchLabels":{"app":nginx}},"template":{"metadata":{"labels":{"app":"nginx"}},
      "spec":{"containers":[{"image":"nginx:1.16.1","name":"nginx",
      "ports":[{"containerPort":80}]}]}}}}      
    # ...
spec:
  selector:
    matchLabels:
      # ...
      app: nginx
  replicas: 2 # Set by `kubectl scale`.  Ignored by `kubectl apply`.
  # minReadySeconds cleared by `kubectl apply`
  # ...
  template:
    metadata:
      # ...
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.16.1 # Set by `kubectl apply`
        # ...
        name: nginx
        ports:
        - containerPort: 80
        # ...
      # ...
    # ...
  # ...

不同字段类型的合并方式

配置文件中特定字段与存活配置的合并方式取决于字段的类型。有几种字段类型

  • 原始类型（primitive）：字符串、整数或布尔值类型的字段。例如，image 和 replicas 是原始字段。操作：替换。

  • 映射（map），也称为 对象（object）：映射类型或包含子字段的复杂类型字段。例如，labels、annotations、spec 和 metadata 都是映射。操作：合并元素或子字段。

  • 列表（list）：包含可以是原始类型或映射的元素列表的字段。例如，containers、ports 和 args 是列表。操作：不同情况不同处理。

当 kubectl apply 更新映射或列表字段时，它通常不会替换整个字段，而是更新单个子元素。例如，当合并 Deployment 上的 spec 时，整个 spec 不会被替换。相反，spec 的子字段（如 replicas）会被比较和合并。

合并原始（primitive）字段的更改

原始字段会被替换或清除。

说明

- 表示“不适用”，因为该值未被使用。
对象配置文件中的字段存活对象配置中的字段last-applied-configuration 中的字段操作
是是-将存活配置设置为配置文件值。
是否-将存活配置设置为本地配置。
否-是从存活配置中清除。
否-否什么都不做。保持存活值。

合并映射（map）字段的更改

代表映射的字段通过比较映射的每个子字段或元素来合并

说明

- 表示“不适用”，因为该值未被使用。
对象配置文件中的键存活对象配置中的键last-applied-configuration 中的字段操作
是是-比较子字段值。
是否-将存活配置设置为本地配置。
否-是从存活配置中删除。
否-否什么都不做。保持存活值。

合并列表（list）类型字段的更改

合并列表更改使用三种策略之一

  • 如果列表的所有元素都是原始类型，则替换列表。
  • 合并复杂元素列表中的各个元素。
  • 合并原始元素列表。

策略的选择是基于每个字段进行的。

如果所有元素都是原始类型，则替换列表

将列表视为与原始字段相同。替换或删除整个列表。这会保留顺序。

示例：使用 kubectl apply 更新 Pod 中容器的 args 字段。这会将存活配置中 args 的值设置为配置文件中的值。之前添加到存活配置中的任何 args 元素都会丢失。配置文件中定义的 args 元素的顺序在存活配置中得到保留。

# last-applied-configuration value
    args: ["a", "b"]

# configuration file value
    args: ["a", "c"]

# live configuration
    args: ["a", "b", "d"]

# result after merge
    args: ["a", "c"]

解释：合并使用配置文件值作为新的列表值。

合并复杂元素列表的各个元素

将列表视为映射，并以每个元素的特定字段作为键。添加、删除或更新各个元素。这不会保留顺序。

此合并策略在每个字段上使用一个称为 patchMergeKey 的特殊标签。patchMergeKey 是为 Kubernetes 源代码中每个字段定义的：types.go 合并映射列表时，为给定元素指定的 patchMergeKey 字段将被用作该元素的映射键。

示例：使用 kubectl apply 更新 PodSpec 的 containers 字段。这会像合并映射一样合并该列表，其中每个元素都以 name 为键。

# last-applied-configuration value
    containers:
    - name: nginx
      image: nginx:1.16
    - name: nginx-helper-a # key: nginx-helper-a; will be deleted in result
      image: helper:1.3
    - name: nginx-helper-b # key: nginx-helper-b; will be retained
      image: helper:1.3

# configuration file value
    containers:
    - name: nginx
      image: nginx:1.16
    - name: nginx-helper-b
      image: helper:1.3
    - name: nginx-helper-c # key: nginx-helper-c; will be added in result
      image: helper:1.3

# live configuration
    containers:
    - name: nginx
      image: nginx:1.16
    - name: nginx-helper-a
      image: helper:1.3
    - name: nginx-helper-b
      image: helper:1.3
      args: ["run"] # Field will be retained
    - name: nginx-helper-d # key: nginx-helper-d; will be retained
      image: helper:1.3

# result after merge
    containers:
    - name: nginx
      image: nginx:1.16
      # Element nginx-helper-a was deleted
    - name: nginx-helper-b
      image: helper:1.3
      args: ["run"] # Field was retained
    - name: nginx-helper-c # Element was added
      image: helper:1.3
    - name: nginx-helper-d # Element was ignored
      image: helper:1.3

解释

  • 名为 "nginx-helper-a" 的容器被删除，因为配置文件中没有出现名为 "nginx-helper-a" 的容器。
  • 名为 "nginx-helper-b" 的容器保留了存活配置中对 args 的更改。kubectl apply 能够识别出存活配置中的 "nginx-helper-b" 与配置文件中的是同一个，即使它们的字段值不同（配置文件中没有 args）。这是因为 patchMergeKey 字段值（name）在两者中是完全一样的。
  • 名为 "nginx-helper-c" 的容器被添加，因为存活配置中没有出现该名称的容器，而配置文件中出现了。
  • 名为 "nginx-helper-d" 的容器被保留，因为 last-applied-configuration 中没有出现该名称的元素。

合并原始元素列表

截至 Kubernetes 1.5，不支持合并原始元素列表。

说明

给定字段选择上述哪种策略由 types.go 中的 patchStrategy 标签控制。如果列表类型的字段没有指定 patchStrategy，则该列表会被替换。

默认字段值

如果对象创建时未指定某些字段，API 服务器会在存活配置中为它们设置默认值。

这是一个 Deployment 的配置文件。该文件未指定 strategy

application/simple_deployment.yaml 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  minReadySeconds: 5
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

使用 kubectl apply 创建对象

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

使用 kubectl get 打印存活配置

kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml

输出显示 API 服务器在存活配置中为几个字段设置了默认值。这些字段在配置文件中未指定。

apiVersion: apps/v1
kind: Deployment
# ...
spec:
  selector:
    matchLabels:
      app: nginx
  minReadySeconds: 5
  replicas: 1 # defaulted by apiserver
  strategy:
    rollingUpdate: # defaulted by apiserver - derived from strategy.type
      maxSurge: 1
      maxUnavailable: 1
    type: RollingUpdate # defaulted by apiserver
  template:
    metadata:
      creationTimestamp: null
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx:1.14.2
        imagePullPolicy: IfNotPresent # defaulted by apiserver
        name: nginx
        ports:
        - containerPort: 80
          protocol: TCP # defaulted by apiserver
        resources: {} # defaulted by apiserver
        terminationMessagePath: /dev/termination-log # defaulted by apiserver
      dnsPolicy: ClusterFirst # defaulted by apiserver
      restartPolicy: Always # defaulted by apiserver
      securityContext: {} # defaulted by apiserver
      terminationGracePeriodSeconds: 30 # defaulted by apiserver
# ...

在补丁请求中，除非作为补丁请求的一部分被显式清除，否则默认字段不会重新应用默认值。这可能导致基于其他字段值进行默认设置的字段出现意外行为。当后续更改其他字段时，除非显式清除，否则默认值不会更新。

因此，建议在配置文件中显式定义由服务器设置默认值的某些字段，即使期望的值与服务器默认值匹配。这使得更容易识别那些不会由服务器重新设置默认值的冲突值。

示例

# last-applied-configuration
spec:
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

# configuration file
spec:
  strategy:
    type: Recreate # updated value
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

# live configuration
spec:
  strategy:
    type: RollingUpdate # defaulted value
    rollingUpdate: # defaulted value derived from type
      maxSurge : 1
      maxUnavailable: 1
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

# result after merge - ERROR!
spec:
  strategy:
    type: Recreate # updated value: incompatible with rollingUpdate
    rollingUpdate: # defaulted value: incompatible with "type: Recreate"
      maxSurge : 1
      maxUnavailable: 1
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.14.2
        ports:
        - containerPort: 80

解释

  1. 用户创建了一个未定义 strategy.type 的 Deployment。
  2. 服务器将 strategy.type 默认设置为 RollingUpdate，并将 strategy.rollingUpdate 的值设置为默认值。
  3. 用户将 strategy.type 更改为 Recreate。strategy.rollingUpdate 的值保持其默认值，尽管服务器希望它们被清除。如果 strategy.rollingUpdate 的值在配置文件中最初就已定义，那么它们需要被删除这一点就会更清晰。
  4. Apply 失败，因为 strategy.rollingUpdate 未被清除。当 strategy.type 为 Recreate 时，不能定义 strategy.rollingUpdate 字段。

建议：这些字段应在对象配置文件中显式定义

  • 工作负载（如 Deployment、StatefulSet、Job、DaemonSet、ReplicaSet 和 ReplicationController）的选择器和 Pod 模板标签
  • Deployment 滚动更新策略

如何清除服务端默认值或由其他写入者设置的字段

未出现在配置文件中的字段可以通过将其值设置为 null 然后应用配置文件来清除。对于服务器设置默认值的字段，这会触发重新应用默认值。

如何在配置文件和直接命令式写入者之间更改字段的所有权

这些是你应该用来更改单个对象字段的唯一方法

  • 使用 kubectl apply。
  • 直接写入存活配置而不修改配置文件：例如，使用 kubectl scale。

将所有者从直接命令式写入者更改为配置文件

将字段添加到配置文件。对于该字段，停止使用不经过 kubectl apply 的存活配置直接更新方式。

将所有者从配置文件更改为直接命令式写入者

截至 Kubernetes 1.5，将字段所有权从配置文件更改为命令式写入者需要手动步骤

  • 从配置文件中移除该字段。
  • 从存活对象的 kubectl.kubernetes.io/last-applied-configuration 注解中移除该字段。

更改管理方法

Kubernetes 对象一次应仅通过一种方法进行管理。从一种方法切换到另一种方法是可能的，但这是一个手动过程。

说明

在使用声明式管理时使用命令式删除是可以的。

从命令式命令管理迁移到声明式对象配置

从命令式命令管理迁移到声明式对象配置涉及几个手动步骤

  1. 将存活对象导出到本地配置文件

    kubectl get <kind>/<name> -o yaml > <kind>_<name>.yaml

  2. 手动从配置文件中移除 status 字段。

    说明

    这一步是可选的，因为即使 status 字段存在于配置文件中，kubectl apply 也不会更新它。

  3. 在对象上设置 kubectl.kubernetes.io/last-applied-configuration 注解

    kubectl replace --save-config -f <kind>_<name>.yaml

  4. 更改流程以仅使用 kubectl apply 管理该对象。

从命令式对象配置迁移到声明式对象配置

  1. 在对象上设置 kubectl.kubernetes.io/last-applied-configuration 注解

    kubectl replace --save-config -f <kind>_<name>.yaml

  2. 更改流程以仅使用 kubectl apply 管理该对象。

定义控制器选择器和 Pod 模板标签

警告

强烈不建议更新控制器上的选择器。

推荐的方法是定义一个仅由控制器选择器使用且不具有其他语义含义的单一、不可变的 Pod 模板标签。

示例

selector:
  matchLabels:
      controller-selector: "apps/v1/deployment/nginx"
template:
  metadata:
    labels:
      controller-selector: "apps/v1/deployment/nginx"

接下来


最后修改时间 2023 年 8 月 24 日下午 6:38 PST：使用 code_sample shortcode 代替 code shortcode (e8b136c3b3)