Alauda DevOps Connectors Docs
  • 简体中文

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

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

    目录

    常见问题概览检查 CSI 卷配置验证卷挂载查看 Pod 事件查找生成的 OCI 配置文件检查 OCI 客户端配置内容docker-configbuildkitd 配置高级故障排除CSI 驱动日志代理服务日志使用诊断 Pod 进行测试其他资源

    常见问题概览

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

    检查 CSI 卷配置

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

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

    常见配置选项：

    配置名称描述使用场景
    docker-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

    验证卷挂载

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

    volumeMounts:
- name: docker-config
  mountPath: "/root/.docker"  # 针对 docker-config

    不同配置的常见挂载路径：

    配置名称推荐挂载路径描述
    docker-config/root/.docker 或 $HOME/.dockerOCI 客户端如 buildkit、buildah 的认证配置目录
    buildkitd/etc/buildkitBuildKit 守护进程配置目录

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

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

    查找生成的 OCI 配置文件

    定位配置文件：

    # 针对 docker-config
kubectl exec <pod-name> -n <namespace> -- cat /root/.docker/config.json

# 针对 buildkitd
kubectl exec <pod-name> -n <namespace> -- cat /etc/buildkit/buildkitd.toml

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

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

    检查 OCI 客户端配置内容

    docker-config

    查看生成的 config.json 文件：

    kubectl exec <pod-name> -n <namespace> -- cat /root/.docker/config.json

    预期配置内容：

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

    buildkitd 配置

    查看生成的 buildkitd.toml 文件：

    kubectl exec <pod-name> -n <namespace> -- cat /etc/buildkit/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

    使用诊断 Pod 进行测试

    创建诊断 Pod 测试 OCI 功能：

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

    其他资源