kubeconfig：集群连接、身份凭据与 Context 管理

1. kubeconfig 是什么？#

kubeconfig 是 Kubernetes 客户端使用的配置文件。

它告诉 kubectl 三件事情：

1. Cluster：连接哪个 Kubernetes 集群？
2. User：使用什么身份访问？
3. Context：使用哪个集群、哪个用户，以及默认哪个 Namespace？

默认配置文件位置：

1
~/.kube/config

也可以通过环境变量指定：

1
export KUBECONFIG=/path/to/config

查看当前使用的 kubeconfig：

1
kubectl config view

查看当前 Context：

1
kubectl config current-context

查看所有 Context：

1
kubectl config get-contexts

1.1 kubeconfig 的整体结构#

一个典型的 kubeconfig 文件：

1
apiVersion: v1
2
kind: Config
3

4
clusters:
5
  - name: dev-cluster
6
    cluster:
7
      server: https://192.168.1.100:6443
8
      certificate-authority-data: BASE64_CA_CERT
9

10
users:
11
  - name: dev-user
12
    user:
13
      client-certificate-data: BASE64_CLIENT_CERT
14
      client-key-data: BASE64_CLIENT_KEY
15

16
contexts:
17
  - name: dev-context
18
    context:
19
      cluster: dev-cluster
20
      user: dev-user
21
      namespace: dev
22

23
current-context: dev-context

重点看四个部分：

可以把它们理解成：

• Cluster：服务器地址。
• User：登录凭据。
• Context：登录哪个服务器、使用哪个身份、默认进入哪个 Namespace。

2. clusters：集群连接信息#

2.1 Cluster 配置#

Cluster 用来定义 Kubernetes API Server 的连接信息。

例如：

1
clusters:
2
  - name: production
3
    cluster:
4
      server: https://10.0.0.10:6443
5
      certificate-authority: /etc/kubernetes/pki/ca.crt

两个重要字段：

server

API Server 的访问地址：

1
server: https://10.0.0.10:6443

默认情况下，kubeadm 集群 API Server 监听的端口通常是 6443。

certificate-authority

指定 CA 证书文件路径。

1
certificate-authority: /etc/kubernetes/pki/ca.crt

也可以将证书内容直接 Base64 编码后放入：

1
certificate-authority-data: LS0tLS1CRUdJTi...

注意：

CA 证书用于验证 API Server 的服务端身份，避免客户端连接到伪造的 API Server。

2.2 查看当前集群信息#

1
kubectl config get-clusters

查看配置：

1
kubectl config view

只查看当前使用的集群信息：

1
kubectl config view --minify

如果想查看完整证书数据：

1
kubectl config view --raw

注意：--raw 可能显示私钥和 Token，不要随意将输出分享给他人。

3. users：客户端身份凭据#

User 定义客户端访问 Kubernetes API Server 时使用的身份凭据。

常见方式：

3.1 客户端证书认证#

例如：

1
users:
2
  - name: alice
3
    user:
4
      client-certificate: /home/alice/alice.crt
5
      client-key: /home/alice/alice.key

这里：

• alice.crt：客户端证书。
• alice.key：客户端私钥。

API Server 通过配置的 CA 验证客户端证书，并从证书信息中识别用户身份。

例如证书 Subject：

1
CN=alice
2
O=developers

对应的身份信息：

1
username: alice
2
groups:
3
  - developers
4
  - system:authenticated

3.2 Token 认证#

如果使用 ServiceAccount Token，也可以这样配置：

1
users:
2
  - name: app-user
3
    user:
4
      token: eyJhbGciOiJSUzI1NiIs...

实际生产中不建议将长期有效的敏感 Token 明文写入共享 kubeconfig。

对于需要动态获取凭据的环境，可以使用 exec 插件。

3.3 exec 认证插件#

某些企业集群使用外部身份提供商，例如云厂商 IAM 或 OIDC 身份系统。

这时 kubeconfig 可以通过 exec 调用外部程序获取凭据。

例如：

1
users:
2
  - name: cloud-user
3
    user:
4
      exec:
5
        apiVersion: client.authentication.k8s.io/v1
6
        command: example-auth
7
        interactiveMode: Never
8
        args:
9
          - get-token

