Kubernetes 配置管理

配置分类

类型	建议载体	示例
非敏感、体积小	ConfigMap	功能开关、日志级别、配置文件
敏感、体积小	Secret 或外部密钥系统	密码、Token、证书
大文件/模型	对象存储、镜像或 OCI Artifact	词典、模型、静态数据
动态中心配置	组织批准的配置系统/Operator	高频动态业务配置
应用默认值	镜像内配置	安全、可工作的默认行为

ConfigMap 和 Secret 都保存在 Kubernetes API 中，不适合大文件或高频更新。

ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: web-config
  namespace: demo
data:
  LOG_LEVEL: info
  app.yaml: |
    server:
      port: 8080
    featureFlags:
      checkoutV2: true

生成草稿：

kubectl -n demo create configmap web-config \
  --from-literal=LOG_LEVEL=info \
  --from-file=app.yaml=./config/app.yaml \
  --dry-run=client -o yaml

Secret 并不等于加密

apiVersion: v1
kind: Secret
metadata:
  name: web-credentials
  namespace: demo
type: Opaque
stringData:
  username: app-user
  password: replace-via-approved-secret-workflow

data 是 base64 编码，不是加密；stringData 只是提交时由 API Server 编码。生产应：

• 启用 etcd 静态数据加密，并保护密钥管理系统。
• 用 RBAC 限制 get/list/watch secrets，注意 list 返回数据。
• 优先短期凭据和 Workload Identity，避免长期云密钥。
• 使用组织批准的外部 Secret Controller/CSI 驱动或密文 GitOps 方案。
• 不把真实 Secret 提交 Git、命令历史、日志、Event 或 Pod 注解。

# 只查看键名，不输出值
kubectl -n demo get secret web-credentials -o json | jq -r '.data | keys[]'

环境变量注入

env:
  - name: LOG_LEVEL
    valueFrom:
      configMapKeyRef:
        name: web-config
        key: LOG_LEVEL
  - name: DB_PASSWORD
    valueFrom:
      secretKeyRef:
        name: web-credentials
        key: password
envFrom:
  - configMapRef:
      name: shared-env

通过环境变量注入的值在 Pod 创建时确定，ConfigMap/Secret 更新后不会自动改变，必须重建 Pod。环境变量可能被进程转储、调试命令或错误日志暴露；敏感值优先挂载文件并收紧进程权限。

Volume 挂载

volumes:
  - name: config
    configMap:
      name: web-config
      items:
        - key: app.yaml
          path: app.yaml
  - name: credentials
    secret:
      secretName: web-credentials
      defaultMode: 0400
containers:
  - name: web
    volumeMounts:
      - name: config
        mountPath: /etc/web
        readOnly: true
      - name: credentials
        mountPath: /var/run/secrets/web
        readOnly: true

完整目录挂载的投射文件通常会在 kubelet 同步后最终更新，但不是瞬时通知；使用 subPath 挂载单文件时不会收到自动更新。应用还必须实现安全重载，否则仍需滚动重启。

不要直接覆盖镜像中已有且需要保留的整个目录；Volume 会遮蔽原目录内容。

Projected Volume

一个 projected Volume 可以组合 Secret、ConfigMap、Downward API 和短期 ServiceAccount Token：

volumes:
  - name: identity
    projected:
      defaultMode: 0400
      sources:
        - serviceAccountToken:
            path: token
            audience: internal-api
            expirationSeconds: 3600
        - downwardAPI:
            items:
              - path: namespace
                fieldRef:
                  fieldPath: metadata.namespace

短期投射 Token 会由 kubelet 轮换，应用必须重新读取文件，不能只在启动时缓存到过期。

Downward API

env:
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
  - name: POD_NAMESPACE
    valueFrom:
      fieldRef:
        fieldPath: metadata.namespace
  - name: CPU_REQUEST
    valueFrom:
      resourceFieldRef:
        containerName: web
        resource: requests.cpu

Downward API 适合把身份和资源信息传入容器，不要让应用依赖可通过 Kubernetes API 查询的庞大对象状态。

ServiceAccount

每个命名空间有 default ServiceAccount，但业务应使用专用身份：

apiVersion: v1
kind: ServiceAccount
metadata:
  name: web
  namespace: demo
automountServiceAccountToken: false

如果应用不访问 Kubernetes API，将 automountServiceAccountToken: false。需要访问时显式挂载受众和期限受控的 projected token，并用最小 RBAC 授权；详见 RBAC 与安全。

配置变更与发布

Deployment 不会因为被引用的 ConfigMap/Secret 改变而自动生成新 ReplicaSet。常见策略：

1. 不可变版本名：如 web-config-20260812-01，更新 PodTemplate 引用；回滚清晰。
2. 模板校验和注解：Helm/Kustomize/GitOps 计算配置 Hash，变化触发 rollout。
3. 应用热重载：监视文件变化并原子加载，失败时保留旧配置。
4. 受控 restart：配置更新后执行 rollout restart，但必须纳入发布记录。

不可变对象可防止误修改并减轻 API Server/kubelet 观察负担：

apiVersion: v1
kind: ConfigMap
metadata:
  name: web-config-v3
  namespace: demo
immutable: true
data:
  LOG_LEVEL: info

不可变 ConfigMap/Secret 不能原地更新，只能创建新对象并切换引用。

配置验证清单

• 默认配置可安全启动，必填项缺失时快速失败并给出不含密钥的错误。
• 配置 Schema、范围、单位和兼容性在部署前验证。
• 敏感信息不进入环境转储、日志、指标标签或崩溃报告。
• 更新方式是明确的：热重载或滚动重启，不依赖猜测。
• Secret 有轮换、吊销、所有者和过期监控。
• 配置与应用版本支持向前/向后兼容滚动窗口。
• 删除旧配置前确认没有 Pod、Job 或回滚版本仍引用。