TIL

Horizontal Pod Autoscaler

• 공식 문서 - Horizontal Pod Autoscaling
• 워크로드 리소스(Deployment, StatefulSet 등)의 replica 수를 부하에 맞춰 자동 조정하는 메커니즘
• Horizontal scaling — Pod 개수를 늘림 (vs vertical = Pod 1개에 더 많은 리소스 할당)
• Kubernetes API resource(HorizontalPodAutoscaler) + control plane의 controller로 구현
• scale 불가능한 객체엔 적용 안 됨 — 예: DaemonSet

동작 원리

• HPA는 control loop — 연속이 아니라 주기적으로 실행
• 주기 — kube-controller-manager의 --horizontal-pod-autoscaler-sync-period (default 15s)
• 매 주기마다 controller-manager가 수행:
  1. scaleTargetRef로 대상 워크로드 찾기
  2. 대상의 .spec.selector로 Pod 선택
  3. metrics API에서 사용량 조회
  4. desired replica 계산
  5. 워크로드의 scale subresource를 통해 replica 갱신
• 메트릭 처리 방식 3가지

메트릭 분류	데이터 출처	처리
per-Pod resource (CPU, memory)	metrics.k8s.io	utilization(요청 대비 %) 또는 raw 값. 모든 대상 Pod의 평균을 desired와 비교
per-Pod custom	custom.metrics.k8s.io	utilization 없이 raw 값만. 평균 후 비교
object / external	custom.metrics.k8s.io / external.metrics.k8s.io	단일 값. autoscaling/v2에선 비교 전 Pod 수로 나눌 수 있음

• container의 resource request가 없으면 — 해당 Pod의 CPU utilization은 정의되지 않음 → HPA가 그 메트릭에 대해 아무 동작도 안 함

Algorithm details

• 기본 공식 — desiredReplicas = ceil(currentReplicas × currentMetricValue / desiredMetricValue)
• 예시
  • current 200m, desired 100m → ratio 2.0 → replicas 2배
  • current 50m, desired 100m → ratio 0.5 → replicas 절반
• tolerance — ratio가 1.0에 충분히 가까우면 스킵 (default 0.1 = 10%)
• targetAverageValue / targetAverageUtilization — 모든 대상 Pod의 평균을 currentMetricValue로 사용
• Pod 필터링 단계 — tolerance 적용 전에 메트릭 누락·not-ready 처리
  • per-Pod resource — deletion timestamp 있는 Pod 무시, failed Pod 제거
  • external / object — Running & Ready 기준 (Ready 상태인 terminating Pod도 포함)
  • 메트릭 없는 Pod은 set aside (최종 조정에 사용)
  • CPU 메트릭 — Pod이 not-ready거나 메트릭이 Ready 전이면 set aside
• 보수적 재계산 — 누락·not-ready Pod이 있으면
  • 스케일 다운 시 — 누락 Pod이 desired의 100% 사용한다고 가정
  • 스케일 업 시 — 누락·not-ready Pod이 0% 사용한다고 가정
  • 재계산 결과 방향이 반대로 바뀌거나 tolerance 안이면 액션 없음
• HPA status에 보고되는 평균값은 원래 값 (보수적 재계산 전 값)
• 다중 메트릭 — 메트릭별로 desired replicas 계산 후 가장 큰 값 선택
• 메트릭 fetch 실패 + 다른 메트릭은 scale-down 제안 → 스킵 (scale-up은 가능)
• scale-down stabilization — 스케일 직전, controller가 일정 window 안의 모든 추천값 중 최댓값을 선택. --horizontal-pod-autoscaler-downscale-stabilization (default 5분)

Pod readiness와 autoscaling metrics

• HPA가 Pod 시작 시점의 CPU 메트릭을 어떻게 다룰지에 영향을 주는 cluster-wide CLI 옵션 2개

옵션	기본값	역할
--horizontal-pod-autoscaler-cpu-initialization-period	5m	Pod 시작 후 이 기간 동안 — Ready 상태이고 그 Ready 구간 동안 측정된 메트릭만 카운트. 그 외 CPU 사용량은 무시
--horizontal-pod-autoscaler-initial-readiness-delay	30s	Pod 시작 후 이 기간 동안 — 현재 Unready인 Pod은 여전히 initializing으로 취급. 짧게 Ready로 전환됐다가 다시 Unready된 경우에도 무시

• 의도 — JVM warm-up처럼 시작 직후의 misleading high CPU 사용량이 HPA 결정에 영향을 주지 않게 함
• 두 옵션 모두 cluster-wide만 — Pod·HPA 단위로는 변경 불가
• 권장 패턴
  • startupProbe — CPU spike가 지나기 전까지 통과하지 않게 구성
  • 또는 readinessProbe의 initialDelaySeconds를 CPU spike 이후로 맞춤
  • 추가로 --horizontal-pod-autoscaler-cpu-initialization-period를 startup 시간만큼 늘림

