MacBook 配置 kubectl 连接 Kubernetes 集群

这篇文章记录在 MacBook 上配置 kubectl 连接 Kubernetes 集群的基本过程。核心思路是从控制节点取回 admin.conf，放到本地 ~/.kube/config，再根据实际证书情况调整 API Server 地址。

适用场景

这种做法适用于：

• 已经有可用的 Kubernetes 集群
• 本机只是作为运维管理端
• 需要在 macOS 上直接执行 kubectl

前提条件

开始之前，最好先确认这几件事：

• 本机可以访问 Kubernetes 控制平面的网络地址
• 你有权限从控制节点获取 /etc/kubernetes/admin.conf
• 目标集群的证书地址和你准备访问的地址基本一致

配置步骤

1. 安装 kubectl

如果本机还没有安装：

brew install kubectl
kubectl version --client

2. 创建 kubeconfig 目录

mkdir -p ~/.kube

3. 获取集群配置文件

最常见的做法，是从任意一个控制节点复制 /etc/kubernetes/admin.conf 到本地：

scp root@<master-ip>:/etc/kubernetes/admin.conf ~/.kube/config

如果不方便直接拷贝文件，也可以 SSH 登录控制节点后把内容复制出来，再手动写入本地 ~/.kube/config。

调整 server 地址

很多时候，admin.conf 里的 server 地址并不一定适合你当前的外部访问方式。

例如原配置可能写的是：

server: https://lb-vip:6443

如果本地 MacBook 无法解析这个域名，或者证书里没有包含对应的 VIP 地址，就需要改成证书里实际包含的地址，例如某个 Master 节点的 IP：

sed -i '' 's|server: https://lb-vip:6443|server: https://10.0.5.1:6443|' ~/.kube/config

这一步的关键不在于“能不能连”，而在于“连接地址是否和证书匹配”。如果地址不匹配，即使网络是通的，也会因为证书校验失败而无法正常访问。

验证连接

配置完成后，先执行最基本的验证：

kubectl get nodes

如果能正常返回节点列表，就说明本地 kubectl 已经能和集群通信。

也可以顺手再执行一次：

kubectl cluster-info

这样可以顺便确认当前连接到的是哪一个控制平面地址。

常见问题

证书报错

如果提示类似 x509: certificate is valid for...，通常说明你当前访问的地址不在 API Server 证书的 SAN 列表里。

常见处理方式有两种：

• 改用证书中已经包含的 IP 或域名
• 重新生成 API Server 证书，把 VIP 或域名补进去

连接超时

可以先确认网络和端口是否可达：

ping 10.0.5.1
nc -zv 10.0.5.1 6443

权限不足

如果操作受限，先确认当前使用的是不是 admin.conf，因为它通常对应的是集群管理员权限。

可选：配置命令补全

如果平时使用频率高，可以顺手开一下补全：

source <(kubectl completion zsh)
echo "source <(kubectl completion zsh)" >> ~/.zshrc

总结

在 MacBook 上接入 Kubernetes 集群，真正决定是否顺利的通常只有三件事：

1. 本机装好了 kubectl
2. 拿到了正确的 kubeconfig
3. server 地址和证书实际匹配

只要这三点没问题，本地管理集群本身并不复杂。