Migrating from Kubernetes Dashboard to Headlamp: A Step-by-Step Guide

随着 Kubernetes Dashboard 归档，团队需要一条不会破坏现有工作方式的迁移路径。本指南帮助你把切换变成常规操作，减少风险。

Kubernetes Dashboard 长期帮助团队构建和学习 Kubernetes：查看正在运行的资源、检查 Pod，让复杂集群更容易理解。归档之后，许多团队都在问：

替代工具是什么，又如何在不打断工作流程的情况下迁移？

本指南逐步介绍迁移过程，并解释每一步的意义。完成后，你将拥有可用的 Headlamp 环境，并妥善下线 Dashboard。

1. 开始之前：了解将发生的变化

Kubernetes Dashboard 和 Headlamp 都能显示集群中运行的内容，但工作方式不同。

• 桌面版 Headlamp 使用现有 kubeconfig 连接一个或多个集群，并支持通过插件扩展。
• Headlamp 在集群内运行时，使用 Kubernetes ServiceAccount 访问 API，并遵循 RBAC 规则。
• 相比之下，Kubernetes Dashboard 只能在集群内运行，且始终依赖 ServiceAccount 令牌。

提前理解这些模型，有助于选择合适的部署方式与权限。

概括来说：

• Dashboard 在集群内运行，通常通过 port-forward 或 Ingress 访问，往往依赖 ServiceAccount 令牌。
• Headlamp 可以在桌面或集群内运行。
  • 桌面版读取 kubeconfig，与 kubectl 一样。
  • 集群内部署可以像其他工作负载一样，使用 ServiceAccount 并遵循 RBAC。

1.1 Kubernetes Dashboard 如何工作

Dashboard 是运行在集群内的 Web 应用。

• 安装在集群内，通常使用 Helm。
• 每个集群通常运行一个 Dashboard。
• 通常通过 kubectl port-forward 或 Ingress 访问。
• 使用 Bearer 令牌登录，令牌通常来自 ServiceAccount。
• 提供帮助创建资源的表单。
• 主要通过表格和列表导航。

1.2 Headlamp 如何工作

Headlamp 更像带有图形界面的 Kubernetes 客户端。

• 可以在桌面或集群内运行。
• 读取 kubeconfig，与 kubectl 一样。
• 可以在同一个界面显示多个集群。
• 创建或修改资源时更偏向使用 YAML。
• 包含列表视图和可视化地图。
• 可以通过插件添加功能。

1.3 保持不变的部分

许多工作流程仍然熟悉：

• 浏览工作负载与资源
• 按命名空间筛选
• 检查 YAML、事件和状态
• 查看日志
• 执行 RBAC 允许的操作

1.4 发生变化的部分

有些体验会不同：

• 登录从粘贴令牌转为使用 kubeconfig，有时也会使用 SSO。
• 资源创建从表单转为应用 YAML。
• 多集群成为常规方式。
• 地图视图展示资源之间的连接。

2. 迁移前检查清单

这份清单让切换稳定、可预测，提前发现错误集群上下文、权限缺失等容易拖慢团队的小问题，并保留既有安全模型。Headlamp 应依赖你在 Kubernetes 中已经信任的身份与 RBAC。准备好这些之后，就能在直观的界面中高效工作，并适应集群和工作负载的增长。

完成本节后，在关闭 Dashboard 之前，你将能够验证迁移是否成功。

2.1 记录当前的使用情况

列出基本信息：

• 使用哪些集群，例如开发、预发布、生产
• 最常使用哪些命名空间
• 最常执行哪些操作，例如查看、编辑、扩缩容、删除、调试
• 目前如何访问 Dashboard：端口转发或 Ingress
• 如何登录：ServiceAccount 令牌，以及使用哪些 RBAC 绑定

这些信息构成迁移基线。

2.2 检查 kubeconfig 是否可用

Headlamp 尤其在桌面环境中依赖 kubeconfig。安装之前，先确认配置可用。

kubectl config current-context

然后尝试：

kubectl get nodes

