# k8s-etcd-lab

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

## 목적

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

## 환경 스펙

| 항목 | 값 |
|------|----|
| Host OS | Ubuntu 24.04.4 LTS |
| Hypervisor | KVM + QEMU 8.2.2 + Libvirt 10.0.0 |
| VM OS | Ubuntu 22.04 LTS (cloud image) |
| VM 수 | 3개 (전부 control plane + etcd) |
| 네트워크 | 203.0.113.0/24 (k8s-lab 전용 NAT 네트워크) |
| Kubernetes | kubespray (최신 release 브랜치) |
| CNI | Calico |

## VM 구성

| 호스트명 | IP | vCPU | RAM | Disk | 역할 |
|----------|----|------|-----|------|------|
| k8s-ctrl1 | 203.0.113.11 | 4 | 8GB | 40GB | control-plane + etcd |
| k8s-ctrl2 | 203.0.113.12 | 4 | 8GB | 40GB | control-plane + etcd |
| k8s-ctrl3 | 203.0.113.13 | 4 | 8GB | 40GB | control-plane + etcd |

> 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: 스냅샷 복구
```

## 빠른 시작 순서

```bash
# 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](https://github.com/kubernetes-sigs/kubespray)
- [kubespray 공식 문서](https://kubespray.io)
- [etcd 운영 가이드](https://etcd.io/docs/v3.5/op-guide/)
- [etcd 재해 복구](https://etcd.io/docs/v3.5/op-guide/recovery/)