Alauda DevOps Connectors Docs
简体中文

CSI 工作负载配置故障排除

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

目录

常见问题概览

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

检查 CSI 卷配置

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

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

常见配置选项：

配置名称描述使用场景
docker-config标准 Docker 配置通用容器操作
dockerdDocker 守护进程配置用于 Docker 守护进程的 Docker 模式
buildkitdBuildKit 守护进程配置用于基于 BuildKit 的操作

常见配置问题：

问题表现解决方案
驱动名称错误出现 MountVolume.SetUp failed 错误将 driver 精确设置为 connectors-csi
找不到 Connector出现 could not get connector 错误确保 Connector 存在于相同命名空间
配置名称错误未生成 Docker 配置设置正确的 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/.dockerDocker 客户端配置目录
dockerd/etc/dockerDocker 守护进程配置目录
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

# 针对 dockerd
kubectl exec <pod-name> -n <namespace> -- cat /etc/docker/daemon.json

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

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

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

检查 Docker 配置内容

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>"
    }
  }
}

dockerd 配置

检查生成的 daemon.json 文件：

kubectl exec <pod-name> -n <namespace> -- cat /etc/docker/daemon.json

预期配置内容：

{
  "insecure-registries": [
    "c-<connector-name>.<namespace>.svc.cluster.local"
  ]
}

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

非安全注册表问题

症状：

  • 出现 server certificate verification failed 错误
  • TLS 握手失败

排查步骤：

  1. 验证非安全注册表设置是否正确配置：

    kubectl exec <pod-name> -n <namespace> -- cat /etc/docker/daemon.json

  2. 检查容器运行时是否使用了挂载的配置：

    kubectl exec <pod-name> -n <namespace> -- docker info | grep -A 5 "Insecure Registries"

  3. 对于 containerd，验证代理地址配置是否正确：

    kubectl exec -it <node-name> -n <namespace> -- cat /etc/containerd/config.toml | grep -A 10 registry

高级故障排除

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"

其他资源