blog,Kubernetes

설치 경로는 학습용 로컬 클러스터(kind·minikube), 경량 배포판(k3s), 직접 구축(kubeadm), 매니지드 서비스 네 갈래이며, 목적이 학습인지 운영인지에 따라 갈립니다.

쿠버네티스 공식 문서는 설치 환경을 크게 학습 환경(learning environment)과 운영 환경(production environment)으로 나눕니다(kubernetes.io — 설치). 이 구분을 실무 언어로 풀면 다음 네 경로가 됩니다.

선택 기준은 단순합니다. 쿠버네티스를 처음 만져 본다면 로컬 학습용으로 시작해 개념과 명령어에 익숙해지고, 컨트롤 플레인(control plane, 클러스터 전체를 관리하는 두뇌 역할 구성 요소)이 실제로 어떻게 조립되는지 이해하고 싶거나 온프레미스 운영을 준비한다면 kubeadm으로 직접 구축해 봅니다. 매니지드 서비스는 컨트롤 플레인 운영을 클라우드 사업자에게 맡기는 방식이라 가장 편하지만, 내부 동작이 가려져 있어 학습 단계에서는 오히려 얻는 것이 적습니다.

여기서 한 가지 짚어 둘 것은, 설치 경로를 고른다는 말이 곧 “어디에 올릴지”를 고르는 일이기도 하다는 점입니다. 쿠버네티스는 베어메탈부터 온프레미스 데이터센터, 퍼블릭·프라이빗·하이브리드 클라우드, 그리고 엣지 장비까지 같은 API로 돌아갑니다.

그림 1. 쿠버네티스가 실행되는 여섯 환경 — 설치 경로 선택은 곧 배포 대상 선택이다

이 이식성 덕분에 학습 단계의 선택이 나중을 크게 제약하지 않습니다. 어느 경로로 시작하든 매니페스트와 kubectl 명령은 그대로 통용되므로, “일단 가장 빨리 손에 잡히는 것부터” 시작해도 무방합니다. 조직 단위로 배포판까지 검토해야 한다면 쿠버네티스 배포판 비교에서 상용·오픈소스 선택지를 함께 보시길 권합니다.

어느 경로든 공통 준비물이 하나 있습니다. 클러스터와 대화하는 명령줄 도구 kubectl 입니다. 설치 방법은 운영체제별로 공식 문서(kubernetes.io — kubectl 설치)에 정리되어 있습니다.

kind는 도커 컨테이너를 노드로 쓰는 초경량 클러스터, minikube는 애드온이 풍부한 학습용 표준 클러스터입니다.

kind(Kubernetes in Docker) 는 이름 그대로 도커 컨테이너 하나하나를 쿠버네티스 노드(node, 컨테이너가 실제로 실행되는 서버)로 삼아 클러스터를 만드는 도구입니다(kind 공식 문서). 도커만 설치돼 있으면 명령 한 줄로 클러스터가 만들어지고, 지우는 것도 한 줄입니다. 멀티 노드 구성을 설정 파일로 흉내 낼 수 있어 CI 파이프라인에서 테스트용 클러스터를 만들었다 부수는 용도로도 널리 쓰입니다.

# kind 클러스터 생성과 확인
kind create cluster --name playground
kubectl cluster-info --context kind-playground
kind delete cluster --name playground   # 정리도 한 줄

minikube 는 학습용 로컬 클러스터의 표준으로 불려 온 도구입니다. 2 CPU·2GB 메모리·20GB 디스크 정도면 구동되고, 컨테이너 또는 가상 머신 위에 단일 노드 클러스터를 올립니다(minikube 공식 문서). 대시보드, Ingress, 메트릭 서버 같은 부가 기능을 minikube addons enable 명령으로 켤 수 있어, 클러스터 주변 생태계까지 실습하기에 좋습니다.

