Kubernetes 실전 가이드 | Pod·Deployment

이 글의 핵심

Kubernetes로 컨테이너를 오케스트레이션하는 실전 가이드입니다. Pod, Deployment, Service, Ingress, ConfigMap, Secret, Helm까지 실무 예제로 정리했습니다.

실무 경험 공유: 마이크로서비스 아키텍처를 Kubernetes로 구축하면서, 배포 시간을 1시간에서 5분으로 단축하고 무중단 배포를 구현한 경험을 공유합니다.

들어가며: “Docker만으로는 부족해요”

실무 문제 시나리오

시나리오 1: 컨테이너가 죽으면 수동 재시작해야 해요

Docker만으로는 자동 복구가 안 됩니다. Kubernetes는 자동으로 재시작합니다. 시나리오 2: 로드 밸런싱이 필요해요

여러 컨테이너에 트래픽을 분산해야 합니다. Kubernetes Service가 자동으로 처리합니다. 시나리오 3: 무중단 배포가 어려워요

배포 중 다운타임이 발생합니다. Kubernetes Rolling Update로 해결합니다.

1. Kubernetes란?

핵심 특징

Kubernetes (K8s)는 컨테이너 오케스트레이션 플랫폼입니다. 주요 기능:

• 자동 복구: 컨테이너 장애 시 재시작
• 로드 밸런싱: 트래픽 자동 분산
• 스케일링: 자동 확장/축소
• 무중단 배포: Rolling Update
• 서비스 디스커버리: 자동 DNS

---

2. 설치

Minikube (로컬)

# Windows (Chocolatey)
choco install minikube
# macOS
brew install minikube
# 시작
minikube start
# kubectl 설치
minikube kubectl -- get pods

kubectl 명령어

# 클러스터 정보
kubectl cluster-info
# 노드 확인
kubectl get nodes
# 모든 리소스 확인
kubectl get all

---

3. Pod

기본 Pod

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

# 생성
kubectl apply -f pod.yaml
# 확인
kubectl get pods
# 로그 확인
kubectl logs nginx-pod
# 삭제
kubectl delete pod nginx-pod

---

4. Deployment

기본 Deployment

# 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 deployment.yaml
# 확인
kubectl get deployments
kubectl get pods
# 스케일링
kubectl scale deployment nginx-deployment --replicas=5
# 롤링 업데이트
kubectl set image deployment/nginx-deployment nginx=nginx:1.26
# 롤백
kubectl rollout undo deployment/nginx-deployment

---

5. Service

ClusterIP (내부 통신)

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

LoadBalancer (외부 노출)

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

NodePort

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

---

6. Ingress

Ingress 설치

# NGINX Ingress Controller
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/cloud/deploy.yaml

Ingress 설정

# ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: app-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - host: myapp.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: frontend-service
            port:
              number: 80
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: backend-service
            port:
              number: 8000
  tls:
  - hosts:
    - myapp.example.com
    secretName: tls-secret

---

7. ConfigMap & Secret

ConfigMap

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  DATABASE_HOST: postgres-service
  DATABASE_PORT: "5432"
  LOG_LEVEL: info

# Deployment에서 사용
spec:
  containers:
  - name: app
    image: myapp:latest
    envFrom:
    - configMapRef:
        name: app-config

Secret

# Secret 생성
kubectl create secret generic db-secret \
  --from-literal=username=admin \
  --from-literal=password=secret123

# Deployment에서 사용
# 실행 예제
spec:
  containers:
  - name: app
    image: myapp:latest
    env:
    - name: DB_USERNAME
      valueFrom:
        secretKeyRef:
          name: db-secret
          key: username
    - name: DB_PASSWORD
      valueFrom:
        secretKeyRef:
          name: db-secret
          key: password

---

8. Helm

설치

# Windows
choco install kubernetes-helm
# macOS
brew install helm

Chart 사용

# Chart 검색
helm search hub wordpress
# Chart 설치
helm install my-wordpress bitnami/wordpress
# 업그레이드
helm upgrade my-wordpress bitnami/wordpress
# 삭제
helm uninstall my-wordpress

커스텀 Chart

# Chart 생성
helm create myapp
# 구조
myapp/
├── Chart.yaml
├── values.yaml
└── templates/
    ├── deployment.yaml
    ├── service.yaml
    └── ingress.yaml