如果不能列出节点，就在有权限的命名空间中测试：

kubectl get pods -n <namespace>

如果这些命令可用，Headlamp 就能使用相同身份与 RBAC。

2.3 选择上线计划

无需匆忙切换。多数团队选择以下一种方式：

并行上线，推荐

• 安装 Headlamp。
• 让成员试用。
• 短期保留 Dashboard。
• 团队准备好之后，移除 Dashboard。

直接切换

• 安装 Headlamp。
• 更新文档与链接。
• 随后尽快移除 Dashboard。

对共享集群而言，并行上线更稳妥。

2.4 决定 Headlamp 运行在哪里

两种方案都可行，许多团队会同时使用。

桌面

• 依赖个人 kubeconfig
• 不消耗集群资源
• 无需端口转发
• 开箱即用的多集群支持

集群内

• 适合通过浏览器共享访问
• 可以像其他集群应用一样管理
• 通常配合 Ingress 与 SSO

2.5 记录可选依赖

以下依赖很常见，可以稍后处理。

• metrics-server：用于 CPU 与内存图表
• Ingress：提供集群内部署的访问 URL
• OIDC / SSO：用于浏览器登录
• 清理旧 Dashboard 的 ServiceAccount 与 RBAC

3. 选择桌面版或集群内部署

Headlamp 提供两种开始方式，可在桌面或集群内运行。选择取决于日常需求。若想以最少配置快速开始，桌面版通常最直接；若需要由平台团队管理的共享 URL，集群内部署通常更合适。

本节帮助你按团队、访问模型及未来运维方式选择方案。

方案 A：桌面版，由用户管理

桌面版 Headlamp 在每位用户的机器上运行，读取与 kubectl 相同的 kubeconfig，因此访问仍绑定到用户自己的身份与 RBAC。

团队选择它的原因

• 无需部署或暴露集群内服务。
• 不消耗集群 CPU 或内存。
• 使用现有 kubeconfig 与 RBAC。
• 一个应用可以连接多个集群。
• 日常使用无需端口转发。

方案 B：集群内部署，适合共享访问

Headlamp 作为 Kubernetes 工作负载安装，通常使用 Helm，使集群管理员能够像其他集群应用一样管理它。

• 管理员通过 Helm Chart 和标准 Kubernetes 工具管理安装、升级与配置。
• 管理员控制 Ingress，并可配置 OIDC 登录以共享访问。
• 支持团队环境中的共享使用。

4. 安装 Headlamp：桌面版与集群内

目标是建立符合工作流程的 Headlamp 环境。桌面版读取本地 kubeconfig，不向集群添加组件，因此能快速启动；集群内部署则像其他 Kubernetes 工作负载一样，可管理、保护并共享。两种方式都遵循你现有的 RBAC 规则。

完成本节后，应能打开 Headlamp，确认当前使用的集群和命名空间可见。

4.1 安装桌面版：最快的开始方式

在自己的机器上安装 Headlamp，然后像普通应用一样打开。它读取 kubeconfig，使用与 kubectl 相同的身份和 RBAC。

Windows

通过 WinGet 安装：

winget install headlamp

或者使用 Chocolatey：

choco install headlamp

macOS

通过 Homebrew 安装：

brew install --cask headlamp

Linux

通过 Flatpak（Flathub）安装：

flatpak install flathub io.kinvolk.Headlamp

快速检查

1. 启动 Headlamp。
2. 确认能看到集群上下文。
3. 打开一个有权限的命名空间，确认列出了工作负载。Headlamp 只显示 RBAC 允许的操作。

4.2 集群内安装：共享访问

如果需要平台团队管理的共享界面，选择此路径。Headlamp 支持 Helm 或 YAML 清单部署。

使用 Helm 安装

添加仓库并更新：

helm repo add headlamp https://kubernetes-sigs.github.io/headlamp/helm repo update

创建命名空间，示例如下：

kubectl create namespace headlamp

安装 Chart：

helm install headlamp headlamp/headlamp --namespace headlamp

使用 YAML 清单安装，可选