minikube start --driver=docker   # 클러스터 시작
minikube addons enable ingress   # Ingress 애드온 활성화
minikube dashboard               # 웹 대시보드 열기

둘 중 무엇을 고를지 고민된다면 이렇게 정리할 수 있습니다. 가볍게 만들었다 지우기를 반복하며 명령어 감각을 익히는 데는 kind가, 대시보드와 애드온까지 갖춘 환경에서 차근차근 배우는 데는 minikube가 낫습니다. 명령줄 설정 자체를 줄이고 싶다면 GUI로 쿠버네티스 버전과 컨테이너 런타임을 고를 수 있는 Rancher Desktop도 후보입니다. 도구별 성격 차이는 eBook 5.1.2 다양한 로컬 쿠버네티스 도구 비교에서 표로 정리해 두었습니다.

k3s는 CNCF 인증을 통과한 경량 배포판으로, 스크립트 한 줄이면 런타임·CNI·인그레스까지 붙은 클러스터가 완성됩니다.

kind와 minikube가 “학습용 클러스터를 만들어 주는 도구”라면, k3s는 표준 쿠버네티스 그 자체를 가볍게 재포장한 배포판입니다. 컨트롤 플레인 전체가 단일 바이너리에 담겨 있고 공식 최소 요구 사양은 메모리 512MB 수준이라, 라즈베리 파이급 장비에서도 돌아갑니다(출처: k3s 공식 문서 — Requirements). CNCF 적합성 테스트를 통과한 인증 배포판이므로 kubectl·Helm·오퍼레이터가 수정 없이 그대로 동작합니다.

# 서버(컨트롤 플레인) 노드 — 이 한 줄로 설치 완료
curl -sfL https://get.k3s.io | sh -
sudo k3s kubectl get nodes

# 워커 노드 합류
curl -sfL https://get.k3s.io | K3S_URL=https://<서버IP>:6443 K3S_TOKEN=<토큰> sh -

주목할 점은 이 한 줄이 무엇을 대신해 주는가입니다. 뒤에서 보게 될 kubeadm 절차의 런타임 설치, CNI 플러그인 배포, 인증서 구성이 설치 스크립트 안으로 흡수돼 있습니다. containerd·Flannel·CoreDNS·Traefik·로컬 스토리지 프로비저너가 기본 동봉되므로 설치 직후 바로 서비스를 올릴 수 있습니다. 다만 이 편리함은 기본 구성을 그대로 받아들일 때의 이야기이고, 조직 표준 CNI나 인그레스로 바꾸려면 설치 옵션으로 기본 컴포넌트를 끄고 시작해야 합니다. 구조와 배포판 선택 기준은 k3s란? 경량 쿠버네티스의 구조와 배포판 선택 가이드에서 자세히 다룹니다. 설치 화면을 그대로 따라가려면 eBook의 5.3.2 openSUSE에 K3s 설치와 5.3.3 K3s 환경 확인 및 kubectl 설정가 단계별 실습을 제공합니다.

kubeadm 구축은 노드 준비 → 컨테이너 런타임·패키지 설치 → 컨트롤 플레인 초기화 → CNI 설치 → 워커 조인 다섯 단계로 진행합니다.

kubeadm은 쿠버네티스 프로젝트가 제공하는 공식 클러스터 부트스트랩 도구입니다. 최소 사양은 노드당 2GB 메모리와 2 CPU이며, 각 노드의 호스트명·MAC 주소가 겹치지 않아야 하고 스왑(swap)은 꺼 두어야 합니다(kubernetes.io — kubeadm 설치). 아래는 컨트롤 플레인 1대 + 워커 1대 구성의 뼈대 절차입니다.

1단계 — 모든 노드 공통 준비. 스왑을 끄고, 컨테이너 간 통신에 필요한 커널 모듈과 네트워크 설정을 적용합니다.

sudo swapoff -a                      # 스왑 비활성화 (kubelet 요구 사항)
sudo modprobe br_netfilter           # 브리지 네트워크 필터 모듈

