Etcd on homelab89

01. 사전 준비

Mon, 29 Jun 2026 00:00:00 +0000

호스트 패키지 확인 및 설치

# 필수 패키지 확인
dpkg -l | grep -E "virt-install|qemu-kvm|libvirt-daemon|genisoimage|cloud-image-utils|sshpass"

# 설치 (없는 것만)
sudo apt-get install -y \
  qemu-kvm \
  libvirt-daemon-system \
  libvirt-clients \
  virt-install \
  genisoimage \
  cloud-image-utils \
  sshpass \
  python3-pip \
  python3-venv

# libvirt 그룹 확인 (현재 사용자가 포함되어 있어야 함)
groups $USER | grep libvirt
# 없으면: sudo usermod -aG libvirt $USER && newgrp libvirt

SSH 키 준비

# 랩 전용 SSH 키 생성 (기존 키와 분리 권장)
ssh-keygen -t ed25519 -f ~/.ssh/k8s-lab -N "" -C "k8s-lab"

# 생성 확인
ls -la ~/.ssh/k8s-lab*
# ~/.ssh/k8s-lab      ← private key
# ~/.ssh/k8s-lab.pub  ← public key (cloud-init에 삽입됨)

Ubuntu 22.04 Cloud Image 다운로드

# 저장 위치: OS SSD에 여유 충분 (367GB available)
CLOUD_IMAGE_DIR="/var/lib/libvirt/images"
IMAGE_NAME="ubuntu-22.04-server-cloudimg-amd64.img"
IMAGE_URL="https://cloud-images.ubuntu.com/jammy/current/${IMAGE_NAME}"

sudo wget -O "${CLOUD_IMAGE_DIR}/${IMAGE_NAME}" "${IMAGE_URL}"

# 무결성 확인
sudo qemu-img info "${CLOUD_IMAGE_DIR}/${IMAGE_NAME}"

Python 가상환경 + kubespray 의존성 준비

cd /home/jinsoo/Documents/k8s-etcd-lab

# kubespray clone (03-setup-kubespray.sh에서 자동 처리)
git clone https://github.com/kubernetes-sigs/kubespray.git /tmp/kubespray-src

# Python venv 생성
python3 -m venv .venv
source .venv/bin/activate

# kubespray 의존성 설치
pip install -r /tmp/kubespray-src/requirements.txt

# ansible 버전 확인
ansible --version

리소스 요건 확인

항목	필요	현재 호스트
vCPU	12개 (4×3)	24스레드 ✅
RAM	24GB (8×3)	40GB ✅
디스크	120GB (40×3)	SSD 367GB 여유 ✅
네트워크	NAT 브릿지 1개	libvirt 사용 ✅

사전 확인 체크리스트

# KVM 사용 가능 여부
kvm-ok || sudo apt-get install cpu-checker

# libvirtd 실행 상태
sudo systemctl status libvirtd

# 기존 네트워크 확인 (libvirt default network)
virsh net-list --all

# 기존 VM 목록 확인
virsh list --all

03. kubespray 배포 가이드

Mon, 29 Jun 2026 00:00:00 +0000

kubespray 개요

kubespray는 Ansible 기반의 프로덕션급 Kubernetes 클러스터 배포 도구입니다.

kubespray (Ansible Playbook)
    └── cluster.yml
        ├── 부트스트랩 (python, pip 설치)
        ├── etcd 클러스터 구성 (3-node)
        ├── kube-apiserver, kube-scheduler, kube-controller-manager
        ├── kubelet, kube-proxy
        └── CNI (Calico)

kubespray Clone 및 환경 구성

cd /home/jinsoo/Documents/k8s-etcd-lab

# kubespray clone
git clone https://github.com/kubernetes-sigs/kubespray.git /tmp/kubespray-src

# 인벤토리 복사
cp -rfp /tmp/kubespray-src/inventory/sample kubespray/inventory/k8s-etcd-lab

# Python 가상환경 활성화 후 의존성 설치
source .venv/bin/activate
pip install -r /tmp/kubespray-src/requirements.txt

# ansible 연결 테스트
ansible all -i kubespray/inventory/k8s-etcd-lab/hosts.yaml \
    -m ping \
    --private-key ~/.ssh/k8s-lab \
    -u ubuntu

인벤토리 구조

kubespray/inventory/k8s-etcd-lab/hosts.yaml 파일을 사용합니다.

04. etcd 장애 실험 시나리오

Mon, 29 Jun 2026 00:00:00 +0000

etcd Raft 쿼럼 기본 원리

3-node etcd 클러스터:
  - 쿼럼(과반수) = 2
  - 1개 장애: 쿼럼 유지 (2/3 살아있음) → 클러스터 정상 운영
  - 2개 장애: 쿼럼 붕괴 (1/3만 살아있음) → 클러스터 읽기 전용 / 쓰기 불가
  - 3개 장애: 완전 다운

  장애 허용 공식: floor((n-1)/2)
  3노드: floor((3-1)/2) = 1개까지 허용

실험 전 준비

export KUBECONFIG=~/.kube/k8s-etcd-lab.conf

# 실험 전 etcd 상태 베이스라인 기록
kubectl get nodes
kubectl get pods -n kube-system

# etcd 헬스체크 (ctrl1에서)
ssh k8s-ctrl1 "sudo ETCDCTL_API=3 etcdctl \
  --endpoints=https://203.0.113.11:2379,https://203.0.113.12:2379,https://203.0.113.13:2379 \
  --cacert=/etc/ssl/etcd/ssl/ca.pem \
  --cert=/etc/ssl/etcd/ssl/member-k8s-ctrl1.pem \
  --key=/etc/ssl/etcd/ssl/member-k8s-ctrl1-key.pem \
  endpoint health -w table"

시나리오 1: 단일 노드 장애 (쿼럼 유지)

목표: etcd 노드 1개 정지 후 클러스터 운영 영향 확인

05. etcd 복구 절차

Mon, 29 Jun 2026 00:00:00 +0000

복구 시나리오 분류

상황	방법
단일 노드 장애 (데이터 intact)	etcd 재시작으로 자동 동기화
단일 노드 장애 (데이터 손상)	멤버 제거 → 재추가
과반수 장애 (데이터 intact)	모든 노드 재시작
전체 장애 / 데이터 손상	스냅샷으로 복구

복구 1: 단일 노드 자동 재동기화

etcd 데이터가 살아있고 단순히 프로세스가 죽은 경우입니다.