使用 Kustomize 声明式管理 Kubernetes 对象
Kustomize 是一个独立的工具，用于通过 kustomization 文件 自定义 Kubernetes 对象。
从 1.14 版本开始，kubectl 也支持使用 kustomization 文件管理 Kubernetes 对象。要查看包含 kustomization 文件的目录中找到的资源，请运行以下命令
kubectl kustomize <kustomization_directory>
要应用这些资源，请使用 kubectl apply 命令，并带有 --kustomize 或 -k 标志
kubectl apply -k <kustomization_directory>
开始之前
安装 kubectl。
您需要一个 Kubernetes 集群，并且 kubectl 命令行工具必须配置为与您的集群通信。建议在至少有两个节点（不充当控制平面主机）的集群上运行此教程。如果您还没有集群，可以使用 minikube 创建一个，或者可以使用以下 Kubernetes 游乐场
要检查版本，请输入 kubectl version。
Kustomize 概述
Kustomize 是一种用于自定义 Kubernetes 配置的工具。它具有以下功能来管理应用程序配置文件
- 从其他来源生成资源
- 为资源设置跨切面字段
- 组合和自定义资源集合
生成资源
ConfigMap 和 Secret 包含其他 Kubernetes 对象（例如 Pod）使用的配置或敏感数据。ConfigMap 或 Secret 的真实来源通常在集群外部，例如 .properties 文件或 SSH 密钥文件。Kustomize 具有 secretGenerator 和 configMapGenerator，它们可以从文件或字面量生成 Secret 和 ConfigMap。
configMapGenerator
要从文件生成 ConfigMap，请将条目添加到 configMapGenerator 中的 files 列表中。以下是一个从 .properties 文件生成包含数据项的 ConfigMap 的示例
# Create a application.properties file
cat <<EOF >application.properties
FOO=Bar
EOF
cat <<EOF >./kustomization.yaml
configMapGenerator:
- name: example-configmap-1
files:
- application.properties
EOF
可以使用以下命令检查生成的 ConfigMap
kubectl kustomize ./
生成的 ConfigMap 是
apiVersion: v1
data:
application.properties: |
FOO=Bar
kind: ConfigMap
metadata:
name: example-configmap-1-8mbdf7882g
要从 env 文件生成 ConfigMap，请将条目添加到 configMapGenerator 中的 envs 列表中。以下是一个从 .env 文件生成包含数据项的 ConfigMap 的示例
# Create a .env file
cat <<EOF >.env
FOO=Bar
EOF
cat <<EOF >./kustomization.yaml
configMapGenerator:
- name: example-configmap-1
envs:
- .env
EOF
可以使用以下命令检查生成的 ConfigMap
kubectl kustomize ./
生成的 ConfigMap 是
apiVersion: v1
data:
FOO: Bar
kind: ConfigMap
metadata:
name: example-configmap-1-42cfbf598f
说明
.env 文件中的每个变量都成为生成的 ConfigMap 中的一个单独的键。这与上一个示例不同，上一个示例将名为 application.properties 的文件（及其所有条目）嵌入为单个键的值。ConfigMap 也可以从字面量键值对生成。要从字面量键值对生成 ConfigMap，请将条目添加到 configMapGenerator 中的 literals 列表中。以下是一个从键值对生成包含数据项的 ConfigMap 的示例
cat <<EOF >./kustomization.yaml
configMapGenerator:
- name: example-configmap-2
literals:
- FOO=Bar
EOF
可以通过以下命令检查生成的 ConfigMap
kubectl kustomize ./
生成的 ConfigMap 是
apiVersion: v1
data:
FOO: Bar
kind: ConfigMap
metadata:
name: example-configmap-2-g2hdhfc6tk
要在 Deployment 中使用生成的 ConfigMap，请引用 configMapGenerator 的名称。Kustomize 会自动将此名称替换为生成的名称。
这是一个使用生成的 ConfigMap 的 Deployment 示例
# Create an application.properties file
cat <<EOF >application.properties
FOO=Bar
EOF
cat <<EOF >deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
labels:
app: my-app
spec:
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: app
image: my-app
volumeMounts:
- name: config
mountPath: /config
volumes:
- name: config
configMap:
name: example-configmap-1
EOF
cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
configMapGenerator:
- name: example-configmap-1
files:
- application.properties
EOF
生成 ConfigMap 和 Deployment
kubectl kustomize ./
生成的 Deployment 将按名称引用生成的 ConfigMap
apiVersion: v1
data:
application.properties: |
FOO=Bar
kind: ConfigMap
metadata:
name: example-configmap-1-g4hk9g2ff8
---
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: my-app
name: my-app
spec:
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- image: my-app
name: app
volumeMounts:
- mountPath: /config
name: config
volumes:
- configMap:
name: example-configmap-1-g4hk9g2ff8
name: config
secretGenerator
您可以从文件或字面量键值对生成 Secret。要从文件生成 Secret，请将条目添加到 secretGenerator 中的 files 列表中。以下是一个从文件生成包含数据项的 Secret 的示例
# Create a password.txt file
cat <<EOF >./password.txt
username=admin
password=secret
EOF
cat <<EOF >./kustomization.yaml
secretGenerator:
- name: example-secret-1
files:
- password.txt
EOF
生成的 Secret 如下
apiVersion: v1
data:
password.txt: dXNlcm5hbWU9YWRtaW4KcGFzc3dvcmQ9c2VjcmV0Cg==
kind: Secret
metadata:
name: example-secret-1-t2kt65hgtb
type: Opaque
要从字面量键值对生成 Secret，请将条目添加到 secretGenerator 中的 literals 列表中。以下是一个从键值对生成包含数据项的 Secret 的示例
cat <<EOF >./kustomization.yaml
secretGenerator:
- name: example-secret-2
literals:
- username=admin
- password=secret
EOF
生成的 Secret 如下
apiVersion: v1
data:
password: c2VjcmV0
username: YWRtaW4=
kind: Secret
metadata:
name: example-secret-2-t52t6g96d8
type: Opaque
与 ConfigMap 类似，生成的 Secret 可以在 Deployment 中通过引用 secretGenerator 的名称来使用
# Create a password.txt file
cat <<EOF >./password.txt
username=admin
password=secret
EOF
cat <<EOF >deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-app
labels:
app: my-app
spec:
selector:
matchLabels:
app: my-app
template:
metadata:
labels:
app: my-app
spec:
containers:
- name: app
image: my-app
volumeMounts:
- name: password
mountPath: /secrets
volumes:
- name: password
secret:
secretName: example-secret-1
EOF
cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
secretGenerator:
- name: example-secret-1
files:
- password.txt
EOF
generatorOptions
生成的 ConfigMap 和 Secret 具有附加的内容哈希后缀。这可确保在内容更改时生成新的 ConfigMap 或 Secret。要禁用附加后缀的行为，可以使用 generatorOptions。除此之外，还可以为生成的 ConfigMap 和 Secret 指定跨切面选项。
cat <<EOF >./kustomization.yaml
configMapGenerator:
- name: example-configmap-3
literals:
- FOO=Bar
generatorOptions:
disableNameSuffixHash: true
labels:
type: generated
annotations:
note: generated
EOF
运行kubectl kustomize ./ 以查看生成的 ConfigMap
apiVersion: v1
data:
FOO: Bar
kind: ConfigMap
metadata:
annotations:
note: generated
labels:
type: generated
name: example-configmap-3
设置跨切面字段
为项目中的所有 Kubernetes 资源设置相同的跨切面字段是很常见的。设置跨切面字段的一些用例
- 为所有资源设置相同的命名空间
- 添加相同的前缀或后缀
- 添加相同的标签集
- 添加相同的注释集
这是一个示例
# Create a deployment.yaml
cat <<EOF >./deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
labels:
app: nginx
spec:
selector:
matchLabels:
app: nginx
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx
EOF
cat <<EOF >./kustomization.yaml
namespace: my-namespace
namePrefix: dev-
nameSuffix: "-001"
labels:
- pairs:
app: bingo
includeSelectors: true
commonAnnotations:
oncallPager: 800-555-1212
resources:
- deployment.yaml
EOF
运行 kubectl kustomize ./ 以查看这些字段都已设置在 Deployment 资源中
apiVersion: apps/v1
kind: Deployment
metadata:
annotations:
oncallPager: 800-555-1212
labels:
app: bingo
name: dev-nginx-deployment-001
namespace: my-namespace
spec:
selector:
matchLabels:
app: bingo
template:
metadata:
annotations:
oncallPager: 800-555-1212
labels:
app: bingo
spec:
containers:
- image: nginx
name: nginx
组合和自定义资源
在项目中组合一组资源并在同一文件或目录中管理它们是很常见的。Kustomize 提供了从不同文件组合资源以及对其进行修补或其他自定义的功能。
组合
Kustomize 支持资源的组合。kustomization.yaml 文件中的 resources 字段定义了包含在配置中的资源列表。将资源的配置文件的路径设置为 resources 列表。以下是一个由 Deployment 和 Service 组成的 NGINX 应用程序的示例
# Create a deployment.yaml file
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
spec:
selector:
matchLabels:
run: my-nginx
replicas: 2
template:
metadata:
labels:
run: my-nginx
spec:
containers:
- name: my-nginx
image: nginx
ports:
- containerPort: 80
EOF
# Create a service.yaml file
cat <<EOF > service.yaml
apiVersion: v1
kind: Service
metadata:
name: my-nginx
labels:
run: my-nginx
spec:
ports:
- port: 80
protocol: TCP
selector:
run: my-nginx
EOF
# Create a kustomization.yaml composing them
cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
- service.yaml
EOF
来自 kubectl kustomize ./ 的资源包含 Deployment 和 Service 对象。
自定义
可以使用修补程序对资源应用不同的自定义。Kustomize 通过 StrategicMerge 和 Json6902 使用 patches 字段支持不同的修补机制。patches 可以是文件或内联字符串，针对单个或多个资源。
patches 字段包含按指定顺序应用的修补程序列表。修补程序目标通过 group、version、kind、name、namespace、labelSelector 和 annotationSelector 选择资源。
建议创建执行单一操作的小修补程序。例如，创建一个修补程序来增加 Deployment 的副本数，再创建一个修补程序来设置内存限制。修补程序目标使用修补程序文件中的 group、version、kind 和 name 字段进行匹配。
# Create a deployment.yaml file
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
spec:
selector:
matchLabels:
run: my-nginx
replicas: 2
template:
metadata:
labels:
run: my-nginx
spec:
containers:
- name: my-nginx
image: nginx
ports:
- containerPort: 80
EOF
# Create a patch increase_replicas.yaml
cat <<EOF > increase_replicas.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
spec:
replicas: 3
EOF
# Create another patch set_memory.yaml
cat <<EOF > set_memory.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
spec:
template:
spec:
containers:
- name: my-nginx
resources:
limits:
memory: 512Mi
EOF
cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
patches:
- path: increase_replicas.yaml
- path: set_memory.yaml
EOF
运行 kubectl kustomize ./ 以查看 Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
spec:
replicas: 3
selector:
matchLabels:
run: my-nginx
template:
metadata:
labels:
run: my-nginx
spec:
containers:
- image: nginx
name: my-nginx
ports:
- containerPort: 80
resources:
limits:
memory: 512Mi
并非所有资源或字段都支持 strategicMerge 修补程序。为了支持修改任意资源中任意字段，Kustomize 提供了通过 Json6902 应用 JSON patch。要找到 Json6902 修补程序的正确资源，必须在 kustomization.yaml 中指定 target 字段。
例如，可以通过 Json6902 修补程序增加 Deployment 对象的副本数。修补程序目标使用 target 字段中的 group、version、kind 和 name 进行匹配。
# Create a deployment.yaml file
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
spec:
selector:
matchLabels:
run: my-nginx
replicas: 2
template:
metadata:
labels:
run: my-nginx
spec:
containers:
- name: my-nginx
image: nginx
ports:
- containerPort: 80
EOF
# Create a json patch
cat <<EOF > patch.yaml
- op: replace
path: /spec/replicas
value: 3
EOF
# Create a kustomization.yaml
cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
patches:
- target:
group: apps
version: v1
kind: Deployment
name: my-nginx
path: patch.yaml
EOF
运行 kubectl kustomize ./ 以查看 replicas 字段已更新
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
spec:
replicas: 3
selector:
matchLabels:
run: my-nginx
template:
metadata:
labels:
run: my-nginx
spec:
containers:
- image: nginx
name: my-nginx
ports:
- containerPort: 80
除了修补程序之外，Kustomize 还提供了自定义容器镜像或将其他对象中的字段值注入容器的功能，而无需创建修补程序。例如，您可以通过在 kustomization.yaml 文件中的 images 字段中指定新的镜像来更改容器中使用的镜像。
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
spec:
selector:
matchLabels:
run: my-nginx
replicas: 2
template:
metadata:
labels:
run: my-nginx
spec:
containers:
- name: my-nginx
image: nginx
ports:
- containerPort: 80
EOF
cat <<EOF >./kustomization.yaml
resources:
- deployment.yaml
images:
- name: nginx
newName: my.image.registry/nginx
newTag: "1.4.0"
EOF
运行 kubectl kustomize ./ 以查看正在使用的镜像已更新
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
spec:
replicas: 2
selector:
matchLabels:
run: my-nginx
template:
metadata:
labels:
run: my-nginx
spec:
containers:
- image: my.image.registry/nginx:1.4.0
name: my-nginx
ports:
- containerPort: 80
有时，Pod 中运行的应用程序可能需要使用来自其他对象的配置值。例如，来自 Deployment 对象的 Pod 需要从 Env 或作为命令参数读取相应的 Service 名称。由于 Service 名称可能会随着 namePrefix 或 nameSuffix 添加到 kustomization.yaml 文件而更改。不建议在命令参数中硬编码 Service 名称。对于这种用法，Kustomize 可以通过 replacements 将 Service 名称注入容器。
# Create a deployment.yaml file (quoting the here doc delimiter)
cat <<'EOF' > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
spec:
selector:
matchLabels:
run: my-nginx
replicas: 2
template:
metadata:
labels:
run: my-nginx
spec:
containers:
- name: my-nginx
image: nginx
command: ["start", "--host", "MY_SERVICE_NAME_PLACEHOLDER"]
EOF
# Create a service.yaml file
cat <<EOF > service.yaml
apiVersion: v1
kind: Service
metadata:
name: my-nginx
labels:
run: my-nginx
spec:
ports:
- port: 80
protocol: TCP
selector:
run: my-nginx
EOF
cat <<EOF >./kustomization.yaml
namePrefix: dev-
nameSuffix: "-001"
resources:
- deployment.yaml
- service.yaml
replacements:
- source:
kind: Service
name: my-nginx
fieldPath: metadata.name
targets:
- select:
kind: Deployment
name: my-nginx
fieldPaths:
- spec.template.spec.containers.0.command.2
EOF
运行 kubectl kustomize ./ 以查看注入到容器中的 Service 名称为 dev-my-nginx-001
apiVersion: apps/v1
kind: Deployment
metadata:
name: dev-my-nginx-001
spec:
replicas: 2
selector:
matchLabels:
run: my-nginx
template:
metadata:
labels:
run: my-nginx
spec:
containers:
- command:
- start
- --host
- dev-my-nginx-001
image: nginx
name: my-nginx
基础和叠加
Kustomize 具有 基础 和 叠加 的概念。基础 是一个包含 kustomization.yaml 的目录，其中包含一组资源和相关的自定义。基础可以是本地目录或来自远程仓库的目录，只要目录中存在 kustomization.yaml。叠加 是一个包含 kustomization.yaml 的目录，它将其他 kustomization 目录作为其 bases 引用。基础 不了解叠加，并且可以在多个叠加中使用。
叠加 目录中的 kustomization.yaml 可以引用多个 bases，将这些 bases 中定义的所有资源组合成统一的配置。此外，它可以对这些资源应用自定义以满足特定要求。
这是一个基础示例
# Create a directory to hold the base
mkdir base
# Create a base/deployment.yaml
cat <<EOF > base/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
spec:
selector:
matchLabels:
run: my-nginx
replicas: 2
template:
metadata:
labels:
run: my-nginx
spec:
containers:
- name: my-nginx
image: nginx
EOF
# Create a base/service.yaml file
cat <<EOF > base/service.yaml
apiVersion: v1
kind: Service
metadata:
name: my-nginx
labels:
run: my-nginx
spec:
ports:
- port: 80
protocol: TCP
selector:
run: my-nginx
EOF
# Create a base/kustomization.yaml
cat <<EOF > base/kustomization.yaml
resources:
- deployment.yaml
- service.yaml
EOF
此基础可以在多个叠加中使用。您可以在不同的叠加中添加不同的 namePrefix 或其他跨切面字段。以下是使用相同基础的两个叠加。
mkdir dev
cat <<EOF > dev/kustomization.yaml
resources:
- ../base
namePrefix: dev-
EOF
mkdir prod
cat <<EOF > prod/kustomization.yaml
resources:
- ../base
namePrefix: prod-
EOF
使用 Kustomize 应用/查看/删除对象的方法
在 kubectl 命令中使用 --kustomize 或 -k 来识别由 kustomization.yaml 管理的资源。请注意，-k 应该指向一个 kustomization 目录，例如
kubectl apply -k <kustomization directory>/
给定以下 kustomization.yaml，
# Create a deployment.yaml file
cat <<EOF > deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: my-nginx
spec:
selector:
matchLabels:
run: my-nginx
replicas: 2
template:
metadata:
labels:
run: my-nginx
spec:
containers:
- name: my-nginx
image: nginx
ports:
- containerPort: 80
EOF
# Create a kustomization.yaml
cat <<EOF >./kustomization.yaml
namePrefix: dev-
labels:
- pairs:
app: my-nginx
includeSelectors: true
resources:
- deployment.yaml
EOF
运行以下命令以应用 Deployment 对象 dev-my-nginx
> kubectl apply -k ./
deployment.apps/dev-my-nginx created
运行以下命令之一以查看 Deployment 对象 dev-my-nginx
kubectl get -k ./
kubectl describe -k ./
运行以下命令以将 Deployment 对象 dev-my-nginx 与应用 manifest 后集群的状态进行比较
kubectl diff -k ./
运行以下命令以删除 Deployment 对象 dev-my-nginx
> kubectl delete -k ./
deployment.apps "dev-my-nginx" deleted
Kustomize 功能列表
| 字段 | 类型 | 说明 |
|---|---|---|
| bases | []string | 此列表中的每个条目应解析为一个包含 kustomization.yaml 文件的目录 |
| commonAnnotations | map[string]string | 要添加到所有资源的注解 |
| commonLabels | map[string]string | 要添加到所有资源和选择器的标签 |
| configMapGenerator | []ConfigMapArgs | 此列表中的每个条目都会生成一个 ConfigMap |
| configurations | []string | 此列表中的每个条目应解析为一个包含 Kustomize transformer 配置的文件 |
| crds | []string | 此列表中的每个条目应解析为 Kubernetes 类型 OpenAPI 定义文件 |
| generatorOptions | GeneratorOptions | 修改所有 ConfigMap 和 Secret 生成器的行为 |
| images | []Image | 每个条目用于修改一个镜像的名称、标签和/或摘要，而无需创建补丁 |
| labels | map[string]string | 添加标签，而不自动注入相应的选择器 |
| namePrefix | 字符串 | 此字段的值将添加到所有资源名称的前面 |
| nameSuffix | 字符串 | 此字段的值将添加到所有资源名称的后面 |
| patchesJson6902 | []Patch | 此列表中的每个条目应解析为一个 Kubernetes 对象和一个 Json Patch |
| patchesStrategicMerge | []string | 此列表中的每个条目应解析为 Kubernetes 对象的战略合并补丁 |
| replacements | []Replacements | 将资源字段中的值复制到任何数量的指定目标。 |
| resources | []string | 此列表中的每个条目必须解析为现有的资源配置文件 |
| secretGenerator | []SecretArgs | 此列表中的每个条目都会生成一个 Secret |
| vars | []Var | 每个条目用于从一个资源的字段中捕获文本 |