k8s-etcd-lab

KVM 기반 3-노드 Kubernetes 클러스터를 구성하고 etcd 장애 시나리오를 실험하는 로컬 랩 환경입니다.

목적

• kubespray로 HA 컨트롤 플레인(3-node etcd 클러스터) 구성 실습
• etcd 단일 노드 장애 / 다수 노드 장애 / 스냅샷 백업·복구 실험
• 실제 프로덕션 장애 패턴을 안전한 VM 환경에서 재현

환경 스펙

VM 구성

Host 리소스: Ryzen 9 5900X (24t) / 40GB RAM → VM 3대에 12vCPU + 24GB 할당, Host 여유 충분

디렉토리 구조

k8s-etcd-lab/
├── README.md
├── docs/
│   ├── 01-prerequisites.md       # 사전 준비 및 패키지 설치
│   ├── 02-vm-setup.md            # VM 생성 가이드
│   ├── 03-kubespray-deploy.md    # kubespray 설치·배포 가이드
│   ├── 04-etcd-experiments.md    # etcd 장애 실험 시나리오
│   └── 05-recovery.md            # 복구 절차
├── network/
│   └── k8s-lab-network.xml       # libvirt 전용 네트워크 정의
├── cloud-init/
│   ├── user-data                 # VM 초기화 설정 (SSH, 패키지 등)
│   └── meta-data                 # VM 메타데이터 (hostname, instance-id)
├── scripts/
│   ├── lib/common.sh             # 공통 함수
│   ├── 01-setup-network.sh       # libvirt 네트워크 생성
│   ├── 02-create-vms.sh          # VM 3대 생성
│   ├── 03-setup-kubespray.sh     # kubespray clone + 인벤토리 구성
│   ├── 04-run-kubespray.sh       # 클러스터 배포 실행
│   └── 99-cleanup.sh             # 전체 환경 정리(삭제)
├── kubespray/
│   └── inventory/
│       └── k8s-etcd-lab/
│           ├── hosts.yaml
│           └── group_vars/
│               ├── all/all.yml
│               └── k8s_cluster/
│                   ├── k8s-cluster.yml
│                   └── addons.yml
└── experiments/
    ├── lib/etcd-helpers.sh           # etcd 공통 헬퍼 함수
    ├── 01-single-node-failure.sh     # 시나리오1: 단일 노드 장애
    ├── 02-majority-failure.sh        # 시나리오2: 과반수 장애
    ├── 03-snapshot-backup.sh         # 시나리오3: 스냅샷 백업
    └── 04-restore-from-snapshot.sh   # 시나리오4: 스냅샷 복구

빠른 시작 순서

# 1. 사전 준비 확인
cat docs/01-prerequisites.md

# 2. 전용 네트워크 생성
bash scripts/01-setup-network.sh

# 3. VM 3대 생성
bash scripts/02-create-vms.sh

# 4. kubespray 준비
bash scripts/03-setup-kubespray.sh

# 5. 클러스터 배포 (약 20~30분)
bash scripts/04-run-kubespray.sh

# 6. 실험 진행
bash experiments/01-single-node-failure.sh
bash experiments/03-snapshot-backup.sh
bash experiments/04-restore-from-snapshot.sh

# 7. 전체 정리
bash scripts/99-cleanup.sh

참고 자료

• kubespray GitHub
• kubespray 공식 문서
• etcd 운영 가이드
• etcd 재해 복구