쿠버네티스(Kubernetes, k8s)를 테스트하거나 로컬 환경에서 간단하게 실행해보고 싶다면 k3d가 완벽한 솔루션이 될 수 있습니다.
k3d는 k3s를 Docker 컨테이너 내에서 실행할 수 있도록 도와주는 경량 도구로, 가볍고 빠르게 쿠버네티스 클러스터를 구축할 수 있습니다.
이번 포스트에서는 Ubuntu 환경에서 k3d를 설치하고 기본적인 클러스터를 생성하는 방법을 단계별로 알아보겠습니다.
또한 노드 수를 조정하는 방법과 추가적인 기능도 함께 살펴보겠습니다.
✅ 1. k3d 설치 전 준비사항
k3d를 설치하기 전에, 아래 필수 패키지들이 설치되어 있어야 합니다.
🔹 1) Docker 설치
k3d는 k3s를 Docker 컨이너 안에서 실행하기 때문에 Docker가 필수적으로 필요합니다.
Docker가 설치되어 있지 않다면, 공식 가이드를 참고하여 설치해 주세요.
🔹 2) curl 설치
설치 스크립트를 다운로드하기 위해 curl이 필요합니다.
설치되지 않았다면 아래 명령어로 설치합니다.
sudo apt update
sudo apt install curl -y
✅ 2. k3d 설치 방법
k3d는 공식 설치 스크립트를 사용하여 간단하게 설치할 수 있습니다.
🔹 설치 스크립트 실행
터미널에서 아래 명령어를 실행하면 최신 버전의 k3d가 설치됩니다.
curl -s <https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh> | bash
💡 보안 TIP: 직접 실행하기 전에 스크립트를 확인하는 것이 좋습니다.
아래 방법으로 스크립트를 다운로드하고 내용을 검토할 수 있습니다.
curl -s <https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh> -o install.sh
less install.sh # 코드 확인
bash install.sh # 직접 실행
✅ 3. k3d 설치 확인
설치가 완료되면 k3d 명령어가 정상적으로 실행되는지 확인합니다.
k3d version
출력 예시는 다음과 같습니다.
k3d version vX.Y.Z
k3s version v1.A.B
버전 정보가 정상적으로 표시된다면 k3d 설치가 완료된 것입니다! 🎉
✅ 4. k3d를 이용한 k3s 클러스터 생성
이제 로컬 환경에서 간단한 k3s 클러스터를 생성해 보겠습니다.
🔹 기본 클러스터 생성
아래 명령어를 실행하면 mycluster라는 이름의 기본 k3s 클러스터가 생성됩니다.
k3d cluster create mycluster
이 명령어를 실행하면 다음과 같은 작업이 자동으로 수행됩니다.
✔️ Docker 컨테이너 기반의 k3s 클러스터 생성
✔️ kubeconfig 설정 자동 적용
설치가 완료되면 kubectl을 이용해 클러스터 상태를 확인할 수 있습니다.
kubectl get nodes
출력 예시:
NAME STATUS ROLES AGE VERSION
k3d-mycluster-server Ready control-plane,master 1m v1.23.6+k3s1
✅ 5. k3d 클러스터 노드 확장/축소
기본적으로 생성되는 클러스터는 단일 노드 환경입니다.
노드를 늘리거나 줄여서 원하는 규모의 클러스터를 구축할 수 있습니다.
🔹 클러스터 생성 시 다중 노드 추가
아래와 같이 --agents 옵션을 사용하면 워커 노드를 추가할 수 있습니다.
k3d cluster create mycluster --agents 2
이렇게 하면 1개의 마스터 노드(Control Plane)와 2개의 워커 노드(Agent Node)로 구성된 클러스터가 생성됩니다.
확인 명령어:
kubectl get nodes
출력 예시:
NAME STATUS ROLES AGE VERSION
k3d-mycluster-server Ready control-plane,master 1m v1.23.6+k3s1
k3d-mycluster-agent-0 Ready <none> 1m v1.23.6+k3s1
k3d-mycluster-agent-1 Ready <none> 1m v1.23.6+k3s1
🔹 노드 수 줄이기 (클러스터 삭제 후 재생성)
현재 k3d에서는 직접 노드를 줄이는 기능이 없습니다.
따라서 클러스터를 삭제하고 다시 생성하는 방법을 사용해야 합니다.
k3d cluster delete mycluster
k3d cluster create mycluster --agents 1
이제 하나의 워커 노드만 있는 클러스터가 생성됩니다.
✅ 6. 추가 기능 및 활용 예시
k3d는 로컬 개발 환경에서 매우 유용한 기능을 제공합니다.
🔹 포트 매핑 설정
특정 포트를 호스트 머신과 연결하려면 --port 옵션을 사용합니다.
예를 들어, 8080 포트를 클러스터의 API 서버와 연결하려면 다음과 같이 실행합니다.
k3d cluster create mycluster --port 8080:80@loadbalance
🔹 특정 Kubernetes 버전으로 클러스터 생성
원하는 k3s 버전으로 클러스터를 실행하고 싶다면 --image 옵션을 사용하면 됩니다.
k3d cluster create mycluster --image rancher/k3s:v1.23.6-k3s1
✅ 7. 마무리 및 정리
지금까지 k3d를 사용하여 간편하게 k3s 클러스터를 구축하고, 노드를 확장/축소하는 방법을 알아보았습니다.
🔹 k3d는 초경량 Kubernetes 환경을 빠르게 테스트할 때 매우 유용합니다.
🔹 Docker 기반이므로, 손쉽게 클러스터를 삭제하고 재구성할 수 있습니다.
🔹 kubectl과 함께 사용하면 실제 Kubernetes 환경과 거의 동일한 경험을 제공합니다.
k8s를 로컬에서 빠르게 테스트하고 싶은 분들에게 강력 추천합니다! 🚀
더 다양한 기능이 궁금하다면 공식 문서도 참고해 보세요. 😊
매주 한 page, 기술 한 spoon 