ConfigMap 挂载踩坑指南

ConfigMap 里的"文件"，本质是符号链接，不是真文件。

ConfigMap 挂载的底层结构

当 ConfigMap 挂载到 Pod 的目录后，实际的文件系统结构如下：

/app/config/
├── application.properties -> ..data/application.properties
├── logback.xml -> ..data/logback.xml
└── ..data/
    ├── application.properties
    └── logback.xml

目录中的每个"文件"都是一个符号链接，指向 ..data 目录下的真实文件。这种设计是为了支持 ConfigMap 的原子热更新：

1. 更新 ConfigMap 内容时，K8s 创建一个新的 ..data 目录存放新文件
2. 瞬间切换符号链接指向（旧 ..data → 新 ..data）
3. 整个过程原子完成，无需重启 Pod

坑点一：ConfigMap 挂载默认只读

现象： open /app/config/license_token: read-only file system

ConfigMap 挂载是只读的——这是 K8s 的设计逻辑，ConfigMap 属于"静态资源"，防止误改。

标准解决模式：initContainer + emptyDir

当目录既要读配置、又要允许程序写文件时：

1. emptyDir — 临时可写目录
2. initContainer — 把 ConfigMap 内容复制到 emptyDir
3. 主容器 — 挂载 emptyDir，既读配置也写文件

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      initContainers:
        - command:
            - sh
            - "-c"
            - "cp -rL /config/. /app/config/ && chown -R 1001:1001 /app/config"
          image: "busybox:1.32"
          name: init
          volumeMounts:
            - mountPath: /config
              name: app-config
            - mountPath: /app/config
              name: config-tmp
      containers:
        - volumeMounts:
            - mountPath: /app/config
              name: config-tmp
      volumes:
        - name: app-config
          configMap:
            name: app-config
        - name: config-tmp
          emptyDir: {}

链路：ConfigMap → initContainer（复制）→ emptyDir → 主容器

替代方案：subPath（不推荐）

ConfigMap 也支持 subPath 方式挂载单个文件，但会导致不能热更新（Pod 必须重启才能看到新配置），且无法用于多文件目录：

volumeMounts:
  - name: app-config
    mountPath: /app/config/application.properties
    subPath: application.properties

subPath 挂载后的文件是普通文件（不是符号链接），可以写入，但写操作不会更新 ConfigMap，不会影响其他 Pod。

坑点二：cp 复制符号链接而非内容

现象： Pod 内 ls 能看到文件，但 cat 报错 No such file or directory。

这是因为 ConfigMap 挂载的文件都是符号链接，而 cp 命令默认复制"链接本身"，不是链接指向的内容。复制到 emptyDir 后，链接的目标 ..data 目录在 emptyDir 中不存在，所以文件"看得见、摸不着"。

正确复制命令

# ❌ 错误：复制的是符号链接本身
cp -r /config/* /app/config/

# ✅ 正确：跟随符号链接，复制真实文件内容
cp -rL /config/. /app/config/

关键参数：

• -L / --dereference — 跟随符号链接，复制真实内容
• /config/. — 代替 /config/*，避免遗漏隐藏文件
• chown -R <uid>:<gid> /app/config — 调整权限，使应用容器能写入

排查命令速查

# 查看文件是否为符号链接
ls -l /app/config/
# lrwxrwxrwx ... application.properties -> ..data/application.properties

# 查看符号链接指向的真实内容（跟随链接读取）
readlink -f /app/config/application.properties

# 查看完整挂载信息
kubectl exec <pod-name> -- mount | grep config

# 查看 ConfigMap 是否存在
kubectl get configmap <name> -n <namespace>

# 查看 Pod 中 ConfigMap 是否挂载成功
kubectl describe pod <pod-name> -n <namespace>
# 关注 Volumes 段：检查 configMap 名称和挂载路径

关联页面