Headlamp 也提供可直接应用、再按需调整的 YAML 清单。标准步骤参见在集群内安装 Headlamp——使用简单 YAML。

检查安装

确认 Pod 正在运行：

kubectl get pods -n headlamp

确认 Service 已存在：

kubectl get svc -n headlamp

访问：两种常见方式

用端口转发快速测试。这是验证服务可用的最快方式：

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

然后打开：http://localhost:8080

通过 Ingress 共享访问。若需要稳定 URL，通过 Ingress 控制器暴露服务。具体 Ingress YAML 取决于环境。Headlamp 的 OIDC 回调 URL 是公共 URL 加上 /oidc-callback，因此 Ingress 与 TLS 设置很重要。

4.3 更新 Headlamp

更新方式取决于最初安装方法。包管理器可以原地升级；通过 DMG 或 EXE 安装的版本需要下载新安装包再安装。

macOS

如果通过 Homebrew 安装，运行：

brew upgrade headlamp

如果通过 DMG 安装，下载最新 DMG，把 Headlamp 拖入 /Applications，替换旧版本。DMG 安装不会自动升级。

Windows

如果通过 WinGet 安装，运行：

winget upgrade headlamp

如果通过 Chocolatey 安装，运行：

choco upgrade headlamp

如果通过 EXE 安装，下载最新安装程序并再次运行。EXE 安装不会自动升级。

Linux

如果通过 Flatpak 安装，运行：

flatpak update io.kinvolk.Headlamp

如果使用 AppImage，下载最新 AppImage，运行新文件。

如果使用 tarball，下载最新压缩包、解压并运行新的 headlamp 二进制文件。

4.4 集群内访问注意事项

像对待其他面向集群的服务一样对待这一界面：使用 TLS，限制能够访问它的人，并通过 Kubernetes 认证与 RBAC 控制用户操作。

5. 认证与 RBAC

新界面不应带来一套新的安全模型。决定用户能做什么的是 Kubernetes，Headlamp 只是反映集群已经执行的认证与 RBAC 规则。

本节安排用户登录方式，并确认权限按预期工作。完成后，用户应只能看到和执行各自被授权的内容与操作。

本节覆盖桌面版和集群内部署两种配置。

5.1 桌面版：使用 kubeconfig

桌面版 Headlamp 读取 kubeconfig，使用与 kubectl 相同的凭据，无需管理独立的令牌登录流程。

步骤1：确认 kubeconfig 可用

kubectl config current-context

然后测试访问：

kubectl get nodes

如果不能列出节点，就测试一个有权限的命名空间：

kubectl get pods -n <namespace>

这些命令可用时，kubeconfig 和凭据对 Headlamp 同样有效。

步骤2：如有需要，指定正确的 kubeconfig

Headlamp 可以使用默认 kubeconfig 路径，也支持自定义文件路径。设置 KUBECONFIG 选择特定文件。

示例：

KUBECONFIG=/path/to/config headlamp

可以同时加载多个 kubeconfig 文件。Unix 系统中用 : 分隔路径，Windows 中用 ; 分隔。

界面中的预期行为

Headlamp 根据 RBAC 权限调整界面；没有编辑或删除资源的权限时，就不会提供这些操作。

5.2 集群内：共享访问需要登录方案

集群内部署供多个用户共享，需要明确的登录与访问计划。Headlamp 支持 OpenID Connect（OIDC）登录流程。

多数团队选择以下一种模式：

• A. 使用 Headlamp 内置 OIDC。
• B. 在 Headlamp 前部署认证层，企业环境中很常见。

A. Headlamp 内置 OIDC

使用 OIDC 时，Headlamp 需要：

• 客户端 ID
• 客户端密钥
• Issuer URL
• 可选的 scopes

OIDC 提供方还必须允许 Headlamp 的回调 URL，即 Headlamp URL 加上 /oidc-callback。

示例：https://headlamp.example.com/oidc-callback

