Kubernetes ConfigMap 使用指南

ConfigMap 是一种 API 对象，用来将非机密性的数据保存到键值对中。使用时， Pod 可以将其用作环境变量、命令行参数或者存储卷中的配置文件。
ConfigMap 将你的环境配置信息和容器镜像解耦，便于应用配置的修改。

注意：
ConfigMap 并不提供保密或者加密功能。 如果你想存储的数据是机密的，
请使用 Secret， 或者使用其他第三方工具来保证你的数据的私密性，而不是用 ConfigMap。

创建 ConfigMap

你可以使用 kubectl create configmap 或者在 kustomization.yaml 中的 ConfigMap 生成器来创建 ConfigMap。

使用 kubectl create configmap 创建 ConfigMap
你可以使用 kubectl create configmap 命令基于目录、 文件或者字面值来创建 ConfigMap：

kubectl create configmap <映射名称> <数据源>

其中，<映射名称> 是为 ConfigMap 指定的名称，<数据源> 是要从中提取数据的目录、 文件或者字面值。
ConfigMap 对象的名称必须是合法的 DNS 子域名。

在你基于文件来创建 ConfigMap 时，<数据源> 中的键名默认取自文件的基本名， 而对应的值则默认为文件的内容。

你可以使用 kubectl describe 或者 kubectl get 获取有关 ConfigMap 的信息

1. 基于一个目录来创建 ConfigMap

你可以使用 kubectl create configmap 基于同一目录中的多个文件创建 ConfigMap。 当你基于目录来创建 ConfigMap 时，
kubectl 识别目录下文件名可以作为合法键名的文件， 并将这些文件打包到新的 ConfigMap 中。普通文件之外的所有目录项都会被忽略
（例如：子目录、符号链接、设备、管道等等）。

mkdir -p /opt/configmap/

# 将示例文件下载到 `configure-pod-container/configmap/` 目录
wget https://kubernetes.io/examples/configmap/game.properties -O /opt/configmap/game.properties
wget https://kubernetes.io/examples/configmap/ui.properties -O /opt/configmap/ui.properties

# 查看
root@k8s-master01:~# ls /opt/configmap/
game.properties  ui.properties

root@k8s-master01:~# more /opt/configmap/game.properties 
enemies=aliens
lives=3
enemies.cheat=true
enemies.cheat.level=noGoodRotten
secret.code.passphrase=UUDDLRLRBABAS
secret.code.allowed=true
secret.code.lives=30

root@k8s-master01:~# more /opt/configmap/ui.properties 
color.good=purple
color.bad=yellow
allow.textmode=true
how.nice.to.look=fairlyNice


# 创建 ConfigMap
kubectl create configmap game-config --from-file=/opt/configmap/


# 验证

root@k8s-master01:~# kubectl get cm game-config -oyaml
apiVersion: v1
data:
  game.properties: |-
    enemies=aliens
    lives=3
    enemies.cheat=true
    enemies.cheat.level=noGoodRotten
    secret.code.passphrase=UUDDLRLRBABAS
    secret.code.allowed=true
    secret.code.lives=30
  ui.properties: |
    color.good=purple
    color.bad=yellow
    allow.textmode=true
    how.nice.to.look=fairlyNice
kind: ConfigMap
metadata:
  creationTimestamp: "2025-04-08T14:12:23Z"
  name: game-config
  namespace: default

kubectl describe configmaps game-config

/opt/configmap/ 目录中的 game.properties 和 ui.properties 文件出现在 ConfigMap 的 data 部分。

2. 基于文件创建 ConfigMap

你可以使用 kubectl create configmap 基于单个文件或多个文件创建 ConfigMap。

例如：
kubectl create configmap game-config-2 --from-file=/opt/configmap/game.properties

kubectl describe configmaps game-config-2
kubectl get cm game-config-2 -oyaml

你可以多次使用 --from-file 参数，从多个数据源创建 ConfigMap。
kubectl create configmap game-config-3 --from-file=/opt/configmap/game.properties --from-file=/opt/configmap/ui.properties

kubectl describe configmaps game-config-3
kubectl get cm game-config-3 -oyaml

