Kubernetes HPA가 확장되지 않을 때: 디버깅 가이드

Source: Dev.to

사진 제공: Ibrahim Yusuf / Unsplash

소개

프로덕션 환경에서는 필요에 따라 확장할 수 있는 능력이 성능과 신뢰성을 위해 필수적입니다. HPA는 이를 달성하기 위한 핵심 구성 요소이지만, 작동하지 않을 때 문제를 진단하기가 어려울 수 있습니다. 이 글을 끝까지 읽으면 다음을 할 수 있게 됩니다:

• HPA가 확장되지 않을 수 있는 이유를 이해합니다.
• 명확한 단계별 문제 해결 워크플로우를 따라갑니다.
• 향후 확장 문제를 방지하기 위한 모범 사례를 적용합니다.

문제 이해

비스케일링 HPA의 일반적인 증상은 다음과 같습니다:

• 예상대로 파드가 스케일 업 또는 스케일 다운되지 않음.
• CPU, 메모리 또는 사용자 정의 메트릭의 변화에 HPA가 반응하지 않음.
• HPA 컨트롤러 로그에 오류가 발생함.

실제 예시: 마케팅 캠페인으로 트래픽 급증이 발생했지만 파드 수가 원래 복제본 수에 머물러 지연 시간이 급증하고 다운타임이 발생할 수 있습니다. 이를 해결하려면 HPA 내부 구조와 의사결정에 영향을 주는 구성 요소를 이해해야 합니다.

Prerequisites

To follow this guide you need:

• Basic knowledge of Kubernetes and HPA.
• A Kubernetes cluster with the HPA feature gate enabled.
• kubectl installed and configured to talk to the cluster.
• A text editor or IDE for editing YAML manifests.
• Access to a terminal/command prompt.

단계별 솔루션

단계 1: 진단

1. HPA 객체 확인

   kubectl get hpa -A

2. Pod 상태 점검

   kubectl get pods -A

3. Running이 아닌 Pod 찾기

   kubectl get pods -A | grep -v Running

4. HPA 이벤트 및 컨트롤러 로그 확인

   kubectl describe hpa -n <namespace> <hpa-name>

   # 컨트롤러 매니저 로그에 접근할 수 있는 경우
   kubectl logs -n kube-system -l component=horizontal-pod-autoscaler

   “failed to get metrics” 또는 “unable to scale”와 같은 경고가 있는지 확인합니다.

단계 2: 구현 (올바른 HPA 생성)

아래는 Deployment와 매칭되는 HPA의 최소 예시입니다. 워크로드에 맞게 리소스 요청/제한 및 메트릭 목표를 조정하세요.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-deployment
  labels:
    app: example
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example
  template:
    metadata:
      labels:
        app: example
    spec:
      containers:
        - name: example
          image: example/image:latest
          resources:
            requests:
              cpu: 100m
            limits:
              cpu: 200m
---
apiVersion: autoscaling/v2beta2
kind: HorizontalPodAutoscaler
metadata:
  name: example-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: example-deployment
  minReplicas: 3
  maxReplicas: 10
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 50   # 필요에 따라 조정

핵심 포인트

• HPA가 Deployment를 가리키도록 scaleTargetRef(selector가 아님)를 사용합니다.
• Deployment의 Pod 템플릿에 동일한 라벨(app: example)이 포함되어 있는지 확인합니다.
• HPA가 활용률을 올바르게 계산할 수 있도록 현실적인 requests/limits를 설정합니다.
• 적절한 averageUtilization을 지정하고, 필요하면 사용자 정의 메트릭을 사용합니다.

단계 3: HPA 정상 동작 확인

1. 매니페스트 적용

   kubectl apply -f deployment-and-hpa.yaml

2. 부하 생성 (hey 또는 wrk 등 사용)하여 CPU 사용량을 목표치 이상으로 올립니다.

3. HPA 상태 모니터링

   kubectl get hpa example-hpa -w

   메트릭이 임계값을 초과하면 CURRENT 복제본 수가 증가하는 것을 확인할 수 있습니다.

모범 사례 및 일반적인 함정

