问题背景

在 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-imagenamespace: 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 是否覆盖配置

通过以上方法，你应该能成功解决 Rancher Dashboard Shell 镜像拉取失败的问题。如果仍有疑问，欢迎在评论区交流！ 🚀