Alauda DevOps Connectors Docs
  • 简体中文

    • CSI 工作负载配置故障排除

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

    目录

    常见问题概览检查 CSI 卷配置验证卷挂载检查 Pod 事件查找生成的 Git 配置检查 Git 配置内容高级故障排除CSI 驱动日志使用诊断 Pod 进行测试其他资源

    常见问题概览

    问题可能原因影响
    卷挂载失败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"

    其他资源