워크로드 컨트롤러

Pod을 직접 만들지 않는 이유

컨트롤러 — 왜 필요하고 무엇을 고르나

컨트롤러가 필요한 이유

Pod을 직접 만들면 —

• 노드가 죽으면 그걸로 끝이다. 아무도 다시 만들어주지 않는다
• 개수를 늘리려면 이름을 바꿔가며 손으로 복사해야 한다
• 이미지를 바꾸려면 전부 지우고 다시 만들어야 한다

컨트롤러는 “몇 개가 어떤 모습으로 있어야 하는가”를 선언받고, 그 상태를 계속 유지한다. 이것이 자가치유(self-healing)의 실체다.

시험

커리큘럼의 “자가치유 배포의 기본 요소(primitives)“가 이 장 전체다. Deployment / DaemonSet / StatefulSet / Job 을 언제 쓰는지가 핵심.

어떤 컨트롤러를 쓸 것인가

필요한 것	컨트롤러
상태 없는 앱을 N개	Deployment
모든(또는 일부) 노드에 하나씩	DaemonSet
고유한 이름·저장소·순서가 필요한 앱	StatefulSet
한 번 실행하고 끝나는 작업	Job
일정에 따라 반복되는 작업	CronJob
Pod 개수만 유지 (직접 쓸 일은 거의 없다)	ReplicaSet

기본은 Deployment다. 나머지는 “왜 Deployment로는 안 되는가”에 답이 있을 때 쓴다.

함정

“DB니까 StatefulSet”이 항상 맞지는 않다. 기준은 “각 인스턴스가 고유한 신원과 저장소를 가져야 하는가”다. 단일 인스턴스 DB라면 Deployment + PVC(PersistentVolumeClaim — 저장소 요청, Pod별 저장소와 업데이트)로도 충분하다.

ReplicaSet — 개수를 맞추는 루프

apiVersion: apps/v1
kind: ReplicaSet
metadata:
  name: web-rs
spec:
  replicas: 3
  selector:                       # 어떤 Pod을 내 것으로 볼 것인가
    matchLabels:
      app: web
  template:                       # 부족하면 이 틀로 만든다
    metadata:
      labels:
        app: web                  # selector와 반드시 일치해야 한다
    spec:
      containers:
        - name: nginx
          image: nginx:1.27

• 루프: 셀렉터에 맞는 Pod 개수를 센다 → 부족하면 만들고, 많으면 지운다
• 셀렉터와 템플릿 라벨이 다르면 생성 시 거부된다 (무한 생성 방지)

ReplicaSet의 무서운 성질

셀렉터에 맞기만 하면 자기가 안 만든 Pod도 자기 것으로 센다.

# 관리에서 떼어내 디버깅하는 기법
kubectl label pod web-abc-123 app=web-debug --overwrite
# → ReplicaSet은 부족분을 새로 채우고, 이 Pod은 그대로 남아 조사할 수 있다

시험

“ReplicaSet이 Pod을 안 만든다” 문제의 단골 원인은 selector.matchLabels와 template.metadata.labels 불일치다. describe보다 get rs -o yaml로 두 값을 눈으로 비교하는 게 빠르다.

Deployment — ReplicaSet 위의 롤아웃 관리자

• 템플릿을 바꾸면 새 ReplicaSet을 만들고, 옛 것을 0으로 줄이며 새 것을 올린다
• 옛 ReplicaSet은 지워지지 않는다 (0개로 남는다) — 이것이 롤백의 재료다
• ReplicaSet 이름의 해시는 Pod 템플릿의 해시다. 템플릿이 같으면 새로 안 만든다

Deployment 만들기

