본문으로 건너뛰기

Windows에서 무료 쿠버네티스 실습 환경 만들기: WSL2 + Docker Engine + kind

클라우드 비용 없이 내 PC에 노드 3개짜리 클러스터를 만든 과정과 실제로 겪은 문제

로컬 쿠버네티스 실습 시리즈 목차 · 글 15개
  1. 1편Windows에서 무료 쿠버네티스 실습 환경 만들기: WSL2 + Docker Engine + kind
  2. 2편Headlamp 설치와 사용법: 로컬 쿠버네티스를 화면으로 보고 파드 배포하기
  3. 3편NGINX Ingress 대신 Gateway API: kind 클러스터 앱을 Windows localhost로 접속하기
  4. 4편kube-prometheus-stack 설치와 Grafana 접속: kind 클러스터 모니터링과 target down 해결
  5. 5편Fluent Bit과 Loki로 쿠버네티스 로그 모으기: kind 실습과 Grafana 조회, AWS 확장 예시
  6. 6편cert-manager로 Gateway API HTTPS 붙이기: 사설 CA, 자동 갱신, 만료 알림까지 kind 실습
  7. 7편Keycloak 운영 모드로 Grafana SSO 만들기: Keycloak Operator, CloudNativePG, 이중화와 장애·백업 훈련
  8. 8편OpenTelemetry로 쿠버네티스 트레이스 모으기: Collector, Tempo, 샘플링과 장애 훈련까지 kind 실습
  9. 9편Argo CD로 쿠버네티스 GitOps 전환하기: Helm 설치 넘겨받기, Sealed Secrets, Keycloak SSO와 장애 훈련까지 kind 실습
  10. 부록Argo CD로 nginx 파드 하나 배포하기: GitHub에서 파일 두 개 커밋하고 replicas 바꿔 보기
  11. 10편Trivy Operator로 쿠버네티스 취약점 점검하기: 이미지·설정·비밀값 스캔, Grafana 경보, Argo CD로 고치기까지 kind 실습
  12. 번외편Trivy로 찾은 컨테이너 이미지 취약점 고치기: nginx apk upgrade, Go 의존성 올리기, Grafana처럼 직접 못 고치는 경우까지
  13. 11편Istio Ambient 모드로 서비스 메시 붙이기: 사이드카 없이 mTLS, 권한 정책, waypoint 트래픽 분할과 장애 훈련까지 kind 실습
  14. 12편Strimzi로 쿠버네티스에 Kafka 올리기: KRaft 브로커 3대, SCRAM·ACL, 소비 지연 경보와 장애·업그레이드 훈련까지 kind 실습
  15. 13편Airflow를 쿠버네티스에 올리기: KubernetesExecutor, git-sync DAG 배포, 재시도·catchup부터 스케줄러 장애와 3.4 업그레이드까지 kind 실습

Windows 11에서는 WSL2에 Ubuntu를 설치하고, 그 안에 Docker Engine과 kind를 올리면 클라우드 비용 없이 제어 플레인 1개와 워커 2개로 된 쿠버네티스 클러스터를 만들 수 있습니다. 실제로 해 보니 클러스터 생성은 52초면 끝났고, 시간이 걸린 부분은 WSL 설치 뒤 재부팅과 배포판 설치였습니다. Docker Desktop 없이 Docker 공식 apt 저장소로 설치하고, kubectl·kind·helm은 공식 배포처 파일을 SHA256으로 확인한 뒤 설치합니다.

Windows 11 Pro(빌드 26200), WSL 3.0.3, Ubuntu 24.04 LTS 기준입니다. 설치한 버전은 Docker 29.9.3, kubectl v1.37.2, kind v0.33.0, helm v4.3.1이며 클러스터 노드는 kindest/node:v1.37.0입니다. 회사 PC처럼 관리자 권한이나 가상화 설정이 막힌 환경은 다루지 않습니다.

