Alauda DevOps Connectors Docs
简体中文

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 存在于相同的命名空间中
  • configuration.names 设置为 gitconfig 用于 Git 操作
  • 确保 connector 与 pod 在同一命名空间

如何验证：

# 检查 connector 是否存在
kubectl get connector <connector-name> -n <namespace>

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

# 检查 CSI 驱动是否可用
kubectl get pods -n connectors-system -l app.kubernetes.io/name=connectors-csi

验证卷挂载

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

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

重要注意事项：

  • 挂载路径必须与运行 Git 命令的用户的主目录匹配
  • 对于 Git 配置，文件总是创建在 <mountPath>/.gitconfig

查找正确的主目录：

# 查看容器内用户的主目录
kubectl exec <pod-name> -n <namespace> -- env | grep HOME

# 根据容器镜像常见路径：
# - root 用户：/root/
# - git 用户：/home/git/
# - 非 root 用户：/home/<username>/

验证挂载是否成功：

# 检查卷是否正确挂载
kubectl describe pod <pod-name> -n <namespace> | grep -A 5 "Mounts:"

# 查看 pod 描述中的挂载事件
kubectl describe pod <pod-name> -n <namespace> | grep -A 10 "Events:"

检查 Pod 事件

查看 Pod 事件以排查挂载相关问题：

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

常见错误信息及解决方案：

错误信息原因解决方案
MountVolume.SetUp failedCSI 驱动问题或配置错误检查驱动健康状态和卷配置
waiting for ephemeral inline CSI driverCSI 驱动未就绪或未找到验证 CSI 驱动 Pod 是否运行
connector not foundConnector 不存在或命名空间错误创建 connector 或修正命名空间
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 配置文件：

# 检查预期路径下是否存在文件
kubectl exec <pod-name> -n <namespace> -- ls -la /path/to/home/.gitconfig

如果未找到配置文件，请检查：

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

检查 Git 配置内容

查看生成的 .gitconfig 文件内容：

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

预期配置内容：

  1. 带有认证令牌的 HTTP 头：

    [http]
    extraHeader = Authorization: Basic <token>

  2. URL 重写规则：

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

高级故障排除

CSI 驱动日志

查看 CSI 驱动日志以获取详细错误信息：

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"

其他资源