생산성

쿠버네티스 입문 가이드: 핵심 개념과 Minikube 실전 설정법

March 8, 2026 5 min read 한국어
쿠버네티스 입문 가이드: 핵심 개념과 Minikube 실전 설정법

Pod가 죽었는데 아무도 몰랐어요. 서버 한 대에 컨테이너 세 개 올려두고 “잘 되겠지” 했다가, 새벽에 알람 받고 일어나서 수동으로 재시작한 경험, 한 번쯤 있지 않나요?

그게 쿠버네티스가 필요한 이유예요.

이 글을 끝까지 읽으면:

  • 쿠버네티스 핵심 아키텍처를 머릿속에 그릴 수 있어요
  • 로컬 환경(Minikube)에서 첫 Pod를 직접 띄울 수 있어요
  • 실제 현장에서 자주 쓰는 패턴을 바로 따라 할 수 있어요
  • 흔한 실수를 미리 피할 수 있어요

Key Takeaways

  • 쿠버네티스는 컨테이너 수백 개를 자동으로 배포·재시작·스케일링해주는 오케스트레이터로, 2026년 기준 CNCF 조사에서 기업의 84%가 프로덕션에 사용하고 있어요.
  • 핵심 구성은 Control Plane(두뇌)과 Worker Node(일꾼)로 나뉘며, 모든 설정은 선언형 YAML로 관리해요.
  • Minikube + kubectl 조합으로 로컬에서 5분 안에 첫 클러스터를 띄울 수 있어요.
  • Pod, Deployment, Service 세 개만 이해하면 기본 앱 배포는 가능해요.
  • YAML 들여쓰기 오류와 Namespace 미지정은 입문자가 가장 많이 걸리는 두 가지 함정이에요.

쿠버네티스가 뭔데 이렇게 난리예요?

도커만 써도 컨테이너 실행은 돼요. 그런데 컨테이너가 열 개, 백 개, 천 개가 되면? 어떤 서버에 어떤 컨테이너를 올릴지, 죽으면 자동으로 살릴지, 트래픽이 몰리면 자동으로 늘릴지를 사람이 직접 관리하는 건 현실적으로 불가능해요.

쿠버네티스는 2014년 구글이 오픈소스로 공개했어요. 구글 내부에서 10년 넘게 쓰던 Borg 시스템을 다듬은 거예요. 2016년 CNCF에 기증된 이후 지금은 AWS, Azure, GCP 모두 관리형 쿠버네티스(EKS, AKS, GKE)를 제공하고 있어요.

지금 배워야 하는 이유

2026년 기준 DevOps/SRE 채용 공고의 73%가 쿠버네티스 경험을 요구해요(Stack Overflow Developer Survey 2025 기준). 도커만 안다고 충분하던 시절은 지났어요.

사전 지식으로 필요한 건:

  • Docker 기본 (이미지 빌드, 컨테이너 실행)
  • Linux 커맨드라인 기초
  • YAML 문법 (들여쓰기가 핵심!)

쿠버네티스 vs 대안 비교

항목쿠버네티스Docker SwarmAWS ECS
학습 난이도높음 (진입장벽 있음)낮음 (Docker와 유사)중간 (AWS 친숙하면 쉬움)
스케일링자동 (HPA/VPA 지원)수동 중심자동 (Fargate 활용)
커뮤니티매우 활발 (CNCF 생태계)활동 축소 중AWS 종속
클라우드 이식성높음 (멀티클라우드)중간낮음 (AWS 전용)
프로덕션 성숙도높음 (84% 기업 사용)낮아지는 추세중간
비용클러스터 운영 비용 필요낮음온디맨드 과금

Docker Swarm은 진입장벽이 낮지만 복잡한 워크로드엔 부족해요. ECS는 AWS 안에서만 쓴다면 편하지만, 멀티클라우드나 온프레미스로 가면 한계가 분명해요. 장기적으로 이식성과 생태계를 보면 쿠버네티스를 익혀두는 게 맞아요.

실전 설정: 첫 클러스터 띄우기

사전 준비물

  • Docker Desktop (v26 이상) 또는 Docker Engine
  • Minikube v1.32 이상
  • kubectl v1.29 이상
  • RAM 4GB 이상 여유 공간

Step 1: Minikube 설치 및 클러스터 시작

# macOS (Homebrew)
brew install minikube kubectl

# 클러스터 시작 (드라이버는 docker 권장)
minikube start --driver=docker --memory=4096

# 클러스터 상태 확인
kubectl cluster-info
# 출력: Kubernetes control plane is running at https://127.0.0.1:PORT

