TIL

Deployment

• 공식 문서 - Deployments
• Stateless 애플리케이션을 선언적으로 관리하는 워크로드 리소스
• 사용자는 desired state만 선언하고, 컨트롤러가 actual state를 점진적으로 맞춘다
• 워크로드 리소스의 위치·역할 개요는 02장 - 워크로드와 컨트롤러 참고

역할과 계층 구조

• Deployment는 ReplicaSet을, ReplicaSet은 Pod를 관리하는 3단 계층

  Deployment ──manages──▶ ReplicaSet ──manages──▶ Pod(s)
  

• 사용자는 Deployment만 다룬다 — Deployment가 소유한 ReplicaSet을 직접 수정·삭제하면 안 됨
• Deployment Controller는 desired/actual 차이를 controlled rate로 좁힘
  • 한 번에 다 바꾸지 않고 maxSurge·maxUnavailable 같은 임계값으로 정해진 안전 범위 안에서 단계적으로 진행해 무중단을 보장
• Pod 템플릿이 바뀌면 새 ReplicaSet을 만들고 이전 ReplicaSet을 줄여가며 교체

사용 사례

• ReplicaSet 롤아웃 — Deployment 생성 시 백그라운드에서 ReplicaSet이 Pod를 띄움
• Pod 상태 갱신 — PodTemplateSpec 수정 시 새 ReplicaSet 생성·기존 ReplicaSet 축소로 점진 교체
• 이전 리비전 롤백 — 현재 상태가 불안정하면 과거 리비전으로 되돌림
• 스케일 업/다운 — replicas 수로 부하 대응
• 롤아웃 일시중단/재개 — 여러 변경을 모았다가 한 번에 적용
• 롤아웃 상태 모니터링 — Deployment status로 진행/stuck 판단
• 오래된 ReplicaSet 정리 — 더 이상 안 쓰는 ReplicaSet 자동 회수

Deployment 생성

• YAML로 desired state를 선언하고 kubectl apply로 적용하는 흐름이 표준

  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: nginx-deployment
    labels:
      app: nginx
  spec:
    replicas: 3                  # 원하는 Pod 개수
    selector:                    # 이 Deployment가 관리할 Pod 식별 기준
      matchLabels:
        app: nginx
    template:                    # Pod 생성 템플릿 (PodTemplateSpec)
      metadata:
        labels:
          app: nginx             # selector.matchLabels와 반드시 일치
      spec:
        containers:
        - name: nginx
          image: nginx:1.14.2
          ports:
          - containerPort: 80
  

핵심 필드

• apiVersion: apps/v1 — Deployment는 apps/v1 그룹
• metadata.name — Deployment 이름. ReplicaSet·Pod 이름의 prefix가 됨
• spec.replicas — 유지할 Pod 개수
• spec.selector — 관리할 Pod를 찾는 라벨 셀렉터. 생성 후 변경 불가(immutable)
• spec.template — Pod 템플릿. template.metadata.labels는 selector와 매칭되어야 하고, 템플릿 변경 시 rollout 트리거

생성 결과 확인

• kubectl get deployments
  • READY — 사용 가능 / 원하는 개수 (예: 3/3)
  • UP-TO-DATE — 최신 템플릿으로 갱신된 replica 수
  • AVAILABLE — 사용자에게 노출 가능한 replica 수
  • AGE — 생성 후 경과 시간
• kubectl rollout status deployment/nginx-deployment — 롤아웃 완료까지 watch
• kubectl get rs — Deployment가 만든 ReplicaSet 확인. 이름은 [DEPLOYMENT-NAME]-[HASH]
• kubectl get pods --show-labels — Pod와 자동 부착된 라벨 확인

pod-template-hash 라벨

• ReplicaSet 이름 [HASH]의 정체. PodTemplateSpec을 해시한 값
• Deployment가 만든 모든 Pod·ReplicaSet에 자동 부착
• 같은 Deployment에서 만들어진 서로 다른 템플릿 버전의 Pod·ReplicaSet 구분용
• 사용자가 직접 지정·변경하면 안 됨

