Kind(Kubernetes IN Docker)를 사용해 Kubernetes 멀티 노드 클러스터를 구축하고, NGINX Ingress Controller를 배포하는 방법까지 소개합니다. 이 글에서는 Raspberry Pi 5를 기반으로 Docker 27.3.1과 Kubernetes v1.30.0을 사용하여 Kubernetes 클러스터를 구축하였습니다.
Kind는 Kubernetes 클러스터를 Docker 컨테이너 위에서 실행할 수 있도록 해주는 도구로, 로컬 환경에서 멀티 노드 클러스터를 손쉽게 구성할 수 있습니다. 각 노드는 Docker 컨테이너로 동작하며, 컨트롤 플레인과 워커 노드를 포함한 구성이 가능하고, 별도의 가상 머신 없이 Docker만 설치되어 있으면 클러스터를 실행할 수 있습니다. 복잡한 설치 과정 없이 단일 머신에서 전체 Kubernetes 환경을 구성할 수 있어 개발 및 테스트 용도로 적합하며, Calico, MetalLB, CSI 드라이버 등을 추가로 설치하면 기업 내 프라이빗 클러스터와 유사한 네트워크, 로드밸런서, 스토리지 환경도 재현할 수 있습니다.
이 가이드는 arm64(aarch64) 아키텍처 기반의 리눅스 환경을 기준으로 작성되었습니다. 만약 amd64(x86_64) 아키텍처를 사용 중이라면, 해당 아키텍처에 맞는 설치 파일을 별도로 다운로드해야 합니다. 단, 이 가이드에서 사용하는 컨테이너 이미지는 AMD64와 ARM64 아키텍처를 모두 지원하므로 동일하게 사용할 수 있습니다.
1. Raspberry Pi 설정
먼저 Raspberry Pi에서 cgroup v1 기능을 활성화해야 Kind가 정상 동작합니다. 아래 설정을 /boot/firmware/cmdline.txt 파일 맨 뒤에 추가한 후 재부팅합니다.
cgroup_enable=cpuset cgroup_memory=1 cgroup_enable=memory systemd.unified_cgroup_hierarchy=0
재부팅 후 다음 명령으로 설정이 적용되었는지 확인할 수 있습니다:
$ cat /proc/cmdline
2. Kind 클러스터 생성
먼저 Docker 설치한 후에 다음과 같이 Kind를 설치합니다. Raspberry Pi의 Docker 설치는 Docker 공식 문서를 참조합니다.
Kind 설치
curl -Lo ./kind https://github.com/kubernetes-sigs/kind/releases/download/v0.27.0/kind-linux-arm64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind
클러스터 설정
다음은 1개의 control-plane과 3개의 worker 노드로 kubernetes 클러스터를 구성하는 kind 설정입니다.
kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
networking:
apiServerAddress: 127.0.0.1
apiServerPort: 6443
nodes:
- role: control-plane
kubeadmConfigPatches:
- |
kind: InitConfiguration
nodeRegistration:
kubeletExtraArgs:
node-labels: "ingress-ready=true"
extraPortMappings:
- containerPort: 80
hostPort: 80
protocol: TCP
- containerPort: 443
hostPort: 443
protocol: TCP
- role: worker
- role: worker
- role: worker
kind 노드 구성에 대한 방법에 대한 자세한 사항은 Kind 공식 문서를 참고하세요.
클러스터 생성
위의 설정을 kind-4nodes.yaml 파일로 저장한 후, kubernetes 클러스터를 시작하려면 다음 명령어를 실행합니다:
kind create cluster --name kind \
--config ./kind-4nodes.yaml \
--image kindest/node:v1.30.0
클러스터 상태 확인
kubectl를 다운로드 받아 설치합니다.
# kubectl 설치
KUBECTL_VERSION="v1.30.0"
curl -sLO "https://dl.k8s.io/release/${KUBECTL_VERSION}/bin/linux/arm64/kubectl"
sudo mv kubectl /usr/local/bin/
sudo chmod +x /usr/local/bin/kubectl
# 설치 확인
kubectl version --client
클러스터가 정상적으로 생성되었는지 확인하려면 다음 명령어를 실행합니다
kubectl cluster-info
Docker 재시작 정책 설정
Kind 노드들이 OS 재부팅 후 자동으로 시작되도록 설정합니다:
docker update --restart unless-stopped kind-control-plane
docker update --restart unless-stopped kind-worker
docker update --restart unless-stopped kind-worker2
docker update --restart unless-stopped kind-worker3
3. Ingress Controller 설치
Kind 환경에서는 Ingress를 사용하기 위해서는 NGINX Ingress Controller를 별도로 설치해야 합니다. 아래 명령어로 설치하세요.
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/refs/tags/helm-chart-4.9.0/deploy/static/provider/kind/deploy.yaml
설치 완료 후에는 ConfigMap을 수정하여 allow-snippet-annotations 설정을 추가합니다.
kubectl -n ingress-nginx edit cm ingress-nginx-controller
apiVersion: v1
data:
allow-snippet-annotations: "true"
kind: ConfigMap
이 설정은 Ingress 리소스에서 nginx.ingress.kubernetes.io/server-snippet 등의 커스텀 설정을 허용하기 위한 것입니다.
4. NGINX 배포 및 Ingress 설정
NGINX 배포
먼저 NGINX 웹 서버를 배포합니다. 아래의 kubectl 명령어를 사용하여 배포를 시작할 수 있습니다
kubectl create deploy nginx --image nginx
kubectl expose deploy nginx --type NodePort --port 80
kubectl run curl --image=curlimages/curl:latest --restart=Never -- sleep infinity
배포된 curl Pod 내부에서 NGINX 서버에 접근하여 정상적으로 응답을 받는지 테스트할 수 있습니다.
kubectl exec -it curl -- curl http://nginx
Ingress 설정
Ingress를 설정하여 nginx.local 도메인으로 NGINX에 접근할 수 있도록 설정합니다. Ingress 리소스를 생성하려면 아래의 YAML 구성을 사용합니다.
kubectl apply -f - <<EOF
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: nginx-ingress
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
spec:
rules:
- host: nginx.local
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: nginx
port:
number: 80
EOF
위 YAML 파일에서는 nginx.local이라는 호스트 이름을 사용하여 HTTP 요청을 받을 수 있도록 설정합니다. 또한, 요청 경로는 / 경로로 정의되어 있으며, 이를 통해 nginx 서비스로 트래픽을 전달합니다.
nginx.local 도메인에 접근할 수 있도록 로컬 시스템의 /etc/hosts 파일에 다음과 같이 엔트리를 추가합니다.
127.0.0.1 nginx.local
브라우저에서 http://nginx.local로 접속하면 NGINX 웹 서버에 접근할 수 있습니다. 이때 Ingress가 트래픽을 nginx 서비스로 라우팅하여 응답을 반환하게 됩니다.
5. 클러스터 삭제
테스트가 끝나면 아래 명령어로 Kind 클러스터를 삭제할 수 있습니다:
kind delete cluster --name kind
6. 마무리
이번 글에서는 Kind를 사용해 Kubernetes 클러스터를 구축하고 Ingress Controller와 NGINX 배포를 통해 기본적인 기능 구성과 라우팅 기능을 확인해보았습니다. Kind는 Docker가 설치된 Linux 환경이라면 어디서든 간편하게 Kubernetes 클러스터를 구성할 수 있는 경량 도구입니다. 복잡한 인프라 없이도 멀티 노드 클러스터를 실행할 수 있어, Kubernetes 학습부터 애플리케이션 테스트, CI/CD 환경 검증에 이르기까지 폭넓게 활용할 수 있습니다.
다음 글에서는 최근 CI/CD 환경에서 널리 사용되고 있는 기술인 Helm과 Kustomize를 활용하여, Kubernetes 클러스터에 애플리케이션을 배포하는 방법을 소개하겠습니다.