从 Kubernetes Dashboard 迁移到 Headlamp：部署、认证与清理实战

从 Kubernetes Dashboard 切换到 Headlamp，并不只是替换一个 Web 界面。真正变化的是访问模型：Dashboard 通常随集群部署，用户粘贴 ServiceAccount Token 登录；Headlamp 则更像带图形界面的 Kubernetes 客户端，可以在桌面端复用 kubeconfig，也可以部署到集群内并接入 OIDC。

迁移时最重要的不是尽快卸载 Dashboard，而是确认身份、RBAC 和日常排障流程都能平稳延续。

先选对运行模式

Dashboard 只运行在集群内，通常每个集群部署一套，通过 kubectl port-forward 或 Ingress 访问。Headlamp 提供两种模式，适合不同的协作方式。

桌面端通常是迁移的最佳起点。它不消耗集群资源，也不需要开放新的服务端点，并且直接继承 kubectl 已经使用的身份。开发、测试和生产集群只要出现在 kubeconfig 中，就能在同一个客户端里切换。

集群内模式更适合需要固定 URL 的平台团队。此时应把 Headlamp 当作一个面向集群 API 的管理端点：必须启用 TLS、限制网络访问，并为共享用户设计明确的登录方案。

用并行运行降低迁移风险

在安装 Headlamp 前，先记录当前 Dashboard 的使用基线：

• 团队访问哪些集群和命名空间；
• 用户是否需要查看、编辑、扩缩容、删除或执行 Pod；
• Dashboard 通过端口转发还是 Ingress 暴露；
• 当前 Token 来自哪个 ServiceAccount；
• 哪些 RoleBinding 或 ClusterRoleBinding 只为 Dashboard 创建。

接着验证 kubeconfig。将下面的 team-a 替换为用户实际可访问的命名空间：

kubectl config current-context
kubectl get nodes
kubectl get pods -n team-a
kubectl auth can-i list pods -n team-a
kubectl auth can-i update deployments.apps -n team-a
kubectl auth can-i create pods/exec -n team-a

无法列出 Node 不一定代表配置错误，用户可能只有命名空间权限。kubectl get pods -n team-a 和 kubectl auth can-i 更能准确反映 Headlamp 中将出现哪些资源和操作按钮。

共享集群建议采用一到两个迭代周期的并行迁移：先开放 Headlamp，让用户完成真实工作流验证，同时保留 Dashboard 作为临时回退入口。不要在只确认“页面能打开”后就卸载旧系统。

安装并验证 Headlamp

桌面端：直接复用 kubeconfig

按操作系统选择安装命令：

# macOS
brew install --cask headlamp

# Windows，PowerShell 或终端
winget install headlamp

# Linux，Flatpak
flatpak install flathub io.kinvolk.Headlamp

如果 kubeconfig 不在默认位置，可以在启动前指定文件。Unix 系统用冒号连接多个文件：

KUBECONFIG="$HOME/.kube/dev:$HOME/.kube/prod" headlamp

Windows PowerShell 使用分号：

$env:KUBECONFIG = "$HOME\.kube\dev;$HOME\.kube\prod"
headlamp

启动后应检查集群选择器、命名空间过滤、工作负载列表以及 YAML 详情页。多集群只是统一了入口，每个集群仍独立执行自己的认证与 RBAC 策略。

集群内：使用 Helm 部署共享实例

下面的命令会创建独立命名空间并安装 Headlamp：

helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/
helm repo update
kubectl create namespace headlamp
helm install headlamp headlamp/headlamp --namespace headlamp

kubectl rollout status deployment/headlamp -n headlamp
kubectl get pods,svc -n headlamp

如果命名空间已经存在，kubectl create namespace 会报 AlreadyExists，可直接继续安装。安装完成后，先用端口转发验证服务，不必立即配置公网入口：

kubectl port-forward -n headlamp svc/headlamp 8080:80

浏览器打开 http://localhost:8080。确认服务正常后，再根据现有 Ingress Controller 配置稳定域名。