执行 kubectl 时，客户端会调用指定程序获取凭据。

外部程序需要返回符合 Kubernetes ExecCredential 规范的数据。

例如：

1
{
2
  "apiVersion": "client.authentication.k8s.io/v1",
3
  "kind": "ExecCredential",
4
  "status": {
5
    "token": "EXAMPLE_TOKEN"
6
  }
7
}

这样可以避免在 kubeconfig 中长期保存静态 Token。

4. contexts：集群、用户与命名空间组合#

这是 kubeconfig 最重要的部分之一。

Context 用于组合：

• Cluster
• User
• Namespace

例如：

1
contexts:
2
  - name: dev-context
3
    context:
4
      cluster: dev-cluster
5
      user: dev-user
6
      namespace: dev

它表示：

使用 dev-user 身份，访问 dev-cluster 集群，默认操作 dev Namespace。

再创建一个生产环境 Context：

1
contexts:
2
  - name: prod-context
3
    context:
4
      cluster: prod-cluster
5
      user: prod-user
6
      namespace: production

现在就有了两个访问上下文。

flowchart LR
    D["dev-context"] --> DC["Cluster: dev-cluster"]
    D --> DU["User: dev-user"]
    D --> DN["Namespace: dev"]
    P["prod-context"] --> PC["Cluster: prod-cluster"]
    P --> PU["User: prod-user"]
    P --> PN["Namespace: production"]

Context 是引用关系，不是独立的身份或权限。实际权限由集群端认证和授权机制决定。

4.1 查看所有 Context#

1
kubectl config get-contexts

输出示例：

1
CURRENT   NAME           CLUSTER       AUTHINFO      NAMESPACE
2
*         dev-context    dev-cluster   dev-user      dev
3
          prod-context   prod-cluster prod-user     production

4.2 切换 Context#

切换到开发环境：

1
kubectl config use-context dev-context

切换到生产环境：

1
kubectl config use-context prod-context

查看当前 Context：

1
kubectl config current-context

4.3 修改 Context 默认 Namespace#

1
kubectl config set-context dev-context \
2
  --namespace=testing

之后使用该 Context 执行：

1
kubectl get pods

默认就会访问 testing Namespace。

也可以临时指定 Namespace：

1
kubectl get pods -n production

临时指定不会修改当前 Context。

5. kubectl config 常用命令#

例如创建一个 Context：

1
kubectl config set-context dev-context \
2
  --cluster=dev-cluster \
3
  --user=dev-user \
4
  --namespace=dev

注意：这条命令不会自动创建对应的 Cluster 或 User。它们需要提前存在。

创建集群配置：

1
kubectl config set-cluster dev-cluster \
2
  --server=https://192.168.1.100:6443 \
3
  --certificate-authority=/etc/kubernetes/pki/ca.crt \
4
  --embed-certs=true

--embed-certs 将 CA 证书内容嵌入 kubeconfig。

创建证书用户：

1
kubectl config set-credentials dev-user \
2
  --client-certificate=/home/alice/alice.crt \
3
  --client-key=/home/alice/alice.key \
4
  --embed-certs=true

这会把客户端证书和私钥嵌入 kubeconfig。生成的 kubeconfig 包含私钥，应当作为敏感凭据保护。

如果需要使用 Token：

1
kubectl config set-credentials app-user \
2
  --token='TOKEN_VALUE'

这些命令会修改当前 kubeconfig 文件，操作前应注意备份。

6. 多集群管理与 kubeconfig 合并#

这是生产环境非常常见的场景。

假设你有三套集群：

每套集群可能分别提供一份 kubeconfig。

例如：

flowchart LR
    K["~/.kube/"] --> C["config"]
    K --> D["dev-config"]
    K --> T["test-config"]
    K --> P["prod-config"]

6.1 临时使用不同 kubeconfig#

使用开发环境：

1
kubectl --kubeconfig="$HOME/.kube/dev-config" get pods

使用测试环境：

1
kubectl --kubeconfig="$HOME/.kube/test-config" get pods

使用生产环境：

1
kubectl --kubeconfig="$HOME/.kube/prod-config" get pods

这种方式不会修改默认 kubeconfig。

6.2 合并多个 kubeconfig#

