当前位置：首页 > news >正文

rancher 解决拉取dashboard-shell镜像失败的问题

news 来源：原创 2025/6/19 21:14:25

问题背景

在 Kubernetes 集群中部署 Rancher 后，点击右上角的 "Shell" 按钮时，Rancher 会动态创建一个 dashboard-shell-xxxxx Pod，用于提供 Web 终端功能。然而，由于默认镜像 rancher/shell:v0.1.21 托管在 Docker Hub（docker.io），国内用户可能会遇到拉取失败的问题，报错如下：

Failed to pull image "rancher/shell:v0.1.21": rpc error: 
code = Unknown desc = failed to pull and unpack image "docker.io/rancher/shell:v0.1.21": 
failed to resolve reference "docker.io/rancher/shell:v0.1.21": 
failed to do request: Head "https://registry-1.docker.io/v2/rancher/shell/manifests/v0.1.21": dial tcp 199.59.149.235:443: i/o timeout

或者，如果你已经替换为私有仓库但仍然遇到 401 Unauthorized 错误：

Failed to pull image "uhub.service.ucloud.cn/sre-paas/rancher/shell:v0.1.21": failed to authorize: 401 Unauthorized

解决方案

1. 修改 Rancher 默认 Shell 镜像

Rancher 通过 MutatingWebhookConfiguration 动态注入 Shell Pod 的配置，我们可以修改其默认镜像地址。

步骤 1：查找 Rancher 的 `shell-image` 设置

kubectl get settings.management.cattle.io shell-image -n cattle-system -o yaml

如果不存在，可以手动创建：

kubectl apply -f - <<EOF
apiVersion: management.cattle.io/v3
kind: Setting
metadata:
  name: shell-image
  namespace: cattle-system
value: "your-mirror-registry.com/rancher/shell:v0.1.21"
EOF

步骤 2：更新镜像地址

kubectl edit settings.management.cattle.io shell-image -n cattle-system

修改 value 为你的镜像地址：

value: "uhub.service.ucloud.cn/sre-paas/rancher/shell:v0.1.21"

步骤 3：重启 Rancher 使配置生效

kubectl rollout restart deployment rancher -n cattle-system

2. 配置 `imagePullSecrets` 拉取私有镜像

如果镜像仓库需要认证（如 UCloud、Harbor），需创建 docker-registry Secret 并绑定到 ServiceAccount。

步骤 1：创建 `docker-registry` Secret

kubectl create secret docker-registry ucloud-regcred \
  --docker-server=uhub.service.ucloud.cn \
  --docker-username=<your-username> \
  --docker-password=<your-password> \
  -n cattle-system

步骤 2：绑定到 `default` ServiceAccount

kubectl patch serviceaccount default \
  -p '{"imagePullSecrets": [{"name": "ucloud-regcred"}]}' \
  -n cattle-system

验证是否生效

kubectl get pod <shell-pod-name> -n cattle-system -o yaml | grep imagePullSecrets

3. 检查 Pod 是否正常启动

如果仍然失败，检查 Pod 事件：

kubectl describe pod <shell-pod-name> -n cattle-system

常见问题：

镜像路径错误（确认 uhub.service.ucloud.cn/sre-paas/rancher/shell:v0.1.21 是否存在）
Secret 未正确绑定（检查 kubectl get sa default -n cattle-system -o yaml）
网络策略限制（检查 Calico/NetworkPolicy 是否阻止访问镜像仓库）

总结

问题	解决方案
镜像拉取超时	修改 `shell-image` 设置，使用国内镜像源
401 Unauthorized	创建 `imagePullSecrets` 并绑定到 `default` ServiceAccount
Pod 未继承 `imagePullSecrets`	检查 `MutatingWebhookConfiguration` 是否覆盖配置