K8s ConfigMap 与 Secret¶

一句话概述：ConfigMap 存储非敏感配置（如数据库地址、功能开关），Secret 存储敏感信息（如密码、API Key），两者都能注入到 Pod 中作为环境变量或挂载为文件。

核心知识点¶

概念	白话解释
ConfigMap	配置映射 = 存储配置信息的键值对（明文）
Secret	密钥 = 存储敏感信息的键值对（Base64 编码）
envFrom	把 ConfigMap/Secret 的所有键值对注入为环境变量
volumeMount	把 ConfigMap/Secret 挂载为文件
Opaque	默认 Secret 类型（通用）
Immutable	不可变 = 创建后不能修改（性能更好）

基本使用¶

1. ConfigMap¶

# 命令行创建
kubectl create configmap app-config \
  --from-literal=DATABASE_HOST=db.example.com \
  --from-literal=DATABASE_PORT=5432 \
  --from-literal=LOG_LEVEL=info
# 从键值对创建 ConfigMap

kubectl create configmap nginx-conf --from-file=nginx.conf
# 从文件创建 ConfigMap

# configmap.yaml — YAML 方式创建
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:  # 键值对数据
  DATABASE_HOST: "db.example.com"  # 数据库地址
  DATABASE_PORT: "5432"  # 数据库端口
  LOG_LEVEL: "info"  # 日志级别
  config.yaml: |  # 也可以存完整的配置文件
    server:
      port: 8080
      host: 0.0.0.0
    database:
      pool_size: 10

2. Secret¶

# 命令行创建
kubectl create secret generic db-secret \
  --from-literal=username=admin \
  --from-literal=password=s3cret123
# 值会自动 Base64 编码

# secret.yaml — YAML 方式（值需要 Base64 编码）
apiVersion: v1
kind: Secret
metadata:
  name: db-secret
type: Opaque  # 通用类型
data:  # Base64 编码的值
  username: YWRtaW4=  # echo -n "admin" | base64
  password: czNjcmV0MTIz  # echo -n "s3cret123" | base64
---
# 用 stringData 可以直接写明文（K8s 自动编码）
apiVersion: v1
kind: Secret
metadata:
  name: db-secret-v2
type: Opaque
stringData:  # 明文，K8s 自动 Base64 编码
  username: admin
  password: s3cret123

3. 在 Pod 中使用¶

apiVersion: v1
kind: Pod
metadata:
  name: myapp
spec:
  containers:
    - name: app
      image: myapp:latest

      # 方式1：单个环境变量引用
      env:
        - name: DB_HOST  # 环境变量名
          valueFrom:
            configMapKeyRef:
              name: app-config  # ConfigMap 名
              key: DATABASE_HOST  # 键名
        - name: DB_PASSWORD
          valueFrom:
            secretKeyRef:
              name: db-secret  # Secret 名
              key: password  # 键名

      # 方式2：批量注入所有键值对
      envFrom:
        - configMapRef:
            name: app-config  # 注入 ConfigMap 所有键值对
        - secretRef:
            name: db-secret  # 注入 Secret 所有键值对

      # 方式3：挂载为文件
      volumeMounts:
        - name: config-volume
          mountPath: /etc/config  # 挂载路径
          readOnly: true
        - name: secret-volume
          mountPath: /etc/secrets
          readOnly: true

  volumes:
    - name: config-volume
      configMap:
        name: app-config  # 每个键变成一个文件
    - name: secret-volume
      secret:
        secretName: db-secret
        defaultMode: 0400  # 文件权限（只有 owner 可读）

高级用法¶

不可变 ConfigMap/Secret¶

apiVersion: v1
kind: ConfigMap
metadata:
  name: immutable-config
immutable: true  # 设为不可变（创建后不能修改）
data:
  VERSION: "1.0"
# 好处：K8s 不用持续监听变化，减轻 API Server 压力

TLS Secret¶

# 创建 TLS Secret（HTTPS 证书）
kubectl create secret tls tls-secret \
  --cert=path/to/cert.pem \
  --key=path/to/key.pem

Docker Registry Secret¶

# 创建镜像仓库认证 Secret
kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=user \
  --docker-password=pass

常见报错¶

报错信息	原因	解决方法
`configmap "xxx" not found`	ConfigMap 不存在	先创建 ConfigMap
`secret "xxx" not found`	Secret 不存在	先创建 Secret
`invalid base64 data`	Base64 编码错误	用 `echo -n "value" \| base64` 正确编码
`Forbidden: field is immutable`	修改了不可变资源	删除后重新创建

速查表¶

# === ConfigMap ===
kubectl create configmap <n> --from-literal=k=v  # 从键值对创建
kubectl create configmap <n> --from-file=f        # 从文件创建
kubectl get configmap        # 列出
kubectl describe configmap <n>  # 查看详情
kubectl delete configmap <n>    # 删除

# === Secret ===
kubectl create secret generic <n> --from-literal=k=v  # 创建
kubectl get secrets          # 列出
kubectl get secret <n> -o yaml  # 查看（Base64）
kubectl get secret <n> -o jsonpath='{.data.key}' | base64 -d  # 解码查看

# === ConfigMap vs Secret ===
# ConfigMap: 明文存储，适合非敏感配置
# Secret:    Base64 编码，适合密码/密钥
# 两者都可以：环境变量注入、文件挂载
# Secret 注意：Base64 不是加密！生产环境建议启用 etcd 加密

参考：K8s ConfigMap | K8s Secret | 更新于 2026 年