Ingress 注意事项：如果 Headlamp 位于 Ingress 或负载均衡器之后，必须确保它转发 X-Forwarded-Proto。否则 Headlamp 可能生成 http 回调 URL，而不是 https，导致登录失败。

B. 在 Headlamp 前部署认证层

有些团队使用具备身份感知能力的代理或平台认证系统保护 Headlamp，以保持不同工具的登录体验一致。

Headlamp 文档提供 OpenUnison 示例，可使用加固的默认配置部署 Headlamp，并集成身份提供方。

5.3 RBAC：保持最小权限

Kubernetes 安全从 API 认证与授权（RBAC）开始，Headlamp 遵循这些规则。

实践建议

• 从足以完成工作的最低权限开始。
• 如果 Dashboard 使用高权限 ServiceAccount 令牌，迁移后计划移除或收紧这些访问。
• 集群内部署应像其他端点一样，使用 TLS 并限制网络访问。

5.4 快速排障

桌面版：“看不到集群”

kubeconfig 可能不在默认位置。通过 KUBECONFIG 或文件路径指定配置。

集群内：“重定向后 OIDC 登录失败”

确认提供方允许 https://YOUR_URL/oidc-callback。使用 Ingress 时，确认转发 X-Forwarded-Proto。

6. 管理多个集群

这是从 Kubernetes Dashboard 迁移后最显著的实际变化之一。Dashboard 通常一次访问一个集群；Headlamp 面向开发、预发布和生产集群并存的团队。不必反复切换标签页或工具，保持一个界面打开，就能随着工作切换集群。

关键是：如果 kubectl 能访问某个集群，Headlamp 通常也可以。本节介绍如何发现集群并在其中切换。

集群来自 kubeconfig

Headlamp 从 kubeconfig 文件读取集群，因此 kubectl 能访问的集群也可以出现在 Headlamp 中。

在界面中切换集群

加载 kubeconfig 后，通过集群选择器切换集群，减少在开发、预发布和生产之间移动的阻力。

可选：使用多个 kubeconfig 文件

如果分别保存 kubeconfig，可以一起加载。Headlamp 支持在 KUBECONFIG 中配置多个路径。

Unix/macOS/Linux：使用 : 分隔：

KUBECONFIG=~/.kube/dev:~/.kube/prod headlamp

Windows：使用 ; 分隔：

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

可选：在 Headlamp 内部添加集群

也可以通过界面加载额外的 kubeconfig 文件来添加集群。

权限保持不变

多集群不会改变安全规则。每个集群仍执行自己的 RBAC，Headlamp 只显示当前身份在所选集群中能够执行的操作。

7. 导航与理解资源

这里会重新变得熟悉。使用过 Dashboard 的人可以马上认出 Headlamp 的核心资源视图：Pod、Deployment、Service 和 Namespace 都还在。变化在于更快地切换资源并理解它们的关联。

本节介绍界面布局、资源位置，以及发生问题时更快建立上下文的工具。

在熟悉的位置查找资源

Headlamp 的资源分组与 Dashboard 很接近：

• Workloads：Pods、Deployments、StatefulSets 和 Jobs
• Network：Services 与 Ingress
• Storage：PersistentVolumes 与 Claims
• Configuration：ConfigMaps 与 Secrets
• Nodes：集群基础设施

命名空间筛选位于界面顶部，与 Dashboard 一样。

检查与编辑资源

在任意列表中点击资源，查看详细信息：

• 状态与条件
• 事件
• 标签与注解
• 完整 YAML 定义

RBAC 允许时，可直接在界面中编辑 YAML；否则资源以只读方式显示，与 kubectl 的行为一致。

使用搜索与筛选加快操作

Headlamp 为列表提供更快的搜索和筛选。集群或命名空间规模较大时，可以直接缩小视图范围，而无需反复跳转页面。

使用地图视图理解资源关系

Dashboard 主要使用列表；Headlamp 还包含 Map View。

Headlamp 中的资源关系视图地图视图展示以下资源之间的关联：

• Deployments
• ReplicaSets
• Pods
• Services

