Cluster Maintenance - 백업 방법(yaml 및 etcd)

Kubernetes 백업/복원은 크게 3축으로 나뉩니다.

1. 클러스터 구성(리소스 매니페스트)
2. 클러스터 상태(etcd)
3. 애플리케이션 데이터(PV/외부 DB 등 영구 스토리지)

이 글은 강의 내용에 맞춰 1)과 2)를 중심으로 정리하고, 특히 etcd 백업/복원에서 많이 헷갈리는 3가지 케이스를 비교합니다.

• (A) etcdctl snapshot save + TLS 옵션(= ca/cert/key) 명시
• (B) etcdctl snapshot save 옵션 없이 짧게 실행(= ca 설정 안 한 것)
• (C) etcdutl backup (파일/데이터 디렉터리 기반)

그리고 복원 시 반드시 만지게 되는 /etc/kubernetes/manifests/etcd.yaml에서 무엇을 수정해야 하는지도 함께 정리합니다.

---

1) 백업 대상: 무엇을 백업해야 하나?

1-1. 선언적 구성(YAML) 백업 (가장 권장)

• Deployment/Service/Ingress/ConfigMap/Secret 등의 정의 파일을 Git에 저장
• 클러스터 유실 시에도 kubectl apply -f로 재배포 가능

팀 표준이 “선언적 + GitOps”로 잘 지켜지면, 구성 백업은 거의 해결됩니다.

1-2. API 서버 기반(현재 상태 덤프)

선언적 표준이 지켜지지 않거나, 명령형으로 만든 리소스가 많다면:

kubectl get deploy,sts,ds,svc,ing,cm,secret -A -o yaml > workload-config.yaml

이 방식은 “복원용 매니페스트”로 쓰려면 status, resourceVersion 같은 필드를 정리하는 추가 작업이 필요할 수 있습니다.

1-3. etcd(클러스터 상태)

etcd는 클러스터 상태(노드/리소스/RBAC 등)의 근간입니다.
따라서 “리소스를 하나씩 덤프”하는 대신 etcd 자체를 백업/복원할 수 있습니다.

---

2) etcd 백업 방식 3종 비교 (요청사항 반영)

결론 요약

• 가장 표준적이고 안정적인 온라인 백업: (A) etcdctl snapshot save + TLS 옵션
• 짧은 명령(B)은 ‘기본값이 맞을 때만’ 성공: kubeadm 기본 etcd(HTTPS+mTLS)에서는 보통 실패
• 파일 레벨 백업(C)은 로컬 파일 기반: 상황에 따라 유용하지만 일관성/절차를 신경 써야 함

---

(A) etcdctl + TLS 옵션: 실행 중 etcd에서 스냅샷(.db) 생성 (온라인/표준)

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.db

• 접속 대상(endpoints) 명확
• kubeadm 등에서 etcd가 보통 HTTPS + mTLS이므로 이 방식이 가장 확실
• 결과물: 단일 파일 .db

스냅샷 무결성/메타데이터 확인:

ETCDCTL_API=3 etcdctl snapshot status /backup/etcd-snapshot.db --write-out=table

---

(B) etcdctl 옵션 없이: etcdctl snapshot save snapshot.db (주의: 대부분 실패하는 패턴)

etcdctl snapshot save snapshot.db

이 명령은 endpoints/TLS/인증서 정보를 안 줍니다.
따라서 etcdctl은 기본값에 의존합니다.

• 기본 endpoints 시도(환경에 따라 127.0.0.1:2379)
• 기본 스킴(환경에 따라 http 시도)
• 인증서/키 없음

kubeadm 기본 etcd가 HTTPS + 인증서 필요이면 흔히 다음과 같은 실패가 납니다.

• TLS handshake 오류
• context deadline exceeded
• bad certificate 등

“짧게” 쓰고 싶다면: 환경변수로 TLS 설정을 고정

아래처럼 한 번 export 해두면 이후엔 짧게 실행해도 (A)와 동일하게 동작합니다.

