Rancher Shell Pod 启动失败的完整排错手册：从401错误到网络策略

Rancher Shell Pod 启动故障深度排查指南从认证到网络的全链路分析当你在Rancher中点击那个诱人的Shell按钮期待着一个便捷的命令行界面时却可能遭遇Pod启动失败的窘境。这不是简单的镜像拉取失败问题而是一系列可能涉及认证、配置、网络策略等多层因素的复杂故障链。本文将带你深入Kubernetes内部系统性地排查和解决Rancher Shell Pod启动问题。1. 故障现象初步诊断Shell Pod启动失败通常会表现为以下几种典型症状401 Unauthorized错误表明认证失败即使你已经配置了镜像仓库地址镜像拉取超时可能是网络策略阻止了对外部仓库的访问ImagePullBackOff状态Kubernetes反复尝试拉取镜像但失败CrashLoopBackOff状态镜像拉取成功但容器启动失败首先获取Pod的详细状态信息kubectl get pods -n cattle-system | grep shell kubectl describe pod shell-pod-name -n cattle-system kubectl logs shell-pod-name -n cattle-system重点关注Events部分的错误信息它们通常会指向问题的根源。例如Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal Scheduled 2m default-scheduler Successfully assigned cattle-system/dashboard-shell-abcde to node-1 Warning Failed 1m kubelet 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 timeout2. 镜像配置问题排查Rancher通过MutatingWebhookConfiguration动态注入Shell Pod的配置我们需要检查几个关键点2.1 检查Shell镜像设置kubectl get settings.management.cattle.io shell-image -n cattle-system -o yaml如果设置不存在或需要修改可以创建或更新apiVersion: management.cattle.io/v3 kind: Setting metadata: name: shell-image namespace: cattle-system value: your-mirror-registry.com/rancher/shell:v0.1.21应用配置后重启Rancher Deploymentkubectl rollout restart deployment rancher -n cattle-system2.2 验证镜像仓库可达性确保你的镜像仓库确实包含所需镜像skopeo inspect docker://your-mirror-registry.com/rancher/shell:v0.1.21如果使用私有仓库确保镜像路径完全匹配包括可能的命名空间前缀。3. 认证问题深度排查当遇到401错误时问题通常出在镜像拉取凭证上。以下是详细的排查步骤3.1 检查Secret配置创建docker-registry类型的Secretkubectl create secret docker-registry my-regcred \ --docker-serveryour-mirror-registry.com \ --docker-usernameyour-username \ --docker-passwordyour-password \ -n cattle-system3.2 关联Secret到ServiceAccountRancher Shell Pod使用cattle-system命名空间下的default ServiceAccountkubectl patch serviceaccount default \ -p {imagePullSecrets: [{name: my-regcred}]} \ -n cattle-system验证配置是否生效kubectl get sa default -n cattle-system -o yaml输出应包含类似内容imagePullSecrets: - name: my-regcred3.3 检查Pod是否继承Secret即使正确配置了ServiceAccount有时Pod也可能无法继承imagePullSecrets。检查实际创建的Pod配置kubectl get pod shell-pod-name -n cattle-system -o yaml | grep imagePullSecrets -A 3如果没有显示可能是MutatingWebhookConfiguration的问题。4. 网络策略与连接问题当认证通过但依然无法拉取镜像时网络问题成为主要怀疑对象。4.1 检查基础网络连接从集群节点测试访问镜像仓库# 测试DNS解析 nslookup your-mirror-registry.com # 测试端口连通性 telnet your-mirror-registry.com 443 # 或 nc -zv your-mirror-registry.com 4434.2 排查网络策略限制如果使用Calico或其他网络插件检查是否有NetworkPolicy阻止访问kubectl get networkpolicy -n cattle-system kubectl describe networkpolicy policy-name -n cattle-system临时创建一个宽松策略测试apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: allow-all-egress namespace: cattle-system spec: podSelector: {} egress: - {} policyTypes: - Egress4.3 检查节点防火墙规则在节点上检查iptables/nftables规则sudo iptables -L -n -v | grep your-mirror-registry.com或者检查云平台的安全组设置确保出站443端口开放。5. MutatingWebhookConfiguration深入分析Rancher通过这个机制动态修改Shell Pod的配置。检查其配置是否正确kubectl get mutatingwebhookconfigurations.admissionregistration.k8s.io rancher.cattle.io -o yaml重点关注webhook规则是否匹配Shell Pod创建客户端配置caBundle等是否正确failurePolicy设置建议为Fail而非Ignore如果webhook失效Pod可能缺少必要的配置注入。可以临时设置failurePolicy为Ignore进行测试kubectl edit mutatingwebhookconfigurations.admissionregistration.k8s.io rancher.cattle.io6. 高级调试技巧当常规方法无法解决问题时这些高级技巧可能会帮到你6.1 手动模拟Pod创建通过手动创建类似的Pod来隔离问题apiVersion: v1 kind: Pod metadata: name: shell-test namespace: cattle-system spec: containers: - name: shell image: your-mirror-registry.com/rancher/shell:v0.1.21 imagePullSecrets: - name: my-regcred6.2 检查kubelet日志在运行Shell Pod的节点上检查kubelet日志journalctl -u kubelet -n 100 --no-pager | grep -i shell6.3 使用临时调试容器如果Pod处于ImagePullBackOff状态可以创建临时调试容器kubectl debug -it shell-pod-name -n cattle-system --imagebusybox -- sh然后在容器内尝试手动拉取镜像wget https://your-mirror-registry.com/v2/ -O - --no-check-certificate7. 预防措施与最佳实践为避免未来出现类似问题建议采取以下措施镜像缓存在集群内部部署镜像仓库缓存如Harbor网络策略预先配置允许访问外部镜像仓库的网络策略凭证管理使用外部Secret管理工具如Vault动态注入凭证监控告警设置对ImagePullBackOff状态的监控告警配置示例定期检查Shell镜像可用性的CronJobapiVersion: batch/v1beta1 kind: CronJob metadata: name: check-shell-image namespace: cattle-system spec: schedule: 0 * * * * jobTemplate: spec: template: spec: containers: - name: checker image: curlimages/curl command: [sh, -c, curl -I https://your-mirror-registry.com/v2/rancher/shell/manifests/v0.1.21] restartPolicy: OnFailure在实际生产环境中我们曾遇到一个棘手案例Shell Pod因节点DNS缓存问题间歇性失败。通过部署NodeLocal DNSCache并调整dnsConfig后问题彻底解决。这提醒我们有时问题可能隐藏在看似不相关的系统组件中。