k8s 마스터 장애, 당황하지 마세요! kubeadm HA etcd 백업/복구 Step-by-Step

1. 도입: 롤백을 위해 백업부터!

쿠버네티스 환경에서 etcd 데이터의 안전한 백업은 장애 대응의 핵심입니다.

저 역시 클러스터에서 예상치 못한 장애나 설정 실수에 대비해

스냅샷 백업을 받아두었고, 실제로 복구(롤백)까지 진행한 경험을 정리합니다.

이 글은 kubeadm으로 구축한 3중화(HA) etcd 클러스터 환경에서

백업
복구(롤백) 실전 명령어와 주의점, 실제로 헷갈릴 수 있는 부분까지 정리한 가이드입니다.

2. etcd 3중화 환경에서 백업하기

etcdctl 설치 및 환경 준비

동작은 master 어느 노드든 하나만 실행하면 됩니다.

wget <https://github.com/etcd-io/etcd/releases/download/v3.5.7/etcd-v3.5.7-linux-amd64.tar.gz>
tar xvf etcd-v3.5.7-linux-amd64.tar.gz
sudo mv etcd-v3.5.7-linux-amd64/etcdctl /usr/local/bin/
sudo chmod +x /usr/local/bin/etcdctl

백업 명령 실행

mkdir /backup
ETCDCTL_API=3 etcdctl \\
  --endpoints="<https://127.0.0.1:2379>" \\
  --cacert="/etc/kubernetes/pki/etcd/ca.crt" \\
  --cert="/etc/kubernetes/pki/etcd/server.crt" \\
  --key="/etc/kubernetes/pki/etcd/server.key" \\
  snapshot save /backup/etcd-snapshot-$(date +%Y%m%d-%H%M%S).db

3. 장애/문제 발생 시 복구(롤백) 절차

1) 기존 데이터 백업(안전 조치)

mv /var/lib/etcd /var/lib/etcd.bak.$(date +%Y%m%d-%H%M%S)
mkdir /var/lib/etcd
chmod 700 /var/lib/etcd

2) etcd 스냅샷에서 데이터 복구

각 etcd 멤버(master1, master2, master3)에서

해당 노드의 이름과 IP에 맞게 아래 명령을 실행합니다.

❗️이 단계에서는 –initial-cluster-state=new 옵션을 사용하지 않습니다!

master1 (예: 192.168.135.61)

etcdctl snapshot restore /backup/etcd-snapshot-20250703-075531.db \\
  --data-dir=/var/lib/etcd \\
  --name=master1 \\
  --initial-cluster="master1=https://192.168.135.61:2380,master2=https://192.168.135.62:2380,master3=https://192.168.135.63:2380" \\
  --initial-advertise-peer-urls=https://192.168.135.61:2380

master2 (예: 192.168.135.62)

etcdctl snapshot restore /backup/etcd-snapshot-20250703-075531.db \\
  --data-dir=/var/lib/etcd \\
  --name=master2 \\
  --initial-cluster="master1=https://192.168.135.61:2380,master2=https://192.168.135.62:2380,master3=https://192.168.135.63:2380" \\
  --initial-advertise-peer-urls=https://192.168.135.62:2380

master3 (예: 192.168.135.63)

etcdctl snapshot restore /backup/etcd-snapshot-20250703-075531.db \\
  --data-dir=/var/lib/etcd \\
  --name=master3 \\
  --initial-cluster="master1=https://192.168.135.61:2380,master2=https://192.168.135.62:2380,master3=https://192.168.135.63:2380" \\
  --initial-advertise-peer-urls=https://192.168.135.63:2380

3) etcd manifest 파일 수정: `-initial-cluster-state=new` 옵션 추가

복구가 끝난 후

etcd를 static pod로 운영하는 경우,/etc/kubernetes/manifests/etcd.yaml에 아래처럼 --initial-cluster-state=new를 반드시 추가해야 합니다.

spec:
  containers:
  - command:
    - etcd
    - --name=master1
    - --data-dir=/var/lib/etcd
    - --initial-advertise-peer-urls=https://192.168.135.61:2380
    - --listen-peer-urls=https://192.168.135.61:2380
    - --listen-client-urls=https://192.168.135.61:2379,<https://127.0.0.1:2379>
    - --advertise-client-urls=https://192.168.135.61:2379
    - --initial-cluster=master1=https://192.168.135.61:2380,master2=https://192.168.135.62:2380,master3=https://192.168.135.63:2380
    - --initial-cluster-state=new    # 반드시 추가!
    # ... (기존 옵션 계속)

이 옵션이 없으면 복구된 데이터로 새로운 클러스터를 시작하지 않고, 기존 클러스터로 조인하려고 시도해서 복구가 실패합니다!
모든 master 노드의 etcd.yaml 파일에 동일하게 반영하세요.

etcd manifest 파일 수정 후 static pod가 자동 재기동됩니다.

4) containerd, kubelet 전체 재기동

복구가 완료되면

컨테이너 런타임(containerd)와 kubelet을 모두 재기동해서

etcd 변경 사항이 정상적으로 반영되도록 합니다.

sudo systemctl restart containerd
sudo systemctl restart kubelet

모든 master 노드에서 순차적으로 실행합니다.

서비스 상태가 모두 active (running) 인지 확인하세요.

4. 복구 후 상태 확인하기

etcd 멤버 목록 확인

ETCDCTL_API=3 etcdctl \\
  --endpoints=https://127.0.0.1:2379 \\
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \\
  --cert=/etc/kubernetes/pki/etcd/server.crt \\
  --key=/etc/kubernetes/pki/etcd/server.key \\
  member list

endpoint health(정상 응답) 체크

ETCDCTL_API=3 etcdctl --endpoints=https://192.168.135.61:2379,<https://192.168.135.62:2379>,<https://192.168.135.63:2379> \\
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \\
  --cert=/etc/kubernetes/pki/etcd/server.crt \\
  --key=/etc/kubernetes/pki/etcd/server.key \\
  endpoint health

모든 노드에서 is healthy를 확인합니다.

컨트롤 플레인 정상 여부도 반드시 kubectl get nodes로 확인!

5. 마지막으로 .. 복구 후에 든 생각

스냅샷 백업은 주기적으로, 외부 스토리지에도 이중 보관!
복구 시
- 각 노드의 이름/주소
- initial-cluster, initial-advertise-peer-urls
- /etc/kubernetes/manifests/etcd.yaml의 -initial-cluster-state=new 를 꼭 다시 확인!
복구 후 etcd, kubelet, containerd 상태도 점검!
실전 전에 test 환경에서 반드시 복구 연습!

명령어와 옵션 위치 하나만 틀려도 etcd 3중화 환경의 백업과 복구(롤백)는 클러스터 전체 장애로 이어질 수 있습니다.

실제 장애상황에서 빠르고 안전하게 복구하려면 정확한 단계별 순서와 옵션 적용이 무엇보다 중요합니다.