쿠버네티스 클러스터에서 제어 플레인(Control Plane)과 etcd는 클러스터의 핵심 구성 요소이며, 장애 발생 시 클러스터 전체의 동작에 영향을 미칩니다.
이 글에서는 쿠버네티스 클러스터 장애 발생 시 복구하는 방법과, etcd 장애를 식별하고 해결하는 전략을 다룹니다.
📌 글에서 다루는 상황들
1. 쿠버네티스 Control Plane 장애 복구 (API 서버, 컨트롤러, 스케줄러 장애 해결)
2. etcd 장애 발생 시 데이터 복구 및 클러스터 정상화
3. kubectl 및 시스템 로그를 활용한 클러스터 복구 디버깅 방법
각 문제를 실무에서 바로 활용할 수 있도록 Manifest 템플릿과 예상 결과 값을 제공합니다.
1️⃣ 쿠버네티스 Control Plane 장애 복구 (API 서버, 컨트롤러, 스케줄러 장애 해결)
❓ 문제 상황
운영팀에서 쿠버네티스 Control Plane이 비정상적으로 동작하면서, 클러스터에서 새로운 Pod이 배포되지 않고 있습니다.
조사를 해보니 kube-apiserver가 종료되었거나, 컨트롤러 매니저 또는 스케줄러가 제대로 실행되지 않고 있습니다.
• 장애 원인: API 서버 다운, 컨트롤러 매니저 장애, 스케줄러 응답 없음
• 영향 범위: 새로운 워크로드 배포 불가능, 클러스터 상태 업데이트 지연
✅ 어떻게 해결할 수 있을까요?
🛠️ 해결 방법
1. kubectl get nodes를 실행하여 컨트롤 플레인 노드의 상태를 확인합니다.
2. kubectl get pods -n kube-system을 사용하여 컨트롤 플레인 구성 요소(API 서버, 컨트롤러, 스케줄러)의 상태를 점검합니다.
3. 비정상적인 컨테이너를 재시작하고, 필요 시 마스터 노드를 재부팅합니다.
✅ Control Plane 장애 점검 및 복구 명령어
🔹 Control Plane 상태 확인
kubectl get nodes
💡 예상 출력 값 (정상적인 경우)
NAME STATUS ROLES AGE VERSION
master-node Ready control-plane 200d v1.25.3
worker-node1 Ready worker 100d v1.25.3
💡 예상 출력 값 (비정상적인 경우)
NAME STATUS ROLES AGE VERSION
master-node NotReady control-plane 200d v1.25.3✅ 마스터 노드가 NotReady 상태인 경우, Control Plane 서비스가 중단되었을 가능성이 높음
🔹 Control Plane 서비스 상태 확인
kubectl get pods -n kube-system -l component=kube-apiserver
kubectl get pods -n kube-system -l component=kube-controller-manager
kubectl get pods -n kube-system -l component=kube-scheduler
💡 예상 출력 값 (비정상적인 경우)
NAME READY STATUS RESTARTS AGE
kube-apiserver-master 0/1 CrashLoopBackOff 10 2m
kube-controller-master 1/1 Running 0 200d
kube-scheduler-master 0/1 CrashLoopBackOff 8 5m✅ API 서버 및 스케줄러가 비정상적으로 동작하고 있음
🔹 Control Plane 서비스 재시작
sudo systemctl restart kubelet
sudo docker ps -a | grep kube-apiserver
sudo docker restart <kube-apiserver-container-id>✅ Control Plane 구성 요소를 재시작하여 정상적으로 복구 가능
2️⃣ etcd 장애 발생 시 데이터 복구 및 클러스터 정상화
❓ 문제 상황
운영팀에서 쿠버네티스 클러스터의 etcd 스토리지 장애로 인해 클러스터 상태 정보가 손실되었거나, etcd 노드가 정상적으로 작동하지 않고 있습니다.
이를 해결하기 위해 etcd 백업을 복원하고, 클러스터 상태를 정상화해야 합니다.
• 장애 원인: etcd 데이터 손상 또는 노드 장애
• 영향 범위: 클러스터 상태 저장 불가능, API 요청 실패
✅ 어떻게 해결할 수 있을까요?
🛠️ 해결 방법
1. etcd 서비스의 상태를 점검하고, 데이터가 손상되었는지 확인합니다.
2. 이전 백업을 복원하여 etcd 클러스터를 정상화합니다.
✅ etcd 장애 점검 및 복구 명령어
🔹 etcd 상태 확인
ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 endpoint status --write-out=table
💡 예상 출력 값 (비정상적인 경우)
+----------------------+------------------+---------+---------+-----------+-----------+
| ENDPOINT | ID | VERSION | DB SIZE | LEADER | RAFT TERM |
+----------------------+------------------+---------+---------+-----------+-----------+
| https://127.0.0.1:2379 | etcd-1 | 3.5.0 | 0 B | false | 3 |
+----------------------+------------------+---------+---------+-----------+-----------+✅ DB 크기가 0B로 표시되면 etcd 데이터가 손상되었거나 초기화되었음을 의미
🔹 etcd 백업 복원
ETCDCTL_API=3 etcdctl snapshot restore /var/lib/etcd/snapshot.db \
--data-dir /var/lib/etcd-restored \
--initial-cluster=etcd-1=https://127.0.0.1:2380 \
--name=etcd-1✅ 백업된 etcd 데이터를 복원하여 클러스터 상태를 정상화 가능
3️⃣ kubectl 및 시스템 로그를 활용한 클러스터 복구 디버깅 방법
❓ 문제 상황
운영팀에서 쿠버네티스 클러스터 장애가 발생했을 때, 로그를 분석하여 문제의 원인을 파악하고 신속하게 해결해야 합니다.
kubectl 및 시스템 로그 분석을 활용하여 장애 발생 원인을 식별해야 합니다.
✅ 어떻게 해결할 수 있을까요?
🛠️ 해결 방법
1. kubectl describe 명령어를 사용하여 클러스터 노드 및 Pod 상태를 점검합니다.
2. journalctl 및 etcd 로그 파일을 확인하여 장애 원인을 분석합니다.
✅ 클러스터 상태 점검 및 로그 분석 명령어
🔹 노드 상태 점검
kubectl describe node master-node
💡 예상 출력 값 (비정상적인 경우)
Conditions:
Type Status LastHeartbeatTime
---- ------ -----------------
MemoryPressure True 1m
DiskPressure True 1m✅ 메모리 또는 디스크 사용량 문제로 인해 노드가 비정상적인 상태일 가능성이 있음
🔹 etcd 로그 확인
journalctl -u etcd -n 50
💡 예상 출력 값
etcdserver: request timed out✅ etcd가 정상적으로 동작하지 않으며, 클러스터 장애를 유발할 가능성이 있음