🛠️ K8S Trouble Shooting : API 서버 및 네트워크 연결 문제 해결하기

 

Kubernetes를 사용하면서 가장 흔히 발생하는 문제 중 하나는 API 서버 및 네트워크 연결 관련 오류입니다.

이 글에서는 Kubernetes 환경에서 발생할 수 있는 대표적인 API 서버 및 네트워크 연결 오류 5가지를 정리하고, 각각의 원인과 해결 방법을 설명합니다. 🚀

 

---

 

1️⃣ “Unable to connect to the server: dial tcp :443: connect: connection refused”

 

🔎 오류 설명

 

이 오류는 kubectl이 Kubernetes API 서버에 연결할 수 없을 때 발생합니다.

일반적으로 API 서버가 비정상적으로 종료되었거나, 네트워크 문제가 있을 때 나타납니다.

 

🔧 해결 방법

 

1) API 서버 상태 확인

 

먼저, API 서버가 실행 중인지 확인합니다.

kubectl get pods -n kube-system

2) 클러스터 정보 확인

 

API 서버가 올바르게 동작하는지 확인합니다.

kubectl cluster-info

 

3) 네트워크 연결 문제 해결

 

API 서버가 실행 중인데도 접속이 안 된다면, 네트워크 연결을 확인합니다.

ping <API_SERVER_IP>
telnet <API_SERVER_IP> 443

 

4) kubeconfig 설정 확인

 

kubeconfig 파일이 올바르게 설정되었는지 확인합니다.

kubectl config view

 

---

 

2️⃣ “The connection to the server localhost:8080 was refused…”

 

🔎 오류 설명

 

이 오류는 Kubernetes 컨트롤 플레인이 실행되지 않았거나, 올바른 kubeconfig가 설정되지 않은 경우 발생합니다.

 

🔧 해결 방법

 

1) 컨트롤 플레인 상태 확인

 

Minikube 환경이라면, 먼저 실행 여부를 확인합니다.

minikube status

 

만약 실행되지 않았다면 시작합니다.

minikube start

 

2) kubeconfig 확인 및 설정 변경

 

kubeconfig가 올바르게 설정되지 않았다면, 현재 클러스터를 kubeconfig에 추가합니다.

kubectl config use-context <your-cluster-name>

 

또는 Minikube를 사용할 경우:

kubectl config use-context minikube

 

3) API 서버 상태 점검

 

API 서버가 실행 중인지 확인합니다.

kubectl get nodes

 

---

 

3️⃣ “Service Unavailable”

 

🔎 오류 설명

 

이 오류는 Kubernetes API 서버가 과부하 상태이거나 다운되었을 때 발생합니다.

 

🔧 해결 방법

 

1) API 서버 로그 확인

 

먼저, 컨트롤 플레인 노드의 API 서버 로그를 확인합니다.

kubectl logs -n kube-system etcd-master

 

2) 네트워크 상태 확인

 

API 서버와의 네트워크 연결을 확인합니다.

ping <API_SERVER_IP>
telnet <API_SERVER_IP> 6443

 

3) 컨트롤 플레인 노드 재시작

 

문제가 해결되지 않는다면 API 서버를 재시작합니다.

sudo systemctl restart kube-apiserver

 

Minikube 환경이라면:

minikube delete
minikube start

 

---

 

4️⃣ “The server was unable to return a response in the time…”

 

🔎 오류 설명

 

이 오류는 Kubernetes API 서버가 응답하지 않거나, 요청을 처리하는 데 시간이 오래 걸릴 때 발생합니다.

 

🔧 해결 방법

 

1) API 서버 상태 점검

 

CPU 및 메모리 사용량을 확인합니다.

kubectl top nodes

 

2) 네트워크 대역폭 확인

 

과부하 상태인지 확인합니다.

netstat -tulnp

 

3) API 요청 시간 초과 값 증가

 

만약 응답 시간이 길다면 --request-timeout 옵션을 사용하여 시간을 늘려볼 수 있습니다.

kubectl get pods --request-timeout=60s

 

4) API 서버 재시작

 

컨트롤 플레인 노드를 재부팅하는 것도 방법입니다.

sudo systemctl restart kubelet

 

---

 

5️⃣ “Unable to connect to server: x509: certificate signed by unknown authority”

 

🔎 오류 설명

 

이 오류는 Kubernetes API 서버의 SSL 인증서가 신뢰할 수 없는 경우 발생합니다.

 

🔧 해결 방법

 

1) Kubernetes 인증서 확인

 

API 서버의 인증서를 확인합니다.

kubectl config view --raw | grep certificate-authority

 

2) 신뢰할 수 있는 CA 인증서 추가

 

인증서를 수동으로 추가합니다.

sudo cp <CA_CERT_PATH> /etc/ssl/certs/
sudo update-ca-certificates

 

3) kubeconfig 재설정

 

만약 인증서가 손상되었다면 kubeconfig를 재설정합니다.

kubectl config set-cluster <your-cluster> --certificate-authority=<ca.crt>

 

4) API 서버 재시작

 

인증서 변경 후 API 서버를 재시작합니다.

sudo systemctl restart kube-apiserver

 

---

 

🎯 마무리

 

이 글에서는 Kubernetes에서 자주 발생하는 API 서버 및 네트워크 연결 오류 5가지와 그 해결 방법을 다뤘습니다.

✔️ API 서버 접속 문제

✔️ 컨트롤 플레인 실행 오류

✔️ 서비스 불가 오류

✔️ 네트워크 타임아웃 문제

✔️ SSL 인증서 오류

 

만약 위 해결 방법으로도 문제가 해결되지 않는다면,

Kubernetes 컨트롤 플레인 로그를 분석하고, 네트워크 상태를 추가로 점검하는 것이 중요합니다.