多集群与访问管理：kubeconfig、上下文与服务账号

一套集群不够用的时候#

前面十几章里你的世界只有一套集群，所有团队、所有环境都靠 Namespace 隔开——这在小规模下够用，因为第 12 章 命名空间与 RBAC 已经把「逻辑隔离」做得很好了。

但隔离是有层次的。Namespace 隔离的是对象的名字和权限，它隔离不了控制面本身：CRD 的版本、Ingress 控制器、CNI 插件、apiserver 参数都是集群级的，某个命名空间里的实验把 etcd 写爆或把 CRD 升坏，其他命名空间会一起受影响。所以「要不要多集群」不是偏好问题，而是隔离级别问题。

多集群从来不是目标，你要的是那个隔离级别。代价是把问题从「隔离」换成「混乱」：

kubeconfig 的四段结构#

kubeconfig 是 kubectl 的配置文件，默认在 ~/.kube/config。它只回答四个问题，而且把这四个问题拆成了四段——新手容易把它当成一坨黑盒，其实拆开看非常简单。

apiVersion: v1
kind: Config
clusters: # ① 去哪：集群地址与 CA
  - name: prod
    cluster:
      server: https://10.0.0.100:6443
      certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0t...
users: # ② 我是谁：凭证
  - name: prod-ci
    user:
      token: eyJhbGciOiJSUzI1NiIsImtpZCI6...
contexts: # ③ 把 ① ② 绑起来，再补一个默认命名空间
  - name: prod-ci
    context:
      cluster: prod
      user: prod-ci
      namespace: demo
current-context: prod-ci # ④ 现在用哪个 context

关键是理解 clusters 和 users 是「零件」，context 才是「组合」：

这套设计的好处是组合自由：同一个 prod 集群可以同时有「我的证书 context」「CI 的 SA token context」「只读排查 context」；同一个身份也能访问多套集群。所以别按「一台集群一份配置」理解，要按「一个身份 + 一套集群 = 一个 context」理解。

  KUBECONFIG=~/.kube/configs/dev.yaml:~/.kube/configs/prod.yaml
        │  kubectl 按顺序合并，同名键以「第一个文件」为准
        ▼
  ┌─ ① clusters（去哪）    dev → https://dev:6443, prod → https://prod:6443
  ├─ ② users（我是谁）     dev-admin → 证书, prod-ci → SA token / exec 插件
  ├─ ③ contexts          prod-ci = cluster prod + user prod-ci + ns demo
  └─ ④ current-context   prod-ci    ←「现在连谁」由这一行决定
        │  kubectl get pods   或   kubectl --context=prod get pods
        ▼
  context "prod" ─┬─ cluster prod ─► https://prod:6443 ─► apiserver
                  └─ user prod-ci ─► token / 证书 / exec 插件

KUBECONFIG：多文件合并与优先级#

真实工作里你不会把所有集群塞进一个 ~/.kube/config——那样任何一次误操作都可能波及全局。推荐一套集群一个文件，用环境变量拼起来：

mkdir -p ~/.kube/configs
cp ~/Downloads/dev-kubeconfig.yaml  ~/.kube/configs/dev.yaml
cp ~/Downloads/prod-kubeconfig.yaml ~/.kube/configs/prod.yaml
# 冒号分隔，顺序即优先级
export KUBECONFIG="$HOME/.kube/configs/dev.yaml:$HOME/.kube/configs/prod.yaml"

合并规则只有一条要记：同名键以第一个文件里的值为准。上面的顺序下，如果两份文件里都有叫 prod 的 cluster，dev.yaml 里那份会赢——这也是「连不上集群」这类怪问题的常见根源。优先级从高到低是：

1. 命令行 --kubeconfig=/path/to/config（只读这一个文件，忽略 KUBECONFIG）
2. 环境变量 KUBECONFIG（冒号分隔，按顺序合并）
3. 默认的 ~/.kube/config

kubectl config view --minify          # 只看当前 context 用到的部分
kubectl config view --flatten         # 看多文件合并后的最终结果
kubectl config view --raw             # 未脱敏（会暴露 token 与私钥，别外传）