왜 WSL2 + Docker Engine + kind인가

클라우드에서 쿠버네티스를 실습하면 관리형 컨트롤 플레인, 노드, 로드밸런서 비용이 시간 단위로 나옵니다. 로컬 PC에서는 이 비용이 없고, 클러스터를 지웠다가 1분 안에 다시 만들 수 있어서 설정을 망가뜨려 보는 실습에도 부담이 없습니다.

kind(Kubernetes IN Docker)는 쿠버네티스 노드 하나를 Docker 컨테이너 하나로 띄우는 도구입니다. 컨테이너만 늘리면 노드가 늘어나므로 제어 플레인과 워커를 나눈 다중 노드 구성을 PC 한 대에서 만들 수 있습니다. kind 빠른 시작

이 글에서 쓰는 구성 요소

구성 요소 역할 설치 위치
WSL2 + Ubuntu 24.04 리눅스 커널과 systemd가 있는 실행 환경 Windows
Docker Engine kind 노드 컨테이너를 실행 Ubuntu 안
kind Docker 컨테이너로 쿠버네티스 노드를 생성 Ubuntu 안
kubectl 클러스터에 명령을 보내는 CLI Ubuntu 안
helm 다음 편부터 쓸 오픈소스 패키지 설치 도구 Ubuntu 안

Docker Desktop을 쓰지 않은 이유는 두 가지입니다. WSL 안에 Docker Engine만 두면 구성 요소가 적어 문제가 생겨도 원인을 좁히기 쉽고, Docker Desktop은 회사 규모에 따라 유료 구독이 필요할 수 있어서 개인 실습 환경을 설명할 때 조건이 하나 더 붙기 때문입니다.

1단계: 가상화 확인과 WSL 설치(재부팅 필수)

먼저 CPU 가상화가 BIOS에서 켜져 있는지 확인합니다. 일반 권한 PowerShell에서 아래 명령을 실행해 둘 다 True면 다음 단계로 갑니다.

$p = Get-CimInstance Win32_Processor | Select-Object -First 1
$p.VirtualizationFirmwareEnabled
$p.SecondLevelAddressTranslationExtensions

실습 PC(Ryzen 5 3600X)에서는 둘 다 True였습니다. 이 PC에는 wsl.exe가 있었지만 wsl --status를 실행하면 WSL이 설치되어 있지 않다는 안내가 나왔습니다. wsl.exe는 Windows에 기본으로 들어 있는 진입점일 뿐이므로, 파일이 있다고 WSL이 설치된 것은 아닙니다.

WSL 설치는 Windows 기능을 켜는 작업이라 관리자 권한 PowerShell에서 실행합니다. WSL 설치 안내

Terminal window
wsl --install -d Ubuntu-24.04

여기서 실제로 막힌 부분이 있습니다. 설치 직후 재부팅하지 않은 상태에서는 wsl --version은 정상으로 나오는데 wsl -l -v는 설치된 배포가 없다고 나왔습니다. 배포판 설치를 다시 시도해도 “시스템을 다시 시작하면 변경 사항이 적용됩니다”라는 메시지만 나왔고, 이때 HypervisorPresent 값은 False였습니다. 가상 머신 플랫폼은 재부팅해야 켜지므로 WSL 설치 뒤에는 반드시 재부팅합니다.

재부팅 뒤에도 배포판이 없다면

재부팅 후 HypervisorPresent는 True가 됐지만 Ubuntu는 자동으로 설치되지 않았습니다. 이때는 일반 권한 PowerShell에서 wsl —install -d Ubuntu-24.04를 한 번 더 실행하면 다운로드와 설치가 바로 진행됩니다. 관리자 권한은 필요 없었습니다.

2단계: Ubuntu 안에 Docker Engine 설치

Ubuntu 셸에서 Docker 공식 apt 저장소를 등록하고 설치합니다. Ubuntu 기본 저장소의 docker.io 패키지가 아니라 Docker가 배포하는 패키지를 쓰는 방식입니다. Docker Engine Ubuntu 설치 안내