Deployment 업데이트

• PodTemplateSpec이 바뀐 경우에만 rollout 발생
  • spec.template.* 변경(이미지·환경변수·리소스 등) → rollout
  • spec.replicas만 바꾸면 rollout 없이 단순 스케일 조정
• 가장 흔한 업데이트 — 컨테이너 이미지 변경

  kubectl set image deployment/nginx-deployment nginx=nginx:1.16.0
  

  • 내부적으로 spec.template.spec.containers[0].image 필드를 갱신
  • 실무에서는 보통 YAML 수정 후 kubectl apply 흐름이 일반적

내부 동작 단계

• 템플릿 변경 시 Deployment Controller가 다음 순서로 진행
  1. 새 ReplicaSet 생성 — 새 PodTemplateSpec에 해당, replicas는 0부터 시작
  2. 새 ReplicaSet 점진적 scale up — 새 Pod를 단계적으로 띄움
  3. 기존 ReplicaSet 점진적 scale down — 새 Pod가 정상이면 그만큼 기존 Pod 축소
  4. 교체 완료 — 새 ReplicaSet이 desired에 도달하면 기존은 0
• 전 과정이 서비스 중단 없이 진행됨

기본 전략과 임계값

• 기본 전략: RollingUpdate
• 두 임계값으로 안전 범위를 제어
  • maxUnavailable (기본 25%) — 업데이트 중 동시에 사용 불가 상태가 될 수 있는 Pod의 최대 비율/개수
  • maxSurge (기본 25%) — desired replicas를 일시적으로 초과할 수 있는 Pod의 최대 비율/개수
• 예: replicas=3, 25% → 1 Pod 기준
  • 항상 최소 2개 Pod는 사용 가능
  • 롤아웃 중 잠깐 4개까지 떠 있을 수 있음
• 상세 동작은 아래 업데이트 전략 참고

라벨 셀렉터 불변성

• spec.selector는 생성 후 변경 불가
• 셀렉터를 바꾸면 기존에 관리하던 Pod·ReplicaSet과의 연결이 끊겨 orphan 발생
• 라벨링 전략은 처음 설계 시 신중히 결정해야 함

Rollover — 롤아웃 중 또 업데이트하면

• 이전 rollout이 끝나기 전에 또 템플릿을 바꿀 경우
  • 이전(부분 스케일링된) ReplicaSet을 그대로 둔 채, 가장 최근 변경에 대한 새 ReplicaSet 생성
  • 이전 ReplicaSet은 즉시 scale down으로 전환
  • 가장 최신 ReplicaSet만 desired까지 올라감
• 즉, 중간 단계 템플릿 버전으로 Pod가 안정 상태에 도달하지 않음

업데이트 전략

• spec.strategy.type으로 두 가지 중 선택. 기본은 RollingUpdate
  • Recreate — 기존 Pod를 모두 종료한 뒤 새 Pod를 생성
  • RollingUpdate — 점진적으로 새 Pod로 교체 (무중단)

Recreate

• 동작: 모든 기존 Pod 종료 → 그 후에 새 Pod 생성
• 그 사이 서비스 다운타임 발생
• 사용 사례
  • 두 버전이 동시에 떠 있으면 안 되는 앱 (예: 동일 DB 스키마를 양쪽이 점유하는 경우)
  • 다운타임이 허용되는 배치·내부용 애플리케이션
• 클러스터 자원이 빠듯해 surge 분의 Pod를 추가로 띄울 수 없을 때도 사용

RollingUpdate

• 동작: 새 ReplicaSet을 점진적으로 scale up하면서 기존 ReplicaSet을 scale down
• 두 임계값 maxUnavailable·maxSurge로 진행 속도와 가용성 보장 수준을 제어
• spec.strategy.rollingUpdate.maxUnavailable과 maxSurge로 명시 가능

  spec:
    strategy:
      type: RollingUpdate
      rollingUpdate:
        maxUnavailable: 25%
        maxSurge: 25%
  

