如何修复 kubectl 报错 “Connection to server was refused”

1. 简介

在本教程中，我们将学习如何修复使用 kubectl 时出现的 “Connection to server was refused” 错误。首先，我们会了解 kubectl 是如何与 Kubernetes API Server 通信的，以及这个错误产生的原因。最后，我们将分析两个常见的根本原因，并提供相应的解决方法。

2. kubectl 与 Kubernetes API Server 的通信机制

kubectl 是一个命令行工具，用于管理 Kubernetes 集群。它通过向集群的 Kubernetes API Server 发起认证和 API 请求，来执行各种管理操作。

当 kubectl 无法与 Kubernetes API Server 正常通信时，就会报出类似如下错误：

$ kubectl get pods
The connection to the server 192.168.122.54:6443 was refused - did you specify the right host or port?

接下来，我们将分析导致该错误的两个最常见原因以及对应的解决方法。

3. kubectl 配置问题

最常见的原因之一是 kubectl 的配置错误。kubectl 依赖一个名为 kubeconfig 的配置文件来指定如何连接 API Server。

如果 kubeconfig 文件缺失或配置错误，就可能导致该连接失败。

我们可以通过以下命令检查当前的配置状态：

$ kubectl config view
apiVersion: v1
clusters: null
contexts: null
current-context: ""
kind: Config
preferences: {}
users: null

如果输出如上所示，说明 ~/.kube/config 文件不存在。

✅ 解决方法：

我们可以手动创建并配置 kubeconfig 文件：

$ mkdir -p $HOME/.kube
$ sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
$ sudo chown $(id -u):$(id -g) $HOME/.kube/config

再次运行 kubectl config view 命令，确认配置已正确加载：

$ kubectl config view
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: DATA+OMITTED
    server: https://192.168.122.54:6443
  name: kubernetes
contexts:
- context:
    cluster: kubernetes
    user: kubernetes-admin
  name: kubernetes-admin@kubernetes
current-context: kubernetes-admin@kubernetes
kind: Config
preferences: {}
users:
- name: kubernetes-admin
  user:
    client-certificate-data: DATA+OMITTED
    client-key-data: DATA+OMITTED

请特别注意 server 字段的值是否与你的 Kubernetes API Server 的实际 IP 和端口一致。

4. Kubernetes API Server 未运行

一旦确认 kubectl 的配置无误，但仍然无法连接，那很可能是 API Server 本身没有运行。

Kubernetes API Server 通常以容器（kube-apiserver）形式运行在 kube-system 命名空间的 Pod 中，并随其他 Kubernetes 服务一同启动。

❗常见原因：

• 节点启用了 Swap 内存（默认不支持）
• 服务异常崩溃或未启动

✅ 解决方法：

临时禁用 Swap：

$ sudo swapoff -a

永久禁用 Swap：

编辑 /etc/fstab 文件，将与 Swap 相关的行注释掉（在行首添加 #）：

#/swapfile none swap sw 0 0

⚠️ 如果必须启用 Swap：

需要在每个节点上启用 NodeSwap 功能。请参考 Kubernetes 官方文档：Swap Memory Support

5. 总结

本教程中，我们学习了如何解决 kubectl 报错 “Connection to server was refused”。

该错误通常出现在以下两种情况：

1. kubectl 的 kubeconfig 配置文件缺失或配置错误
2. Kubernetes API Server 没有正常运行

✅ 修复建议：

• 检查 ~/.kube/config 文件是否存在
• 确保配置中的 server 字段指向正确的 API Server 地址
• 确认 kube-apiserver 容器正在运行，必要时禁用 Swap 或启用 NodeSwap

只要排查清楚配置和节点状态，大多数情况下都可以顺利解决这个连接问题。