Sửa lỗi 'The connection to the server localhost:8443 was refused' trong Kubernetes

Chuyện gì đang xảy ra

Bạn chạy lệnh kubectl và nhận được thông báo:

The connection to the server localhost:8443 was refused - did you specify the right host or port?

kubectl đang cố kết nối tới API server của Kubernetes tại localhost:8443 — nhưng không có gì đang lắng nghe ở đó. Có ba nguyên nhân gây ra điều này: cluster chưa chạy, kubectl không có kubeconfig hợp lệ, hoặc nó đang trỏ tới endpoint sai. Cổng 8443 là mặc định của Minikube; còn các cluster kubeadm dùng cổng 6443. Nếu thấy localhost:8443 trên một cluster kubeadm, đó là dấu hiệu rõ ràng rằng kubeconfig của bạn đã cũ hoặc bị cấu hình sai.

Chẩn đoán nhanh

Hãy xác định nguyên nhân trước khi động tay vào bất cứ thứ gì. Bốn bước kiểm tra sau đây giải quyết được 95% trường hợp.

1. Kiểm tra context hiện tại

kubectl config current-context

Nếu lệnh này báo lỗi — hoặc tên context không quen thuộc — thì đó thường chính là vấn đề. Liệt kê tất cả context đang được cấu hình:

kubectl config get-contexts

2. Kiểm tra kubeconfig có tồn tại không

echo $KUBECONFIG
ls ~/.kube/config

Không có ~/.kube/config? Đó là câu trả lời của bạn. Khi kubectl không tìm thấy config, nó sẽ mặc định dùng localhost:8443 — và điều đó hầu như chắc chắn là sai.

3. Với cluster cục bộ (Minikube / kind)

# Minikube
minikube status

# kind
kind get clusters

Cluster đã dừng hoặc bị xóa đồng nghĩa với việc kubectl không có API server nào để kết nối.

4. Với cluster từ xa (kubeadm / cloud)

kubectl cluster-info

Đối chiếu địa chỉ server trong kubeconfig với IP thực của API server:

kubectl config view --minify | grep server

Cách xử lý theo từng tình huống

Tình huống A: Cluster cục bộ đã dừng (Minikube / kind)

Chín trên mười lần, đây chính là thủ phạm. Hãy khởi động lại cluster:

# Minikube
minikube start

# kind (tạo lại nếu đã bị xóa)
kind create cluster --name my-cluster

Minikube tự động ghi lại ~/.kube/config khi khởi động. Sau khi cluster đã chạy, kiểm tra xem mọi thứ có ổn không:

kubectl get nodes

Tình huống B: Không có kubeconfig hoặc config trống

Máy mới cài? Config bị xóa nhầm? Hãy tạo lại:

# Minikube — tự động tạo lại kubeconfig
minikube update-context

# kubeadm — sao chép admin config từ control plane node
scp user@control-plane-node:/etc/kubernetes/admin.conf ~/.kube/config
chmod 600 ~/.kube/config

Lệnh chmod 600 là bắt buộc, không thể bỏ qua. kubectl sẽ âm thầm từ chối dùng file config nếu quyền truy cập của nó cho phép mọi người đọc.

Các nhà cung cấp cloud có lệnh riêng của họ:

# AWS EKS
aws eks update-kubeconfig --region us-east-1 --name my-cluster

# GKE
gcloud container clusters get-credentials my-cluster --zone us-central1-a

# AKS
az aks get-credentials --resource-group my-rg --name my-cluster

Tình huống C: Đang dùng sai context

Chuyển sang context đúng:

kubectl config use-context my-correct-context

Không muốn thay đổi context mặc định vĩnh viễn? Flag --context cho phép chạy một lệnh duy nhất với bất kỳ cluster nào:

kubectl get pods --context=production-cluster

Tình huống D: API server bị down trên cluster kubeadm

SSH vào control plane và kiểm tra xem container API server có đang thực sự chạy không:

sudo crictl ps | grep kube-apiserver

# Kiểm tra log kubelet để tìm manh mối
sudo journalctl -u kubelet -n 100

# Xác nhận file manifest static pod vẫn còn đó
ls /etc/kubernetes/manifests/kube-apiserver.yaml

Nếu pod bị crash, hãy kéo log của nó trực tiếp:

sudo crictl logs $(sudo crictl ps -a | grep kube-apiserver | awk '{print $1}')

Ba nguyên nhân phổ biến nhất khiến API server bị crash: chứng chỉ hết hạn, etcd bị down, hoặc lỗi đánh máy trong các flag của manifest. Hãy xử lý nguyên nhân gốc — kubelet sẽ tự khởi động lại static pod.

Tình huống E: Firewall chặn cổng

Server đang chạy nhưng vẫn không thể kết nối từ máy khác? Hãy kiểm tra kết nối trước khi đổ lỗi cho config:

# Kiểm tra kết nối trực tiếp
telnet <api-server-ip> 6443
# hoặc
curl -k https://<api-server-ip>:6443/healthz

Mở cổng nếu đang bị chặn:

# UFW (Ubuntu)
sudo ufw allow 6443/tcp

# firewalld (RHEL/CentOS)
sudo firewall-cmd --permanent --add-port=6443/tcp
sudo firewall-cmd --reload

Cần nhắc lại: kubeadm mặc định dùng cổng 6443, không phải 8443. Nếu bạn thấy localhost:8443 trên cluster kubeadm, vấn đề nằm ở URL server trong kubeconfig — không phải firewall.

Tình huống F: URL server trong kubeconfig đã lỗi thời

API server chuyển sang IP mới sau khi rebuild? Cập nhật URL trực tiếp trong kubeconfig:

# Cập nhật URL server
kubectl config set-cluster my-cluster --server=https://<new-api-server-ip>:6443

# Xác nhận thay đổi đã có hiệu lực
kubectl config view --minify | grep server

Kiểm tra sau khi sửa

kubectl cluster-info
kubectl get nodes
kubectl get pods -A

Một cluster hoạt động bình thường sẽ trả về kết quả tương tự như sau từ lệnh kubectl cluster-info:

Kubernetes control plane is running at https://<server>:<port>
CoreDNS is running at https://<server>:<port>/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

Phòng tránh về sau

Người dùng Minikube: thêm lệnh minikube start vào script khởi động môi trường dev. Mất 30 giây để khởi động còn hơn phải mất thời gian truy tìm lỗi này giữa chừng công việc.
Cluster kubeadm: giám sát kube-apiserver bằng Prometheus + Alertmanager. Nhận cảnh báo trước khi các developer của bạn phát hiện ra kubectl bị lỗi.
Cluster từ xa: xem kubeconfig như mật khẩu — lưu trữ trong secrets manager, và tích hợp aws eks update-kubeconfig hoặc gcloud get-credentials vào script onboarding để credentials không bao giờ hết hạn một cách âm thầm.
Nhiều cluster: cài kubectx. Chuyển context bằng kubectx production thay vì gõ đầy đủ lệnh kubectl config use-context chỉ mất hai giây và loại bỏ hẳn một loại lỗi kiểu "sao không có gì hoạt động cả".