KIND Lab Usage Guide

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

도구 요약

클러스터 라이프사이클

클러스터 생성

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

# 단일 노드 (기본)
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

클러스터 목록 확인

kind get clusters

클러스터 삭제

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

# 전체 삭제
kind delete clusters --all

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

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

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

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

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

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

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

Helm 사용

# 리포지토리 추가
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 사용

# 현재 컨텍스트로 실행
k9s

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

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

k9s 핵심 단축키

Docker 이미지를 KIND로 로드

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

# 로컬 이미지를 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 (임시)

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

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

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

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

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

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

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

Docker 리소스 부족

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

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

클러스터 접근 불가

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

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

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

로그 확인

# 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

구성 파일 레퍼런스

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