API object

• API group — autoscaling
• stable 버전 — autoscaling/v2 (memory·custom metrics 지원)
• autoscaling/v2에서 도입된 새 필드는 autoscaling/v1로 작업할 때 annotation으로 보존
• 이름은 DNS subdomain name 규칙

메트릭 소스

• HPA의 metrics 필드에 메트릭 소스 타입을 명시 — 같은 HPA에 여러 개 함께 지정 가능

타입	키 필드	용도
Resource	resource	Pod 전체의 CPU·memory 사용량
ContainerResource	containerResource	Pod 내 특정 컨테이너의 CPU·memory 사용량
Pods	pods	Pod별 custom 메트릭 (raw 값, 평균 비교)
Object	object	K8s 객체 단위 메트릭 (예: Ingress의 RPS)
External	external	클러스터 외부 시스템 메트릭 (예: 클라우드 큐 길이)

Resource metrics

• Pod spec의 resource request가 있어야 utilization 계산 가능

  type: Resource
  resource:
    name: cpu
    target:
      type: Utilization
      averageUtilization: 60   # 평균 사용률을 60%로 유지
  

• Utilization — current usage / requested resources 비율
• 주의 — Pod의 모든 컨테이너 사용량이 합산돼 개별 컨테이너 사용을 정확히 반영하지 않음. 한 컨테이너만 과부하여도 Pod 합산은 정상으로 보일 수 있음

Container resource metrics

• 개별 컨테이너 단위로 스케일링 — 위 합산 문제의 해결책
• 예시 — 웹 앱 + 로깅 sidecar Pod에서 웹 앱만 보고 scale 결정

  type: ContainerResource
  containerResource:
    name: cpu
    container: application
    target:
      type: Utilization
      averageUtilization: 60
  

• 지정된 컨테이너가 일부 Pod에만 있으면 — 그 Pod들은 계산에서 제외, 추천이 재계산됨
• 컨테이너 이름 변경 시 순서 중요 — 스케일링이 끊기지 않도록
  1. HPA에 신·구 이름 둘 다 추가
  2. 워크로드(Deployment 등) 업데이트로 컨테이너 이름 교체
  3. 롤아웃 완료 후 HPA에서 구 이름 제거

Custom metrics

• autoscaling/v2부터 안정화. K8s 빌트인이 아닌 메트릭으로 스케일
• HPA controller가 custom.metrics.k8s.io API를 통해 조회 — adapter 필요

Multiple metrics

• autoscaling/v2에서 여러 메트릭 동시 지정 가능
• 각 메트릭별로 desired replica를 계산 후 가장 큰 값을 선택 (단, maxReplicas 한도 내)
• 어느 한 메트릭 조회 실패 + 다른 메트릭이 scale-down 제안 → 스케일 자체를 스킵 (scale-up은 유효)

Metrics APIs

• HPA controller는 default로 aggregation layer를 거쳐 메트릭 API를 조회
• 클러스터 관리자 사전 조건
  • API aggregation layer 활성화
  • 사용할 메트릭 API가 등록돼 있어야 함

API	메트릭 종류	제공 주체
metrics.k8s.io	resource (CPU·memory)	metrics-server 애드온 (별도 설치 필요)
custom.metrics.k8s.io	custom	벤더의 adapter API 서버 (예: Prometheus Adapter)
external.metrics.k8s.io	external (클러스터 외부)	위 adapter들이 함께 제공하기도 함

• 위 3개는 서로 다른 API — 같은 adapter가 여러 개를 함께 서빙할 수 있음

Workload scale 안정성 (flapping)

• flapping (= thrashing) — 메트릭이 자주 흔들려 replica 수가 짧은 시간에 반복해서 늘었다 줄었다 하는 현상
• 제어 시스템의 hysteresis 개념에 해당 — HPA는 stabilization window·tolerance 등으로 완화
• 구체 설정은 behavior 필드의 stabilization window·tolerance·scaling policy 참고 (다음 세션)

Rolling update 중 HPA

• Deployment — HPA는 Deployment의 replicas 필드만 조정. Deployment controller가 롤링 중 신·구 ReplicaSet의 replica 분배를 알아서 처리
• StatefulSet — 중간 ReplicaSet 없이 StatefulSet이 직접 Pod 관리. HPA가 조정한 replica 수를 그대로 받음

Configurable scaling behavior

• autoscaling/v2의 behavior 필드 — scaleUp, scaleDown을 각 방향별로 따로 구성
• 3가지 메커니즘으로 변경 속도와 안정성 제어
  • scaling policies — replica 변경 속도 제한
  • stabilization window — 짧은 메트릭 변동에 따른 flapping 완화
  • tolerance — 작은 메트릭 편차는 무시