# values.yaml
replicaCount: 3
image:
  repository: myapp
  tag: "1.0.0"
  pullPolicy: IfNotPresent
service:
  type: ClusterIP
  port: 80

---

9. 실전 예제: 풀스택 앱 배포

설정 파일 예시입니다.

# postgres.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
spec:
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - name: postgres
        image: postgres:16
        env:
        - name: POSTGRES_PASSWORD
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: password
        ports:
        - containerPort: 5432
        volumeMounts:
        - name: postgres-storage
          mountPath: /var/lib/postgresql/data
      volumes:
      - name: postgres-storage
        persistentVolumeClaim:
---
          claimName: postgres-pvc
apiVersion: v1
kind: Service
metadata:
  name: postgres-service
spec:
  selector:
    app: postgres
  ports:
  - port: 5432

# backend.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: backend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: backend
  template:
    metadata:
      labels:
        app: backend
    spec:
      containers:
      - name: backend
        image: myapp/backend:1.0.0
        envFrom:
        - configMapRef:
            name: app-config
        - secretRef:
            name: db-secret
        ports:
---
        - containerPort: 8000
apiVersion: v1
kind: Service
metadata:
  name: backend-service
spec:
  selector:
    app: backend
  ports:
  - port: 8000

취업·면접과 연결하기

Pod·Deployment·Service·Ingress를 그림으로 설명할 수 있으면 데브옵스·백엔드 면접에서 강점이 됩니다. 기술 면접 완벽 대비 가이드의 인프라·CS 흐름과, 운영 경험을 문서화하는 방법은 개발자 이력서·서류·면접 가이드를 보세요.

정리 및 체크리스트

핵심 요약

• Kubernetes: 컨테이너 오케스트레이션
• Pod: 최소 배포 단위
• Deployment: 선언적 배포 관리
• Service: 로드 밸런싱
• Ingress: 외부 트래픽 라우팅
• Helm: 패키지 관리자

프로덕션 체크리스트

• 클러스터 구성
• Deployment 작성
• Service 설정
• Ingress 구성
• ConfigMap/Secret 관리
• 모니터링 설정
• 백업 전략 수립

---

같이 보면 좋은 글

• GitHub Actions CI/CD 가이드
• Docker Compose 완벽 가이드
• Redis 고급 가이드

---

이 글에서 다루는 키워드

Kubernetes, K8s, Container, Orchestration, DevOps, Docker, Cloud

내부 동작과 핵심 메커니즘

이 글의 주제는 「Kubernetes 실전 가이드 | Pod·Deployment·Service·Ingress·ConfigMap·Helm」입니다. 앞선 튜토리얼을 구현·런타임 관점에서 다시 압축합니다. 구성 요소 간 책임 분리와 관측 가능한 지점을 기준으로 “입력이 어디서 검증되고, 핵심 연산이 어디서 일어나며, 부작용(I/O·네트워크·디스크)·동시성이 어디서 터지는가”를 한 장면으로 그리면 장애 분석이 빨라집니다.

처리 파이프라인(개념도)

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

경계에서의 지연·실패(시퀀스 관점)

sequenceDiagram
  participant C as 클라이언트/호출자
  participant B as 경계(프로세스·런타임·게이트웨이)
  participant D as 의존성(외부 API·DB·큐)
  C->>B: 요청/이벤트
  B->>D: 조회·쓰기·RPC
  D-->>B: 지연·부분 실패·재시도 가능
  B-->>C: 응답 또는 오류(코드·상관 ID)

알고리즘·프로토콜·리소스 관점 체크포인트

• 불변 조건(Invariant): 각 단계가 만족해야 하는 조건(버퍼 경계, 프로토콜 상태, 트랜잭션 격리, 파일 디스크립터 상한)을 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
• 결정성: 동일 입력에 동일 출력이 보장되는 순수 층과, 시간·네트워크·스레드 스케줄에 의해 달라질 수 있는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
• 경계 비용: 직렬화/역직렬화, 문자 인코딩, syscall 횟수, 락 경합, GC·할당, 캐시 미스처럼 누적 비용을 의심 목록에 넣습니다.
• 백프레셔: 생산자가 소비자보다 빠를 때(소켓 버퍼, 큐 깊이, 스트림) 어디서 어떤 신호로 속도를 줄일지 정의합니다.

