Configmap基础

文档

k8s

Configmap基础

概述

ConfigMap 是 Kubernetes 中用于存储非敏感配置数据的 API 资源，支持将配置与容器镜像解耦，便于应用配置的集中管理和动态更新。本文档涵盖 ConfigMap 的四种常见使用方式：环境变量、命令行参数、目录挂载和文件挂载。

核心能力：

配置与镜像分离，无需重新构建镜像即可修改配置
支持多种注入方式（环境变量、命令行参数、卷挂载）
支持热更新（挂载方式修改 ConfigMap 后自动同步到 Pod）
支持从文件、目录或字面量创建

环境变量注入

将 ConfigMap 的键值对作为容器环境变量注入。

单个环境变量

apiVersion: v1
kind: Pod
metadata:
  name: pod-env-config-demo
spec:
  containers:
  - name: demo-container
    image: busybox
    command: ["/bin/sh", "-c", "env | grep APP_ && sleep 3600"]
    env:
      - name: APP_ENV
        valueFrom:
          configMapKeyRef:
            name: app-yaml-config
            key: app.env
      - name: APP_VERSION
        valueFrom:
          configMapKeyRef:
            name: app-yaml-config
            key: app.version
  restartPolicy: Never

批量注入（所有键值对）

envFrom:
  - configMapRef:
      name: app-simple-config

使用场景：适用于配置项较多时，避免逐个声明 env 条目。

命令行参数注入

通过环境变量中转，将 ConfigMap 值传递给容器启动命令。

apiVersion: v1
kind: Pod
metadata:
  name: pod-command-config-demo
spec:
  containers:
  - name: demo-container
    image: busybox
    command:
      - /bin/sh
      - -c
      - "echo '当前环境：$(APP_ENV)，版本：$(APP_VERSION)' && sleep 3600"
    env:
      - name: APP_ENV
        valueFrom:
          configMapKeyRef:
            name: app-yaml-config
            key: app.env
      - name: APP_VERSION
        valueFrom:
          configMapKeyRef:
            name: app-yaml-config
            key: app.version
  restartPolicy: Never

使用场景：应用启动时需要将配置作为启动参数传递（如 --env=prod）。

挂载为目录

将 ConfigMap 的键值对挂载为容器内的文件目录，每个键对应一个文件，内容为键对应的值。

apiVersion: v1
kind: Pod
metadata:
  name: pod-volume-dir-config-demo
spec:
  containers:
  - name: demo-container
    image: busybox
    command: ["/bin/sh", "-c", "ls /app/config && cat /app/config/app.conf && sleep 3600"]
    volumeMounts:
      - name: config-volume
        mountPath: /app/config
  volumes:
    - name: config-volume
      configMap:
        name: app-yaml-config
  restartPolicy: Never

挂载效果：

/app/config/
├── app.conf
├── app.env
├── app.version
└── db.properties

注意：挂载目录会覆盖目标目录中的原有文件。

挂载为文件

通过 subPath 将 ConfigMap 的特定键挂载为单个文件。

apiVersion: v1
kind: Pod
metadata:
  name: pod-volume-file-config-demo
spec:
  containers:
  - name: demo-container
    image: busybox
    command: ["/bin/sh", "-c", "cat /app/db.properties && sleep 3600"]
    volumeMounts:
      - name: config-volume
        mountPath: /app/db.properties
        subPath: db.properties
  volumes:
    - name: config-volume
      configMap:
        name: app-yaml-config
        items:
          - key: db.properties
            path: db.properties
  restartPolicy: Never

使用场景：

不希望覆盖目标目录下已有文件
需要将配置文件放在特定路径（如 /etc/app/config.yaml）

ConfigMap 创建示例

# 从字面量创建
kubectl create configmap app-simple-config \
  --from-literal=app.env=prod \
  --from-literal=app.version=v1.0.0

# 从文件创建
kubectl create configmap app-yaml-config --from-file=app.conf

# 从目录创建
kubectl create configmap app-dir-config --from-file=./config/

# 查看 ConfigMap
kubectl get cm
kubectl describe cm app-yaml-config

使用方式对比

方式	优点	缺点	热更新	适用场景
环境变量	简单易用，无需修改应用代码	不支持热更新，需重启 Pod	❌	少量配置，无需动态变更
命令行参数	与启动命令耦合清晰	依赖环境变量中转，不支持热更新	❌	启动参数传递
目录挂载	支持热更新，文件自动同步	覆盖目标目录所有文件	✅	大量配置文件统一管理
文件挂载（subPath）	支持热更新，不覆盖目录	单个文件挂载，需逐个配置	✅	指定配置文件挂载

热更新说明

挂载方式（目录/文件）：修改 ConfigMap 后，Pod 内文件会自动同步（存在几秒延迟），应用需支持文件变更自动重载
环境变量方式：修改 ConfigMap 后，需重启 Pod 使新的环境变量生效
强制重启：可通过 kubectl rollout restart 或修改 Pod 注解触发重启：

kubectl patch deployment <deploy-name> -p '{"spec":{"template":{"metadata":{"annotations":{"config-update":"'$(date +%s)'"}}}}}'

常见问题与注意事项

ConfigMap 必须在使用前存在

在 Pod 引用 ConfigMap 之前，该 ConfigMap 必须已存在，否则 Pod 启动失败。

subPath 挂载不自动更新

使用 subPath 挂载的配置文件，默认不支持热更新，需要重启 Pod 才能感知变更。

挂载目录覆盖问题

ConfigMap 挂载为目录时，会覆盖目标目录中的原有文件。如需保留原文件，请使用 subPath 方式挂载。

ConfigMap 大小限制

ConfigMap 的大小限制为 1MiB，大文件请考虑使用持久化存储卷。

特殊字符处理

ConfigMap 的键名只能包含字母、数字、-、_ 和 .，值无特殊限制。

查看 Pod 内配置

# 查看环境变量
kubectl exec <pod-name> -- env | grep APP_

# 查看挂载的配置文件
kubectl exec <pod-name> -- cat /app/config/app.conf

# 查看 ConfigMap 原始内容
kubectl get cm <configmap-name> -o yaml

参考链接

权限基础问题优化