Kubernetes ConfigMap 怎样区分环境变量与文件挂载

同一份 ConfigMap 可以提供环境变量，也可以提供配置文件。选择时先看应用的读取接口：它接收一个启动参数式的字符串，还是需要打开一份 YAML 文件？官方说明可复制查看：https://kubernetes.io/docs/concepts/configuration/configmap/。本文以报表服务为例，区分配置交付方式、更新传播与应用重载三个问题。

先看应用从哪里读取配置

假设服务读取 APP_LOG_LEVEL 决定启动日志等级，并从 /etc/report-settings/report.yaml 读取导出规则。前者适合选择性注入环境变量，后者适合文件挂载。两种消费方式可以并用，不必把整个服务的配置强行改成一种格式。

下面是一份声明示例，未在实际集群执行。它只含非敏感业务配置；密码、令牌等信息不要塞进 ConfigMap。

# 非敏感演示配置；Pod 与它放在同一命名空间
apiVersion: v1
kind: ConfigMap
metadata:
  name: report-config
data:
  LOG_LEVEL: "info"
  report.yaml: |
    output:
      format: csv
      directory: /tmp/reports

data 的值是字符串。report.yaml 在 ConfigMap 中是一个键，值才是多行文件内容；键名的后缀不会让 Kubernetes 自动验证业务 YAML，也不会替应用解释导出规则。

候选一：把单个键注入环境变量

应用已经支持从环境变量读取日志等级时，使用 env.valueFrom.configMapKeyRef 指定来源。容器内变量名与来源键名可以不同：这里用 APP_LOG_LEVEL 接收 LOG_LEVEL。这种显式映射能让部署配置与应用接口保持清楚的对应关系。

# 合并到现有 Pod 模板的 spec.containers 对应容器中
env:
  - name: APP_LOG_LEVEL
    valueFrom:
      configMapKeyRef:
        name: report-config
        key: LOG_LEVEL

这是容器配置片段，不是可独立提交的完整工作负载。应放入现有 Deployment 的 spec.template.spec.containers 中对应容器；直接创建 Pod 时放入它的容器定义。

envFrom.configMapRef 适合一次导入一组环境变量，但要先确认所有待导入键都符合当前集群对环境变量名的要求。对本例包含多行文件内容的 ConfigMap，逐键选择更容易说明哪些配置交给应用。不要因为有 envFrom 就把一份完整配置文件当成普通日志等级变量来传递。

环境变量不会随着 ConfigMap 修改而自动刷新。更新 Deployment 模板以创建新 Pod，或按发布策略替换现有 Pod 后，新容器才会按新的配置初始化环境。单独修改 ConfigMap 也不会自动触发 Deployment 滚动更新。

候选二：把配置投射为目录中的文件

应用需要读取文件时，声明 ConfigMap 卷，再把卷以目录方式挂入容器。下面选择 report.yaml 这个键，映射为卷内同名文件。

# 合并到现有 Pod 模板的 spec；保留原来的镜像等字段
volumes:
  - name: report-settings
    configMap:
      name: report-config
      items:
        - key: report.yaml
          path: report.yaml
# 以下 volumeMounts 放到需要读取配置的容器定义中
# containers:
#   - name: app
#     volumeMounts:
#       - name: report-settings
#         mountPath: /etc/report-settings
#         readOnly: true

示例中的 volumes 位于 Pod spec，注释展示的 volumeMounts 位于容器定义，两者通过 report-settings 关联。实际合并时，应把注释里的挂载字段添加到现有容器，而不是直接提交这段示意代码。应用最终打开的是 /etc/report-settings/report.yaml。

items 让这个卷只投射选中的键。若不指定它，ConfigMap 中的键通常会分别形成卷内文件；本例显式选择可避免把 LOG_LEVEL 也当成文件交付。选择一个应用镜像原本未使用的目录，避免挂载遮住镜像内已有文件。

readOnly: true 表明这里用文件读取配置。不要设计成应用通过写回挂载文件去修改 ConfigMap；配置变更应走集群配置管理入口。

更新之后，分别由谁负责生效

目录投射的 ConfigMap 卷在配置变化后会最终更新。传播延迟受 kubelet 同步周期及其配置变更检测策略等因素影响，不能承诺保存后立刻看到新文件，也不能给所有集群套用一个固定等待秒数。

即使文件内容已经改变，进程是否采用它仍取决于应用。只在启动时读取文件的程序，需要替换或重启工作负载；支持重新读取的程序，才可能通过自身的重载机制采用新配置。Kubernetes 不会因为文件更新就自动替应用执行某个业务重载动作。

还有一个容易误判的例外：使用 subPath 挂载 ConfigMap 中的单个文件，不会收到 ConfigMap 更新。如果选择它是为了保留目标目录其他文件，应同时明确采用替换 Pod 的更新策略，不能沿用目录投射的更新预期。

若设置 immutable: true，配置内容就不能按普通可变 ConfigMap 的方式原地修改。可以使用新名称创建新版本，并调整工作负载引用完成发布。无论采用哪种方式，都应把配置版本与工作负载版本的对应关系保存在发布记录中。

用决策表确定部署方式

排查“ConfigMap 改了却没有生效”时，先确认 Pod 引用的名称和命名空间，再看它走的是环境变量、目录卷还是 subPath，最后确认应用的读取时机。这样能把来源引用错误、传播等待与业务重载问题分别定位。

对本例，日志等级走 APP_LOG_LEVEL，报表规则走目录文件就足够清楚。如果服务只有启动读取能力，两条配置通道都纳入 Pod 替换流程；如果文件部分支持可靠重载，再为它制定独立的更新流程。不要仅凭“已经挂载文件”推断服务具备热更新能力。

依据：Kubernetes 官方 ConfigMap 文档。本文配置为解释性片段，未声称完成集群运行或线上验证。