etcd 백업과 복구

왜 etcd 인가

쿠버네티스의 모든 오브젝트(디플로이먼트, 시크릿, RBAC …)는 etcd 한곳에 저장됩니다. etcd 스냅샷 하나가 곧 클러스터 설정 전체의 백업입니다(볼륨 안의 데이터는 제외).

1. 필요한 값 찾기 — 매니페스트에 다 있다

외우지 마세요. etcd 가 static pod 이니 매니페스트를 봅니다.

grep -E "listen-client-urls|cert-file|key-file|trusted-ca-file" /etc/kubernetes/manifests/etcd.yaml
#    - --cert-file=/etc/kubernetes/pki/etcd/server.crt
#    - --key-file=/etc/kubernetes/pki/etcd/server.key
#    - --listen-client-urls=https://127.0.0.1:2379,https://172.30.1.2:2379
#    - --trusted-ca-file=/etc/kubernetes/pki/etcd/ca.crt

2. 백업(스냅샷 저장)

ETCDCTL_API=3 etcdctl snapshot save /opt/etcd-backup.db \
  --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

etcdutl snapshot status /opt/etcd-backup.db -w table     # 확인

• ETCDCTL_API=3 은 최신 etcdctl 에서는 기본값이라 생략해도 되지만, 붙여서 손해 볼 것은 없습니다.
• 인증서를 빼먹으면 오류가 context deadline exceeded 로만 나옵니다. “시간 초과”처럼 보이지만 실제로는 인증 실패인 경우가 대부분입니다.
• etcd 는 보통 컨트롤 플레인 노드에서만 접근됩니다(127.0.0.1). 다른 노드에 있다면 ssh 로 이동하세요.

3. 복구

복구는 세 단계입니다: 새 디렉터리에 풀기 → etcd 가 그 디렉터리를 쓰게 하기 → 확인.

# ① 스냅샷을 새 데이터 디렉터리로 (서버 접속 불필요 → 인증서 필요 없음)
etcdutl snapshot restore /opt/backup/etcd-snapshot.db --data-dir /var/lib/etcd-restore

# ② etcd 매니페스트의 데이터 볼륨을 새 디렉터리로
vi /etc/kubernetes/manifests/etcd.yaml

  volumes:
  - hostPath:
      path: /var/lib/etcd-restore     # ← /var/lib/etcd 에서 변경
      type: DirectoryOrCreate
    name: etcd-data

# ③ kubelet 이 etcd(와 API 서버)를 다시 띄울 때까지 1~2분 기다린 뒤
kubectl get pods -n kube-system
kubectl get deploy -A          # 스냅샷 시점의 상태인지

컨테이너 안의 경로(--data-dir=/var/lib/etcd, mountPath: /var/lib/etcd)는 그대로 두고 호스트 경로(hostPath)만 바꾸는 것이 가장 간단하고 실수가 적습니다. --data-dir 까지 바꾸려면 mountPath 도 같이 바꿔야 합니다.

기다리는 동안 kubectl 이 안 되는 것은 정상입니다. 오래 걸리면 crictl ps -a | grep etcd, crictl logs <ID> 로 확인합니다. 이미 있는 디렉터리로 restore 하면 data-dir … not empty 오류가 나니 새 이름을 쓰세요.

요약 카드

# 백업
etcdctl snapshot save <파일> --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
# 확인
etcdutl snapshot status <파일> -w table
# 복구
etcdutl snapshot restore <파일> --data-dir <새 디렉터리>
vi /etc/kubernetes/manifests/etcd.yaml     # etcd-data hostPath → 새 디렉터리