上下文实操：切换、改默认命名空间、重命名#

日常最高频的三个动作是切 context、改当前 context 的默认命名空间、给 context 起个看得懂的名字。

kubectl config get-contexts
kubectl config use-context prod
kubectl config set-context --current --namespace=demo
kubectl config rename-context prod prod-bj   # 改名不影响连接信息

kubectl config current-context
kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}{"\n"}'
kubectl config view --minify -o jsonpath='{..namespace}{"\n"}'
kubectl --context=prod-bj -n kube-system get pods

只读查询建议永远显式带 --context 和 -n，尤其是脚本里——上下文是全局状态，脚本一旦依赖它，就会在别人的机器上做出你没预期的事。再加一道人眼防线，让提示符把当前 context 显示出来：

# 一行版（bash，放进 ~/.bashrc）
PS1='[$(kubectl config current-context 2>/dev/null)] \W $ '
# 更完整的选择是 kube-ps1（macOS: brew install kube-ps1；Linux 直接下载脚本）
source "$(brew --prefix)/opt/kube-ps1/share/kube-ps1.sh"
PS1='[\u@\h \W $(kube_ps1)]\$ '
KUBE_PS1_SYMBOL_ENABLE=false

一行版每次出提示符都会调一次 kubectl，配置多或网络不通时会有轻微卡顿。核心价值只有一个：prompt 里写着 prod 的时候，你会本能地多看一眼。

认证方式对比：证书、token、OIDC、exec 插件#

kubeconfig 的 users 段决定「你是谁」，凭证有四种常见形态。选型的核心不是哪个更先进，而是轮转难度——凭证发出去，你多久能收回。

OIDC 与 exec 插件在配置上是一回事，都写在 user.exec 里，由 kubectl 在每次请求前调用外部命令换 token：

users:
  - name: cloud-oidc
    user:
      exec:
        apiVersion: client.authentication.k8s.io/v1
        command: kubectl
        args: [oidc-login, get-token, --oidc-client-id=kubernetes]
        interactiveMode: IfAvailable

具体插件与参数取决于你的 IdP 与集群发行版。给「人」发凭证的长期答案是 OIDC/SSO，给「机器」发凭证的答案是短期 SA token，证书尽量留给集群组件自己用。

ServiceAccount 与 kubeconfig 的关系#

ServiceAccount（SA）本来是给 Pod 用的身份，它同样可以给人和流水线用：把 kubeconfig 的 user 段填成一份 SA 短期 token，这份配置的全部权限就被 SA 绑定的 Role 限制住了。

kubectl create namespace demo
kubectl -n demo create serviceaccount ci-deploy
kubectl -n demo create rolebinding ci-deploy-edit \
  --clusterrole=edit --serviceaccount=demo:ci-deploy

TOKEN=$(kubectl -n demo create token ci-deploy --duration=24h)

kubectl --kubeconfig=./demo-ci.kubeconfig config set-cluster prod \
  --server=https://10.0.0.100:6443 \
  --certificate-authority=/etc/kubernetes/pki/ca.crt --embed-certs=true
kubectl --kubeconfig=./demo-ci.kubeconfig config set-credentials ci-deploy --token="$TOKEN"
kubectl --kubeconfig=./demo-ci.kubeconfig config set-context demo-ci \
  --cluster=prod --user=ci-deploy --namespace=demo
kubectl --kubeconfig=./demo-ci.kubeconfig config use-context demo-ci

KUBECONFIG=./demo-ci.kubeconfig kubectl auth can-i --list -n demo
# 应当被拒绝
KUBECONFIG=./demo-ci.kubeconfig kubectl auth can-i delete pods -n demo
KUBECONFIG=./demo-ci.kubeconfig kubectl auth can-i list nodes
# 管理员视角复核同一个身份
kubectl auth can-i --list -n demo --as=system:serviceaccount:demo:ci-deploy

为什么不要把集群 admin 证书发给同事#

很多团队的默认操作是把 ~/.kube/config 复制给同事，那份配置里的身份通常叫 kubernetes-admin，绑定的是 cluster-admin：