maxUnavailable

• 업데이트 중 동시에 사용 불가 상태가 될 수 있는 Pod의 최대치
• 값 형식
  • 절대값 (예: 1, 2)
  • 백분율 (예: "25%") — desired replicas 기준으로 계산
• 기본값: 25%
• 의미: desired - maxUnavailable = 항상 떠 있어야 할 최소 Pod 수
  • replicas=10, maxUnavailable=25% → 최소 8개는 항상 사용 가능

maxSurge

• desired replicas를 일시적으로 초과할 수 있는 Pod의 최대치
• 값 형식: 절대값 또는 백분율 (기본 25%)
• 백분율은 올림(round up)
  • replicas=3, 25% → 0.75 → 1
• 의미: 새 Pod를 미리 띄워둘 여유분. surge가 클수록 롤아웃이 빠르지만 클러스터 자원을 더 점유

둘 다 0이면?

• maxUnavailable=0 AND maxSurge=0 조합은 불가
• 둘 다 0이면 Pod를 줄이지도, 추가로 띄우지도 못해 롤아웃이 진행 불가
• 적어도 하나는 양수여야 한다

롤백

• 새 버전이 crash loop·readiness 실패 등으로 stuck 되면 이전 안정 리비전으로 되돌릴 수 있음
• Deployment는 각 리비전을 ReplicaSet 형태로 보관 — 옛 ReplicaSet이 남아 있어 롤백이 가능
• 실패 인지: kubectl rollout status, kubectl get deployments, Deployment 컨디션·이벤트 확인

Rollout History 확인

• 리비전 목록 조회

  kubectl rollout history deployment/nginx-deployment
  

  REVISION  CHANGE-CAUSE
  1         <none>
  2         kubectl set image deployment/nginx-deployment nginx=nginx:1.9.1
  3         kubectl set image deployment/nginx-deployment nginx=nginx:1.14.2
  

• CHANGE-CAUSE 컬럼은 kubernetes.io/change-cause 어노테이션 값
  • 직접 어노테이션을 달아 각 리비전이 어떤 변경인지 표시 가능

    kubectl annotate deployment/nginx-deployment \
      kubernetes.io/change-cause="Updated image to 1.16.0" --overwrite
    

• 특정 리비전의 PodTemplateSpec 상세 확인

  kubectl rollout history deployment/nginx-deployment --revision=2
  

이전 리비전으로 되돌리기

• 직전 리비전으로 롤백

  kubectl rollout undo deployment/nginx-deployment
  

• 특정 리비전으로 롤백

  kubectl rollout undo deployment/nginx-deployment --to-revision=2
  

• 내부 동작
  • 대상 리비전의 ReplicaSet을 다시 scale up
  • 현재 ReplicaSet은 0으로 scale down
  • Deployment의 revision 번호는 새 번호로 증가 (롤백도 새 변경으로 기록됨)
  • 옛 ReplicaSet은 삭제되지 않고 남아 — 추가 롤백이 가능

Pause와 Resume

• 롤아웃을 멈춰두고 여러 변경을 모았다가 한 번에 적용하는 메커니즘
• 일시 중단

  kubectl rollout pause deployment/nginx-deployment
  

  • Deployment Controller가 변경에 반응하지 않음
  • 이 상태에서 set image·set resources 등을 여러 번 해도 새 ReplicaSet이 매번 생기지 않음
• 사용 시점
  • 이미지·환경변수·리소스 한계 등을 함께 묶어서 한 번의 롤아웃으로 처리하고 싶을 때
  • 중간 단계 ReplicaSet이 잔뜩 생기는 걸 방지
• 재개

  kubectl rollout resume deployment/nginx-deployment
  

  • 누적된 모든 변경을 반영한 단일 rollout이 트리거됨
  • 이때부터 maxSurge·maxUnavailable 규칙이 적용