2단계 — 컨테이너 런타임과 쿠버네티스 패키지 설치. 모든 노드에 containerd 같은 컨테이너 런타임(container runtime, 컨테이너를 실제로 실행하는 소프트웨어)을 설치한 뒤, kubeadm·kubelet·kubectl 세 패키지를 설치합니다. 배포판별 저장소 등록 절차는 공식 문서의 명령을 그대로 따르는 편이 안전합니다(kubernetes.io — kubeadm 설치).

이 단계에서 “왜 도커가 아니라 containerd인가”라는 질문이 자주 나옵니다. 쿠버네티스는 컨테이너를 직접 만들지 않고, 각 노드의 kubelet이 CRI(Container Runtime Interface)라는 표준 규약으로 런타임에 실행을 요청합니다. 도커 엔진은 CRI가 생기기 전의 도구라 어댑터(dockershim)를 거쳐야 했고, 그 어댑터가 쿠버네티스 1.24에서 제거되면서 노드의 실행 엔진 자리는 containerd·CRI-O 같은 CRI 네이티브 런타임으로 정리됐습니다. 도커로 빌드한 이미지는 OCI 표준이라 지금도 그대로 동작하니 빌드 도구를 바꿀 필요는 없습니다. 계층 구분은 containerd·CRI-O·runc 해설과 쿠버네티스 vs 도커에서 이어집니다.

3단계 — 컨트롤 플레인 초기화. 첫 번째 노드에서 kubeadm init을 실행합니다. 파드(Pod, 쿠버네티스의 최소 배포 단위) 네트워크 대역은 뒤에 설치할 CNI 플러그인과 맞춰야 합니다.

sudo kubeadm init --pod-network-cidr=10.244.0.0/16
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

4단계 — CNI 플러그인 설치. 초기화 직후에는 노드가 NotReady 상태입니다. 파드끼리 통신할 네트워크가 아직 없기 때문입니다. Calico, Cilium, Flannel 같은 CNI(Container Network Interface) 플러그인을 설치해야 노드가 Ready로 바뀝니다. 플러그인이 파드에 네트워크를 붙이는 원리와 선택 기준은 eBook 8.1.3 컨테이너 네트워크 인터페이스(CNI)에서 다룹니다.

5단계 — 워커 노드 조인. kubeadm init 출력 마지막에 나온 kubeadm join 명령을 워커 노드에서 실행하면 클러스터에 합류합니다. 토큰을 잃어버렸다면 kubeadm token create --print-join-command로 다시 만들 수 있습니다.

kubectl get nodes    # 모든 노드가 Ready면 구축 완료

폐쇄망이나 사내 표준 환경이라면 여기에 한 가지가 더 붙습니다. 노드가 외부 레지스트리에 접근하지 못하므로 이미지를 사내에 두어야 하는데, 그 구성은 컨테이너 레지스트리와 쿠버네티스 프라이빗 레지스트리 연동에서 확인하실 수 있습니다.

설치 확인의 가장 좋은 방법은 Deployment로 파드를 띄우고 Service로 접속 통로를 여는 첫 배포입니다.

클러스터가 만들어졌다면 실제 워크로드를 올려 봅니다. 아래 매니페스트는 Nginx 웹 서버 파드 2개를 유지하는 디플로이먼트(Deployment)와, 그 파드들에 고정 접속 주소를 부여하는 서비스(Service)를 선언합니다(kubernetes.io — Deployment).

apiVersion: apps/v1
kind: Deployment
metadata:
  name: hello-web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
        - name: nginx
          image: nginx:1.27
          ports:
            - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: hello-svc
spec:
  selector:
    app: hello
  ports:
    - port: 80
      targetPort: 80
  type: NodePort

적용과 확인은 세 줄이면 충분합니다.

