k8s-csi-s3 排障笔记PVC Pending 与挂载失败的 8 个定位动作【免费下载链接】k8s-csi-s3GeeseFS-based CSI for mounting S3 buckets as PersistentVolumes项目地址: https://gitcode.com/gh_mirrors/k8s/k8s-csi-s3k8s-csi-s3 是一个 Kubernetes CSI 驱动把 S3 兼容的对象存储AWS S3、Yandex Object Storage 等动态挂载为持久卷。这份笔记面向负责存储的运维和后端同学把 PVC Pending 排查、k8s S3 挂载失败这类 CSI 驱动部署故障从基础体检到 geesefs 配置与版本兼容拆成 8 个可执行动作。按顺序核对即可定位问题不必逐台节点翻日志。排障前先过的三道体检挂载传播是否可用驱动依赖 FUSE 卷节点必须开启挂载传播kubelet 的MountPropagationDocker daemon 也要允许共享挂载。这一层断了后面所有挂载都会失败日志里往往只剩笼统的超时。特权容器是否放行csi-s3 节点插件需要特权模式运行。节点收紧了 Pod 安全策略或禁止特权容器时驱动 Pod 起不来挂载无从谈起。日志在哪看组件分两组——节点插件labelappcsi-s3容器名csi-s3与 provisionerlabelappcsi-provisioner-s3。PVC 侧问题看 provisioner挂载侧问题看节点插件先分清归属再读日志。PVC 卡在 Pending按顺序核对 4 项配置PVC 长时间停在 Pending 时按下面顺序核对前一项排除再看下一项核对项看哪里常见错误凭证Secret 中的accessKeyID、secretAccessKey密钥写错或过期与 endpoint 不配套端点Secret 中的endpointAWS 应为https://s3.region.amazonaws.com形式存储类StorageClass 的mounter、options挂载器拼错geesefs 配置缺失命名空间Secret 所在 ns 与 StorageClass 声明声明指向 kube-systemSecret 却放在别处配套命令kubectl get pvc # 确认 PVC 卡在 Pending kubectl describe pvc pvc-name # Events 段会给出 provisioner 报错 kubectl logs -l appcsi-provisioner-s3 -c csi-s3 # 看 provisioner 侧完整日志Pod 挂载异常从日志到挂载点先拿节点插件日志再确认挂载是否真正落到容器内kubectl logs -l appcsi-s3 -c csi-s3 # 节点插件的挂载过程日志 kubectl exec -ti pod-name -- mount | grep fuse # 容器内应能看到对应 fuse 挂载挂载器mounter直接决定性能与兼容表现挂载器POSIX 兼容表现特征适合场景geesefs最好大小文件性能均衡生产环境默认选择s3fs较好大文件优秀、小文件慢以大文件为主的负载rclone较差性能一般临时验证不建议生产挂载器与选项的组合参考 deploy/kubernetes/examples/storageclass.yaml。数据与权限Secret、命名空间与存储桶Secret 的最小可用形态对照 deploy/kubernetes/examples/secret.yamlstringData: accessKeyID: YOUR_ACCESS_KEY_ID secretAccessKey: YOUR_SECRET_ACCESS_KEY endpoint: https://storage.yandexcloud.net命名空间有三处必须对齐Secret 自身的命名空间、StorageClass 里的csi.storage.k8s.io/*-secret-namespace参数、驱动实际查找的位置。三者默认都落在kube-system手动挪动 Secret 时最容易漏掉 StorageClass 那一处。存储桶分两种供给方式。动态创建失败时依次查 S3 用户是否有权建桶、桶名是否符合 S3 命名规则、区域设置是否正确。复用已有桶更简单在 StorageClass 的parameters里写bucket: your-existing-bucket-name。预建的桶或桶内前缀走静态供应示例见 deploy/kubernetes/examples/pvc-manual.yaml。权限侧坚持最小权限原则S3 用户只授予所需桶的读写权限避免宽泛的 List 或建桶授权。网络与端点连通性从集群内起临时容器直连端点判断问题在集群网络还是 S3 侧kubectl run -it --rm debug --imagebusybox --restartNever -- wget -O- endpoint-url连接不通时逐层排除代理设置、集群网络策略、节点防火墙以及 S3 服务侧的访问白名单。自签名证书或私有 S3 场景下先确保证书链受信任禁用 TLS 验证仅限测试环境。性能参数与版本兼容geesefs 的主要调优参数放在 StorageClass 的options里options: --memory-limit 1000 --dir-mode 0777 --file-mode 0666 --no-systemd--memory-limit控制内存缓存上限按节点内存设定--no-systemd用于规避升级或重启时挂载点断开的已知问题。另有两个方向按工作负载调整 geesefs 缓存大小与并发连接数并为网络波动配置重试。版本层面驱动要求 Kubernetes 1.17 及以上CSI 驱动版本需与集群版本匹配。从 v0.35.5 或更早版本升级时旧 attacher 资源要手动删除再重新应用新的部署文件否则残留的 attacher 会干扰挂载流程。 一键体检#!/bin/bash echo csi-s3 快速体检 echo 1. 驱动组件 Pod 状态 kubectl get pods -A -l appcsi-s3 echo 2. 全局 PVC 状态关注 Pending kubectl get pvc -A | grep -E csi-s3|Pending echo 3. 最近事件 kubectl get events --sort-by.lastTimestamp | tail -20 echo 4. provisioner 最近 50 行日志 kubectl logs -l appcsi-provisioner-s3 -c csi-s3 --tail50 echo 5. 节点插件最近 50 行日志 kubectl logs -l appcsi-s3 -c csi-s3 --tail50 上生产前检查清单挂载器默认选geesefsrclone 只用于临时验证。--memory-limit按节点实际内存设置防止 FUSE 进程内存失控。生产默认走 systemd 挂载模式--no-systemd仅在需要规避升级或重启断挂时启用。S3 用户按最小权限原则授权只覆盖所需桶与必要操作。Secret 交给 Kubernetes Secret 或外部密钥管理系统不走明文配置。网络层限制对 S3 端点的访问收敛暴露面。按负载类型调整 geesefs 缓存与并发连接数并配置重试策略。PVC 状态与挂载点健康纳入监控告警。按这套顺序走下来PVC Pending、k8s S3 挂载失败、CSI 驱动部署故障这几类问题大多能在前几节内定位。更深层的行为以项目文档为准README.md 有完整的故障排除章节deploy/kubernetes/examples/ 下是可对照的官方示例。【免费下载链接】k8s-csi-s3GeeseFS-based CSI for mounting S3 buckets as PersistentVolumes项目地址: https://gitcode.com/gh_mirrors/k8s/k8s-csi-s3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 k8s-csi-s3 排障笔记：PVC Pending 与挂载失败的 8 个定位动作
k8s-csi-s3 排障笔记PVC Pending 与挂载失败的 8 个定位动作【免费下载链接】k8s-csi-s3GeeseFS-based CSI for mounting S3 buckets as PersistentVolumes项目地址: https://gitcode.com/gh_mirrors/k8s/k8s-csi-s3k8s-csi-s3 是一个 Kubernetes CSI 驱动把 S3 兼容的对象存储AWS S3、Yandex Object Storage 等动态挂载为持久卷。这份笔记面向负责存储的运维和后端同学把 PVC Pending 排查、k8s S3 挂载失败这类 CSI 驱动部署故障从基础体检到 geesefs 配置与版本兼容拆成 8 个可执行动作。按顺序核对即可定位问题不必逐台节点翻日志。排障前先过的三道体检挂载传播是否可用驱动依赖 FUSE 卷节点必须开启挂载传播kubelet 的MountPropagationDocker daemon 也要允许共享挂载。这一层断了后面所有挂载都会失败日志里往往只剩笼统的超时。特权容器是否放行csi-s3 节点插件需要特权模式运行。节点收紧了 Pod 安全策略或禁止特权容器时驱动 Pod 起不来挂载无从谈起。日志在哪看组件分两组——节点插件labelappcsi-s3容器名csi-s3与 provisionerlabelappcsi-provisioner-s3。PVC 侧问题看 provisioner挂载侧问题看节点插件先分清归属再读日志。PVC 卡在 Pending按顺序核对 4 项配置PVC 长时间停在 Pending 时按下面顺序核对前一项排除再看下一项核对项看哪里常见错误凭证Secret 中的accessKeyID、secretAccessKey密钥写错或过期与 endpoint 不配套端点Secret 中的endpointAWS 应为https://s3.region.amazonaws.com形式存储类StorageClass 的mounter、options挂载器拼错geesefs 配置缺失命名空间Secret 所在 ns 与 StorageClass 声明声明指向 kube-systemSecret 却放在别处配套命令kubectl get pvc # 确认 PVC 卡在 Pending kubectl describe pvc pvc-name # Events 段会给出 provisioner 报错 kubectl logs -l appcsi-provisioner-s3 -c csi-s3 # 看 provisioner 侧完整日志Pod 挂载异常从日志到挂载点先拿节点插件日志再确认挂载是否真正落到容器内kubectl logs -l appcsi-s3 -c csi-s3 # 节点插件的挂载过程日志 kubectl exec -ti pod-name -- mount | grep fuse # 容器内应能看到对应 fuse 挂载挂载器mounter直接决定性能与兼容表现挂载器POSIX 兼容表现特征适合场景geesefs最好大小文件性能均衡生产环境默认选择s3fs较好大文件优秀、小文件慢以大文件为主的负载rclone较差性能一般临时验证不建议生产挂载器与选项的组合参考 deploy/kubernetes/examples/storageclass.yaml。数据与权限Secret、命名空间与存储桶Secret 的最小可用形态对照 deploy/kubernetes/examples/secret.yamlstringData: accessKeyID: YOUR_ACCESS_KEY_ID secretAccessKey: YOUR_SECRET_ACCESS_KEY endpoint: https://storage.yandexcloud.net命名空间有三处必须对齐Secret 自身的命名空间、StorageClass 里的csi.storage.k8s.io/*-secret-namespace参数、驱动实际查找的位置。三者默认都落在kube-system手动挪动 Secret 时最容易漏掉 StorageClass 那一处。存储桶分两种供给方式。动态创建失败时依次查 S3 用户是否有权建桶、桶名是否符合 S3 命名规则、区域设置是否正确。复用已有桶更简单在 StorageClass 的parameters里写bucket: your-existing-bucket-name。预建的桶或桶内前缀走静态供应示例见 deploy/kubernetes/examples/pvc-manual.yaml。权限侧坚持最小权限原则S3 用户只授予所需桶的读写权限避免宽泛的 List 或建桶授权。网络与端点连通性从集群内起临时容器直连端点判断问题在集群网络还是 S3 侧kubectl run -it --rm debug --imagebusybox --restartNever -- wget -O- endpoint-url连接不通时逐层排除代理设置、集群网络策略、节点防火墙以及 S3 服务侧的访问白名单。自签名证书或私有 S3 场景下先确保证书链受信任禁用 TLS 验证仅限测试环境。性能参数与版本兼容geesefs 的主要调优参数放在 StorageClass 的options里options: --memory-limit 1000 --dir-mode 0777 --file-mode 0666 --no-systemd--memory-limit控制内存缓存上限按节点内存设定--no-systemd用于规避升级或重启时挂载点断开的已知问题。另有两个方向按工作负载调整 geesefs 缓存大小与并发连接数并为网络波动配置重试。版本层面驱动要求 Kubernetes 1.17 及以上CSI 驱动版本需与集群版本匹配。从 v0.35.5 或更早版本升级时旧 attacher 资源要手动删除再重新应用新的部署文件否则残留的 attacher 会干扰挂载流程。 一键体检#!/bin/bash echo csi-s3 快速体检 echo 1. 驱动组件 Pod 状态 kubectl get pods -A -l appcsi-s3 echo 2. 全局 PVC 状态关注 Pending kubectl get pvc -A | grep -E csi-s3|Pending echo 3. 最近事件 kubectl get events --sort-by.lastTimestamp | tail -20 echo 4. provisioner 最近 50 行日志 kubectl logs -l appcsi-provisioner-s3 -c csi-s3 --tail50 echo 5. 节点插件最近 50 行日志 kubectl logs -l appcsi-s3 -c csi-s3 --tail50 上生产前检查清单挂载器默认选geesefsrclone 只用于临时验证。--memory-limit按节点实际内存设置防止 FUSE 进程内存失控。生产默认走 systemd 挂载模式--no-systemd仅在需要规避升级或重启断挂时启用。S3 用户按最小权限原则授权只覆盖所需桶与必要操作。Secret 交给 Kubernetes Secret 或外部密钥管理系统不走明文配置。网络层限制对 S3 端点的访问收敛暴露面。按负载类型调整 geesefs 缓存与并发连接数并配置重试策略。PVC 状态与挂载点健康纳入监控告警。按这套顺序走下来PVC Pending、k8s S3 挂载失败、CSI 驱动部署故障这几类问题大多能在前几节内定位。更深层的行为以项目文档为准README.md 有完整的故障排除章节deploy/kubernetes/examples/ 下是可对照的官方示例。【免费下载链接】k8s-csi-s3GeeseFS-based CSI for mounting S3 buckets as PersistentVolumes项目地址: https://gitcode.com/gh_mirrors/k8s/k8s-csi-s3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考