使用 --from-env-file 选项基于 env 文件创建 ConfigMap，例如

# Env 文件包含环境变量列表。其中适用以下语法规则:
# 这些语法规则适用：
#   Env 文件中的每一行必须为 VAR=VAL 格式。
#   以＃开头的行（即注释）将被忽略。
#   空行将被忽略。
#   引号不会被特殊处理（即它们将成为 ConfigMap 值的一部分）。

# 将示例文件下载到 `configure-pod-container/configmap/` 目录
wget https://kubernetes.io/examples/configmap/game-env-file.properties -O /opt/configmap/game-env-file.properties
wget https://kubernetes.io/examples/configmap/ui-env-file.properties -O /opt/configmap/ui-env-file.properties



# Env 文件 `game-env-file.properties` 如下所示
root@k8s-master01:~# more /opt/configmap/ui-env-file.properties 
color=purple
textmode=true
how=fairlyNice
root@k8s-master01:~# more /opt/configmap/game-env-file.properties 
enemies=aliens
lives=3
allowed="true"

# This comment and the empty line above it are ignored

# 创建 
kubectl create configmap game-config-env-file \
       --from-env-file=/opt/configmap/game-env-file.properties

查看
root@k8s-master01:~# kubectl get configmap game-config-env-file -o yaml
apiVersion: v1
data:
  allowed: '"true"'
  enemies: aliens
  lives: "3"
kind: ConfigMap
metadata:
  creationTimestamp: "2025-04-08T14:19:04Z"
  name: game-config-env-file
  namespace: default
  resourceVersion: "719635"
  uid: 1b5a2e14-4124-4a96-b82d-1b132f671ad1

从 Kubernetes 1.23 版本开始，kubectl 支持多次指定 --from-env-file 参数来从多个数据源创建 ConfigMap。

# 创建 
kubectl create configmap config-multi-env-files \
        --from-env-file=/opt/configmap/game-env-file.properties \
        --from-env-file=/opt/configmap/ui-env-file.properties

# 查看
root@k8s-master01:~# kubectl get configmap config-multi-env-files -o yaml
apiVersion: v1
data:
  allowed: '"true"'
  color: purple
  enemies: aliens
  how: fairlyNice
  lives: "3"
  textmode: "true"
kind: ConfigMap
metadata:
  creationTimestamp: "2025-04-08T14:20:21Z"
  name: config-multi-env-files
  namespace: default
  resourceVersion: "719783"
  uid: e30d81fd-6ca5-420b-804b-5e40cecb1155

定义从文件创建 ConfigMap 时要使用的键

在使用 --from-file 参数时，你可以定义在 ConfigMap 的 data 部分出现键名， 而不是按默认行为使用文件名：

kubectl create configmap game-config-3 --from-file=<我的键名>=<文件路径>

<我的键名> 是你要在 ConfigMap 中使用的键名，<文件路径> 是你想要键所表示的数据源文件的位置。

# 创建 
kubectl create configmap game-config-3 --from-file=game-special-key=/opt/configmap/game.properties

# 查看
root@k8s-master01:~# kubectl get configmaps game-config-3 -o yaml
apiVersion: v1
data:
  game-special-key: |-
    enemies=aliens
    lives=3
    enemies.cheat=true
    enemies.cheat.level=noGoodRotten
    secret.code.passphrase=UUDDLRLRBABAS
    secret.code.allowed=true
    secret.code.lives=30
kind: ConfigMap
metadata:
  creationTimestamp: "2025-04-08T14:22:36Z"
  name: game-config-3
  namespace: default
  resourceVersion: "720045"
  uid: 30a5aaec-b583-43de-9b7a-b204a02bfccd

根据字面值创建 ConfigMap

你可以将 kubectl create configmap 与 --from-literal 参数一起使用， 通过命令行定义文字值：

kubectl create configmap special-config --from-literal=special.how=very --from-literal=special.type=charm

你可以传入多个键值对。命令行中提供的每对键值在 ConfigMap 的 data 部分中均表示为单独的条目。

root@k8s-master01:~# kubectl get configmaps special-config -o yaml
apiVersion: v1
data:
  special.how: very
  special.type: charm