export ETCDCTL_API=3
export ETCDCTL_ENDPOINTS=https://127.0.0.1:2379
export ETCDCTL_CACERT=/etc/kubernetes/pki/etcd/ca.crt
export ETCDCTL_CERT=/etc/kubernetes/pki/etcd/server.crt
export ETCDCTL_KEY=/etc/kubernetes/pki/etcd/server.key

etcdctl snapshot save snapshot.db

---

(C) etcdutl backup: 데이터 디렉터리 파일 백업(파일 레벨)

etcdutl backup \
  --data-dir /var/lib/etcd \
  --backup-dir /backup/etcd-backup

• etcd에 네트워크로 접속하지 않고, 로컬 data-dir 기반으로 백업
• 결과물: /backup/etcd-backup/ 아래에 여러 파일(backend/WAL 등)

주의(중요)

• 파일 레벨 백업은 “복사 시점” 일관성이 이슈가 될 수 있어 운영에서는 절차를 엄격히 합니다.
• 일반적인 “정기 백업” 목적이면 (A) etcdctl snapshot save가 더 흔한 선택입니다.

---

한눈에 비교표

구분	방식	etcd 실행 중 필요	TLS/인증서 필요	결과물	장점	단점/주의
(A) etcdctl + TLS	온라인 스냅샷	O	O(대부분)	단일 .db	표준/확실/일관된 시점 스냅샷	옵션이 길다
(B) etcdctl 무옵션	온라인 스냅샷(기본값 의존)	O	환경 따라 다름	단일 .db	짧다	kubeadm HTTPS+mTLS에서는 보통 실패
(C) etcdutl backup	파일 레벨 백업	X도 가능	보통 X	디렉터리	네트워크 불필요, 로컬 백업	일관성/절차 신경 필요

---

3) etcd 복원 시 “무조건 알아야 하는” 사실

• etcd 복원은 스냅샷 시점으로 클러스터 상태를 롤백합니다.
• RBAC도 롤백되므로 복원 후 Forbidden이 뜰 수 있습니다(스냅샷 시점에 바인딩이 없었으면 정상적으로도 발생).

---

4) restore 전에 무엇을 내려야 하나?

restore(데이터 디렉터리 교체)는 etcd 실행 중에 하면 안 됩니다.

권장 흐름(쿠브어드민 static pod 환경 기준):

• ✅ etcd 내림
• ✅ kube-apiserver도 내림(복원 중 apiserver가 etcd에 붙으려 해서 꼬일 수 있음)
• 노드 자체 전원/리부팅은 보통 불필요

static pod 내리는 가장 확실한 방법은 /etc/kubernetes/manifests에서 파일을 잠깐 이동하는 방식입니다.

---

5) etcd.yaml에서 “어디를” 수정해야 하나? (요청사항 반영)

kubeadm + stacked etcd(static pod)에서는 보통 파일이 여기 있습니다.

• /etc/kubernetes/manifests/etcd.yaml

5-1. 복원 데이터를 “다른 디렉터리”로 만들었다면: 보통 수정해야 하는 곳 1순위는 hostPath.path

예: restore 결과를 호스트의 /var/lib/etcd-from-backup에 만들었다면,

volumes:
- name: etcd-data
  hostPath:
    path: /var/lib/etcd-from-backup
    type: DirectoryOrCreate

이 변경이 의미하는 바:

• 컨테이너 내부의 /var/lib/etcd는 그대로 두되
• 호스트에서 마운트해주는 실제 데이터 경로만 갈아끼우는 방식

이 패턴이 성립하려면 아래도 함께 맞아야 합니다.

5-2. mountPath와 --data-dir은 “컨테이너 내부 경로” 기준으로 일치해야 함

대부분 kubeadm 기본은 아래처럼 되어 있습니다.

• --data-dir=/var/lib/etcd
• volumeMounts.mountPath: /var/lib/etcd

즉 컨테이너 내부에서는 계속 /var/lib/etcd를 쓰고,
호스트의 어느 디렉터리를 그 자리에 붙이느냐(hostPath.path)만 바꾸는 방식입니다.