이 글의 명령은 wsl -d Ubuntu-24.04 -u root로 연 root 셸에서 실행했습니다. 일반 사용자 셸이라면 각 명령 앞에 sudo를 붙입니다.

Terminal window
apt-get update
apt-get install -y ca-certificates curl
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
. /etc/os-release
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu ${UBUNTU_CODENAME:-$VERSION_CODENAME} stable" > /etc/apt/sources.list.d/docker.list
apt-get update
apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

signed-by는 이 저장소의 패키지를 Docker 서명 키로만 검증하도록 묶는 설정입니다. Ubuntu 24.04의 코드명은 noble이라 실제로 등록된 줄은 아래와 같았습니다.

deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu noble stable

WSL의 Ubuntu 24.04는 PID 1이 systemd라서 Docker 서비스가 일반 리눅스처럼 바로 실행됐습니다. 설치 후 확인 결과는 아래와 같습니다.

Terminal window
$ docker version --format 'Client {{.Client.Version}} / Server {{.Server.Version}}'
Client 29.9.3 / Server 29.9.3
$ systemctl is-active docker
active
$ docker run --rm hello-world
Hello from Docker!

3단계: kubectl·kind·helm 설치와 체크섬 확인

세 도구는 모두 실행 파일 하나라서 공식 배포처에서 받아 /usr/local/bin에 넣으면 됩니다. 받은 파일이 배포된 파일과 같은지 SHA256 체크섬을 먼저 확인합니다. 아래는 kubectl 예시입니다. kubectl 설치 안내