kubectl create deploy web --image=nginx:1.27 --replicas=3 --dry-run=client -o yaml > web.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 3
  revisionHistoryLimit: 10        # 보관할 옛 ReplicaSet 개수 (기본 10)
  selector:
    matchLabels:
      app: web
  strategy:
    type: RollingUpdate           # RollingUpdate(기본) | Recreate
    rollingUpdate:
      maxSurge: 25%               # 목표보다 몇 개 더 만들 수 있나
      maxUnavailable: 25%         # 몇 개까지 없어도 되나
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.27

롤링 업데이트의 두 손잡이

RollingUpdate (기본)

무중단으로 조금씩 교체한다. 기본 전략이다.

Recreate

전부 죽이고 전부 새로 만든다. 다운타임이 있지만 RWO(ReadWriteOnce — 한 번에 한 노드만 붙는) 볼륨을 공유하거나 버전 공존이 불가능할 때 필요하다 (Pod별 저장소와 업데이트).

함정

둘 다 0은 아예 저장되지 않는다. 새로 만들 수도(surge 0), 지울 수도(unavailable 0) 없는 조합이라 API 서버가 생성/수정 시점에 거부한다.

롤아웃 다루기

kubectl set image deploy/web nginx=nginx:1.28
kubectl rollout status deploy/web            # 완료될 때까지 지켜본다
kubectl rollout history deploy/web
kubectl rollout history deploy/web --revision=2
kubectl rollout undo deploy/web              # 직전으로
kubectl rollout undo deploy/web --to-revision=2
kubectl rollout restart deploy/web           # 템플릿 변경 없이 전부 재생성
kubectl rollout pause deploy/web
kubectl rollout resume deploy/web

• rollout restart 는 템플릿에 타임스탬프 애노테이션을 넣어 롤아웃을 유발한다 → ConfigMap을 바꾼 뒤 반영하는 표준 방법이다
• pause 는 여러 변경을 모아서 한 번에 롤아웃할 때 쓴다

시험

“이미지를 바꾸고 롤아웃이 끝난 것을 확인하시오”는 set image → rollout status 두 줄이다. 검산도 겸한다.

리비전과 change-cause

kubectl rollout history deploy/web
# REVISION  CHANGE-CAUSE
# 1         <none>
# 2         nginx 1.28로 업그레이드

CHANGE-CAUSE는 애노테이션 kubernetes.io/change-cause 를 읽은 것이다.

kubectl annotate deploy/web kubernetes.io/change-cause="nginx 1.28로 업그레이드"

undo는 “돌아가는” 게 아니라 앞으로 나아간다.

함정

undo는 리비전 번호를 새로 부여한다. 리비전 3에서 2로 롤백하면 그 내용이 리비전 4가 된다. 2로 “돌아가는” 게 아니다.

revisionHistoryLimit을 0으로 두면 롤백이 불가능해진다. 기본 10을 그대로 두자.

스케일링

kubectl scale deploy web --replicas=5
kubectl scale deploy web --replicas=5 --current-replicas=3   # 조건부
kubectl scale --replicas=5 -f web.yaml
kubectl scale statefulset db --replicas=3

• replicas: 0 도 유효하다 — 삭제하지 않고 멈추는 방법
• HPA(Horizontal Pod Autoscaler — 부하에 따라 replicas를 자동 조절)가 붙어 있으면 수동 스케일은 곧 되돌려진다 (오토스케일링)

# 롤아웃/스케일이 끝날 때까지 기다리기 — 검산에 유용
kubectl wait --for=condition=available deploy/web --timeout=60s
kubectl wait --for=condition=ready pod -l app=web --timeout=60s

시험

kubectl wait는 “다 떴는지” 확인에 좋다. 그냥 get pods를 반복해서 치는 것보다 확실하고 빠르다.

DaemonSet — 노드마다 하나씩