따라서 “restore를 /var/lib/etcd-from-backup에 했는데 --data-dir도 그걸로 바꿔야 하나?”
보통은 아니고, hostPath.path만 바꾸는 게 더 일반적입니다.

5-3. HA/토폴로지 관련 파라미터는 임의로 바꾸지 말 것

restore 과정에서 아래 값들이 클러스터 토폴로지와 연관됩니다.

• --name
• --initial-cluster
• --initial-advertise-peer-urls
• --listen-peer-urls
• --listen-client-urls
• --advertise-client-urls

단일 실습 환경에서도 원래 파일에 있던 값을 유지하는 게 안전합니다.
호스트 path만 바꾸는 방식이라면 이 값들은 보통 그대로 둡니다.

5-4. DirectoryOrCreate의 함정

type: DirectoryOrCreate는 디렉터리가 없으면 “빈 디렉터리”를 만들어 마운트합니다.
즉 restore 결과가 없는 경로로 바꾸면 빈 etcd로 새 클러스터처럼 올라갈 수 있습니다.

---

6) 실전 restore 절차(요약 런북)

1. 스냅샷 상태 확인

ETCDCTL_API=3 etcdctl snapshot status /backup/etcd-snapshot.db --write-out=table

2. static pod 내리기(권장: manifest 이동)

sudo mkdir -p /etc/kubernetes/manifests.disabled
sudo mv /etc/kubernetes/manifests/kube-apiserver.yaml /etc/kubernetes/manifests.disabled/
sudo mv /etc/kubernetes/manifests/etcd.yaml /etc/kubernetes/manifests.disabled/

3. restore 결과를 만들 디렉터리 준비(예: /var/lib/etcd-from-backup)

sudo mkdir -p /var/lib/etcd-from-backup

4. restore 실행(예: etcdctl snapshot restore를 그 경로로)

ETCDCTL_API=3 etcdctl snapshot restore /backup/etcd-snapshot.db \
  --data-dir=/var/lib/etcd-from-backup

5. /etc/kubernetes/manifests/etcd.yaml 수정

• volumes.hostPath.path를 /var/lib/etcd-from-backup로 변경
• --data-dir와 mountPath는 보통 /var/lib/etcd 그대로 유지(컨테이너 내부 경로 일치 확인)

6. etcd → apiserver 순서로 올리기

sudo mv /etc/kubernetes/manifests.disabled/etcd.yaml /etc/kubernetes/manifests/
sudo mv /etc/kubernetes/manifests.disabled/kube-apiserver.yaml /etc/kubernetes/manifests/

7. 검증

export KUBECONFIG=/etc/kubernetes/admin.conf
kubectl get nodes
kubectl get pods -A

복원 후 RBAC가 롤백되어 Forbidden이 뜨면 스냅샷 시점 상태로 돌아간 것입니다.

---

7) 체크 포인트(실수 방지)

• (B)처럼 옵션 없는 etcdctl snapshot save는 kubeadm HTTPS+mTLS에서 실패할 가능성이 높음
  → 환경변수로 TLS를 고정하거나 (A)처럼 옵션 명시
• restore는 etcd 실행 중에 하면 안 됨
  → static pod 내리고 수행
• etcd.yaml에서 “호스트 데이터 경로”는 volumes.hostPath.path
  “컨테이너 내부 데이터 경로”는 mountPath + --data-dir
  → 이 관계가 맞아야 정상 기동

 

Practice Test: https://uklabs.kodekloud.com/topic/practice-test-backup-and-restore-methods-2/

 

 

**가장 안전한 방법

<백업>
ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=<trusted-ca-file> --cert=<cert-file> --key=<key-file> \
  snapshot save <backup-file-location>
#https://kubernetes.io/docs/tasks/administer-cluster/configure-upgrade-etcd/

<복구>

etcdutl --data-dir <data-dir-location> snapshot restore snapshot.db

<etcd에 연결>

/etc/kubernetes/pki/etcd/etcd.yaml에서 host path의 path를 위 백업 경로로 변경