如果希望统一管理，可以使用 KUBECONFIG 环境变量。

Linux：

1
export KUBECONFIG=~/.kube/dev-config:~/.kube/test-config:~/.kube/prod-config

Windows PowerShell 使用分号分隔：

1
$env:KUBECONFIG="$HOME\.kube\dev-config;$HOME\.kube\test-config;$HOME\.kube\prod-config"

查看合并结果：

1
kubectl config get-contexts

此时可以看到三个集群的 Context。

需要注意：

• 多个 kubeconfig 通过环境变量合并时，配置项按合并规则处理。
• 如果多个文件存在相同名称的 Cluster、User 或 Context，可能发生命名冲突。
• 多文件合并通常不应直接视为可写的单一配置文件。
• 需要持久化合并结果时，可以显式使用 kubectl config view --flatten --raw，但要妥善保护其中的敏感凭据。

例如：

1
kubectl config view --merge --flatten --raw > ~/.kube/merged-config

设置：

1
export KUBECONFIG=~/.kube/merged-config

注意：--raw 会暴露敏感凭据，生成的文件应限制访问权限。

1
chmod 600 ~/.kube/merged-config

6.3 实际生产中的多集群切换#

建议使用明确的 Context 名称：

1
company-dev
2
company-test
3
company-prod

切换：

1
kubectl config use-context company-dev

执行生产环境操作之前：

1
kubectl config current-context

确认当前环境。

还可以给命令增加显式 Context：

1
kubectl --context=company-prod get pods -A

这样不依赖当前默认 Context，可以降低误操作风险。

7. kubeadm 集群中的 kubeconfig#

使用 kubeadm 部署 Kubernetes 后，控制平面节点通常会生成多个 kubeconfig 文件。

查看：

1
ls -l /etc/kubernetes/

常见结构：

flowchart LR
    K["/etc/kubernetes/"] --> A["admin.conf"]
    K --> C["controller-manager.conf"]
    K --> S["scheduler.conf"]
    K --> L["kubelet.conf"]
    K --> M["manifests/"]
    K --> P["pki/"]

几个重要文件：

7.1 admin.conf#

这是 kubeadm 集群中非常重要的 kubeconfig。

查看：

1
kubectl config view \
2
  --kubeconfig=/etc/kubernetes/admin.conf

可以看到：

• API Server 地址。
• 集群 CA 证书。
• 管理员客户端证书。
• 当前 Context。

通常可以将它复制到管理员用户的家目录：

1
mkdir -p ~/.kube
2

3
sudo cp /etc/kubernetes/admin.conf ~/.kube/config
4

5
sudo chown "$(id -u):$(id -g)" ~/.kube/config
6

7
chmod 600 ~/.kube/config

之后就可以直接执行：

1
kubectl get nodes

注意：admin.conf 包含高权限访问凭据，不能随意分发给开发人员，也不应提交到 Git 仓库。

7.2 kubelet.conf#

kubelet 是运行在每个 Node 上的重要组件。

它需要与 API Server 通信：

• 注册 Node。
• 上报 Node 状态。
• 获取 Pod 相关信息。
• 更新节点运行状态。

kubelet 使用自己的 kubeconfig：

1
/etc/kubernetes/kubelet.conf

通常对应的身份类似：

1
system:node:<node-name>

并属于：

1
system:nodes

例如：

1
system:node:worker-01

Kubernetes 还通过 Node Authorizer 和 NodeRestriction 等机制，限制节点身份能够访问的资源范围。

7.3 Scheduler 与 Controller Manager#

它们同样需要访问 API Server。

Scheduler：

1
/etc/kubernetes/scheduler.conf

Controller Manager：

1
/etc/kubernetes/controller-manager.conf

它们使用独立身份执行各自的控制平面任务，而不是所有组件共用管理员身份。

这体现了一个重要的生产设计原则：

不同组件应该使用不同的身份，并且只拥有完成自身职责所需的权限。

8. kubeconfig 与证书认证的关系#

假设 Alice 需要访问 Kubernetes 集群。

她获得以下文件：

1
alice.crt
2
alice.key
3
ca.crt

分别代表：

• alice.crt：客户端证书。
• alice.key：客户端私钥。
• ca.crt：集群 CA 证书。