kind: ConfigMap
metadata:
  creationTimestamp: "2025-04-08T14:23:42Z"
  name: special-config
  namespace: default
  resourceVersion: "720171"
  uid: b90c2de2-3cb6-48d9-873e-a135b694a007

基于字面值生成 ConfigMap

此示例向你展示如何使用 Kustomize 和 kubectl，基于两个字面键/值对 special.type=charm 和 special.how=very 创建一个 ConfigMap。
为了实现这一点，你可以配置 ConfigMap 生成器。 创建（或替换）kustomization.yaml，使其具有以下内容。

---
# 基于字面创建 ConfigMap 的 kustomization.yaml 内容
cat >kustomization.yaml <<EOF
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
configMapGenerator:
- name: special-config-2
  literals:
  - special.how=very
  - special.type=charm
EOF

临时清理

在继续之前，清理你创建的一些 ConfigMap：

kubectl delete configmap special-config
kubectl delete configmap env-config
kubectl delete configmap -l 'game-config in (config-4,config-5)'

使用 ConfigMap 数据定义容器环境变量

使用单个 ConfigMap 中的数据定义容器环境变量

1.在 ConfigMap 中将环境变量定义为键值对：

kubectl create configmap special-config --from-literal=special.how=very

2.将 ConfigMap 中定义的 special.how 赋值给 Pod 规约中的 SPECIAL_LEVEL_KEY 环境变量。

apiVersion: v1
kind: Pod
metadata:
  name: dapi-test-pod
spec:
  containers:
    - name: test-container
      image: registry.k8s.io/busybox
      command: [ "/bin/sh", "-c", "env" ]
      env:
        # 定义环境变量
        - name: SPECIAL_LEVEL_KEY
          valueFrom:
            configMapKeyRef:
              # ConfigMap 包含你要赋给 SPECIAL_LEVEL_KEY 的值
              name: special-config
              # 指定与取值相关的键名
              key: special.how
  restartPolicy: Never
  
Pod 的输出包含环境变量 SPECIAL_LEVEL_KEY=very
  

使用来自多个 ConfigMap 的数据定义容器环境变量

与前面的示例一样，首先创建 ConfigMap。 这是你将使用的清单：

apiVersion: v1
kind: ConfigMap
metadata:
  name: special-config
  namespace: default
data:
  special.how: very
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: env-config
  namespace: default
data:
  log_level: INFO

在 Pod 规约中定义环境变量。

apiVersion: v1
kind: Pod
metadata:
  name: dapi-test-pod
spec:
  containers:
    - name: test-container
      image: registry.k8s.io/busybox
      command: [ "/bin/sh", "-c", "env" ]
      env:
        - name: SPECIAL_LEVEL_KEY
          valueFrom:
            configMapKeyRef:
              name: special-config
              key: special.how
        - name: LOG_LEVEL
          valueFrom:
            configMapKeyRef:
              name: env-config
              key: log_level
  restartPolicy: Never

现在，Pod 的输出包含环境变量 SPECIAL_LEVEL_KEY=very 和 LOG_LEVEL=INFO。

将 ConfigMap 中的所有键值对配置为容器环境变量

创建一个包含多个键值对的 ConfigMap。

apiVersion: v1
kind: ConfigMap
metadata:
  name: special-config
  namespace: default
data:
  SPECIAL_LEVEL: very
  SPECIAL_TYPE: charm

使用 envFrom 将所有 ConfigMap 的数据定义为容器环境变量，ConfigMap 中的键成为 Pod 中的环境变量名称。

apiVersion: v1
kind: Pod
metadata:
  name: dapi-test-pod
spec:
  containers:
    - name: test-container
      image: registry.k8s.io/busybox
      command: [ "/bin/sh", "-c", "env" ]
      envFrom:
      - configMapRef:
          name: special-config
  restartPolicy: Never

在 Pod 命令中使用 ConfigMap 定义的环境变量

你可以使用 $(VAR_NAME) Kubernetes 替换语法在容器的 command 和 args 属性中使用 ConfigMap 定义的环境变量。

例如，以下 Pod 清单：