활용도: 50

kubectl apply -f example.yaml

검증

HPA 설정이 올바르게 작동하는지 확인하려면 다음을 실행합니다:

kubectl get hpa example-hpa -o yaml

이 명령은 현재 HPA 구성과 복제본 수를 표시합니다.

또한 파드 상태를 확인할 수 있습니다:

kubectl get pods -A

전체 매니페스트 예시

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: example
  template:
    metadata:
      labels:
        app: example
    spec:
      containers:
      - name: example
        image: example/image
        resources:
          requests:
            cpu: 100m
          limits:
            cpu: 200m
---
apiVersion: autoscaling/v2beta2
kind: HorizontalPodAutoscaler
metadata:
  name: example-hpa
spec:
  selector:
    matchLabels:
      app: example
  minReplicas: 3
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 50
---
apiVersion: v1
kind: Service
metadata:
  name: example-service
spec:
  selector:
    app: example
  ports:
  - name: http
    port: 80
    targetPort: 8080
  type: LoadBalancer

이 매니페스트는 세 개의 복제본을 가진 배포, **CPU 사용량 50 %**를 목표로 하는 HPA, 그리고 파드를 노출하는 LoadBalancer 서비스를 생성합니다.

일반적인 함정 및 회피 방법

• 리소스 부족 – 클러스터에 확장할 충분한 용량이 있는지 확인하세요.
• 잘못된 메트릭 – HPA가 올바른 메트릭(CPU, 메모리 또는 사용자 정의)을 사용하는지 확인하세요.
• 모니터링 부족 – HPA 문제를 조기에 감지할 수 있도록 알림을 설정하세요.
• 라벨 불일치 – 컨트롤러가 매칭할 수 있도록 배포와 HPA 라벨을 동기화하세요.
• 테스트 부족 – HPA가 기대대로 동작하는지 확인하기 위해 부하를 시뮬레이션하세요.

Best Practices Summary

• resource‑based와 custom metrics를 결합하여 반응형 스케일링을 구현합니다.
• 모니터링 HPA 상태와 파드 성능을 지속적으로 수행합니다.
• 리소스 전반에 걸쳐 일관된 라벨 및 어노테이션을 사용합니다.
• 현실적인 워크로드에서 스케일링 동작을 테스트합니다.
• 트래픽을 고르게 분산시키기 위해 로드 밸런서 또는 인그레스 컨트롤러를 배포합니다.

결론

우리는 HPA가 확장되지 않을 수 있는 일반적인 이유들을 살펴보고 단계별 문제 해결 가이드를 제공했습니다. 모범 사례 권장 사항을 따르면 Kubernetes 클러스터가 효율적으로 확장되어 사용자에게 신뢰할 수 있는 경험을 제공할 수 있습니다.

추가 읽을거리

• Kubernetes 배포 전략 – 롤링 업데이트, 블루‑그린, 카나리 등.
• Kubernetes 네트워킹 – Pods, Services, Ingress 컨트롤러.
• Kubernetes 보안 – 네트워크 정책, 시크릿, RBAC.

Source:

🚀 DevOps 실력을 레벨업하세요

Kubernetes 문제 해결을 마스터하고 싶으신가요? 다음 리소스를 확인해 보세요:

📚 추천 도구

• Lens – 디버깅을 10배 빠르게 해주는 Kubernetes IDE.
• k9s – 터미널 기반 Kubernetes 대시보드.
• Stern – 멀티‑팟 로그 테일링.

📖 강좌 및 도서

• Kubernetes Troubleshooting in 7 Days – 단계별 이메일 강좌 ($7).
• Kubernetes in Action – 권위 있는 가이드 (Amazon).
• Cloud Native DevOps with Kubernetes – 프로덕션 베스트 프랙티스.

📬 최신 정보 받아보기

DevOps Daily Newsletter 구독하면:

• 주당 3개의 선별 기사
• 프로덕션 인시던트 사례 연구
• 독점 문제 해결 팁

이 내용이 도움이 되었나요? 팀과 공유해 주세요!

원본은 aicontentlab.xyz에서 게시되었습니다.