• 权限没有边界：一条 kubectl delete namespace 就能删掉整个命名空间，甚至能改 RBAC 把自己变成永久管理员。
• 无法按人吊销：Kubernetes 没有内置的证书吊销列表（CRL），证书签出去只能等到期或轮换整个 CA。
• 审计失去意义：审计日志里所有操作都是 kubernetes-admin，出事时分不清是谁干的。
• 复制成本为零：一份配置在群里传一圈，你根本不知道有多少份副本。

正确顺序是：人走 OIDC/SSO，机器走 SA 短期 token，证书留给集群组件。真需要临时给同事排查权限，用 --duration=1h 签一份，排查完让它自然过期。证书过期是同一类问题，kubeadm 集群一句话检查：

sudo kubeadm certs check-expiration   # 列出各组件证书的到期时间

kubeadm 签发的客户端证书默认 1 年、CA 默认 10 年；续期与重启控制面组件的步骤取决于你的发行版与部署方式，托管集群一般不需要你操心。

多集群切换的工程化#

手上有 3 套以上集群时，「切 context」本身就成了工程问题，第一步是建立目录约定：

~/.kube/
├── config                     # 本机默认，尽量保持最小
└── configs/
    ├── bj1-dev.yaml           # 命名：<地区机房>-<集群用途>.yaml
    ├── bj1-prod-ro.yaml       # 只读凭证单独一份，名字里写清 -ro
    └── zw1-prod.yaml

export KUBECONFIG="$HOME/.kube/configs/bj1-dev.yaml:$HOME/.kube/configs/zw1-prod.yaml"
kx ctx bj1-prod     # kubie：每个 shell 独立上下文，提示符显示 [bj1-prod|default]

三条硬规矩：一集群一文件（合并顺序带来的歧义比省事更重要）、只读与可写凭证分文件（排查时用只读那份，delete 根本打不出去）、CI 用独立的最小权限 SA，token 由 secret 注入、现签现用。日常还可以给每套集群额外准备一份只读 kubeconfig（绑定内置 view ClusterRole），专供看板与临时排查。参考：reference/k8s-in-action/k8s/client.md

CI 里的典型写法是显式指定文件、不依赖全局状态，并在动手前先做权限预检：

# token 由 CI 的 secret 注入环境变量，拼出只属于本次构建的配置
kubectl --kubeconfig=/tmp/ci.kubeconfig config set-cluster prod \
  --server=https://10.0.0.100:6443 --certificate-authority=/tmp/ci-ca.crt --embed-certs=true
kubectl --kubeconfig=/tmp/ci.kubeconfig config set-credentials ci-deploy --token="$KUBE_TOKEN"
kubectl --kubeconfig=/tmp/ci.kubeconfig config set-context ci \
  --cluster=prod --user=ci-deploy --namespace=demo
kubectl --kubeconfig=/tmp/ci.kubeconfig config use-context ci
# 预检：权限不对立刻失败，而不是 apply 到一半才报 403
kubectl --kubeconfig=/tmp/ci.kubeconfig auth can-i create deployment -n demo
kubectl --kubeconfig=/tmp/ci.kubeconfig apply -f deploy/

更进一步的方案是让 CI 通过云厂商的 workload identity 换取集群凭证（不需要长期 secret），是否支持取决于你的云与集群版本。部署链路的完整做法见 GitOps 持续交付：把 kubectl 直连换成 ArgoCD 之后，CI 甚至不需要持有任何集群凭证。

网络互通与数据面：先记住一句话#

不同集群的 Pod 网段默认互不可达，DNS 也各自独立——不要把多套集群当成一套用。跨集群访问通常通过 Ingress/网关加显式 DNS 完成，而不是假装它们在同一个网络里；规划阶段唯一要做对的事是让各集群的 Pod/Service 网段互不重叠（和 集群部署 里的网段规划是同一件事）。真正意义上的「多集群 Service 发现」属于更高级主题，本站在规划中，具体实现取决于你的 CNI 与网关选型，本章不展开。

用 sa-management 集中管理人员凭证#