apiVersion: v1
kind: Pod
metadata:
  name: dapi-test-pod
spec:
  containers:
    - name: test-container
      image: registry.k8s.io/busybox
      command: [ "/bin/echo", "$(SPECIAL_LEVEL_KEY) $(SPECIAL_TYPE_KEY)" ]
      env:
        - name: SPECIAL_LEVEL_KEY
          valueFrom:
            configMapKeyRef:
              name: special-config
              key: SPECIAL_LEVEL
        - name: SPECIAL_TYPE_KEY
          valueFrom:
            configMapKeyRef:
              name: special-config
              key: SPECIAL_TYPE
  restartPolicy: Never

此 Pod 在 test-container 容器中产生以下输出：

kubectl logs dapi-test-pod
very charm

将 ConfigMap 数据添加到一个卷中

如基于文件创建 ConfigMap 中所述，当你使用 --from-file 创建 ConfigMap 时，文件名成为存储在 ConfigMap 的 data 部分中的键， 文件内容成为键对应的值。

本节中的示例引用了一个名为 special-config 的 ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
name: special-config
namespace: default
data:
SPECIAL_LEVEL: very
SPECIAL_TYPE: charm

使用存储在 ConfigMap 中的数据填充卷
在 Pod 规约的 volumes 部分下添加 ConfigMap 名称。 这会将 ConfigMap 数据添加到 volumeMounts.mountPath 所指定的目录
（在本例中为 /etc/config）。command 部分列出了名称与 ConfigMap 中的键匹配的目录文件。

apiVersion: v1
kind: Pod
metadata:
  name: dapi-test-pod
spec:
  containers:
    - name: test-container
      image: registry.k8s.io/busybox
      command: [ "/bin/sh", "-c", "ls /etc/config/" ]
      volumeMounts:
      - name: config-volume
        mountPath: /etc/config
  volumes:
    - name: config-volume
      configMap:
        # 提供包含要添加到容器中的文件的 ConfigMap 的名称
        name: special-config
  restartPolicy: Never

创建 Pod：

kubectl create -f pod-configmap-volume.yaml
Pod 运行时，命令 ls /etc/config/ 产生下面的输出：

SPECIAL_LEVEL
SPECIAL_TYPE

文本数据会展现为 UTF-8 字符编码的文件。如果使用其他字符编码， 可以使用 binaryData（详情参阅 ConfigMap 对象）。

说明：
如果该容器镜像的 /etc/config 目录中有一些文件，卷挂载将使该镜像中的这些文件无法访问。

将 ConfigMap 数据添加到卷中的特定路径

使用 path 字段为特定的 ConfigMap 项目指定预期的文件路径。 在这里，ConfigMap 中键 SPECIAL_LEVEL 的内容将挂载在
config-volume 卷中 /etc/config/keys 文件中

apiVersion: v1
kind: Pod
metadata:
  name: dapi-test-pod
spec:
  containers:
    - name: test-container
      image: registry.k8s.io/busybox
      command: [ "/bin/sh","-c","cat /etc/config/keys" ]
      volumeMounts:
      - name: config-volume
        mountPath: /etc/config
  volumes:
    - name: config-volume
      configMap:
        name: special-config
        items:
        - key: SPECIAL_LEVEL
          path: keys
  restartPolicy: Never

执行并输出

kubectl create -f pod-configmap-volume-specific-key.yaml

当 Pod 运行时，命令 cat /etc/config/keys 产生以下输出： very
注意：
如前，/etc/config/ 目录中所有先前的文件都将被删除。

删除该 Pod：

kubectl delete pod dapi-test-pod --now

你可以将密钥投射到特定路径，语法请参阅 Secret 指南中的相应部分。 你可以设置密钥的 POSIX 权限，语法请参阅 Secret 指南中的相应部分

映射键到指定路径并设置文件访问权限

你可以将指定键名投射到特定目录，也可以逐个文件地设定访问权限。 Secret 指南中为这一语法提供了解释。

可选引用
ConfigMap 引用可以被标记为可选。 如果 ConfigMap 不存在，则挂载的卷将为空。 如果 ConfigMap 存在，但引用的键不存在，
则挂载点下的路径将不存在。 有关更多信息，请参阅可选 ConfigMap 细节。

