Kubernetes中如何将容器多目录挂载至不同Persistent Volume？

需求背景 #

容器内存在如下目录结构：

• /usr/src/app/upload/library
• /usr/src/app/upload/encoded-video
• /usr/src/app/upload/profile
• /usr/src/app/upload/thumbs

需要实现：

• 将/usr/src/app/upload/library挂载到一个Kubernetes PV（对应PVC：pvc-nfs-library）
• 将/usr/src/app/upload/encoded-video、/usr/src/app/upload/profile、/usr/src/app/upload/thumbs挂载到另一个Kubernetes PV（对应PVC：pvc-nfs-generated-media）

之前尝试多种带/不带subPath的配置，均触发containerconfigerror，错误信息为Failed to prepare subPath for volumeMount，错误配置示例如下：

错误配置1：重复挂载同一容器路径 #

volumeMounts:
  - name: library
    mountPath: /usr/src/app/upload
    subPath: library
  - name: generated-media
    mountPath: /usr/src/app/upload
    subPath: encoded-video
  - name: generated-media
    mountPath: /usr/src/app/upload
    subPath: profile
  - name: generated-media
    mountPath: /usr/src/app/upload
    subPath: thumbs
volumes:
  - name: library
    persistentVolumeClaim:
      claimName: pvc-nfs-library
  - name: generated-media
    persistentVolumeClaim:
      claimName: pvc-nfs-generated-media

错误配置2：subPath拼写错误 #

volumeMounts:
  - name: library
    mountPath: /usr/src/app/upload/library
    subPath: library
  - name: generated-media
    mountPath: /usr/src/app/upload/encoded-video
    subPath: encoded-video
  - name: generated-media
    mountPath: /usr/src/app/upload/profile
    subPath: profile
  - name: generated-media
    mountPath: /usr/src/app/upload/thumbs
    subPath: encoded-video  # 此处应为thumbs，拼写错误
volumes:
  - name: library
    persistentVolumeClaim:
      claimName: pvc-nfs-library
  - name: generated-media
    persistentVolumeClaim:
      claimName: pvc-nfs-generated-media

错误配置3：未使用subPath导致挂载覆盖 #

volumeMounts:
  - name: library
    mountPath: /usr/src/app/upload/library
  - name: generated-media
    mountPath: /usr/src/app/upload/encoded-video
  - name: generated-media
    mountPath: /usr/src/app/upload/profile
  - name: generated-media
    mountPath: /usr/src/app/upload/thumbs
volumes:
  - name: library
    persistentVolumeClaim:
      claimName: pvc-nfs-library
  - name: generated-media
    persistentVolumeClaim:
      claimName: pvc-nfs-generated-media

需求可行性分析 #

这个需求完全可行，不需要为每个目录单独创建PV。只需要利用subPath将单个PV的不同子目录映射到容器的对应路径即可，之前的报错都是配置逻辑错误导致的。

正确配置方案 #

核心要点 #

1. 每个volumeMount的mountPath指向容器内的具体目标目录，避免重复挂载同一路径
2. subPath对应PV存储后端中提前创建好的子目录
3. 确保PV存储后端（比如NFS服务器）存在所有需要的子目录

正确配置示例 #

volumeMounts:
  # 挂载library PV的library子目录到容器的/library路径
  - name: library
    mountPath: /usr/src/app/upload/library
    subPath: library
  # 挂载generated-media PV的encoded-video子目录到容器的/encoded-video路径
  - name: generated-media
    mountPath: /usr/src/app/upload/encoded-video
    subPath: encoded-video
  # 挂载generated-media PV的profile子目录到容器的/profile路径
  - name: generated-media
    mountPath: /usr/src/app/upload/profile
    subPath: profile
  # 挂载generated-media PV的thumbs子目录到容器的/thumbs路径
  - name: generated-media
    mountPath: /usr/src/app/upload/thumbs
    subPath: thumbs
volumes:
  - name: library
    persistentVolumeClaim:
      claimName: pvc-nfs-library
  - name: generated-media
    persistentVolumeClaim:
      claimName: pvc-nfs-generated-media

关键注意事项 #

• 提前创建存储目录：必须在PV对应的存储后端手动创建所有subPath指定的目录，比如：
  • 在pvc-nfs-library对应的NFS路径下创建library目录
  • 在pvc-nfs-generated-media对应的NFS路径下创建encoded-video、profile、thumbs目录
• 避免挂载冲突：不要将多个volumeMount指向容器内的同一个路径，这会导致挂载覆盖或配置错误
• 动态PV适配：如果使用动态PV provisioner，部分厂商的provisioner支持自动创建subPath目录，但大部分需要手动提前创建

内容的提问来源于stack exchange，提问作者theautomation