Alauda DevOps Connectors Docs
  • 简体中文

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

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

    目录

    常见问题概述检查 CSI 卷配置检查 Pod 事件查找生成的 OCI 配置文件检查 OCI 客户端配置内容registry-configbuildkitd 配置高级故障排除CSI 驱动日志代理服务日志其他资源

    常见问题概述

    问题可能原因影响
    卷挂载失败CSI 配置错误，驱动不可用工作负载无法启动
    配置未找到挂载路径错误，缺少卷镜像拉取/推送操作失败
    认证失败令牌问题，配置错误注册表访问被拒绝

    检查 CSI 卷配置

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

    volumes:
- name: registry-config
  csi:
    readOnly: true
    driver: connectors-csi
    volumeAttributes:
      connector.name: "<connector-name>"
      configuration.names: "registry-config"

    常见配置选项：

    配置名称描述使用场景
    registry-config标准 OCI 客户端（如 buildkit、buildah）认证配置通用容器操作
    buildkitdBuildKit 守护进程配置基于 BuildKit 的操作

    常见配置问题：

    问题表现解决方案
    驱动名称错误出现 MountVolume.SetUp failed 错误将 driver 精确设置为 connectors-csi
    未找到 Connector出现 could not get connector 错误确保 Connector 存在于相同命名空间
    配置名称错误未生成配置设置正确的 configuration.names 值
    命名空间不匹配卷挂载失败确保 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

    检查 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 "registry-config" :
  rpc error: code = NotFound desc = connector "oci-registry" not found

    解决方案：创建 Connector 或修正卷属性中的 Connector 名称。

    查找生成的 OCI 配置文件

    定位配置文件：

    # 针对 registry-config
kubectl exec <pod-name> -n <namespace> -- cat {YOUR-MOUNT-PATH}/config.json

# 针对 buildkitd
kubectl exec <pod-name> -n <namespace> -- cat {YOUR-MOUNT-PATH}/buildkitd.toml

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

    1. 卷是否成功挂载
    2. CSI 驱动是否健康
    3. ServiceAccount 是否有权限
    4. Connector 是否处于 Ready 状态
    5. 挂载路径是否与容器用户预期路径匹配

    检查 OCI 客户端配置内容

    registry-config

    查看生成的 config.json 文件：

    kubectl exec <pod-name> -n <namespace> -- cat {YOUR-MOUNT-PATH}/config.json

    预期配置内容：

    {
  "auths": {
    "c-<connector-name>.<namespace>.svc.cluster.local": {
      "auth": "<base64-encoded-token>"
    }
  }
}

    buildkitd 配置

    查看生成的 buildkitd.toml 文件：

    kubectl exec <pod-name> -n <namespace> -- cat {YOUR-MOUNT-PATH}/buildkitd.toml

    预期配置内容：

    insecure-entitlements = [ "network.host", "security.insecure" ]
[registry."c-<connector-name>.<namespace>.svc.cluster.local"]
  http = true

    高级故障排除

    CSI 驱动日志

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

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

    代理服务日志

    查看代理服务日志以排查认证或访问问题：

    kubectl logs -n connectors-system -l app.kubernetes.io/name=connectors-proxy

    其他资源