配置 kubeconfig：

1
apiVersion: v1
2
kind: Config
3

4
clusters:
5
  - name: kubernetes
6
    cluster:
7
      server: https://192.168.1.100:6443
8
      certificate-authority: ca.crt
9

10
users:
11
  - name: alice
12
    user:
13
      client-certificate: alice.crt
14
      client-key: alice.key
15

16
contexts:
17
  - name: alice-dev
18
    context:
19
      cluster: kubernetes
20
      user: alice
21
      namespace: dev
22

23
current-context: alice-dev

完整访问过程：

flowchart TB
    K["kubectl 读取 kubeconfig"] --> C["Context 组合身份与集群"]
    C --> CL["Cluster<br/>API Server 地址与 CA"]
    C --> U["User<br/>客户端证书和私钥"]
    CL --> T["建立 TLS 连接"]
    U --> T
    T --> A["API Server 验证客户端身份"]
    A --> R["RBAC 授权<br/>检查 Alice 对 dev Namespace 的操作权限"]
    R --> O["返回 API 请求结果"]

这里要记住：

• kubeconfig 负责告诉客户端如何连接、如何认证。
• API Server 负责验证身份。
• RBAC 负责检查权限。
• Context 中的 Namespace 只是默认请求范围，不代表自动获得该 Namespace 的权限。

9. kubeconfig 安全管理#

kubeconfig 本身就是一个非常敏感的配置文件。

因为它可能包含：

• 客户端私钥。
• 身份认证 Token。
• 外部认证插件信息。
• 集群 API Server 地址。

如果 kubeconfig 泄露，攻击者可能直接使用其中的凭据访问集群。

9.1 文件权限#

1
chmod 600 ~/.kube/config

查看：

1
ls -l ~/.kube/config

建议：

1
-rw------- 1 user user ...

只有文件所有者能够读取和修改。

9.2 不要提交到 Git#

错误做法：

1
git add ~/.kube/config

正确做法：

1
.kube/
2
*.kubeconfig
3
admin.conf

还需要注意：如果 kubeconfig 已经提交到 Git，即使之后删除文件，也不代表历史版本中的凭据已经消失，应当及时吊销或轮换相关凭据。

9.3 使用独立身份#

不要所有人都使用：

1
kubernetes-admin

应该为不同角色分配不同身份：

1
alice-dev
2
bob-test
3
ops-admin
4
monitoring-sa

再通过 RBAC 授予对应权限。

9.4 生产环境避免共享私钥#

例如：

1
alice.crt
2
alice.key

不应该复制给 Bob 使用。

否则审计时很难确认到底是谁执行了操作。

应该做到：

• 每个人独立身份。
• 每个身份独立凭据。
• 每个身份独立权限。
• 定期轮换凭据。
• 对敏感操作进行审计。

10. 常见问题与故障排查#

10.1 Unable to connect to the server#

例如：

1
The connection to the server 192.168.1.100:6443 was refused

可能原因：

• API Server 没有启动。
• IP 地址或端口配置错误。
• 网络不通。
• 防火墙阻断。

排查：

1
kubectl config view --minify

1
nc -zv 192.168.1.100 6443

10.2 x509: certificate signed by unknown authority#

例如：

1
x509: certificate signed by unknown authority

可能原因：

• CA 证书配置错误。
• 使用了错误的集群 CA。
• 证书文件损坏。
• 证书链不可信。

排查：

1
kubectl config view --raw --minify

重点检查：

1
certificate-authority-data: ...

或者：

1
certificate-authority: /path/to/ca.crt

10.3 You must be logged in to the server#

例如：

1
error: You must be logged in to the server (Unauthorized)

可能原因：

• Token 过期。
• 客户端证书过期。
• 身份认证配置错误。
• 外部认证插件失效。

重点排查：

1
kubectl config view --minify

如果使用客户端证书，还可以检查：

1
openssl x509 -in alice.crt -noout -subject -dates

10.4 Forbidden#

例如：

1
Error from server (Forbidden)

说明通常已经通过身份认证，但没有相应操作权限。

排查：

1
kubectl auth can-i get pods -n dev

进一步检查 Role 和 RoleBinding。