Alauda DevOps Connectors Docs
简体中文

CSI 工作负载配置故障排除

本指南提供了详细步骤，帮助诊断和解决在工作负载中挂载配置时与 Connectors CSI 驱动程序相关的常见问题。

目录

常见问题概述

问题潜在原因影响
卷挂载失败错误的 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
  • 确保连接器存在于同一命名空间
  • 将 configuration.names 设置为 gitconfig 用于 Git 操作
  • 确保连接器与 Pod 在同一命名空间中

如何验证：

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

# 验证连接器是否为 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 found连接器不存在或命名空间错误创建连接器或修复命名空间
failed to generate configuration模板渲染错误检查连接器和 ConnectorClass 状态

示例错误及解决办法：

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

解决方案: 创建连接器或更正卷属性中的连接器名称。

查找生成的 Git 配置

定位 Git 配置文件：

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

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

  1. 卷挂载是否成功
  2. CSI 驱动程序是否正常
  3. ServiceAccount 是否具备权限
  4. 连接器是否处于 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"

其他资源