排障时，不必点击多个页面就能看到连接，更快发现缺失连接或破损关系。

何时使用列表，何时使用地图

• 已经知道目标资源时，使用列表。
• 需要理解为什么某项内容没有正常工作时，使用地图。

两种视图基于相同数据，区别是当下需要多少上下文。

8. 使用 YAML 部署应用

对许多 Dashboard 用户而言，这里最能感受到差异：Dashboard 用表单引导用户，Headlamp 倾向于清单。这让实际部署内容更明确、更可重复。应用 YAML 时，集群收到的就是页面上呈现的内容；同一清单也可在 Git、CI 或其他工作流程中重复使用。

本节展示如何在 Headlamp 中使用 YAML 部署，并帮助习惯向导的用户管理这一过程。

从表单到清单

在 Dashboard 中，应用通常通过填写表单部署：

• 容器镜像
• 副本数
• Service 类型

Headlamp 不提供相同的向导，而是直接从界面应用 YAML。

这与多数团队如今的部署方式相符：

• 清单保存在 Git 中。
• CI/CD 应用清单。
• Helm 或 GitOps 工具管理变更。

Headlamp 融入这一流程，而不是取代它。

通过 YAML 创建资源

在 Headlamp 中部署应用：

1. 选择集群和命名空间。
2. 点击 Create。
3. 粘贴或上传 YAML 清单。
4. 审阅清单。
5. 点击 Apply。

资源会立即出现在界面中。如果清单无效，Headlamp 显示 Kubernetes API 返回的相同错误。

快速生成 YAML

如果习惯 Dashboard 向导，仍然可以快速生成 YAML，例如：

kubectl create deployment nginx \  --image=nginx \  --dry-run=client \  -o yaml > nginx.yaml

按需编辑文件，再粘贴到 Headlamp 并应用。这样得到的是可重复使用的清单，而不是只能通过界面创建的对象。

Helm 与 GitOps 怎么办？

二者都可以与 Headlamp 配合。

• 照常使用 Helm 安装。
• 照常通过 GitOps 流水线部署。
• 使用 Headlamp 查看、检查和调试运行中的内容。

Headlamp 不取代这些工具，而是显示它们创建的资源。

相较 Dashboard，有哪些变化？

• 没有多步骤部署表单。
• 更直接地操作 YAML。
• 更清楚地看到实际应用到集群的内容。
• 同一清单可在 CI、Git 或其他工具中复用。

9. 部署与调试工作负载

日常调试是这两种 Kubernetes 界面的重要用途。Dashboard 用户常在其中打开日志、检查事件并分析失败原因。Headlamp 支持同样的流程，同时减少常见操作阻力。

本节介绍 Headlamp 的核心调试循环：日志、exec、指标和事件，让排障能够在界面内完成。

查看日志

可以直接在界面中查看 Pod 日志。

查看步骤：

1. 打开 Workloads。
2. 选择 Pods。
3. 点击一个 Pod。
4. 打开 Logs 标签页。

Pod 中有多个容器时，可以切换容器。日志实时流式显示，适合观察发布过程或处理正在发生的故障。

进入运行中的 Pod 执行命令

Headlamp 也可以在容器内打开 shell。

在 Pod 视图中：

• 打开 Pod 操作菜单。
• 选择 Terminal 或 Exec。

这会在容器内建立交互会话，快速检查时无需返回独立终端。

此操作遵循 RBAC。如果不允许 kubectl exec，Headlamp 也不会允许。

检查指标与资源使用

Headlamp 可以显示 Pod 和 Node 的 CPU、内存使用情况，工作方式与 Dashboard 相同。

需要了解几点：

• 指标要求集群中安装 metrics-server。
• 缺少指标时，Headlamp 会显示明确提示。
• 指标可用后，使用情况会出现在 Pod 与 Node 视图中。

可以方便地回答以下问题：

• 这个 Pod 是否使用了太多内存？
• 某个 Node 是否处于资源压力之下？

出错时查看事件

事件通常是理解失败原因的最快方式。在 Headlamp 中：

