使用配置文件声明式管理 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
标志以递归处理目录。这是一个对象配置文件的示例:
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
使用 server-side dry-run,这需要在 kube-apiserver
上启用。
由于 diff
在空运行模式下执行服务器端应用请求,因此它需要授予 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
更新目录中定义的所有对象,即使这些对象已经存在。这种方法实现了以下目的:
- 在实时配置中设置配置文件中出现的字段。
- 清除实时配置中已从配置文件中移除的字段。
kubectl diff -f <directory>
kubectl apply -f <directory>
注意
添加-R
标志以递归处理目录。这是一个配置文件的示例:
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
字段。
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 delete -f <filename>
替代方法:kubectl apply -f <directory> --prune
作为 kubectl delete
的替代方法,你可以使用 kubectl apply
在清单从本地文件系统中的目录中移除后识别要删除的对象。
在 Kubernetes 1.34 中,kubectl apply 中有两种可用的修剪模式:
- 基于白名单的修剪:此模式自 kubectl v1.5 以来一直存在,但由于其设计存在可用性、正确性和性能问题,仍处于 Alpha 阶段。基于 ApplySet 的模式旨在取代它。
- 基于 ApplySet 的修剪:ApplySet 是一个服务器端对象(默认是 Secret),kubectl 可以使用它在 apply 操作中准确高效地跟踪集合成员。此模式在 kubectl v1.27 中作为基于白名单的修剪的替代方案以 Alpha 阶段引入。
Kubernetes v1.5 [alpha]
警告
在允许列表模式下将--prune
与 kubectl apply
一起使用时请小心。修剪哪些对象取决于 --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>
警告
应用修剪只应针对包含对象清单的根目录运行。如果对象先前已应用、具有给定标签(如果有)且未出现在子目录中,则针对子目录运行可能会导致对象意外删除。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 父对象。为此,请用以下标签标记定义要使用的资源的 Custom Resource Definition (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 操作结束时,它会查询 API 服务器,查找属于该集合的、位于这些命名空间中(或在集群范围内,视情况而定)的那些类型对象,这些对象由 applyset.kubernetes.io/part-of=<parentID>
标签定义。
注意事项和限制
- 每个对象最多只能是一个集合的成员。
- 当使用任何命名空间父级(包括默认 Secret)时,需要
--namespace
标志。这意味着跨多个命名空间的 ApplySets 必须使用集群范围的自定义资源作为父对象。 - 要安全地将基于 ApplySet 的修剪与多个目录一起使用,请为每个目录使用唯一的 ApplySet 名称。
如何查看对象
您可以使用 kubectl get
配合 -o yaml
查看实时对象的配置。
kubectl get -f <filename|url> -o yaml
应用如何计算差异并合并更改
注意
补丁(patch)是一种更新操作,它仅限于对象的特定字段,而不是整个对象。这使得仅更新对象上的特定字段集而无需先读取对象成为可能。当 kubectl apply
更新对象的实时配置时,它通过向 API 服务器发送一个补丁请求来完成。该补丁定义了针对实时对象配置的特定字段的更新。kubectl apply
命令使用配置文件、实时配置以及存储在实时配置中的 last-applied-configuration
注解来计算此补丁请求。
合并补丁计算
kubectl apply
命令将配置文件内容写入 kubectl.kubernetes.io/last-applied-configuration
注解。这用于识别已从配置文件中移除并需要从实时配置中清除的字段。以下是用于计算应删除或设置哪些字段的步骤:
- 计算要删除的字段。这些字段存在于
last-applied-configuration
中,但配置文件中缺少。 - 计算要添加或设置的字段。这些字段存在于配置文件中,但其值与实时配置不匹配。
这是一个例子。假设这是一个 Deployment 对象的配置文件:
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
将执行的合并计算:
- 通过读取
last-applied-configuration
中的值并将其与配置文件中的值进行比较来计算要删除的字段。无论last-applied-configuration
中是否出现,清除本地对象配置文件中明确设置为 null 的字段。在此示例中,minReadySeconds
出现在last-applied-configuration
注解中,但未出现在配置文件中。操作:从实时配置中清除minReadySeconds
。 - 通过读取配置文件中的值并将其与实时配置中的值进行比较来计算要设置的字段。在此示例中,配置文件中
image
的值与实时配置中的值不匹配。操作:设置实时配置中image
的值。 - 将
last-applied-configuration
注解设置为与配置文件值匹配。 - 将 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
# ...
# ...
# ...
# ...
不同类型字段的合并方式
配置文件中特定字段与实时配置的合并方式取决于该字段的类型。有几种字段类型:
原始类型:字符串、整数或布尔类型的字段。例如,
image
和replicas
都是原始字段。操作:替换。映射,也称为 对象:映射类型或包含子字段的复杂类型的字段。例如,
labels
、annotations
、spec
和metadata
都是映射。操作:合并元素或子字段。列表:包含原始类型或映射的列表的字段。例如,
containers
、ports
和args
都是列表。操作:因情况而异。
当 kubectl apply
更新映射或列表字段时,它通常不会替换整个字段,而是更新单个子元素。例如,在合并 Deployment 上的 spec
时,不会替换整个 spec
。相反,会比较和合并 spec
的子字段,例如 replicas
。
合并原始字段的更改
原始字段被替换或清除。
注意
-
表示“不适用”,因为该值未被使用。对象配置文件中的字段 | 实时对象配置中的字段 | last-applied-configuration 中的字段 | 行动 |
---|---|---|---|
是 | 是 | - | 将实时配置设置为配置文件值。 |
是 | 否 | - | 将实时配置设置为本地配置。 |
否 | - | 是 | 从实时配置中清除。 |
否 | - | 否 | 不执行任何操作。保留实时值。 |
合并映射字段的更改
表示映射的字段通过比较映射的每个子字段或元素来合并。
注意
-
表示“不适用”,因为该值未被使用。对象配置文件中的键 | 实时对象配置中的键 | last-applied-configuration 中的字段 | 行动 |
---|---|---|---|
是 | 是 | - | 比较子字段值。 |
是 | 否 | - | 将实时配置设置为本地配置。 |
否 | - | 是 | 从实时配置中删除。 |
否 | - | 否 | 不执行任何操作。保留实时值。 |
合并列表类型字段的更改
合并对列表的更改使用以下三种策略之一:
- 如果列表的所有元素都是原始类型,则替换该列表。
- 合并复杂元素列表中的单个元素。
- 合并原始元素列表。
策略的选择是针对每个字段进行的。
如果列表的所有元素都是原始类型,则替换该列表。
将列表视为与原始字段相同。替换或删除整个列表。这会保留顺序。
示例:使用 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" 与配置文件中的 "nginx-helper-b" 是相同的,尽管它们的字段值不同(配置文件中没有args
)。这是因为patchMergeKey
字段值(name)在两者中都相同。 - 名为 "nginx-helper-c" 的容器被添加了,因为实时配置中没有同名容器,但配置文件中有一个同名容器。
- 名为 "nginx-helper-d" 的容器被保留,因为 last-applied-configuration 中没有同名元素。
合并原始元素列表
自 Kubernetes 1.5 起,不支持合并原始元素列表。
默认字段值
如果对象创建时未指定某些字段,API 服务器会在实时配置中将其设置为默认值。
这是一个 Deployment 的配置文件。该文件未指定 strategy
:
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
说明
- 用户在未定义
strategy.type
的情况下创建了一个 Deployment。 - 服务器将
strategy.type
默认为RollingUpdate
并默认strategy.rollingUpdate
值。 - 用户将
strategy.type
更改为Recreate
。strategy.rollingUpdate
值保持其默认值,尽管服务器期望它们被清除。如果strategy.rollingUpdate
值最初在配置文件中定义,那么它们需要被删除会更清楚。 - 由于
strategy.rollingUpdate
未清除,应用失败。strategy.rollingupdate
字段不能与Recreate
的strategy.type
一起定义。
建议:这些字段应在对象配置文件中明确定义:
- 工作负载(例如 Deployment、StatefulSet、Job、DaemonSet、ReplicaSet 和 ReplicationController)上的选择器和 PodTemplate 标签。
- 部署回滚策略
如何清除服务器默认字段或由其他写入器设置的字段
未在配置文件中出现的字段可以通过将其值设置为 null
然后应用配置文件来清除。对于服务器默认的字段,这将触发重新默认这些值。
如何在配置文件和直接命令式写入器之间更改字段的所有权
这些是您应该用于更改单个对象字段的唯一方法:
- 使用
kubectl apply
。 - 直接写入实时配置,而不修改配置文件:例如,使用
kubectl scale
。
将所有者从直接命令式写入器更改为配置文件
将字段添加到配置文件中。对于该字段,停止对不通过 kubectl apply
的实时配置进行直接更新。
将所有者从配置文件更改为直接命令式写入器
自 Kubernetes 1.5 起,将字段的所有权从配置文件更改为命令式写入器需要手动步骤:
- 从配置文件中删除该字段。
- 从实时对象上的
kubectl.kubernetes.io/last-applied-configuration
注解中删除该字段。
管理方法变更
Kubernetes 对象应一次只使用一种方法进行管理。从一种方法切换到另一种方法是可能的,但这是一个手动过程。
注意
将命令式删除与声明式管理结合使用是可以的。从命令式管理迁移到声明式对象配置
从命令式管理迁移到声明式对象配置涉及几个手动步骤:
将实时对象导出到本地配置文件
kubectl get <kind>/<name> -o yaml > <kind>_<name>.yaml
手动从配置文件中删除
status
字段。注意
此步骤是可选的,因为kubectl apply
不会更新 status 字段,即使它存在于配置文件中。在对象上设置
kubectl.kubernetes.io/last-applied-configuration
注解kubectl replace --save-config -f <kind>_<name>.yaml
更改流程以独占使用
kubectl apply
管理对象。
从命令式对象配置迁移到声明式对象配置
在对象上设置
kubectl.kubernetes.io/last-applied-configuration
注解kubectl replace --save-config -f <kind>_<name>.yaml
更改流程以独占使用
kubectl apply
管理对象。
定义控制器选择器和 PodTemplate 标签
警告
强烈不鼓励更新控制器上的选择器。推荐的方法是定义一个唯一的、不可变的 PodTemplate 标签,该标签仅由控制器选择器使用,没有其他语义含义。
示例
selector:
matchLabels:
controller-selector: "apps/v1/deployment/nginx"
template:
metadata:
labels:
controller-selector: "apps/v1/deployment/nginx"