Scaling policies

• behavior.scaleUp.policies / behavior.scaleDown.policies 아래 1개 이상 지정
• 정책 타입 — Pods(절대 개수) 또는 Percent(현재 replica의 %)
• periodSeconds — 정책이 적용되는 시간 창. 최대 1800초(30분)

• 여러 정책이 있으면 — default로 selectPolicy: Max → 가장 큰 변화를 허용하는 정책 선택

  behavior:
    scaleDown:
      policies:
      - type: Pods
        value: 4              # 분당 최대 4 Pod 감소
        periodSeconds: 60
      - type: Percent
        value: 10             # 분당 최대 10% 감소
        periodSeconds: 60
  

• 위 예 — replica가 40 초과면 Percent가 더 큰 변화 → 10% 감소 적용. 40 이하면 Pods 정책의 4가 더 큼 → 4 감소
• selectPolicy 값 — Max(기본) / Min(가장 작은 변화) / Disabled(해당 방향 스케일 완전 중단)

Stabilization window

• 메트릭 변동에 따른 replica fluctuation 방지 — 일정 시간 동안의 이전 desired states를 참고

• scale-down 시 — 윈도우 내 추천값들 중 최댓값을 채택 (rolling max). Pod을 줄이자마자 다시 만드는 패턴을 막음

  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300  # 과거 5분치 desired state 고려
  

Tolerance

• tolerance — 이 값 이하의 메트릭 편차에는 스케일링하지 않음
• scale-up과 scale-down에 각각 설정 가능

• 예시 — memory target 100MiB, scale-up tolerance 5% → 105MiB 초과여야 scale up

  behavior:
    scaleUp:
      tolerance: 0.05   # 5%
  

• 미지정 시 cluster-wide 기본값 10% — --horizontal-pod-autoscaler-tolerance CLI 옵션으로만 변경 가능 (API로는 변경 불가)

Default behavior

• behavior에 일부만 지정하면 — 미지정 필드는 default와 merge됨

방향	stabilization	정책	selectPolicy
scaleDown	300s	Percent 100% / 15s (최소 replica까지 한 번에 가능)	Max
scaleUp	0s (즉시)	Percent 100% / 15s + Pods 4 / 15s	Max

• scale-down은 보수적 — 5분 stabilization으로 천천히 줄임
• scale-up은 공격적 — stabilization 없이 즉시 반응

자주 쓰는 패턴

• scale-down stabilization 단축 (1분)

  behavior:
    scaleDown:
      stabilizationWindowSeconds: 60
  

• scale-down rate 제한 (분당 10%, 동시에 분당 최대 5 Pod)

  behavior:
    scaleDown:
      policies:
      - type: Percent
        value: 10
        periodSeconds: 60
      - type: Pods
        value: 5
        periodSeconds: 60
      selectPolicy: Min      # 더 작은 변화 선택
  

• scale-down 완전 비활성

  behavior:
    scaleDown:
      selectPolicy: Disabled
  

kubectl 지원

• 다른 API 리소스와 동일 — kubectl create / get hpa / describe hpa / delete hpa
• kubectl autoscale 단축 명령

  kubectl autoscale rs foo --min=2 --max=5 --cpu=80%
  # ReplicaSet foo에 대해 CPU 80% target, replica 2~5인 HPA 생성
  

Implicit maintenance-mode

• HPA 설정을 건드리지 않고도 일시적으로 스케일링을 중단시킬 수 있음
• 조건 — target의 desired replicas가 0 AND HPA의 minReplicas > 0
• 동작 — HPA가 조정을 멈춤. self condition에 ScalingActive: false 기록
• 재활성화 — target의 desired replicas 또는 HPA의 minReplicas 중 하나를 수동으로 조정

Deployment / StatefulSet을 HPA로 마이그레이션

• HPA를 활성화한 워크로드의 매니페스트에서 — spec.replicas 제거 권장
• 안 제거하면 — kubectl apply -f deployment.yaml 할 때마다 매니페스트의 replicas 값으로 되돌림 → HPA 결정과 충돌하며 flapping
• 제거 시 주의 — spec.replicas의 default가 1이라 한 번 1로 떨어졌다 다시 올라갈 수 있음 (Pod count 일시 저하)
• 무중단 방법

적용 방식	절차
Client-Side Apply (기본)	kubectl apply edit-last-applied deployment/<name>로 last-applied annotation에서 spec.replicas 제거 → 매니페스트에서도 제거 → 이후 정상 apply
Server-Side Apply	transferring ownership 가이드를 따라 replicas 필드의 소유권을 HPA로 이전