kubectl apply -f hello.yaml
kubectl get pods -o wide          # 파드 2개가 Running인지
kubectl get svc hello-svc         # NodePort 번호 확인 후 브라우저 접속

kubectl apply 한 줄로 파드 2개가 뜨는 과정은 사실 컨트롤러의 연쇄입니다. Deployment 컨트롤러가 Deployment를 감시하다 ReplicaSet을 만들고, ReplicaSet 컨트롤러가 그것을 감시하다 선언한 복제본 수만큼 파드를 만듭니다. 각 단계가 독립적으로 도는 조정 루프이기 때문에, 파드가 사라지면 같은 경로를 따라 다시 만들어집니다.

그림 2. kubectl apply 이후 — Deployment → ReplicaSet → Pod로 이어지는 컨트롤러 연쇄

브라우저에서 http://<노드IP>:<NodePort>로 Nginx 환영 페이지가 뜨면 첫 배포까지 성공한 것입니다. 파드가 Pending이나 CrashLoopBackOff에 머문다면 kubectl describe pod <이름>으로 이벤트를 읽는 습관을 들이시길 권합니다. 같은 실습을 화면 단위로 따라가려면 eBook 5.4.1 간단한 Nginx 웹서버 배포와 5.4.2 Service를 이용한 외부 노출를 참고하시고, 파드 상태와 수명주기를 깊이 이해하려면 파드 완벽 가이드가 도움이 됩니다.

노드 Ready, 시스템 파드 Running, DNS 조회, 서비스 접속 네 가지가 통과되면 클러스터는 정상입니다.

설치 직후 아래 항목을 순서대로 점검하면 대부분의 초기 문제를 걸러낼 수 있습니다.

1. 노드 상태 — kubectl get nodes에서 모든 노드가 Ready인지 확인합니다. NotReady라면 CNI 미설치 또는 kubelet 문제일 가능성이 큽니다.
2. 시스템 파드 — kubectl get pods -n kube-system에서 API 서버·스케줄러·CoreDNS 등이 Running인지 봅니다.
3. DNS 동작 — 임시 파드에서 nslookup kubernetes.default가 응답하는지 확인합니다. DNS가 죽어 있으면 서비스 이름 기반 통신이 전부 막힙니다.
4. 서비스 접속 — 앞서 만든 NodePort 서비스에 실제로 HTTP 응답이 오는지 확인합니다.

이 점검이 의미를 가지는 이유는 쿠버네티스가 한 번 만들고 끝내는 시스템이 아니기 때문입니다. 매니페스트를 등록하면 클러스터는 관찰(Observe) → 비교(Analyze) → 조정(Act)을 끝없이 반복하며 선언한 상태로 수렴합니다. 그래서 위 네 항목은 “설치가 됐는가”보다 “조정 루프가 돌고 있는가”를 보는 지표에 가깝습니다.

그림 3. 매니페스트를 등록하면 시작되는 조정 루프 — 설치 검증은 이 루프가 도는지 보는 일이다

여기에 더해 kubeadm 구축이라면 인증서 만료일(kubeadm certs check-expiration)과 방화벽에서 API 서버 포트(6443)가 열려 있는지도 함께 점검해야 합니다. 운영 단계의 사고를 미리 막는 최소한의 안전장치입니다. 조정 루프를 포함한 컨트롤 플레인 내부 동작은 쿠버네티스 아키텍처 완전 정복에서 컴포넌트 단위로 해부합니다.

설치는 하루면 끝나지만, 업그레이드·모니터링·백업 체계를 갖추는 일이 실제 도입의 대부분을 차지합니다.

첫 클러스터를 세우고 나면 학습 곡선의 두 번째 구간이 시작됩니다. 쿠버네티스 도입이 어려운 이유가 설치 난이도가 아니라 운영 체계에 있다는 지적은 여러 번 정리된 바 있습니다(쿠버네티스 도입의 진입 장벽). 실습 클러스터와 운영 클러스터를 가르는 항목은 대략 다음과 같습니다.

