# Runbook: KIND-Based Local Kubernetes Lab Setup

**Date:** 2026-03-02
**KIND:** v0.31.0
**Kubernetes:** v1.34.3 (single-node, control-plane only)
**Cluster Name:** lab (context: kind-lab)

---

## Verified Environment

| Component | Detail |
|---|---|
| OS | Ubuntu 24.04.4 LTS, Linux 6.17.0-14-generic |
| Docker | 29.2.1 (cgroup v2, systemd) |
| kubectl | v1.35.1 |
| KIND | v0.31.0 |
| Helm | v3.20.0 |
| krew | v0.4.5 (플러그인 매니저) |
| k9s | v0.50.18 |
| Shell | zsh + oh-my-zsh + Powerlevel10k |

---

## 1. KIND 설치

GitHub releases에서 바이너리를 직접 다운로드하여 설치.

```bash
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.31.0/kind-linux-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind
```

설치 경로: `/usr/local/bin/kind`

---

## 2. 클러스터 구성 파일 생성

`~/kind-configs/` 디렉토리에 3개의 구성 파일을 생성했다.

### 디렉토리 구조

```
~/kind-configs/
├── single-node.yaml         # 기본 단일노드 (현재 사용 중)
├── multi-worker.yaml         # CP1 + Worker3 (레퍼런스)
└── ha-control-plane.yaml     # CP3 + Worker3 (레퍼런스)
```

### single-node.yaml (현재 사용)

```yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: lab
nodes:
  - role: control-plane
networking:
  podSubnet: "10.244.0.0/16"
  serviceSubnet: "10.96.0.0/12"
```

- control-plane 1대가 워커 역할을 겸한다 (KIND 기본 동작).
- taint가 없으므로 별도 toleration 없이 워크로드 스케줄링 가능.

### multi-worker.yaml (레퍼런스, 미생성)

```yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: lab-multi
nodes:
  - role: control-plane
  - role: worker
  - role: worker
  - role: worker
networking:
  podSubnet: "10.244.0.0/16"
  serviceSubnet: "10.96.0.0/12"
```

- Gateway API, CNI 교체, Pod 분산 스케줄링 실험 등에 적합.

### ha-control-plane.yaml (레퍼런스, 미생성)

```yaml
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: lab-ha
nodes:
  - role: control-plane
  - role: control-plane
  - role: control-plane
  - role: worker
  - role: worker
  - role: worker
networking:
  podSubnet: "10.244.0.0/16"
  serviceSubnet: "10.96.0.0/12"
```

- etcd 클러스터링, leader election, control-plane HA 스터디용.

---

## 3. 클러스터 생성

```bash
kind create cluster --config ~/kind-configs/single-node.yaml --image kindest/node:v1.34.3
```

생성 후 `kubectl context`가 자동으로 `kind-lab`으로 설정된다.

---

## 4. Helm v3.20.0 설치

공식 설치 스크립트 사용:

```bash
curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | DESIRED_VERSION=v3.20.0 bash
```

설치 경로: `/usr/local/bin/helm`

---

## 5. krew 설치

```bash
(
  set -x; cd "$(mktemp -d)" &&
  OS="$(uname | tr '[:upper:]' '[:lower:]')" &&
  ARCH="$(uname -m | sed -e 's/x86_64/amd64/' -e 's/aarch64/arm64/')" &&
  KREW="krew-${OS}_${ARCH}" &&
  curl -fsSLO "https://github.com/kubernetes-sigs/krew/releases/download/v0.5.0/${KREW}.tar.gz" &&
  tar zxvf "${KREW}.tar.gz" &&
  ./"${KREW}" install krew
)
```

설치 경로: `~/.krew/bin/kubectl-krew`

### krew 플러그인 설치

```bash
kubectl krew install ctx   # kubectx — 컨텍스트 전환
kubectl krew install ns    # kubens — 네임스페이스 전환
```

---

## 6. k9s 설치

webi.sh를 통해 설치:

```bash
curl -sS https://webi.sh/k9s | sh
```

설치 경로: `~/.local/bin/k9s` (v0.50.18)

---

## 7. Shell 설정 (~/.zshrc)

이번 작업에서 추가한 항목:

```bash
# alias k에 자동완성 연결
compdef k=kubectl

# KIND / Helm 자동완성
source <(kind completion zsh)
source <(helm completion zsh)
```

기존에 이미 설정되어 있던 항목:

| 항목 | 출처 |
|---|---|
| kubectl 자동완성 | oh-my-zsh `kubectl` 플러그인 |
| `alias k=kubectl` | `~/.zshrc` 직접 설정 |
| `alias kns=kubens`, `alias kctx=kubectx` | `~/.zshrc` 직접 설정 |
| krew PATH (`~/.krew/bin`) | `~/.zshrc` PATH 설정 |
| k9s PATH (`~/.local/bin`) | envman (`~/.config/envman/load.sh`) |

---

## 8. 검증 결과

```
kind version              → v0.31.0
kubectl get nodes         → lab-control-plane  Ready  v1.34.3
helm version --short      → v3.20.0
kubectl krew version      → v0.4.5
k9s version --short       → v0.50.18
kubectl run nginx          → Pod 생성·Running 확인 후 삭제 완료
```