给人和流水线发凭证时，最容易失控的是「SA 散落在各个业务命名空间、没人说得清谁有什么」。工程化做法是把权限主体和权限规则分开放：面向人员的 SA 统一建在一个专门的命名空间（例如 sa-management），而 Role / RoleBinding 仍然建在业务命名空间里——因为 Role 建在哪个命名空间，就只赋予那个命名空间的权限。

apiVersion: v1
kind: ServiceAccount
metadata:
  name: bj1-harbor-developer
  namespace: sa-management
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: bj1-harbor-developer
  namespace: harbor
rules:
  - apiGroups: [""]                # core 组（APIVERSION 为 v1）用空字符串
    resources: ["pods", "services", "configmaps"]
    verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: bj1-harbor-developer
  namespace: harbor
subjects:
  - kind: ServiceAccount
    name: bj1-harbor-developer
    namespace: sa-management
roleRef:
  kind: Role
  name: bj1-harbor-developer
  apiGroup: rbac.authorization.k8s.io

命名建议 <集群>-<团队或业务>-<角色>，一眼看出它给谁、给哪套集群、什么权限。两个易错点：apiGroups 对 core 组要写 "" 而不是 v1；用 kubectl api-resources 的 NAMESPACED 列判断该用 Role 还是 ClusterRole——nodes、storageclasses、namespaces 这类集群级资源只能用 ClusterRole。通常还要给团队一份命名空间查看权限，否则 kubectx 这类插件列不出资源。参考：reference/k8s-in-action/k8s/sa-management/README.md

凭证轮转：谁持有、多久换、怎么吊销#

发出去只是开始。给每类凭证定一个轮转节奏，比事后追查「谁还有权限」省事：

轮转清单要能回答四个问题：这份凭证现在在谁手里（人 / CI / 某个脚本）、权限边界是什么、什么时候到期、怎么在五分钟内吊销。前三项靠命名与集中管理解决，最后一项决定你能不能放心给「人」发短期 token 而不是长期证书。定期用 kubectl -n sa-management get sa 清点在用身份，再用 kubectl auth can-i --list -n harbor --as=system:serviceaccount:sa-management:bj1-harbor-developer 复核权限边界。

常见错误速查表#

访问类问题的排查顺序很固定：先确认「我是谁」（认证），再确认「能不能」（授权），最后才怀疑网络。

自测题#

小结#

• 多集群不是目标，隔离级别才是；它换来硬隔离，也带来配置漂移、凭证翻倍、观测割裂和网络不通。
• kubeconfig 分四段：clusters 回答「去哪」、users 回答「我是谁」、contexts 把两者绑起来再加默认命名空间、current-context 决定现在用哪个。
• KUBECONFIG 用冒号分隔多个文件，同名键以第一个文件为准；优先级是 --kubeconfig > KUBECONFIG > ~/.kube/config。
• 切集群前先 kubectl config current-context 和 kubectl config view --minify，脚本里一律显式 --context 与 -n，提示符显示 context 是一道廉价防线。
• 人用 OIDC/SSO，机器用短期 SA token，证书留给集群组件；永远不要把 admin kubeconfig 发给同事。

练习#

1. 在本地造两份 kubeconfig 文件，让它们包含同名的 cluster 但不同的 server，分别用 KUBECONFIG=a.yaml:b.yaml 与 KUBECONFIG=b.yaml:a.yaml 执行 kubectl config view --flatten，验证「第一个文件优先」。
2. 给 demo 命名空间再建一个只读 SA（绑定内置 view ClusterRole），签一份 1 小时 token 拼成 kubeconfig，用 kubectl auth can-i --list -n demo 对比它和本章 ci-deploy 的权限差异。
3. 想一下你手上的流水线：它现在用的是谁的凭证？要改成「专用 SA + 短时 token + 权限预检」，需要动哪几个地方？

本章解决的是「怎么安全地连上多套集群」。凭证之外，集群本身还有一堆需要按机器去调的东西——节点内核参数、DNS 缓存、设备发现，继续看下一章；权限规则写不明白就回看第 12 章 命名空间与 RBAC 与安全加固，凭证泄漏后的处置思路在排障手册。