• 주의: pause 상태에서는 롤백 불가
  • kubectl rollout undo가 실패함
  • 롤백하려면 먼저 resume으로 풀어야 함

스케일링

• replicas 수만 바꾸는 변경은 rollout을 트리거하지 않음 — 단순히 ReplicaSet의 desired count만 조정됨
• 스케일링은 수동 / 오토스케일 / Proportional Scaling 세 가지 맥락으로 등장

수동 스케일

• kubectl scale로 즉시 변경

  kubectl scale deployment/nginx-deployment --replicas=10
  

• YAML의 spec.replicas를 수정해 kubectl apply로 적용해도 동일한 결과
• 변경 즉시 ReplicaSet이 desired에 맞춰 Pod를 늘리거나 줄임

오토스케일 (HPA 연결)

• HorizontalPodAutoscaler를 붙이면 메트릭 기반으로 자동 스케일

  kubectl autoscale deployment/nginx-deployment --min=10 --max=15 --cpu-percent=80
  

  • CPU 80% 기준으로 10~15개 사이를 오감
• HPA는 메트릭을 보고 Deployment의 spec.replicas를 직접 조정 — Deployment는 그에 맞춰 ReplicaSet을 늘리거나 줄이는 역할만 함
• 즉, HPA + Deployment 조합이 메트릭 기반 자동 스케일의 표준 구성

Proportional Scaling

• rollout 진행 중에 스케일링이 들어오면 Deployment Controller가 두 ReplicaSet에 새 replica를 비례 분배
• 분배 기준: 현재 두 ReplicaSet의 Pod 수 비율
• 예시
  • replicas=10, maxSurge=3, maxUnavailable=2로 RollingUpdate 진행 중
  • 옛 ReplicaSet 6개 + 새 ReplicaSet 4개 상태에서 replicas=15로 스케일
  • 늘어난 5개를 6:4 비율로 분배 (옛에 더 많이, 새에 덜)
• 효과
  • 한쪽 ReplicaSet으로 트래픽이 갑자기 쏠리지 않음
  • maxSurge·maxUnavailable 제약은 그대로 지켜짐
  • 점진적 교체 흐름이 끊기지 않음

Cleanup과 진행 데드라인

• Deployment를 운영할 때 자주 만지는 두 가지 spec 필드

spec.revisionHistoryLimit

• 보관할 옛 ReplicaSet 개수 — 롤백 가능한 리비전 범위를 결정
• 기본값: 10
• 한도를 넘은 옛 ReplicaSet은 가비지 컬렉션됨
• 0으로 설정하면
  • 모든 옛 ReplicaSet이 정리됨
  • 롤백 불가 — kubectl rollout undo로 되돌릴 대상이 없음
• 트레이드오프
  • 너무 크면 etcd·API 서버에 ReplicaSet 객체가 누적됨
  • 너무 작으면 롤백할 수 있는 안전 버퍼가 줄어듦

spec.progressDeadlineSeconds

• rollout이 진전 없이 멈춰 있어도 되는 최대 시간(초)
• 기본값: 600 (10분)
• 진행(progress) 판정 기준
  • Deployment가 새 replica를 만들고 available로 가져가는 동안은 progress
  • 그 진전이 지정한 시간 동안 일어나지 않으면 failed로 판단
• 데드라인 초과 시 상태
  • Progressing 컨디션이 status: False로 전환
  • reason: ProgressDeadlineExceeded
  • 컨트롤러는 더 이상 rollout을 진행하지 않고, 기존 replica는 그대로 유지
• 회복 방법
  • 문제가 되는 PodTemplateSpec을 되돌리거나 (rollout undo)
  • pause/resume으로 다시 시도하거나
  • 원인(이미지 pull 실패·readiness probe 실패 등) 자체를 해결

Deployment Status 컨디션

• Deployment의 현재 상태는 status.conditions로 표현됨
• 주요 컨디션 타입: Progressing, Available