• 업그레이드 주기 — 쿠버네티스는 마이너 버전 주기가 빠릅니다. 수동 업그레이드 대신 순차 절차와 롤백 계획을 미리 세워 두어야 합니다(쿠버네티스 업그레이드 가이드 자료).
• 모니터링과 자동화 — 노드·파드 상태를 사람이 눈으로 확인하는 방식은 클러스터가 늘어나는 순간 무너집니다. 운영 자동화의 범위는 쿠버네티스 운영 가이드와 쿠버네티스 자동화 가이드에서 다룹니다.
• 무중단 배포 — 첫 배포가 되면 다음은 재배포입니다. 구버전을 순차 교체하는 롤링 업데이트가 기본 전략입니다.
• 규모의 감각 — 클러스터가 수십·수백 개가 되면 개별 클러스터의 사양보다 “같은 구성을 어떻게 찍어내고 관리하는가”가 승부처가 됩니다. 카카오의 온프레미스 7,000개 클러스터 운영 사례와 LY(라인·야후)가 15명으로 1,300개 클러스터를 운영하는 사례가 그 규모의 실제를 보여 줍니다.

가상화 환경을 운영해 온 엔지니어라면 기존 감각과 무엇이 달라지는지부터 맞춰 두는 편이 빠릅니다. 그 대응표는 VM 엔지니어를 위한 쿠버네티스에 정리되어 있습니다.

설치를 마쳤다면 아키텍처 → 워크로드 → 네트워킹 순서로 학습을 넓히는 경로를 권합니다.

첫 클러스터는 끝이 아니라 출발점입니다. 방금 만든 클러스터를 교보재 삼아 다음 순서로 이해를 넓혀 가시길 권합니다.

• 쿠버네티스 아키텍처 완전 정복 — kubeadm init이 만들어 낸 컨트롤 플레인 구성 요소들이 각각 무슨 일을 하는지 해부합니다.
• 쿠버네티스 Pod 완벽 가이드 — 첫 배포에서 띄운 파드의 생명주기와 멀티컨테이너 패턴을 다룹니다.
• 8.1.3 컨테이너 네트워크 인터페이스(CNI) — 4단계에서 설치한 CNI 플러그인이 어떤 원리로 파드를 연결하는지 이어집니다.
• 클라우드 네이티브 4대 요소 — 클러스터를 세운 다음 조직이 갖춰야 할 나머지 축(MSA·CI/CD·DevOps)을 짚습니다.

학습용 클러스터에서 손에 익힌 명령과 개념은 매니지드 서비스든 온프레미스든 그대로 통용됩니다. 오늘 만든 작은 클러스터가 팀의 운영 표준을 세우는 첫 실험대가 되기를 바랍니다.

쿠버네티스 설치는 무엇으로 시작하는 것이 좋나요?

처음이라면 kind 또는 minikube로 로컬 클러스터를 만들어 시작하는 것이 가장 빠릅니다. 노트북 한 대(2 CPU·2GB 이상)면 충분하고, 만들고 지우기를 부담 없이 반복하며 kubectl 명령과 핵심 개념을 익힐 수 있습니다(kubernetes.io — 설치).

kubeadm과 minikube는 무엇이 다른가요?

minikube는 한 대 안에 학습용 클러스터를 자동으로 만들어 주는 도구이고, kubeadm은 여러 서버로 실제 클러스터를 직접 조립하는 공식 부트스트랩 도구입니다. 학습 초기는 minikube, 클러스터 내부 구조 이해와 온프레미스 구축 준비는 kubeadm이 적합합니다.

kubeadm 대신 k3s로 시작해도 되나요?