Terminal window
KV=$(curl -fsSL https://dl.k8s.io/release/stable.txt)
curl -fsSLO "https://dl.k8s.io/release/$KV/bin/linux/amd64/kubectl"
curl -fsSLO "https://dl.k8s.io/release/$KV/bin/linux/amd64/kubectl.sha256"
echo "$(cat kubectl.sha256) kubectl" | sha256sum --check
install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

kind는 https://kind.sigs.k8s.io/dl/버전/kind-linux-amd64와 같은 위치의 .sha256sum 파일로, helm은 https://get.helm.sh/helm-버전-linux-amd64.tar.gz와 .sha256sum 파일로 같은 방식으로 확인했습니다. 세 파일 모두 OK가 나온 뒤 설치했고, 설치된 버전은 아래와 같습니다.

Client Version: v1.37.2
Kustomize Version: v5.8.1
kind v0.33.0 go1.26.7 linux/amd64
v4.3.1+gc0d08d0

실제로 겪은 오류: curl (23)

최신 버전 번호를 curl … | grep -m1 tag_name 식으로 뽑았더니 curl: (23) Failure writing output to destination이 나왔습니다. grep -m1이 첫 줄을 찾자마자 파이프를 닫아 curl이 쓰기 오류를 내고, set -o pipefail을 켠 스크립트가 그 자리에서 멈춘 것입니다. 응답을 변수에 먼저 담은 뒤 grep하도록 바꾸자 해결됐습니다.

4단계: 노드 3개짜리 kind 클러스터 만들기

노드 구성은 설정 파일로 정합니다. 제어 플레인 1개와 워커 2개를 두고, 다음 편에서 Gateway API를 시험할 수 있게 제어 플레인의 80·443 포트를 Windows 쪽 8080·8443으로 연결했습니다.

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: lab
nodes:
- role: control-plane
kubeadmConfigPatches:
- |
kind: InitConfiguration
nodeRegistration:
kubeletExtraArgs:
node-labels: "ingress-ready=true"
extraPortMappings:
- containerPort: 80
hostPort: 8080
protocol: TCP
- containerPort: 443
hostPort: 8443
protocol: TCP
- role: worker
- role: worker

extraPortMappings는 노드 컨테이너의 포트를 호스트 포트로 내보내는 설정이고, ingress-ready=true 라벨은 이후 게이트웨이 컨트롤러를 이 노드에 두기 위한 표시입니다. 80·443을 그대로 쓰지 않은 이유는 Windows에서 이미 쓰는 포트와 겹치지 않게 하기 위해서입니다.

Terminal window
kind create cluster --config kind-lab.yaml --wait 180s

노드 이미지(kindest/node:v1.37.0) 다운로드를 포함해 52초가 걸렸습니다. 출력 마지막에 Ready after 8s가 나오고 kubectl 컨텍스트가 kind-lab으로 바뀝니다.

워커가 NotReady로 나올 때: 확인과 동작 테스트

생성 직후 바로 kubectl get nodes를 실행하면 제어 플레인만 Ready이고 워커 2개는 NotReady였습니다. 워커가 붙은 지 10초밖에 지나지 않은 시점이었고, kind 출력에도 Waiting ≤ 3m0s for control-plane = Ready라고 나오듯 --wait는 제어 플레인만 기다립니다. 모든 노드를 기다리려면 아래 명령을 씁니다.

Terminal window
$ kubectl wait --for=condition=Ready nodes --all --timeout=180s
node/lab-control-plane condition met
node/lab-worker condition met
node/lab-worker2 condition met
$ kubectl get nodes
NAME STATUS ROLES AGE VERSION
lab-control-plane Ready control-plane 33s v1.37.0
lab-worker Ready <none> 21s v1.37.0
lab-worker2 Ready <none> 21s v1.37.0

노드 목록만으로는 워커가 실제로 파드를 받는지 알 수 없으므로 nginx 파드 2개를 띄워 봤습니다. 약 6초 만에 둘 다 Running이 됐고 lab-worker와 lab-worker2에 하나씩 배치됐습니다. 확인한 뒤 바로 지웁니다.

Terminal window
kubectl create deployment hello --image=nginx:alpine --replicas=2
kubectl rollout status deploy/hello --timeout=120s
kubectl get pods -l app=hello -o wide
kubectl delete deployment hello

만들어진 클러스터 구성

항목 값
노드 lab-control-plane, lab-worker, lab-worker2 (모두 Docker 컨테이너)
노드 OS·런타임 Debian 13, containerd 2.3.4, 커널은 WSL2 커널 공유
네트워크(CNI) kindnet
스토리지 local-path-provisioner (기본 StorageClass)
WSL에 잡힌 자원 CPU 12개, 메모리 약 23GB (PC 48GB의 절반)

자주 묻는 질문

WSL 설치 후 재부팅을 꼭 해야 하나요?

네. 실습 PC에서는 재부팅 전까지 하이퍼바이저가 꺼져 있어(HypervisorPresent False) 배포판이 설치되지 않았습니다. 재부팅 후에도 배포판이 없으면 일반 권한으로 wsl —install -d Ubuntu-24.04를 다시 실행합니다.

일반 사용자로 docker와 kubectl을 쓰려면 어떻게 하나요?

사용자를 docker 그룹에 넣고(sudo usermod -aG docker 사용자명) WSL 셸을 다시 연 뒤, kind export kubeconfig —name lab으로 그 사용자의 kubeconfig에 클러스터 접속 정보를 씁니다. 이 글은 root 셸에서 진행했습니다.

작성 방식과 다음 편

이 글의 명령과 출력은 위에 적은 PC에서 직접 실행한 결과이며, 설치 순서는 Microsoft·Docker·Kubernetes·kind·Helm 공식 문서를 기준으로 했습니다. 실행 기록 정리와 글 작성에 AI 도구를 함께 사용했습니다. 다음 편에서는 이 클러스터를 Windows 앱 Headlamp로 연결해 화면으로 보고, WSL이 꺼졌다 켜졌을 때 클러스터가 다시 살아나는지도 확인합니다.

사진을 누르면 원본 크기