진행 중 (Progressing)

• rollout이 정상적으로 흘러가는 동안 type=Progressing, status=True
• reason 값으로 단계 식별
  • NewReplicaSetCreated — 새 ReplicaSet 생성됨
  • FoundNewReplicaSet — 기존 ReplicaSet을 재사용
  • ReplicaSetUpdated — ReplicaSet이 갱신되는 중
  • NewReplicaSetAvailable — 새 ReplicaSet의 replica가 모두 ready (= 완료 신호)

완료 (Complete)

• type=Progressing, status=True, reason=NewReplicaSetAvailable 상태가 곧 완료
• desired replica가 모두 최신 템플릿으로 떠 있고 available함을 의미

실패 (Failed)

• type=Progressing, status=False, reason=ProgressDeadlineExceeded
• 원인이 되는 흔한 케이스
  • 리소스 quota 부족
  • readiness probe 실패
  • 이미지 pull 오류 (오타·권한·태그 없음)
  • RBAC·권한 부족
  • LimitRange 초과
  • 애플리케이션 런타임 오설정

상태 확인 명령어

• kubectl rollout status deployment/<name> — 성공이면 exit 0, 실패면 non-zero
• kubectl describe deployment <name> — 컨디션·이벤트·메시지를 한눈에 확인
• CI 파이프라인에서는 rollout status의 종료 코드로 배포 성공/실패를 판정하는 패턴이 일반적

Canary 배포 패턴

• Deployment 단독으로 카나리를 구성하는 방식 — 두 Deployment를 같은 Service 라벨로 묶는다
• 기본 아이디어
  • 안정 버전(stable) Deployment + 카나리 버전(canary) Deployment를 동시에 운영
  • Service의 셀렉터를 공통 라벨(예: app: nginx)로 두고, 버전은 별도 라벨(version: stable / version: canary)로 구분
  • Service가 양쪽 Pod로 자동 로드밸런싱 → Pod 개수 비율 = 트래픽 비율
• 9 stable + 1 canary = 90:10 트래픽 분배

  # Service — 공통 라벨로 양쪽 Pod 모두 셀렉트
  spec:
    selector:
      app: nginx              # version 무관하게 매칭
  ---
  # Stable Deployment — replicas 9
  spec:
    replicas: 9
    template:
      metadata:
        labels:
          app: nginx
          version: stable
  ---
  # Canary Deployment — replicas 1
  spec:
    replicas: 1
    template:
      metadata:
        labels:
          app: nginx
          version: canary
  

• 한계
  • 트래픽 비율은 Pod 개수로만 조정됨 — 1% 카나리 같은 세밀 분할은 어려움
  • 더 정교한 트래픽 분할이 필요하면 Ingress Controller 가중치나 Service Mesh(Istio·Linkerd 등) 활용

Spec 필드 레퍼런스

• 본문에서 흩어져 다룬 spec 최상위 필드를 참조용으로 한 표에 정리

필드	타입	의미	기본값
replicas	integer	유지할 Pod 개수	1
selector	LabelSelector	관리할 Pod 식별 셀렉터. 생성 후 변경 불가	필수
template	PodTemplateSpec	만들 Pod의 템플릿	필수
strategy.type	string	RollingUpdate 또는 Recreate	RollingUpdate
strategy.rollingUpdate.maxUnavailable	int·%	동시에 사용 불가가 될 수 있는 Pod 최대치	25%
strategy.rollingUpdate.maxSurge	int·%	desired를 일시 초과할 수 있는 Pod 최대치	25%
minReadySeconds	integer	Pod ready 후 available로 인정되기까지 최소 대기 초	0
revisionHistoryLimit	integer	보관할 옛 ReplicaSet 수. 0이면 롤백 불가	10
paused	boolean	rollout 일시 중단 여부	false
progressDeadlineSeconds	integer	rollout 진전 없이 대기 가능한 최대 초. 초과 시 failed	600