됩니다. k3s는 CNCF 적합성 인증을 통과한 배포판이라 표준 API가 그대로 유지되고, 설치 스크립트 한 줄로 런타임·CNI·인그레스까지 붙습니다. 다만 컨트롤 플레인이 어떻게 조립되는지 손으로 확인하는 학습 효과는 kubeadm 쪽이 큽니다. 목적이 “빨리 쓰는 것”이면 k3s, “구조를 아는 것”이면 kubeadm입니다.

kubeadm 설치 최소 사양은 어떻게 되나요?

노드당 최소 2GB 메모리와 2 CPU가 필요하며, 스왑을 비활성화해야 하고 노드 간 호스트명·MAC 주소가 겹치지 않아야 합니다(kubernetes.io — kubeadm 설치). 실습이라면 VM 2대(컨트롤 플레인 1 + 워커 1)로 시작하는 구성을 권합니다.

설치 후 노드가 NotReady로 남아 있으면 어떻게 하나요?

가장 흔한 원인은 CNI 플러그인 미설치입니다. 파드 네트워크가 없으면 노드는 Ready가 되지 않습니다. Calico·Cilium·Flannel 중 하나를 설치하고, 그래도 해결되지 않으면 kubectl describe node와 kubelet 로그에서 원인을 확인합니다.

노드 런타임으로 도커를 쓰면 안 되나요?

쿠버네티스 1.24에서 도커 엔진을 잇던 어댑터(dockershim)가 제거돼, 노드 실행 엔진은 containerd·CRI-O 같은 CRI 네이티브 런타임을 씁니다. 반면 도커로 빌드한 이미지는 OCI 표준이라 그대로 실행되므로 빌드 도구를 바꿀 필요는 없습니다(containerd·CRI-O·runc 해설).

프로덕션도 kubeadm으로 구축해야 하나요?

반드시 그렇지는 않습니다. 운영 부담을 줄이려면 매니지드 서비스가 현실적 선택이고, 데이터 주권·규제·비용 때문에 온프레미스가 필요할 때 kubeadm 기반 직접 구축이 의미를 가집니다. 상용·오픈소스 선택지를 함께 보려면 쿠버네티스 배포판 비교가 출발점이 됩니다.

• 쿠버네티스란 무엇인가 — AI 표준 플랫폼
• 쿠버네티스 아키텍처 완전 정복 — 컨트롤 플레인부터 워커 노드까지
• 쿠버네티스 Pod 완벽 가이드 — 개념·생명주기·멀티컨테이너 패턴
• 쿠버네티스 vs 도커 — 차이와 관계, 언제 무엇을 쓰나
• k3s란? 경량 쿠버네티스의 구조와 배포판 선택 가이드
• containerd·CRI-O·runc — 컨테이너 런타임 표준과 구분
• 쿠버네티스 배포판 비교 — 무엇을 고를 것인가
• 쿠버네티스 도입의 진입 장벽
• VM 엔지니어를 위한 쿠버네티스
• 클라우드 네이티브 4대 요소 — 컨테이너·MSA·CI/CD·DevOps

쿠버네티스 공식 문서

• 쿠버네티스 공식 문서 — 설치(한국어)
• kubectl 설치 가이드
• kubeadm 설치 공식 문서
• kind 공식 문서
• minikube 공식 문서
• k3s 공식 문서 — Requirements

쿠버네티스 eBook (cncf.co.kr)

• 제5장 로컬 쿠버네티스 클러스터 구축
• 5.1.2 다양한 로컬 쿠버네티스 도구 비교
• 5.3.2 openSUSE에 K3s 설치
• 5.3.3 K3s 환경 확인 및 kubectl 설정
• 5.4.1 간단한 Nginx 웹서버 배포
• 5.4.2 Service를 이용한 외부 노출
• 8.1.3 컨테이너 네트워크 인터페이스(CNI)

자료 다운로드 (cncf.co.kr)

• 컨테이너와 쿠버네티스 기술 자료
• 쿠버네티스 아키텍처 가이드
• 컨테이너 런타임 — 주요 기술과 비교
• 쿠버네티스 업그레이드 가이드