---

프로덕션 운영 패턴

실서비스에서는 기능과 함께 관측·배포·보안·비용·규제가 동시에 요구됩니다.

영역	운영 관점 질문
관측성	요청 단위 상관 ID, 에러율/지연 분위수(p95/p99), 의존성 타임아웃·재시도가 대시보드에 보이는가
안전성	입력 검증·권한·비밀·감사 로그가 코드 경로마다 일관적인가
신뢰성	재시도는 멱등 연산에만 적용되는가, 서킷 브레이커·백오프·DLQ가 있는가
성능	캐시 계층·배치 크기·커넥션 풀·인덱스·백프레셔가 데이터 규모에 맞는가
배포	롤백 룬북, 카나리/블루그린, 마이그레이션 호환성·플래그가 문서화되어 있는가
용량	피크 트래픽·디스크·파일 디스크립터·스레드 풀 상한을 주기적으로 검증하는가

스테이징은 데이터 양·네트워크 RTT·동시성을 가능한 한 프로덕션에 가깝게 맞추는 것이 재현율을 높입니다.

---

확장 예시: 엔드투엔드 미니 시나리오

「Kubernetes 실전 가이드 | Pod·Deployment·Service·Ingress·ConfigMap·Helm」을 실제 배포·운영 흐름으로 옮긴 체크리스트형 시나리오입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

1. 입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드 표를 API 또는 이벤트 경계에 둔다.
2. 핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 한 화면(로그+메트릭+트레이스)에서 추적한다.
3. 실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
4. 호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지(또는 피처 플래그) 확인한다.
5. 부하 후 검증: 피크 대비 p95/p99, 에러율, 리소스 상한, 알림 임계값이 기대 범위인지 본다.

의사코드 스케치(프레임워크 무관)

handle(request):
  ctx = newCorrelationId()
  validated = validateSchema(request)        // 경계에서 거절
  authorize(validated, ctx)                  // 권한·테넌트
  result = domainCore(validated)             // 순수에 가까운 규칙
  persistOrEmit(result, idempotentKey)       // I/O: 멱등·재시도 정책
  recordMetrics(ctx, latency, outcome)
  return result

---

문제 해결(Troubleshooting)

증상	가능 원인	조치
간헐적 실패	레이스, 타임아웃, 외부 의존성 불안정, DNS	최소 재현 스크립트, 분산 트레이스·로그 상관관계, 재시도·서킷 설정 점검
성능 저하	N+1, 동기 I/O, 락 경합, 과도한 직렬화, 캐시 미스	프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가	캐시 무제한, 구독/리스너 누수, 대용량 버퍼, 커넥션 미반납	상한·TTL·힙/FD 스냅샷 비교
빌드·배포만 실패	환경 변수, 권한, 플랫폼 차이, lockfile	CI 로그와 로컬 diff, 런타임·이미지 버전 핀
설정이 로컬과 다름	프로필·시크릿·기본값, 지역 리전	단일 소스(예: 스키마 검증된 설정)와 배포 매트릭스 표준화
데이터 불일치	비멱등 재시도, 부분 쓰기, 캐시 무효화 누락	멱등 키·아웃박스·트랜잭션 경계 재검토

권장 순서: (1) 최소 재현 (2) 최근 변경 범위 축소 (3) 환경·의존성 차이 (4) 관측으로 가설 검증 (5) 수정 후 회귀·부하 테스트.

자주 묻는 질문 (FAQ)

Q. Docker Compose vs Kubernetes, 어떤 게 나은가요?

A. Docker Compose는 단일 서버용입니다. Kubernetes는 다중 서버 클러스터용입니다. 소규모는 Docker Compose, 대규모는 Kubernetes를 권장합니다.

Q. 학습 곡선이 가파른가요?

A. 네, Kubernetes는 복잡합니다. 하지만 기본 개념(Pod, Deployment, Service)만 이해하면 시작할 수 있습니다.

Q. 클라우드에서 사용해야 하나요?

A. 아니요, 온프레미스에서도 사용 가능합니다. 하지만 GKE, EKS, AKS 같은 관리형 서비스를 권장합니다.

Q. Helm은 필수인가요?

A. 아니요, 선택사항입니다. 하지만 복잡한 앱 배포를 크게 간소화합니다.