Deployment는 “몇 개”는 보장하지만 “어디에”는 스케줄러에 맡긴다. 로그 수집기·모니터링 에이전트처럼 모든 노드에 정확히 하나씩 있어야 하는 것은 개수가 replicas가 아니라 노드 수를 따라가야 한다 — 그 컨트롤러가 DaemonSet이다.

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: log-agent
spec:
  selector:
    matchLabels:
      app: log-agent
  template:
    metadata:
      labels:
        app: log-agent
    spec:
      tolerations:                      # 컨트롤 플레인에도 놓으려면 필요
        - key: node-role.kubernetes.io/control-plane
          operator: Exists
          effect: NoSchedule
      containers:
        - name: agent
          image: fluent-bit:3.0

• replicas가 없다. 개수는 노드 수가 정한다
• 노드가 추가되면 자동으로 하나 더 생긴다
• 쓰임: 로그 수집기, 모니터링 에이전트, kube-proxy, CNI 플러그인

DaemonSet은 kubectl create 단축 명령이 없다 — 시험장에서는 공식 DaemonSet 페이지의 YAML 뼈대를 복사해 오거나, create deploy로 뽑은 YAML에서 kind를 바꾸고 replicas·strategy를 지운다.

DaemonSet의 배치 제어

kubectl get ds -A                       # kube-proxy, CNI가 보인다
kubectl rollout status ds/log-agent

• 특정 노드에만 놓으려면 nodeSelector 나 affinity 를 쓴다
• taint가 걸린 노드에는 안 뜬다 — tolerations가 필요하다 (스케줄링)
• 업데이트 전략은 RollingUpdate(기본) / OnDelete

함정

DaemonSet Pod이 일부 노드에만 없다면 십중팔구 그 노드의 taint다. kubectl describe node로 Taints를 확인하고 DaemonSet에 toleration을 추가한다. 컨트롤 플레인 노드가 특히 그렇다.

DaemonSet Pod은 기본 스케줄러가 배치하지만, 노드 리소스 부족 등의 이유로 Pending이 될 수 있다.

StatefulSet — 신원이 있는 Pod

Deployment의 Pod은 서로 바꿔치기 가능한 복제본이다 — 이름은 무작위고, 죽으면 다른 이름·다른 저장소로 새로 뜬다. DB 복제처럼 “내가 몇 번 인스턴스인지”와 “내 데이터 디스크가 어느 것인지”가 중요한 앱은 이 무작위성 때문에 Deployment로는 안 된다 — 각 Pod에 고정된 신원을 주는 컨트롤러가 StatefulSet이다.

apiVersion: apps/v1
kind: StatefulSet
metadata: { name: db }
spec:
  serviceName: db-headless          # 반드시 headless Service를 가리킨다
  replicas: 3
  selector: { matchLabels: { app: db } }
  template:
    metadata:
      labels: { app: db }
    spec:
      containers:
        - name: postgres
          image: postgres:17
          volumeMounts:
            - name: data
              mountPath: /var/lib/postgresql/data
  volumeClaimTemplates:             # Pod마다 PVC를 하나씩 만든다
    - metadata: { name: data }
      spec:
        accessModes: ["ReadWriteOnce"]
        storageClassName: standard
        resources: { requests: { storage: 10Gi } }

StatefulSet이 주는 세 가지 보장

1 · 안정적인 이름

db-0, db-1, db-2. 재시작해도 이름이 그대로다.

2 · 안정적인 저장소

data-db-0, data-db-1 … PVC가 Pod 이름에 묶인다. db-0이 죽었다 살아나면 같은 PVC를 다시 붙인다.

3 · 순서 보장

생성은 0 → 1 → 2, 삭제는 2 → 1 → 0. 앞 Pod이 Ready가 되어야 다음이 시작한다.

kubectl get pvc
# data-db-0   Bound   pvc-xxx   10Gi   RWO
# data-db-1   Bound   pvc-yyy   10Gi   RWO

함정

StatefulSet을 지워도 PVC는 남는다. 의도된 동작이다(데이터 보호). 같은 이름으로 다시 만들면 옛 데이터를 그대로 붙인다. 지우려면 PVC를 직접 삭제해야 한다.

headless Service와 안정적인 DNS

