容器与 K8s 故障排查指南

本文整合了 Docker 和 Kubernetes 常见故障的排查方法。

Docker X11 显示问题

在 Docker 容器中运行图形界面应用时，可能遇到：

Error: cannot open display localhost:11.0

解决方案

在 docker run 时添加 --net=host 参数：

docker run --net=host -e DISPLAY=$DISPLAY your-image

---

EKS 节点丢失

问题现象

• EKS 控制台看不到节点
• kubectl get nodes 可以正常显示
• Pod 调度正常

解决方法

在 aws-auth ConfigMap 中添加节点的 IAM Role 映射：

kubectl edit configmap aws-auth -n kube-system

添加配置：

data:
  mapRoles: |
    - groups:
      - system:bootstrappers
      - system:nodes
      rolearn: arn:aws:iam::111122223333:role/my-node-role
      username: system:node:{{EC2PrivateDNSName}}

获取节点 IAM Role

# 获取实例 ID
kubectl get nodes -o wide

# 查询 IAM Role
aws ec2 describe-instances --instance-ids i-xxxxx \
  --query 'Reservations[0].Instances[0].IamInstanceProfile.Arn'

---

Helm Release 找不到

问题现象

$ helm list -n jupyter
# 没有 foobar

$ helm install foobar jupyterhub/jupyterhub -n jupyter
Error: release foobar already exists

原因分析

Release 可能处于失败或 pending 状态。

解决方法

1. 查看所有状态的 Release

helm list --all-namespaces --all

2. 处理不同状态

状态	处理方法
failed	helm rollback 或 helm delete
pending-install	helm delete 然后重新安装
pending-upgrade	helm rollback 或强制升级

3. 手动清理

Helm 3 将 release 信息存储在 Secret 中：

# 查找
kubectl get secret -n jupyter | grep foobar

# 删除
kubectl delete secret sh.helm.release.v1.foobar.v1 -n jupyter

4. 重新安装

helm install foobar jupyterhub/jupyterhub -n jupyter

预防措施

# 使用 --atomic，失败自动回滚
helm install foobar chart -n jupyter --atomic

# 设置超时
helm install foobar chart -n jupyter --timeout 5m

---

完整排查流程

# 1. 查看所有 release
helm list -n namespace --all

# 2. 查看详细状态
helm status release-name -n namespace

# 3. 查看历史
helm history release-name -n namespace

# 4. 尝试回滚
helm rollback release-name 1 -n namespace

# 5. 如果失败，手动清理
kubectl get secret -n namespace | grep release-name
kubectl delete secret sh.helm.release.v1.release-name.v1 -n namespace

# 6. 重新安装
helm install release-name chart -n namespace

---

参考链接

• Docker X11 Display Issue
• EKS aws-auth ConfigMap
• Helm Troubleshooting