Alauda DevOps Connectors Docs
  • 简体中文

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

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

    目录

    常见问题概述

    问题潜在原因影响
    卷挂载失败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
    找不到连接器could not get connector 错误确保连接器存在于同一命名空间
    配置名称错误未生成 Docker 配置设置正确的 configuration.names 值
    命名空间不匹配卷附加失败确保连接器与 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: 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 found连接器不存在或命名空间错误创建连接器或修正命名空间
    failed to generate configuration模板渲染错误检查连接器和 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

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

    查找生成的 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. 连接器是否为 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"

    其他资源