集群内共享访问还需要认证设计。Headlamp 支持 OIDC，通常需要 Client ID、Client Secret、Issuer URL 和可选 scopes。身份提供商中登记的回调地址必须是公开地址加 /oidc-callback，例如：

https://headlamp.example.com/oidc-callback

如果 Headlamp 位于 Ingress 或负载均衡器之后，应确认代理转发 X-Forwarded-Proto: https。否则应用可能生成 http 回调地址，导致身份提供商拒绝登录。企业环境也可以在 Headlamp 前放置统一的身份感知代理，但仍需确认最终访问 Kubernetes API 时使用的是预期用户身份，而不是一个权限过大的共享账户。

把表单操作迁移为可审计的 YAML

Dashboard 用户最明显的体验变化，是资源创建从表单转向 YAML。这个变化值得利用：清单可以进入 Git、接受评审，并由 CI/CD、Helm 或 GitOps 工具重复应用。

可以这样实践：先用 kubectl 生成基础清单，再将文件提交到代码库，或者粘贴到 Headlamp 的 Create 页面。下面的命令不会修改集群：

kubectl create deployment web-demo \
  --image=nginx:1.27-alpine \
  --replicas=2 \
  --dry-run=client \
  -o yaml > web-demo.yaml

kubectl create service clusterip web-demo \
  --tcp=80:80 \
  --dry-run=client \
  -o yaml >> web-demo.yaml

kubectl apply --dry-run=server -f web-demo.yaml

运行前需要选择正确的 kubectl context；如需固定命名空间，可在两个 kubectl create 命令中加入 --namespace=team-a。最后一条命令让 Kubernetes API 执行服务端校验，但不会真正创建资源。

验证无误后，可以在 Headlamp 中选择目标集群和命名空间，打开 Create，粘贴 web-demo.yaml 并 Apply。也可以继续由 GitOps 或流水线部署，只把 Headlamp 用于查看状态、事件、日志和资源关系。

日常排障需要逐项验证：

• Pod 日志能否加载，多容器 Pod 能否切换容器；
• Events 是否能显示调度失败、探针失败等警告；
• 有 pods/exec 权限的用户能否打开终端；
• 无写权限的用户是否只能查看 YAML；
• 安装 metrics-server 后，Pod 和 Node 是否显示 CPU、内存指标；
• Map View 是否能展示 Deployment、ReplicaSet、Pod 和 Service 的关系。

Map View 适合回答“这些资源为什么没有连起来”，列表和搜索则适合快速定位已知对象。两种视图使用相同的 Kubernetes 数据，不会替代 Events、日志和指标等诊断证据。

下线 Dashboard 前的收尾清单

只有在不同角色的用户都完成验证后，才应删除 Dashboard。Helm 安装的 Dashboard 可以这样卸载：

helm uninstall kubernetes-dashboard -n kubernetes-dashboard
kubectl get pods -n kubernetes-dashboard

如果原来通过清单或集群插件安装，应使用对应方式删除。之后重点检查 Dashboard 专用的 ServiceAccount、RoleBinding 和 ClusterRoleBinding。先查看对象，再按名称删除，避免误删被其他系统复用的授权：

kubectl get serviceaccount -n kubernetes-dashboard
kubectl get rolebinding -n kubernetes-dashboard
kubectl get clusterrolebinding | grep -i dashboard

迁移完成的判断标准不只是 Headlamp 已经运行，还应包括：桌面用户能通过 kubeconfig 访问正确集群；共享实例的 OIDC、Ingress 和 TLS 正常；不同角色只看到 RBAC 允许的操作；日志、Exec、Events、指标与 YAML 工作流通过验证；旧 Token、授权绑定、访问地址和内部文档已经清理。

对于大多数团队，稳妥顺序是“桌面端试用、并行验证、共享入口完善、清理 Dashboard”。Headlamp 改善了多集群和资源关系查看体验，但它不会修复过宽的 RBAC，也不应成为绕过 GitOps 的手工变更通道。把身份最小权限和 YAML 审计流程一起纳入迁移，才算真正完成切换。