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

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

#常见问题概述

#检查 CSI 卷配置

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

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

常见配置选项：

常见配置问题：

如何验证：

# 检查连接器是否存在
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

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

#检查 Pod 事件

检查 Pod 事件以获取与挂载相关的问题：

kubectl describe pod <pod-name> -n <namespace>

常见错误消息及解决方案：

示例错误及解决方案：

  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"

#其他资源

• Connectors CSI 驱动程序概念
• OCI 连接器快速入门
• 连接器状态故障排除
• 在 Kubernetes 工作负载中使用 OCI 连接器
• 在 Tekton Pipeline 中使用 OCI 连接器