# KIND Lab Usage Guide

**Verified:** 2026-03-02
**환경:** Ubuntu 24.04 LTS, Docker 29.2.1, KIND v0.31.0

---

## 도구 요약

| 도구 | 경로 | 용도 |
|---|---|---|
| `kind` | `/usr/local/bin/kind` | 클러스터 생성/삭제/관리 |
| `kubectl` | `/usr/local/bin/kubectl` (alias: `k`) | K8s 리소스 조작 |
| `helm` | `/usr/local/bin/helm` | 차트 기반 앱 배포 |
| `kubectl krew` | `~/.krew/bin/` | kubectl 플러그인 매니저 |
| `kubectl ctx` | krew 플러그인 | 컨텍스트 전환 |
| `kubectl ns` | krew 플러그인 | 네임스페이스 전환 |
| `k9s` | `~/.local/bin/k9s` | 터미널 기반 K8s 대시보드 |

---

## 클러스터 라이프사이클

### 클러스터 생성

구성 파일 위치: `~/kind-configs/`

```bash
# 단일 노드 (기본)
kind create cluster --config ~/kind-configs/single-node.yaml --image kindest/node:v1.34.3

# 멀티 워커 (CP1 + Worker3)
kind create cluster --config ~/kind-configs/multi-worker.yaml --image kindest/node:v1.34.3

# HA 구성 (CP3 + Worker3)
kind create cluster --config ~/kind-configs/ha-control-plane.yaml --image kindest/node:v1.34.3
```

`--image` 태그를 변경하면 다른 K8s 버전으로 생성할 수 있다.
사용 가능한 이미지 목록: https://github.com/kubernetes-sigs/kind/releases

### 클러스터 목록 확인

```bash
kind get clusters
```

### 클러스터 삭제

```bash
# 특정 클러스터 삭제
kind delete cluster --name lab

# 전체 삭제
kind delete clusters --all
```

### 클러스터 재생성 (초기화)

KIND는 상태 초기화 기능이 없으므로, 삭제 후 재생성한다:

```bash
kind delete cluster --name lab && \
kind create cluster --config ~/kind-configs/single-node.yaml --image kindest/node:v1.34.3
```

---

## 컨텍스트/네임스페이스 전환

KIND 클러스터의 컨텍스트 이름은 `kind-<클러스터명>` 형식이다.

```bash
# 컨텍스트 목록 및 전환
kubectl ctx              # 목록 표시 (fzf 설치 시 인터랙티브 선택)
kubectl ctx kind-lab     # kind-lab으로 전환

# 네임스페이스 전환
kubectl ns               # 목록 표시
kubectl ns kube-system   # kube-system으로 전환
kubectl ns -             # 이전 네임스페이스로 복귀
```

---

## Helm 사용

```bash
# 리포지토리 추가
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

# 차트 검색
helm search repo nginx

# 설치
helm install my-nginx bitnami/nginx -n default

# 목록 확인
helm list -A

# 삭제
helm uninstall my-nginx -n default
```

---

## k9s 사용

```bash
# 현재 컨텍스트로 실행
k9s

# 특정 컨텍스트 지정
k9s --context kind-lab

# 특정 네임스페이스로 시작
k9s -n kube-system
```

### k9s 핵심 단축키

| 키 | 동작 |
|---|---|
| `:` | 리소스 타입 입력 (`:pod`, `:svc`, `:deploy` 등) |
| `/` | 필터링 (이름 검색) |
| `d` | describe |
| `l` | 로그 보기 |
| `s` | 셸 접속 (exec) |
| `e` | YAML 편집 |
| `ctrl-d` | 삭제 |
| `ctrl-k` | kill (강제 삭제) |
| `esc` | 뒤로 가기 |
| `ctrl-c` | 종료 |

---

## Docker 이미지를 KIND로 로드

로컬에서 빌드한 이미지를 KIND 클러스터에서 사용하려면:

```bash
# 로컬 이미지를 KIND 노드로 로드
kind load docker-image my-app:latest --name lab

# 로드된 이미지 확인
docker exec lab-control-plane crictl images | grep my-app
```

Pod에서 사용할 때 `imagePullPolicy: Never` 또는 `IfNotPresent`로 설정해야 한다.

---

## 포트 포워딩

KIND 노드는 Docker 컨테이너이므로 외부 접근에는 포트 포워딩이 필요하다.

### 방법 1: kubectl port-forward (임시)

```bash
kubectl port-forward svc/my-service 8080:80
# localhost:8080으로 접근 가능
```

### 방법 2: KIND 구성에서 extraPortMappings (영구)

클러스터 생성 시 구성 파일에 포트 매핑을 추가한다:

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

NodePort 서비스(30000번)를 호스트에서 직접 접근할 수 있다.
이미 생성된 클러스터에는 적용할 수 없으므로 재생성이 필요하다.

---

## 트러블슈팅

### 노드가 NotReady

```bash
# 원인 확인
kubectl describe node lab-control-plane | grep -A5 Conditions

# 시스템 Pod 상태 확인
kubectl get pods -n kube-system
```

보통 CNI(kindnet)나 CoreDNS가 아직 초기화 중일 때 발생하며, 1-2분 대기하면 해결된다.

### Docker 리소스 부족

```bash
# Docker가 사용 중인 리소스 확인
docker system df

# 사용하지 않는 이미지/컨테이너 정리
docker system prune -f
```

### 클러스터 접근 불가

```bash
# Docker 컨테이너 상태 확인
docker ps -a | grep kind

# 컨테이너가 중지된 경우 재시작
docker start lab-control-plane

# kubeconfig 컨텍스트 확인
kubectl config get-contexts
```

### 로그 확인

```bash
# KIND 노드의 kubelet 로그
docker exec lab-control-plane journalctl -u kubelet --no-pager -n 50

# 특정 시스템 컴포넌트 로그
kubectl logs -n kube-system -l component=etcd
kubectl logs -n kube-system -l k8s-app=kube-dns
```

---

## 구성 파일 레퍼런스

| 파일 | 구성 | 용도 |
|---|---|---|
| `single-node.yaml` | CP 1 (워커 겸용) | 일반 실험, 앱 배포 연습 |
| `multi-worker.yaml` | CP 1 + Worker 3 | 스케줄링, CNI, Gateway API 실험 |
| `ha-control-plane.yaml` | CP 3 + Worker 3 | HA, etcd, leader election 스터디 |

모든 파일은 `~/kind-configs/`에 위치한다.