guidek8s 2026-06-29kuberneteskindlab

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/

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

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

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

구성 파일 레퍼런스

파일	구성	용도
`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/에 위치한다.

Files

Raw Markdown (index.md)