Kubernetes 配置管理

ConfigMap、Secret、配置挂载、环境变量、配置变更和回滚策略。

Kubernetes 配置管理

Kubernetes 常用 ConfigMap 保存普通配置，用 Secret 保存敏感配置。应用可以通过环境变量、命令行参数或 Volume 文件读取配置。

Kubernetes 配置管理流程

ConfigMap

创建 ConfigMap：

kubectl create configmap app-config \
  --from-literal=APP_ENV=prod \
  --from-literal=LOG_LEVEL=info \
  -n default

YAML 示例：

# API 版本。ConfigMap 是核心资源，使用 v1。
apiVersion: v1
# 资源类型。这里表示创建 ConfigMap。
kind: ConfigMap
metadata:
  # ConfigMap 名称。
  name: app-config
# 普通配置数据，key-value 形式保存。
data:
  # 应用环境。
  APP_ENV: prod
  # 日志级别。
  LOG_LEVEL: info
  # 多行配置文件内容，容器中可以按文件挂载读取。
  application.yaml: |
    server:
      port: 8080

Secret

创建 Secret：

kubectl create secret generic app-secret \
  --from-literal=DB_PASSWORD='change-me' \
  -n default

YAML 示例：

# API 版本。Secret 是核心资源，使用 v1。
apiVersion: v1
# 资源类型。这里表示创建 Secret。
kind: Secret
metadata:
  # Secret 名称。
  name: app-secret
# Secret 类型。Opaque 表示通用 key-value Secret。
type: Opaque
# stringData 允许直接写明文字符串，提交后会转换为 data。
stringData:
  # 数据库密码示例，生产环境不要明文提交到 Git。
  DB_PASSWORD: change-me

stringData 适合手写 YAML，提交到 API Server 后会被转换成 base64 编码的 data。

环境变量注入

# 单个环境变量注入配置。
env:
  # 环境变量名称。
  - name: APP_ENV
    # 从 ConfigMap 或 Secret 等资源引用值。
    valueFrom:
      # 从 ConfigMap 的指定 key 读取。
      configMapKeyRef:
        # ConfigMap 名称。
        name: app-config
        # ConfigMap 中的 key。
        key: APP_ENV
  - name: DB_PASSWORD
    valueFrom:
      # 从 Secret 的指定 key 读取。
      secretKeyRef:
        # Secret 名称。
        name: app-secret
        # Secret 中的 key。
        key: DB_PASSWORD

批量注入：

# 批量将 ConfigMap / Secret 中的 key 注入为环境变量。
envFrom:
  # 引入 ConfigMap 中的全部 key。
  - configMapRef:
      name: app-config
  # 引入 Secret 中的全部 key。
  - secretRef:
      name: app-secret

环境变量只在容器启动时注入，ConfigMap 或 Secret 更新后，运行中的容器不会自动刷新环境变量。

Volume 挂载

# Pod 卷定义。
volumes:
  # 卷名称，供 volumeMounts 引用。
  - name: app-config
    # 卷内容来自 ConfigMap。
    configMap:
      # ConfigMap 名称。
      name: app-config
# 容器列表。
containers:
  # 容器名称。
  - name: app
    # 容器镜像。
    image: nginx:1.27
    # 容器内挂载点。
    volumeMounts:
      # 引用上面定义的卷。
      - name: app-config
        # 挂载到容器内的目录。
        mountPath: /etc/app
        # 只读挂载，避免容器内误修改。
        readOnly: true

挂载单个 key：

# 容器内挂载点列表。
volumeMounts:
  # 引用名为 app-config 的卷。
  - name: app-config
    # 将单个配置文件挂载到指定路径。
    mountPath: /etc/app/application.yaml
    # 只挂载 ConfigMap 中的 application.yaml 这个 key。
    subPath: application.yaml

使用 subPath 挂载时，配置更新通常不会自动反映到容器文件中，需要重新发布 Pod。

配置变更

常用流程：

修改 ConfigMap / Secret。
校验 YAML 和差异。
应用配置变更。
触发工作负载滚动重启。
检查 Pod 状态、日志和业务健康。

kubectl diff -f config.yaml
kubectl apply -f config.yaml
kubectl rollout restart deployment/order-api -n default
kubectl rollout status deployment/order-api -n default

版本化建议

配置变更要能回溯：

ConfigMap 和 Secret YAML 纳入 Git 管理。
敏感值不要明文提交到仓库。
生产 Secret 建议使用 External Secrets、Sealed Secrets 或云厂商密钥服务。
重大配置变更记录变更单和回滚版本。
应用启动时打印配置版本，不打印敏感值。

常见问题

现象	排查方向
Pod 启动报配置不存在	检查 ConfigMap / Secret 名称、key 和命名空间
环境变量未更新	环境变量只在容器启动时注入，需要重启 Pod
Volume 配置未刷新	检查是否使用 `subPath`，以及应用是否重新读取文件
Secret 解码异常	检查 base64、换行符和字符集
配置导致 CrashLoopBackOff	查看 `logs --previous` 和最近配置变更

排查命令

kubectl get configmap,secret -n default
kubectl describe configmap app-config -n default
kubectl describe secret app-secret -n default
kubectl get pod <pod-name> -n default -o yaml
kubectl logs <pod-name> -n default --previous