apiVersion: v1
kind: Service
metadata:
  name: db-headless
spec:
  clusterIP: None            # ← headless
  selector:
    app: db
  ports:
    - port: 5432

clusterIP: None이면 Service IP를 만들지 않고 DNS가 Pod IP들을 직접 반환한다.

db-0.db-headless.default.svc.cluster.local  → 10.244.1.5
db-1.db-headless.default.svc.cluster.local  → 10.244.2.7

그래서 “1번 레플리카에만 연결” 같은 것이 가능하다. DB 복제에서 primary/replica를 구분해 붙일 때 이 이름을 쓴다.

함정

serviceName에 적은 Service가 실제로 없어도 StatefulSet은 뜬다. 다만 Pod별 DNS 이름이 안 생긴다. 조용히 실패하는 유형이라 주의.

StatefulSet 업데이트와 스케일

spec:
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      partition: 2         # 인덱스 2 이상만 업데이트 (카나리)
  podManagementPolicy: OrderedReady   # OrderedReady(기본) | Parallel

• 업데이트는 큰 번호부터 역순으로 진행된다 (2 → 1 → 0)
• partition: N 이면 N 이상 인덱스만 바뀐다 — 단계적 배포에 쓴다
• podManagementPolicy: Parallel 이면 순서 없이 동시에 생성/삭제 (기동이 빠르다)

여기서는 “업데이트가 큰 번호부터 역순”이라는 것만 기억하면 된다. partition·podManagementPolicy까지 깊게 팔 필요는 없다 — 필드 이름과 용도만 알아두자.

kubectl scale sts db --replicas=5      # 3 → 5: db-3, db-4가 순서대로 추가
kubectl scale sts db --replicas=2      # 5 → 2: db-4, db-3, db-2가 역순으로 삭제

축소해도 PVC는 남는다. 다시 늘리면 옛 데이터로 복귀한다.

Job과 CronJob

Job — 끝나는 작업

Deployment는 끝나는 작업에 쓸 수 없다 — Pod 템플릿에 restartPolicy: Always만 허용되니, 작업이 성공해 exit 0으로 끝나도 계속 되살린다. “몇 번 성공하면 완료”라는 개념을 아는 컨트롤러가 따로 필요하다 — 그게 Job이다.

apiVersion: batch/v1
kind: Job
metadata:
  name: import
spec:
  completions: 5              # 총 몇 번 성공해야 하는가
  parallelism: 2              # 동시에 몇 개까지
  backoffLimit: 4             # 실패 재시도 횟수 (기본 6)
  activeDeadlineSeconds: 300  # 전체 제한 시간 — 넘으면 중단
  ttlSecondsAfterFinished: 100  # 끝나고 100초 뒤 Job과 Pod을 자동 삭제
  template:
    spec:
      restartPolicy: OnFailure   # Never 또는 OnFailure만 가능
      containers:
        - name: worker
          image: busybox:1.36
          command: ["sh", "-c", "echo processing; sleep 5"]

kubectl create job import --image=busybox -- echo hi
kubectl create job manual --from=cronjob/nightly     # CronJob을 즉시 한 번 실행

Job 파라미터가 실제로 뜻하는 것

completionMode: Indexed 를 쓰면 각 Pod에 인덱스(0, 1, 2 …) 가 붙는다. JOB_COMPLETION_INDEX 환경변수와 Pod 이름 접미사로 들어온다 — 데이터를 나눠 처리할 때 쓴다. 깊게 팔 필요는 없다 — 이런 모드가 있다는 것만 알아두자.

함정

Job의 Pod 템플릿에 restartPolicy: Always는 쓸 수 없다. 안 쓰면 기본값이 Always라 생성 자체가 거부된다. --dry-run으로 뽑은 YAML을 고칠 때 자주 걸린다.

CronJob — 일정에 따라 Job을 만든다

apiVersion: batch/v1
kind: CronJob
metadata:
  name: nightly