minikube start가 성공하면 로컬에 Control Plane + Worker Node가 하나의 VM 안에 같이 떠요. 학습용으로 딱이에요.

Step 2: 첫 Pod 배포

Pod는 쿠버네티스의 가장 작은 실행 단위예요. 컨테이너 하나(또는 그 이상)를 감싸는 껍데기라고 생각하면 돼요.

# nginx-pod.yaml
apiVersion: v1
kind: Pod
metadata:
  name: my-nginx
  labels:
    app: nginx
spec:
  containers:
  - name: nginx-container
    image: nginx:1.25
    ports:
    - containerPort: 80

kubectl apply -f nginx-pod.yaml
kubectl get pods        # Running 이 뜨면 성공!
kubectl logs my-nginx

Step 3: Deployment로 관리하기

Pod를 직접 쓰면 죽었을 때 자동으로 안 살아나요. Deployment를 쓰면 원하는 개수를 항상 유지해줘요. 실제 현장에서 쓰는 방식이 이거예요.

# nginx-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25
        ports:
        - containerPort: 80
        resources:
          requests:
            memory: "64Mi"
            cpu: "250m"
          limits:
            memory: "128Mi"
            cpu: "500m"

kubectl apply -f nginx-deployment.yaml
kubectl get deployments
# 출력: nginx-deployment   3/3   3   3   30s

Step 4: Service로 외부 접근

Pod는 IP가 계속 바뀌어요. Service가 고정된 엔드포인트를 만들어줘요.

# nginx-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  type: NodePort
  selector:
    app: nginx
  ports:
  - port: 80
    targetPort: 80
    nodePort: 30080

kubectl apply -f nginx-service.yaml
minikube service nginx-service   # 바로 브라우저로 열려요

Step 5: 스케일 업/다운

kubectl scale deployment nginx-deployment --replicas=5
kubectl get pods -w    # 실시간으로 Pod 늘어나는 거 볼 수 있어요

실전 코드: ConfigMap + 환경변수 주입

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  APP_ENV: "production"
  LOG_LEVEL: "info"
  DB_HOST: "postgres-service"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: app
        image: my-app:1.0.0
        envFrom:
        - configMapRef:
            name: app-config

실제 현장에서 DB 비밀번호 같은 민감한 정보는 ConfigMap 대신 Secret을 써요. Secret은 base64 인코딩 + RBAC으로 접근 제어가 가능해요.

흔한 실수와 피하는 법

실수 1: YAML 들여쓰기 오류

탭(Tab) 쓰면 에러 나요. 스페이스 2칸으로 통일하세요. VS Code에서 YAML 확장(Red Hat) 설치하면 실시간으로 잡아줘요.

실수 2: Namespace 안 쓰기

기본 default Namespace에 다 몰아넣으면 나중에 관리 지옥 와요. 팀별·서비스별로 Namespace를 분리하는 게 현장 표준이에요.

kubectl create namespace backend
kubectl apply -f nginx-deployment.yaml -n backend

실수 3: resources 안 설정하기

resources.limits를 안 달면 컨테이너 하나가 Node 자원을 다 먹을 수 있어요. 위 Deployment 예시의 설정을 그대로 참고하세요.

프로덕션 체크리스트

  • 모든 Deployment에 resources.requests/limits 설정
  • Liveness/Readiness Probe 추가
  • ConfigMap과 Secret 분리
  • Namespace로 환경 분리 (dev/staging/prod)
  • kubectl apply 전 kubectl diff로 변경사항 확인

마무리: 지금 바로 시작하세요

핵심은 세 개예요.

  • Pod: 실행 단위
  • Deployment: 상태 유지 관리자
  • Service: 안정적인 네트워크 엔드포인트

지금 당장 minikube start를 치고 Step 1부터 따라해 보세요. 처음엔 에러가 나는 게 정상이에요. kubectl describe pod <이름>으로 에러 이유를 읽는 것, 그게 쿠버네티스를 배우는 가장 빠른 방법이에요.

다음 단계로는 Ingress 설정 → Helm 패키지 매니저 → HPA(자동 스케일링) 순서로 공부하면 자연스럽게 이어져요. 공식 문서는 kubernetes.io/docs가 제일 정확하고요. 막히는 부분은 댓글로 남겨주세요!

참고자료

  1. [자료다운로드] 쿠버네티스 아키텍처 완벽 가이드 : 구조와 동작 원리 A to Z - CNF
  2. 그림과 실습으로 배우는 쿠버네티스 입문
  3. Kubernetes(쿠버네티스)란? 20년차 개발자가 쉽게 풀어드립니다. I 이랜서 블로그

Photo by Surface on Unsplash

쿠버네티스 가이드: 개념과 Docker

Related Posts