CSI 工作负载配置故障排查

本指南提供了详细步骤,用于诊断并解决在工作负载中挂载配置时 Connectors CSI Driver 的常见问题。

常见问题概览

问题可能原因影响
卷挂载失败CSI 配置不正确、驱动不可用工作负载无法启动
未找到 Git 配置挂载路径错误、缺少卷Git 操作失败
身份验证失败令牌问题、配置错误拒绝访问仓库

检查 CSI 卷配置

验证工作负载 YAML 中的 CSI 卷配置:

volumes:
- name: gitconfig
  csi:
    readOnly: true
    driver: connectors-csi
    volumeAttributes:
      connector.name: "<connector-name>"
      configuration.names: "gitconfig"
  • 将 driver 精确设置为 connectors-csi
  • 确保 connector 存在于同一 namespace 中
  • 对于 Git 操作,将 configuration.names 设置为 gitconfig
  • 确保 connector 与 Pod 位于同一 namespace 中

如何验证:

# Check if the connector exists
kubectl get connector <connector-name> -n <namespace>

# Verify the connector is Ready
kubectl get connector <connector-name> -n <namespace> -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}'

# Check CSI driver availability
kubectl get pods -n connectors-system -l app.kubernetes.io/name=connectors-csi

验证卷挂载

检查卷挂载配置是否正确:

volumeMounts:
- name: gitconfig
  mountPath: "/path/to/user/home/"

重要注意事项:

  • 挂载路径必须与运行 Git 命令的用户 home 目录一致
  • 对于 Git 配置,该文件始终会创建在 <mountPath>/.gitconfig

查找正确的 home 目录:

# Check the user's home directory in the container
kubectl exec <pod-name> -n <namespace> -- env | grep HOME

# Common paths depending on container image:
# - For root user: /root/
# - For git user: /home/git/
# - For non-root users: /home/<username>/

验证挂载是否成功:

# Check if volumes are properly mounted
kubectl describe pod <pod-name> -n <namespace> | grep -A 5 "Mounts:"

# Look for mount events in the pod description
kubectl describe pod <pod-name> -n <namespace> | grep -A 10 "Events:"

检查 Pod 事件

检查 Pod 事件中是否存在与挂载相关的问题:

kubectl describe pod <pod-name> -n <namespace>

常见错误消息及解决方案:

错误消息原因解决方案
MountVolume.SetUp failedCSI driver 问题或配置错误检查 driver 健康状态和卷配置
waiting for ephemeral inline CSI driverCSI driver 未就绪或未找到验证 CSI driver Pod 正在运行
connector not foundconnector 不存在或 namespace 错误创建 connector 或修正 namespace
failed to generate configuration模板渲染错误检查 connector 和 ConnectorClass 状态

错误示例及处理:

  Warning  FailedMount  3m (x5 over 5m)  kubelet  MountVolume.SetUp failed for volume "gitconfig" :
  rpc error: code = NotFound desc = connector "git-github" not found

解决方案:创建 connector,或更正卷属性中的 connector 名称。

查找生成的 Git 配置

定位 Git 配置文件:

# Check if the expected path has the file
kubectl exec <pod-name> -n <namespace> -- ls -la /path/to/home/.gitconfig

如果未找到配置文件,请检查:

  1. 卷挂载是否成功
  2. CSI driver 是否健康
  3. ServiceAccount 是否具有权限
  4. connector 是否处于 Ready 状态

检查 Git 配置内容

检查生成的 .gitconfig 文件内容:

kubectl exec <pod-name> -n <namespace> -- cat /path/to/.gitconfig

期望的配置元素:

  1. 带身份验证令牌的 HTTP header,作用域限定为代理地址:

    [http "http://c-<connector-name>.<connector-namespace>.svc"]
        extraHeader = Authorization: Basic <token>
  2. URL 重写规则:

    [url "http://c-<connector-name>.<connector-namespace>.svc"]
        insteadOf = <original-git-url>

高级故障排查

CSI Driver 日志

检查 CSI driver 日志以获取更详细的错误信息:

kubectl logs -n connectors-system -l app.kubernetes.io/name=connectors-csi -c csi-driver

使用诊断 Pod 进行测试

创建一个诊断 Pod 来测试 CSI 功能:

apiVersion: v1
kind: Pod
metadata:
  name: csi-debug-pod
  namespace: <namespace>
spec:
  containers:
  - name: debug
    image: alpine
    command: ["sleep", "3600"]
    volumeMounts:
    - name: gitconfig
      mountPath: "/root/"
  volumes:
  - name: gitconfig
    csi:
      driver: connectors-csi
      readOnly: true
      volumeAttributes:
        connector.name: "<connector-name>"
        configuration.names: "gitconfig"

其他资源