spec:
  schedule: "0 3 * * *"              # 분 시 일 월 요일
  timeZone: "Asia/Seoul"             # 없으면 컨트롤러의 시간대(보통 UTC)
  concurrencyPolicy: Forbid          # Allow(기본) | Forbid | Replace
  startingDeadlineSeconds: 120       # 이 시간 안에 못 시작하면 건너뛴다
  successfulJobsHistoryLimit: 3
  failedJobsHistoryLimit: 1
  suspend: false                     # true면 새 Job을 만들지 않는다
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: backup
              image: busybox:1.36
              command: ["sh", "-c", "echo backup"]

kubectl create cronjob nightly --image=busybox --schedule="0 3 * * *" -- echo backup
kubectl patch cronjob nightly -p '{"spec":{"suspend":true}}'

CronJob에서 헷갈리는 것들

3단 소유 사슬이다. Pod을 찾으려면 두 단계를 내려가야 한다.

concurrencyPolicy — 이전 Job이 아직 도는데 다음 일정이 오면?

• 시간대 기본은 UTC다 (컨트롤러 매니저 기준). timeZone 필드로 명시하는 게 안전하다

kubectl get cronjob nightly
kubectl get jobs --selector=job-name        # CronJob이 만든 Job들
kubectl logs job/nightly-28901234

시험

cron 표현식은 분 시 일 월 요일 순서다. */5 * * * * = 5분마다, 0 3 * * * = 매일 새벽 3시. 헷갈리면 공식 CronJob 페이지에 형식 표가 있다 — 시험 중 열어 볼 수 있는 문서다.

PodDisruptionBudget — 자발적 중단으로부터 보호

컨트롤러가 죽은 Pod을 다시 만들어 주긴 하지만, 새 Pod이 뜨기까지는 시간이 걸린다. 노드 업그레이드로 kubectl drain을 돌릴 때(노드 유지보수) 한 앱의 Pod들이 한꺼번에 축출되면 그 공백 동안 서비스가 순간적으로 비어 버릴 수 있다 — “동시에 죽어도 되는 수의 예산”을 선언해 두는 것이 PodDisruptionBudget(PDB)이다.

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: web-pdb
spec:
  minAvailable: 2          # 또는 maxUnavailable: 1
  selector:
    matchLabels:
      app: web

• kubectl drain이나 노드 업그레이드 같은 “자발적 중단”에서 최소 가용 수를 지킨다
• 노드 장애 같은 비자발적 중단은 막지 못한다
• PDB가 막으면 drain이 멈춰서 기다린다

함정

replicas: 1 인데 minAvailable: 1 이면 drain이 영원히 진행되지 않는다. 실무·시험 모두에서 걸리는 교착 상태다. kubectl get pdb의 ALLOWED DISRUPTIONS가 0이면 이 상황이다. (노드 유지보수)

자가치유는 어디까지 되나

마지막 줄이 중요하다. Kubernetes는 “프로세스가 살아 있는가”만 본다. “제대로 동작하는가”는 프로브를 통해 당신이 알려줘야 한다.

요약

• Deployment → ReplicaSet → Pod. 옛 ReplicaSet이 남아 있는 것이 롤백의 재료다
• 롤링 업데이트는 maxSurge / maxUnavailable 두 손잡이. 둘 다 0은 API가 거부한다
• rollout undo는 되돌아가는 게 아니라 새 리비전을 만든다
• DaemonSet은 노드마다 하나. 안 뜨면 십중팔구 taint
• StatefulSet은 이름·저장소·순서를 보장한다. 삭제해도 PVC는 남는다
• Job의 restartPolicy는 Never/OnFailure만 — 기본값 그대로 두면 거부된다
• CronJob은 UTC 기본, concurrencyPolicy로 겹침을 제어
• PDB는 자발적 중단만 막는다. replicas: 1 + minAvailable: 1 = drain 교착