挂载的 ConfigMap 会被自动更新
当已挂载的 ConfigMap 被更新时，所投射的内容最终也会被更新。 这适用于 Pod 启动后可选引用的 ConfigMap 重新出现的情况。

Kubelet 在每次定期同步时都会检查所挂载的 ConfigMap 是否是最新的。 然而，它使用其基于 TTL 机制的本地缓存来获取 ConfigMap 的当前值。 因此，
从 ConfigMap 更新到新键映射到 Pod 的总延迟可能与 kubelet 同步周期（默认为 1 分钟）+ kubelet 中 ConfigMap 缓存的 TTL（默认为 1 分钟）一样长。
你可以通过更新 Pod 的一个注解来触发立即刷新。

说明：
使用 ConfigMap 作为 subPath 卷的容器将不会收到 ConfigMap 更新。

可选的 ConfigMap

你可以在 Pod 规约中将对 ConfigMap 的引用标记为可选（optional）。 如果 ConfigMap 不存在，那么它在 Pod 中为其提供数据的配置（例如：环境变量、挂载的卷）
将为空。 如果 ConfigMap 存在，但引用的键不存在，那么数据也是空的。

例如，以下 Pod 规约将 ConfigMap 中的环境变量标记为可选：

apiVersion: v1
kind: Pod
metadata:
  name: dapi-test-pod
spec:
  containers:
    - name: test-container
      image: gcr.io/google_containers/busybox
      command: ["/bin/sh", "-c", "env"]
      env:
        - name: SPECIAL_LEVEL_KEY
          valueFrom:
            configMapKeyRef:
              name: a-config
              key: akey
              optional: true # 将环境变量标记为可选
  restartPolicy: Never

当你运行这个 Pod 并且名称为 a-config 的 ConfigMap 不存在时，输出空值。 当你运行这个 Pod 并且名称为 a-config 的 ConfigMap 存在，
但是在 ConfigMap 中没有名称为 akey 的键时，控制台输出也会为空。
如果你确实在名为 a-config 的 ConfigMap 中为 akey 设置了键值， 那么这个 Pod 会打印该值，然后终止。

你也可以在 Pod 规约中将 ConfigMap 提供的卷和文件标记为可选。 此时 Kubernetes 将总是为卷创建挂载路径，
即使引用的 ConfigMap 或键不存在。 例如，以下 Pod 规约将所引用得 ConfigMap 的卷标记为可选：

apiVersion: v1
kind: Pod
metadata:
  name: dapi-test-pod
spec:
  containers:
    - name: test-container
      image: gcr.io/google_containers/busybox
      command: ["/bin/sh", "-c", "ls /etc/config"]
      volumeMounts:
      - name: config-volume
        mountPath: /etc/config
  volumes:
    - name: config-volume
      configMap:
        name: no-config
        optional: true # 将引用的 ConfigMap 的卷标记为可选
  restartPolicy: Never

限制

在 Pod 规约中引用某个 ConfigMap 之前，必须先创建这个对象， 或者在 Pod 规约中将 ConfigMap 标记为 optional（请参阅可选的 ConfigMaps）。 如果所引用的
ConfigMap 不存在，并且没有将应用标记为 optional 则 Pod 将无法启动。 同样，引用 ConfigMap 中不存在的主键也会令 Pod 无法启动，除非你将 Configmap 标记为
optional。如果你使用 envFrom 来基于 ConfigMap 定义环境变量，那么无效的键将被忽略。 Pod 可以被启动，但无效名称将被记录在事件日志中（InvalidVariableNames）。
日志消息列出了每个被跳过的键。例如：

删除

删除你创建那些的 ConfigMap 和 Pod

kubectl delete configmaps/game-config configmaps/game-config-2 configmaps/game-config-3 \
               configmaps/game-config-env-file
kubectl delete pod dapi-test-pod --now

# 你可能已经删除了下一组内容
kubectl delete configmaps/special-config configmaps/env-config
kubectl delete configmap -l 'game-config in (config-4,config-5)'