• 资源详情页面显示事件。
• 警告与错误关联到 Pod、Node 或 Deployment。

工作负载卡住或崩溃时，通常应首先查看这里。

与 Dashboard 的比较

保持不变

• 查看日志
• 检查事件
• 受 RBAC 约束的操作

改善之处

• 内置 exec 会话
• 更清晰的布局与筛选
• 减少界面和 CLI 之间的上下文切换

10. 移除 Kubernetes Dashboard

这是最后一步。移除的是旧访问路径及额外组件，不是 Kubernetes 功能。Headlamp 验证可用、团队适应后，目标是缩小环境中需要维护的范围。

本节先确认常见流程仍然可用，再卸载 Dashboard，并清理仅用于支持它的 ServiceAccount 或 RBAC。

移除 Dashboard 可减少冗余，也避免保留未使用的访问路径。

确认 Headlamp 满足需求

卸载前，确认：

• 用户可以通过 Headlamp 访问所需集群。
• 常见任务可用：
  • 浏览资源
  • 用 YAML 部署
  • 查看日志与事件
  • 在授权情况下进入 Pod 执行命令
• 不同角色的 RBAC 按预期工作。

检查通过后，可以移除 Dashboard。

卸载 Dashboard

如果使用 Helm 安装 Dashboard，通过以下命令移除：

helm uninstall kubernetes-dashboard -n kubernetes-dashboard

如果通过清单或附加组件安装，用最初安装它的方法移除。

移除后，确认资源已经消失：

kubectl get pods -n kubernetes-dashboard

清理访问相关遗留项，推荐

许多 Dashboard 环境使用专门的 ServiceAccount 和集群级角色。

检查并移除仅为 Dashboard 访问创建的内容，例如：

• ServiceAccounts
• RoleBinding 或 ClusterRoleBinding
• 仍指向 Dashboard URL 或端口转发命令的旧文档

这能减少长期凭据和未使用的权限。

通知团队

确保团队知道：

• Headlamp 已成为主要 Kubernetes 界面。
• 如何通过桌面版或 URL 访问。
• 遇到不同体验时，在哪里获取帮助。

11. 迁移后检查清单

以下清单覆盖访问、RBAC 和日常任务，也确保清理确实完成，而不是凭假设认定。

访问与可见性

• Headlamp 打开时没有错误。
• 用户可以访问正确的集群。
• 命名空间筛选按预期工作。
• 多集群切换正常。

认证与 RBAC

• 桌面用户通过 kubeconfig 访问集群。
• 集群内部署用户通过选定认证方式登录。
• 用户只看到 RBAC 允许的操作。
• 正常使用中不出现意外权限错误。

核心工作流程

• Workloads、Network 与 Configuration 能加载资源。
• 权限允许时，可以查看与编辑 YAML。
• 可以通过 Create 与 YAML 部署应用。
• 运行中 Pod 的日志正常加载。
• 获授权用户能够执行 exec。
• 如果已安装 metrics-server，指标正常显示。

运维可靠性

• 团队无需切换工具即可排障。
• 调试时，地图视图有助于解释资源关系。
• 平台或 DevOps 团队了解 Headlamp 的安装与管理方式。

确认清理

• Kubernetes Dashboard 已停止运行。
• 仅供 Dashboard 使用的 ServiceAccount 与 RBAC 绑定已移除。
• 内部文档不再引用 Dashboard URL 或端口转发命令。

团队共识

• 团队知道 Headlamp 是默认 Kubernetes 界面。
• 入职文档引导新成员使用 Headlamp。
• 反馈和提问渠道明确。

从 Kubernetes Dashboard 到 Headlamp 的迁移至此完成。团队继续使用相同的 Kubernetes 访问模型，跨集群工作，并沿用与现有 Kubernetes 用法一致的流程。无论桌面版还是共享环境，Headlamp 都成为默认界面。随着需求增长，可以保持现状，也可通过插件与新视图逐步扩展。

想参与后续发展，可以加入 Headlamp 社区并贡献：headlamp.dev。