1. 部署前的版本选型与方案权衡1.1 版本匹配为什么是第一个坑凡是碰过 k8s dashboard 部署安装的几乎都吃过版本不匹配的亏。Kubernetes 的版本迭代速度快而 Dashboard 作为官方社区维护的可视化面板它的兼容列表往往滞后于集群版本。你拿一个新的 Dashboard 版本去对接一个老旧的集群或者反过来最常见的结局就是 Pod 一直 CrashLoopBackOff打开页面之后接口报错节点和 Pod 列表刷不出来界面空白一片。所以不管你是给生产环境搭管理界面还是在自己电脑上用 kind / minikube 跑一套测试集群第一步先说死先查清楚你的集群版本再决定用哪个 Dashboard 版本。Kubernetes API 是带组和版本号的Dashboard 内部会调用 cluster-info、metrics.k8s.io、apps/v1、batch/v1 这些 API哪怕只是小版本不匹配也可能导致部分接口返回 403 或者直接 EOF。我在一个测试环境里踩过典型例子集群是 Kubernetes 1.29当时装 Dashboard 2.7.0 完全正常但某同事先在 1.28 集群上手动改了镜像标签去拉 3.0 的新版结果 API 兼容层直接罢工Deployment 的副本数都显示不出来。后来切回匹配版本一切恢复。一个比较稳妥的做法在部署菜单还没有变成 Helm 默认之前先去 GitHub 的 releases 页面看那个版本对应的 Kubernetes 最低版本按图索骥。如果你不喜欢翻文档也有个偷懒的办法——用 manifests 子目录里的 recommended.yaml它所绑定的版本一般经过社区回归测试。但我的建议是不要把“latest”标签用于任何生产环境因为你永远不知道下一次 apply 会不会给你推送一个 API 变更的版本。1.2 三种部署方式怎么选k8s dashboard 部署安装的主流方式有三种我按自己的使用频率排序第一种官方 YAML 直接 apply。打开官方 GitHub 仓库找到 releases复制对应版本下的recommended.yaml链接然后kubectl apply -f。这是最省事、最不容易出错的路径也是本文后面实操部分采用的方式。它适合第一次部署、测试环境快速验证和想快速看效果的人所有配置项都集中在 YAML 里方便我们按自己的需求做修改。第二种用 Helm Chart。Dashboard 官方没有单独的 Helm 仓库但社区 Chart 挺多也有维护得不错的。Helm 的优势是通过 values.yaml 暴露配置项比如证书、副本数、镜像仓库地址改起来比手动修改官方 YAML 要干净。但社区 Chart 的维护质量和官方 YAML 不同步偶尔会出现字段名对不上的情况比如extraArgs的写法变了导致你改了不生效。如果你对 Helm 本身不熟我不建议用它作为第一选择。第三种自己拼 YAML。这种属于“受控环境”的玩法比如无外网环境下的离线安装或者公司安全合规要求所有镜像必须走内部镜像仓库。操作上就是把 recommended.yaml 下载下来批量替换 image 字段为内网地址然后 apply。依赖的镜像是kubernetesui/dashboard和kubernetesui/metrics-scraper提前在能联网的机器上docker pull然后docker save再传到内网docker load整个流程就闭环了。我个人的建议是优先官方 YAML后续需要做证书、Ingress 接入再在官方 YAML 基础上改。别把问题复杂化。2. 证书、存储与命名空间的关键细节2.1 证书方式决定了浏览器地址栏长什么样很多人在 k8s dashboard 部署安装完成、Pod 也 Running 了结果访问的时候被浏览器拦截这是因为 Dashboard 默认用的是自签证书。这个证书在启动时会自动生成但你换个设备访问又要重新点一次信任烦得很。如果你只是本机kubectl proxy访问其实可以完全不关心证书问题。但如果要通过 NodePort 或 Ingress 暴露建议在部署前就把证书问题想清楚。常见的做法有两种第一种使用正式的 CA 签发的证书。就是先去申请一张覆盖你域名的证书然后把 tls.crt 和 tls.key 存成 Kubernetes SecretSecret 的名字必须是kubernetes-dashboard-certs命名空间是kubernetes-dashboard。Dashboard 启动时会自动读取这个 Secret 里的证书然后你的浏览器就不会报警了。关键点是你需要在 apply 官方 YAML 之前把 Secret 创建好或者先 apply 再重建 Deployment否则 Pod 启动时发现没有证书就会重新生成自签证书。第二种自建内部 CA。公司内部有很多用户却不想暴露公网就用 OpenSSL 自建 CA签发一张给 Dashboard 域名用然后把 CA 下发到团队所有人的电脑上导入信任列表。这一步做下来浏览器会显示证书受信任也不用每台机器单独点风险提示。我干活时的细节是用 OpenSSL 签发证书之前先检查 SAN 字段证书的 Subject Alternative Name 必须包含你的 Dashboard 域名不能只写在 CommonName 里。这个字段现在浏览器强制执行漏了就等着每台电脑都报错然后你到处解释为什么明明证书是“对”的却不被信任。openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout dashboard.key \ -out dashboard.crt这个只是生成自签证书生产环境请走公司 CA 系统。把证书转成 Secretkubectl -n kubernetes-dashboard create secret tls kubernetes-dashboard-certs \ --certdashboard.crt --keydashboard.key2.2 存储与命名空间的设计思路Dashboard 本身是无状态应用它不需要持久化存储因为它不做数据落盘。但它依赖 metrics-server 或者 metrics-scraper 来展示集群的 CPU、内存监控数据metrics-scraper 同样是无状态的。真正的“存储”问题出现在你的浏览器端。Dashboard 把用户偏好、主题设置之类的东西存在了 localStorage 里所以不存在跨设备同步的问题。不要为了 Dashboard 单独建 PVC那是白费劲。比较值得关注的是命名空间的选择。官方 YAML 固定把什么东西都放在kubernetes-dashboard这个命名空间里。你可以用这个名字也可以改成自己的命名空间但强烈建议保持默认。原因是官方文档里所有证书、ServiceAccount、ClusterRoleBinding 的例子都默认指向这个命名空间你一旦改名后面排查问题的时候看到资料所有命令都要自己改一遍烦不烦而且多个环境统一使用同一个命名空间也方便脚本化处理。生产环境我见过有人把 Dashboard 的 ServiceAccount 权限放大到 cluster-admin这确实最省事但不是最安全的做法。后面我会单独讲权限收紧的问题。3. 实操全过程从下载到访问3.1 下载 recommended.yaml 并检查内容先把 Dashboard 的 YAML 文件拉下来。wget https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml如果你的网络访问 GitHub 比较费力可以用镜像站或者先下到本地再传上去。我一般在服务器上用 wget如果失败就用代理下载再传。注意下载完之后别急着直接 apply先把关键内容读一遍。我习惯打开 YAML 之后重点看几个地方Service 是否定义了 type默认是 ClusterIPDeployment 和 metrics-scraper 的镜像版本ServiceAccount、ClusterRoleBinding 的配置--namespacekubernetes-dashboard参数是否存在。这一步是为了确认这份 YAML 里没有任何让你意外的配置。尤其是当初遇到过某些第三方包往里面塞了一些额外的网络钩子所以自己检查一遍最稳。3.2 执行部署并检查 Pod 状态确认无异常后再执行kubectl apply -f recommended.yaml官方 YAML 的内容比较多包含 Namespace、ServiceAccount、Secret、ConfigMap、Deployment、Service 等多个资源。执行完以后官方也会提示你查看kubernetes-dashboard命名空间下的资源状态。kubectl -n kubernetes-dashboard get pods正常情况你会看到两个 Pod一个是 dashboard一个是 metrics-scraper状态都是 Running。如果出现 ImagePullBackOff通常是镜像拉取失败先确认集群能不能访问 Docker Hub不行就按第一节的方法改内网镜像源。如果是 CrashLoopBackOff优先看日志。kubectl -n kubernetes-dashboard logs -l k8s-appkubernetes-dashboard最常见的原因就是证书 Secret 被改了而 Pod 没有重新创建或者 API 版本不兼容。看日志时留意有没有Failed to start和证书相关的关键字。3.3 创建一个可登录的账号与 TokenDashboard 登录有两种方式Token 和 Kubeconfig。如果你只是开发环境自己用用 Token 最简单。官方 YAML 本身不创建专门的登录用户。你在 Postman 调接口一样得有身份才能访问Dashboard 默认拿 Kubernetes ServiceAccount 认证。所以先创建一个只读的管理员账号。我这里通常创建一个叫 dev-admin 的 ServiceAccountapiVersion: v1 kind: ServiceAccount metadata: name: dev-admin namespace: kubernetes-dashboard然后绑定到集群角色。如果你只是日常看资源用 view 角色就够了但修改不了资源。如果整个测试集群就你自己在用也可以给 cluster-admin生产环境则千万不要。apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: dev-admin roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: cluster-admin subjects: - kind: ServiceAccount name: dev-admin namespace: kubernetes-dashboard保存为 dashboard-account.yaml然后kubectl apply -f dashboard-account.yaml接着查询 Token。旧版 Kubernetes 的 ServiceAccount 会对应一个长期有效的 Secret我们可以直接获取。新版 Kubernetes 从 1.24 开始ServiceAccount 不再自动创建 Secret而是创建 TokenRequest所以我们更推荐用下面这个命令生成一个有有效期的 Tokenkubectl -n kubernetes-dashboard create token dev-admin这条命令的输出就是一份访问令牌把它复制下来在登录页面选择 Token 方式粘贴即可。需要注意这种 Token 有过期时间默认一小时左右。你要做自动化或者给别的同事用就得用定期刷新机制。临时用就无所谓过期了再生成一次。3.4 开启访问通道的三条路Pod 跑起来了账号建好了接下来就是怎么打开页面。第一条路kubectl proxy。在本地执行kubectl proxy然后浏览器访问http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/。这个方式对零暴露最安全但路径又长又丑只适合本地快速看一眼。第二条路NodePort。修改 Dashboard Servicekubectl -n kubernetes-dashboard edit svc kubernetes-dashboard把 type 改成 NodePort然后kubectl -n kubernetes-dashboard get svc查看被分配的节点端口。浏览器访问https://任何节点IP:端口。测试集群懒人方案但生产环境不建议因为直接把端口暴露到局域网缺少额外的认证保护。第三条路Ingress。这也是我生产环境用的方式。需要集群里已有 Ingress Controller然后创建一个 Ingress 对象apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: kubernetes-dashboard namespace: kubernetes-dashboard annotations: nginx.ingress.kubernetes.io/backend-protocol: HTTPS spec: rules: - host: dashboard.example.com http: paths: - path: / pathType: Prefix backend: service: name: kubernetes-dashboard port: number: 443这里最关键的是backend-protocol: HTTPS注解。因为 Dashboard Service 的入口协议是 HTTPS如果你的 Ingress 不声明这一点nginx 会用 HTTP 去连后端结果就是 502。这个坑我见过不止一个人踩过。如果公司内部没有 DNS你可以改本机 hosts 文件把dashboard.example.com指到 Ingress Controller 所在节点。浏览器访问时如果证书是合法 CA 签的就不会报警。4. 生产环境加固与日常运维4.1 RBAC 权限怎么给才算合理k8s dashboard 部署安装完成之后最让人纠结的就是权限管理。默认情况下你手动绑定的 dev-admin 如果是 cluster-admin那整个集群任何一个 namespace 都能改包括 kube-system。生产环境这是不可接受的。更合理的做法是按团队成员的分工分配权限。普通开发人员只需要查看工作负载、Service、ConfigMap可以给 view。需要发布应用的人可以在指定 namespace 里授予 edit。而需要管理集群节点的 SRE才需要 cluster-admin。我在公司内部实践下来会为不同团队创建不同的 ServiceAccount每个账号绑定相应的 Role 或 ClusterRole。比如前端组只能看前端 ns 下的资源绑定 view后端组负责某几个环境绑定 edit运维组绑定自定义 Role给到 secrets 的读取权限和 Deployment 的上下线权限。这样 Dashboard 登录接口签发的 Token 是不同的登录进去能看到的资源范围也是隔离的。你要说这有没有多费劲确实比甩一个 admin 出去费劲但一旦出问题责任边界清晰太多了。4.2 证书轮换与访问安全证书是有有效期的自签证书到期之后 Dashboard 不会自动续期你需要重新生成并更新 Secret然后滚动重启 Deployment。具体步骤生成新证书和 key更新 Secret然后删除当前运行的 Pod让 Deployment 重新创建一个新的 Pod。kubectl -n kubernetes-dashboard delete secret kubernetes-dashboard-certs kubectl -n kubernetes-dashboard create secret tls kubernetes-dashboard-certs \ --certdashboard.crt --keydashboard.key kubectl -n kubernetes-dashboard rollout restart deployment kubernetes-dashboard为了避免到期时手忙脚乱建议在证书到期前一个月设一个日历提醒。如果你用 cert-manager 管理证书还可以把证书存放在 Secret 里然后通过脚本定期刷新 Secret 并 rollout restart。生产环境我强烈建议在 Ingress 层做 IP 白名单或者 OAuth2 代理不要直接把 Dashboard 裸奔到公网。可以先通过内部身份系统登录再转发到 Dashboard 的 Token 登录页。这样即使 Token 泄露攻击者也得先过你那层身份验证。4.3 多集群如何统一管理总有人问我有好几套集群难道每套都部署一遍 Dashboard然后记好几个地址吗最简单的方式就是每套集群各部署一套 Dashboard各看各的。但如果你希望在一个页面里快速切换集群场景Dashboard 本身是不支持的。这个时候我会推荐在客户端层面做聚合比如使用支持多集群配置的 kubeconfig。本地kubectl proxy的时候按 context 切换集群然后 Dashboard 的地址不变只是拿到的是不同集群的数据。或者更进一步可以用开源的统一管理面板把多个集群的 Dashboard 集成进去。但我一般不在生产环境引入额外的控制平面组件因为多一个管理入口就多一份攻击面。实际场景中两三个集群分开管理并不算麻烦关键是把账号密码和 Token 的管理制度化。5. 常见问题与排查技巧实录5.1 经典报错速查表我整理了一些实际操作中经常出现的错误直接用表格看比较方便。现象可能原因处理方式Pod 一直 CrashLoopBackOff证书 Secret 格式错误或 API 版本不兼容先看日志重建 Secret删除 Pod 让它重新创建打开页面提示 403 ForbiddenToken 权限不足检查 ServiceAccount 的 ClusterRoleBinding 绑定关系登录时提示 Could not get tokencreate token 命令的 namespace 打错了确认 ServiceAccount 在 kubernetes-dashboard 命名空间不存在Ingress 访问 502 Bad Gateway缺少backend-protocol: HTTPS在 Ingress annotations 里加上 HTTPS 后端声明页面白屏、接口一直 loadingDashboard 版本和集群 ApiServer 版本不兼容换成版本兼容的 DashboardNodePort 无法访问防火墙或安全组没放行确认节点端口可达镜像一直 ImagePullBackOff拉不到 docker hub 的镜像改内网镜像源或手动导入镜像这几类问题占了我排查工作量的八成。别怕报错只要你先看日志再按这个速查表对一遍基本都能快速定位。5.2 排查时一定要先看日志Dashboard 的日志是排查问题最重要的入口。不管 UI 上显示什么日志里一般都有更明确的错误信息。kubectl -n kubernetes-dashboard logs -f deployment/kubernetes-dashboard如果你在浏览器里登录时每次都看到 403日志里会有一条类似levelerror msgno user authenticated之类的信息这时候就去看你的 Token 是不是过期或者 RBAC 是不是没有绑定好。还有一个很隐秘的问题是 Dashboard 和 metrics-scraper 之间的连接问题。很多时候页面能打开但 CPU、内存图表不显示大概率 metrics-scraper Pod 没有正常工作。直接看 scraper 的日志如果有连接失败的错误检查一下metrics.k8s.io这个 API 是否在集群里可用。没有安装 metrics-server 的集群Dashboard 的图形部分就是残缺的。5.3 避坑笔记与独家技巧关于 k8s dashboard 部署安装我还有几个经验要分享。第一进入生产集群之前先做一次离线演练。演练内容就是在没有外网的情况下把 recommended.yaml 和镜像全部搞定。这一步做好你在任何客户环境都不会被网络问题卡住。第二千万不要手动改 recommended.yaml 里的 Service 类型为 LoadBalancer 就以为万事大吉。LoadBalancer 会创建云厂商的负载均衡器一来可能有费用产生二来直接暴露到了公网。如果真要暴露配合安全组和访问限制一起做。第三如果你把 Dashboard 安装在公司内网的 Kubernetes 集群记得在登录页面选择 Kubeconfig 方式时使用加密后的 Token或者说使用短期凭证。长期 Token 一旦泄露等于把整个集群管理权限都暴露了。每过一段时间重新生成一次凭证算是个好习惯。第四Dashboard 页面上可以看到日志但日志刷新是手动的。你如果习惯在终端里盯日志直接用 kubectl 更方便浏览器里的日志功能更适合新手点一点。第五也是我自己踩过的一个最隐蔽的问题Dashboard 2.7.0 以上版本默认开启 CSRF 保护。如果你通过某些脚本或者前端工具直接调用 Dashboard API可能会遇到 CSRF 校验失败。这种情况不能关保护而是要在请求头里带上正确 token 去适配。6. 个人经验总结与最后几个建议写到这我回头想想这些年做过的 k8s dashboard 部署安装最核心的其实不是“安装”这一步而是安装完成之后你怎么管理和访问它。安装本身只有一条命令的事真正花时间的是版本选型、证书、权限和访问策略。我自己碰过太多同事拿起 recommended.yaml 就直接 apply然后页面开了Token 一贴看到资源全出来了就以为大功告成。直到某一天发现某台集群的 Dashboard 连上之后很多页面报错才意识到版本问题。所以最后几个建议供参考一是养成记录版本的习惯。集群升级Dashboard 也要跟着评估随手记一下当前集群和 Dashboard 的版本组合方便后面排查。二是把证书和权限策略代码化写进团队的知识库里而不是靠某个人脑袋记着。这样即使部署的人休假了其他同学也能接手。三是务必控制访问入口。Dashboard 是管理工具不是给全公司人浏览的。让你需要的人用适当的权限去访问而不是所有人共享一个超管账号。四是不管多忙先做一遍离线部署演练。网络环境变数太大你永远不想在上线前一天被镜像仓库连不上卡住。这些经验看起来不起眼但一次事故的价值往往就值回整个部署流程的十倍苦工。希望这篇 k8s dashboard 部署安装的经验总结能帮你少走弯路把有限的时间留给真正有价值的问题。
1. 部署前的版本选型与方案权衡1.1 版本匹配为什么是第一个坑凡是碰过 k8s dashboard 部署安装的几乎都吃过版本不匹配的亏。Kubernetes 的版本迭代速度快而 Dashboard 作为官方社区维护的可视化面板它的兼容列表往往滞后于集群版本。你拿一个新的 Dashboard 版本去对接一个老旧的集群或者反过来最常见的结局就是 Pod 一直 CrashLoopBackOff打开页面之后接口报错节点和 Pod 列表刷不出来界面空白一片。所以不管你是给生产环境搭管理界面还是在自己电脑上用 kind / minikube 跑一套测试集群第一步先说死先查清楚你的集群版本再决定用哪个 Dashboard 版本。Kubernetes API 是带组和版本号的Dashboard 内部会调用 cluster-info、metrics.k8s.io、apps/v1、batch/v1 这些 API哪怕只是小版本不匹配也可能导致部分接口返回 403 或者直接 EOF。我在一个测试环境里踩过典型例子集群是 Kubernetes 1.29当时装 Dashboard 2.7.0 完全正常但某同事先在 1.28 集群上手动改了镜像标签去拉 3.0 的新版结果 API 兼容层直接罢工Deployment 的副本数都显示不出来。后来切回匹配版本一切恢复。一个比较稳妥的做法在部署菜单还没有变成 Helm 默认之前先去 GitHub 的 releases 页面看那个版本对应的 Kubernetes 最低版本按图索骥。如果你不喜欢翻文档也有个偷懒的办法——用 manifests 子目录里的 recommended.yaml它所绑定的版本一般经过社区回归测试。但我的建议是不要把“latest”标签用于任何生产环境因为你永远不知道下一次 apply 会不会给你推送一个 API 变更的版本。1.2 三种部署方式怎么选k8s dashboard 部署安装的主流方式有三种我按自己的使用频率排序第一种官方 YAML 直接 apply。打开官方 GitHub 仓库找到 releases复制对应版本下的recommended.yaml链接然后kubectl apply -f。这是最省事、最不容易出错的路径也是本文后面实操部分采用的方式。它适合第一次部署、测试环境快速验证和想快速看效果的人所有配置项都集中在 YAML 里方便我们按自己的需求做修改。第二种用 Helm Chart。Dashboard 官方没有单独的 Helm 仓库但社区 Chart 挺多也有维护得不错的。Helm 的优势是通过 values.yaml 暴露配置项比如证书、副本数、镜像仓库地址改起来比手动修改官方 YAML 要干净。但社区 Chart 的维护质量和官方 YAML 不同步偶尔会出现字段名对不上的情况比如extraArgs的写法变了导致你改了不生效。如果你对 Helm 本身不熟我不建议用它作为第一选择。第三种自己拼 YAML。这种属于“受控环境”的玩法比如无外网环境下的离线安装或者公司安全合规要求所有镜像必须走内部镜像仓库。操作上就是把 recommended.yaml 下载下来批量替换 image 字段为内网地址然后 apply。依赖的镜像是kubernetesui/dashboard和kubernetesui/metrics-scraper提前在能联网的机器上docker pull然后docker save再传到内网docker load整个流程就闭环了。我个人的建议是优先官方 YAML后续需要做证书、Ingress 接入再在官方 YAML 基础上改。别把问题复杂化。2. 证书、存储与命名空间的关键细节2.1 证书方式决定了浏览器地址栏长什么样很多人在 k8s dashboard 部署安装完成、Pod 也 Running 了结果访问的时候被浏览器拦截这是因为 Dashboard 默认用的是自签证书。这个证书在启动时会自动生成但你换个设备访问又要重新点一次信任烦得很。如果你只是本机kubectl proxy访问其实可以完全不关心证书问题。但如果要通过 NodePort 或 Ingress 暴露建议在部署前就把证书问题想清楚。常见的做法有两种第一种使用正式的 CA 签发的证书。就是先去申请一张覆盖你域名的证书然后把 tls.crt 和 tls.key 存成 Kubernetes SecretSecret 的名字必须是kubernetes-dashboard-certs命名空间是kubernetes-dashboard。Dashboard 启动时会自动读取这个 Secret 里的证书然后你的浏览器就不会报警了。关键点是你需要在 apply 官方 YAML 之前把 Secret 创建好或者先 apply 再重建 Deployment否则 Pod 启动时发现没有证书就会重新生成自签证书。第二种自建内部 CA。公司内部有很多用户却不想暴露公网就用 OpenSSL 自建 CA签发一张给 Dashboard 域名用然后把 CA 下发到团队所有人的电脑上导入信任列表。这一步做下来浏览器会显示证书受信任也不用每台机器单独点风险提示。我干活时的细节是用 OpenSSL 签发证书之前先检查 SAN 字段证书的 Subject Alternative Name 必须包含你的 Dashboard 域名不能只写在 CommonName 里。这个字段现在浏览器强制执行漏了就等着每台电脑都报错然后你到处解释为什么明明证书是“对”的却不被信任。openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -keyout dashboard.key \ -out dashboard.crt这个只是生成自签证书生产环境请走公司 CA 系统。把证书转成 Secretkubectl -n kubernetes-dashboard create secret tls kubernetes-dashboard-certs \ --certdashboard.crt --keydashboard.key2.2 存储与命名空间的设计思路Dashboard 本身是无状态应用它不需要持久化存储因为它不做数据落盘。但它依赖 metrics-server 或者 metrics-scraper 来展示集群的 CPU、内存监控数据metrics-scraper 同样是无状态的。真正的“存储”问题出现在你的浏览器端。Dashboard 把用户偏好、主题设置之类的东西存在了 localStorage 里所以不存在跨设备同步的问题。不要为了 Dashboard 单独建 PVC那是白费劲。比较值得关注的是命名空间的选择。官方 YAML 固定把什么东西都放在kubernetes-dashboard这个命名空间里。你可以用这个名字也可以改成自己的命名空间但强烈建议保持默认。原因是官方文档里所有证书、ServiceAccount、ClusterRoleBinding 的例子都默认指向这个命名空间你一旦改名后面排查问题的时候看到资料所有命令都要自己改一遍烦不烦而且多个环境统一使用同一个命名空间也方便脚本化处理。生产环境我见过有人把 Dashboard 的 ServiceAccount 权限放大到 cluster-admin这确实最省事但不是最安全的做法。后面我会单独讲权限收紧的问题。3. 实操全过程从下载到访问3.1 下载 recommended.yaml 并检查内容先把 Dashboard 的 YAML 文件拉下来。wget https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml如果你的网络访问 GitHub 比较费力可以用镜像站或者先下到本地再传上去。我一般在服务器上用 wget如果失败就用代理下载再传。注意下载完之后别急着直接 apply先把关键内容读一遍。我习惯打开 YAML 之后重点看几个地方Service 是否定义了 type默认是 ClusterIPDeployment 和 metrics-scraper 的镜像版本ServiceAccount、ClusterRoleBinding 的配置--namespacekubernetes-dashboard参数是否存在。这一步是为了确认这份 YAML 里没有任何让你意外的配置。尤其是当初遇到过某些第三方包往里面塞了一些额外的网络钩子所以自己检查一遍最稳。3.2 执行部署并检查 Pod 状态确认无异常后再执行kubectl apply -f recommended.yaml官方 YAML 的内容比较多包含 Namespace、ServiceAccount、Secret、ConfigMap、Deployment、Service 等多个资源。执行完以后官方也会提示你查看kubernetes-dashboard命名空间下的资源状态。kubectl -n kubernetes-dashboard get pods正常情况你会看到两个 Pod一个是 dashboard一个是 metrics-scraper状态都是 Running。如果出现 ImagePullBackOff通常是镜像拉取失败先确认集群能不能访问 Docker Hub不行就按第一节的方法改内网镜像源。如果是 CrashLoopBackOff优先看日志。kubectl -n kubernetes-dashboard logs -l k8s-appkubernetes-dashboard最常见的原因就是证书 Secret 被改了而 Pod 没有重新创建或者 API 版本不兼容。看日志时留意有没有Failed to start和证书相关的关键字。3.3 创建一个可登录的账号与 TokenDashboard 登录有两种方式Token 和 Kubeconfig。如果你只是开发环境自己用用 Token 最简单。官方 YAML 本身不创建专门的登录用户。你在 Postman 调接口一样得有身份才能访问Dashboard 默认拿 Kubernetes ServiceAccount 认证。所以先创建一个只读的管理员账号。我这里通常创建一个叫 dev-admin 的 ServiceAccountapiVersion: v1 kind: ServiceAccount metadata: name: dev-admin namespace: kubernetes-dashboard然后绑定到集群角色。如果你只是日常看资源用 view 角色就够了但修改不了资源。如果整个测试集群就你自己在用也可以给 cluster-admin生产环境则千万不要。apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: dev-admin roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: cluster-admin subjects: - kind: ServiceAccount name: dev-admin namespace: kubernetes-dashboard保存为 dashboard-account.yaml然后kubectl apply -f dashboard-account.yaml接着查询 Token。旧版 Kubernetes 的 ServiceAccount 会对应一个长期有效的 Secret我们可以直接获取。新版 Kubernetes 从 1.24 开始ServiceAccount 不再自动创建 Secret而是创建 TokenRequest所以我们更推荐用下面这个命令生成一个有有效期的 Tokenkubectl -n kubernetes-dashboard create token dev-admin这条命令的输出就是一份访问令牌把它复制下来在登录页面选择 Token 方式粘贴即可。需要注意这种 Token 有过期时间默认一小时左右。你要做自动化或者给别的同事用就得用定期刷新机制。临时用就无所谓过期了再生成一次。3.4 开启访问通道的三条路Pod 跑起来了账号建好了接下来就是怎么打开页面。第一条路kubectl proxy。在本地执行kubectl proxy然后浏览器访问http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/。这个方式对零暴露最安全但路径又长又丑只适合本地快速看一眼。第二条路NodePort。修改 Dashboard Servicekubectl -n kubernetes-dashboard edit svc kubernetes-dashboard把 type 改成 NodePort然后kubectl -n kubernetes-dashboard get svc查看被分配的节点端口。浏览器访问https://任何节点IP:端口。测试集群懒人方案但生产环境不建议因为直接把端口暴露到局域网缺少额外的认证保护。第三条路Ingress。这也是我生产环境用的方式。需要集群里已有 Ingress Controller然后创建一个 Ingress 对象apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: kubernetes-dashboard namespace: kubernetes-dashboard annotations: nginx.ingress.kubernetes.io/backend-protocol: HTTPS spec: rules: - host: dashboard.example.com http: paths: - path: / pathType: Prefix backend: service: name: kubernetes-dashboard port: number: 443这里最关键的是backend-protocol: HTTPS注解。因为 Dashboard Service 的入口协议是 HTTPS如果你的 Ingress 不声明这一点nginx 会用 HTTP 去连后端结果就是 502。这个坑我见过不止一个人踩过。如果公司内部没有 DNS你可以改本机 hosts 文件把dashboard.example.com指到 Ingress Controller 所在节点。浏览器访问时如果证书是合法 CA 签的就不会报警。4. 生产环境加固与日常运维4.1 RBAC 权限怎么给才算合理k8s dashboard 部署安装完成之后最让人纠结的就是权限管理。默认情况下你手动绑定的 dev-admin 如果是 cluster-admin那整个集群任何一个 namespace 都能改包括 kube-system。生产环境这是不可接受的。更合理的做法是按团队成员的分工分配权限。普通开发人员只需要查看工作负载、Service、ConfigMap可以给 view。需要发布应用的人可以在指定 namespace 里授予 edit。而需要管理集群节点的 SRE才需要 cluster-admin。我在公司内部实践下来会为不同团队创建不同的 ServiceAccount每个账号绑定相应的 Role 或 ClusterRole。比如前端组只能看前端 ns 下的资源绑定 view后端组负责某几个环境绑定 edit运维组绑定自定义 Role给到 secrets 的读取权限和 Deployment 的上下线权限。这样 Dashboard 登录接口签发的 Token 是不同的登录进去能看到的资源范围也是隔离的。你要说这有没有多费劲确实比甩一个 admin 出去费劲但一旦出问题责任边界清晰太多了。4.2 证书轮换与访问安全证书是有有效期的自签证书到期之后 Dashboard 不会自动续期你需要重新生成并更新 Secret然后滚动重启 Deployment。具体步骤生成新证书和 key更新 Secret然后删除当前运行的 Pod让 Deployment 重新创建一个新的 Pod。kubectl -n kubernetes-dashboard delete secret kubernetes-dashboard-certs kubectl -n kubernetes-dashboard create secret tls kubernetes-dashboard-certs \ --certdashboard.crt --keydashboard.key kubectl -n kubernetes-dashboard rollout restart deployment kubernetes-dashboard为了避免到期时手忙脚乱建议在证书到期前一个月设一个日历提醒。如果你用 cert-manager 管理证书还可以把证书存放在 Secret 里然后通过脚本定期刷新 Secret 并 rollout restart。生产环境我强烈建议在 Ingress 层做 IP 白名单或者 OAuth2 代理不要直接把 Dashboard 裸奔到公网。可以先通过内部身份系统登录再转发到 Dashboard 的 Token 登录页。这样即使 Token 泄露攻击者也得先过你那层身份验证。4.3 多集群如何统一管理总有人问我有好几套集群难道每套都部署一遍 Dashboard然后记好几个地址吗最简单的方式就是每套集群各部署一套 Dashboard各看各的。但如果你希望在一个页面里快速切换集群场景Dashboard 本身是不支持的。这个时候我会推荐在客户端层面做聚合比如使用支持多集群配置的 kubeconfig。本地kubectl proxy的时候按 context 切换集群然后 Dashboard 的地址不变只是拿到的是不同集群的数据。或者更进一步可以用开源的统一管理面板把多个集群的 Dashboard 集成进去。但我一般不在生产环境引入额外的控制平面组件因为多一个管理入口就多一份攻击面。实际场景中两三个集群分开管理并不算麻烦关键是把账号密码和 Token 的管理制度化。5. 常见问题与排查技巧实录5.1 经典报错速查表我整理了一些实际操作中经常出现的错误直接用表格看比较方便。现象可能原因处理方式Pod 一直 CrashLoopBackOff证书 Secret 格式错误或 API 版本不兼容先看日志重建 Secret删除 Pod 让它重新创建打开页面提示 403 ForbiddenToken 权限不足检查 ServiceAccount 的 ClusterRoleBinding 绑定关系登录时提示 Could not get tokencreate token 命令的 namespace 打错了确认 ServiceAccount 在 kubernetes-dashboard 命名空间不存在Ingress 访问 502 Bad Gateway缺少backend-protocol: HTTPS在 Ingress annotations 里加上 HTTPS 后端声明页面白屏、接口一直 loadingDashboard 版本和集群 ApiServer 版本不兼容换成版本兼容的 DashboardNodePort 无法访问防火墙或安全组没放行确认节点端口可达镜像一直 ImagePullBackOff拉不到 docker hub 的镜像改内网镜像源或手动导入镜像这几类问题占了我排查工作量的八成。别怕报错只要你先看日志再按这个速查表对一遍基本都能快速定位。5.2 排查时一定要先看日志Dashboard 的日志是排查问题最重要的入口。不管 UI 上显示什么日志里一般都有更明确的错误信息。kubectl -n kubernetes-dashboard logs -f deployment/kubernetes-dashboard如果你在浏览器里登录时每次都看到 403日志里会有一条类似levelerror msgno user authenticated之类的信息这时候就去看你的 Token 是不是过期或者 RBAC 是不是没有绑定好。还有一个很隐秘的问题是 Dashboard 和 metrics-scraper 之间的连接问题。很多时候页面能打开但 CPU、内存图表不显示大概率 metrics-scraper Pod 没有正常工作。直接看 scraper 的日志如果有连接失败的错误检查一下metrics.k8s.io这个 API 是否在集群里可用。没有安装 metrics-server 的集群Dashboard 的图形部分就是残缺的。5.3 避坑笔记与独家技巧关于 k8s dashboard 部署安装我还有几个经验要分享。第一进入生产集群之前先做一次离线演练。演练内容就是在没有外网的情况下把 recommended.yaml 和镜像全部搞定。这一步做好你在任何客户环境都不会被网络问题卡住。第二千万不要手动改 recommended.yaml 里的 Service 类型为 LoadBalancer 就以为万事大吉。LoadBalancer 会创建云厂商的负载均衡器一来可能有费用产生二来直接暴露到了公网。如果真要暴露配合安全组和访问限制一起做。第三如果你把 Dashboard 安装在公司内网的 Kubernetes 集群记得在登录页面选择 Kubeconfig 方式时使用加密后的 Token或者说使用短期凭证。长期 Token 一旦泄露等于把整个集群管理权限都暴露了。每过一段时间重新生成一次凭证算是个好习惯。第四Dashboard 页面上可以看到日志但日志刷新是手动的。你如果习惯在终端里盯日志直接用 kubectl 更方便浏览器里的日志功能更适合新手点一点。第五也是我自己踩过的一个最隐蔽的问题Dashboard 2.7.0 以上版本默认开启 CSRF 保护。如果你通过某些脚本或者前端工具直接调用 Dashboard API可能会遇到 CSRF 校验失败。这种情况不能关保护而是要在请求头里带上正确 token 去适配。6. 个人经验总结与最后几个建议写到这我回头想想这些年做过的 k8s dashboard 部署安装最核心的其实不是“安装”这一步而是安装完成之后你怎么管理和访问它。安装本身只有一条命令的事真正花时间的是版本选型、证书、权限和访问策略。我自己碰过太多同事拿起 recommended.yaml 就直接 apply然后页面开了Token 一贴看到资源全出来了就以为大功告成。直到某一天发现某台集群的 Dashboard 连上之后很多页面报错才意识到版本问题。所以最后几个建议供参考一是养成记录版本的习惯。集群升级Dashboard 也要跟着评估随手记一下当前集群和 Dashboard 的版本组合方便后面排查。二是把证书和权限策略代码化写进团队的知识库里而不是靠某个人脑袋记着。这样即使部署的人休假了其他同学也能接手。三是务必控制访问入口。Dashboard 是管理工具不是给全公司人浏览的。让你需要的人用适当的权限去访问而不是所有人共享一个超管账号。四是不管多忙先做一遍离线部署演练。网络环境变数太大你永远不想在上线前一天被镜像仓库连不上卡住。这些经验看起来不起眼但一次事故的价值往往就值回整个部署流程的十倍苦工。希望这篇 k8s dashboard 部署安装的经验总结能帮你少走弯路把有限的时间留给真正有价值的问题。
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
