수평형 포드 자동 확장 문제 해결

Google Kubernetes Engine(GKE)에서 수평형 포드 자동 확장이 예상대로 작동하지 않으면 워크로드가 올바르게 확장되지 않을 수 있습니다. 이 문제로 인해 애플리케이션이 부하를 처리하지 못해 성능 문제나 서비스 중단이 발생할 수 있습니다. CPU가 높음에도 불구하고 포드가 증가하지 않거나, HorizontalPodAutoscaler 상태에 측정항목 값이 <unknown>로 표시되거나, 확장 작업이 전혀 발생하지 않을 수 있습니다.

이 문서를 사용하여 HorizontalPodAutoscaler의 초기 구성 오류부터 측정항목 파이프라인 내의 더 복잡한 오류에 이르기까지 수평형 포드 자동 확장과 관련된 일반적인 문제를 진단하고 해결할 수 있습니다. 이러한 문제 해결 단계를 따르면 수요에 따라 애플리케이션을 효율적이고 안정적으로 확장할 수 있습니다.

이 정보는 HorizontalPodAutoscaler를 구성하고 애플리케이션이 올바르게 확장되는지 확인해야 하는 애플리케이션 개발자에게 중요합니다. 또한 플랫폼 관리자와 운영자가 모든 자동 확장 워크로드에 영향을 미치는 측정항목 파이프라인 또는 클러스터 구성 문제를 해결하는 데도 도움이 됩니다. Google Cloud 콘텐츠에서 참조하는 일반적인 역할과 예시 태스크에 대한 자세한 내용은 일반 GKE 사용자 역할 및 태스크를 참조하세요.

시작하기 전에

  • 배포 및 StatefulSet와 같은 확장 가능한 워크로드에 HorizontalPodAutoscaler 객체를 사용해야 합니다. DaemonSets와 같이 확장할 수 없는 워크로드에는 수평형 포드 자동 확장을 사용할 수 없습니다.
  • HorizontalPodAutoscaler 객체 검사 및 클러스터 로그 보기를 포함하여 GKE에서 수평형 포드 자동 확장을 문제 해결하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.

    • GKE 리소스 검사: GKE 뷰어(roles/container.viewer)
    • 클러스터 로그 보기: 로그 뷰어(roles/logging.viewer)

    역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

    커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

  • GKE 클러스터와 통신하도록 kubectl 명령줄 도구를 구성합니다.

    gcloud container clusters get-credentials CLUSTER_NAME \
        --location LOCATION \
        --project PROJECT_ID
    

    다음을 바꿉니다.

    • CLUSTER_NAME: 클러스터 이름입니다.
    • LOCATION: 클러스터의 Compute Engine 리전 또는 영역(예: us-central1 또는 us-central1-a)
    • PROJECT_ID: Google Cloud 프로젝트 ID입니다.

HorizontalPodAutoscaler 문제 진단

HorizontalPodAutoscaler 문제를 진단하려면 kubectl 명령어 또는 Google Cloud 콘솔을 사용하여 상태와 구성을 검사합니다.

HorizontalPodAutoscaler 설명

실시간 계산 및 최근 확장 결정을 보려면 kubectl describe hpa 명령어를 사용합니다.

kubectl describe hpa HPA_NAME -n NAMESPACE_NAME

다음을 바꿉니다.

  • HPA_NAME: HorizontalPodAutoscaler 객체의 이름입니다.
  • NAMESPACE_NAME: HorizontalPodAutoscaler 객체의 네임스페이스입니다.

출력은 다음과 비슷합니다.

Name:                                                  php-apache-hpa
Namespace:                                             default
Reference:                                             Deployment/php-apache
Metrics: ( current / target )
  resource cpu on pods (as a percentage of request):   1% (1m) / 50%
Min replicas:                                          1
Max replicas:                                          10
Conditions:
  Type            Status  Reason              Message
  ----            ------  ------              -------
  AbleToScale     True    ReadyForNewScale    recommended size matches current size
  ScalingActive   True    ValidMetricFound    the HorizontalPodAutoscaler was able to successfully calculate a replica count
Events:
  Type     Reason              Age   From                       Message
  ----     ------              ----  ----                       -------
  Normal   SuccessfulRescale   39m   horizontal-pod-autoscaler  New size: 4; reason: cpu resource utilization...
  Normal   SuccessfulRescale   26m   horizontal-pod-autoscaler  New size: 1; reason: cpu resource utilization...

출력에서 다음 세 섹션은 문제를 진단하는 데 도움이 됩니다.

  • Metrics: 목표와 비교하여 현재 측정항목 값을 표시합니다. <unknown> 측정항목 값은 HorizontalPodAutoscaler가 측정항목을 가져오지 않았거나 측정항목 파이프라인이 손상되었음을 나타냅니다.
  • Conditions: HorizontalPodAutoscaler가 측정항목을 가져오고(AbleToScale) 확장 계산을 수행할 수 있는지(ScalingActive) 여부를 보여줍니다. 이러한 조건 중 하나라도 False 상태이면 실패를 나타냅니다.
  • Events: HorizontalPodAutoscaler 컨트롤러의 최근 확장 작업, 경고, 오류를 로깅합니다. FailedGetScale 또는 FailedGetResourceMetric와 같은 특정 오류 메시지나 이유를 찾을 수 있는 첫 번째 위치인 경우가 많습니다.

HorizontalPodAutoscaler 매니페스트 확인

HorizontalPodAutoscaler 객체의 YAML 매니페스트를 사용하면 구성 및 현재 상태에 대한 정보를 볼 수 있습니다.

YAML 매니페스트를 보려면 다음 옵션 중 하나를 선택합니다.

콘솔

  1. Google Cloud 콘솔에서 객체 브라우저 페이지로 이동합니다.

    객체 브라우저로 이동

  2. 객체 종류 목록에서 HorizontalPodAutoscaler 체크박스를 선택하고 확인을 클릭합니다.

  3. 자동 확장 API 그룹으로 이동한 후 HorizontalPodAutoscaler의 펼치기 화살표를 클릭합니다.

  4. 검사할 HorizontalPodAutoscaler 객체의 이름을 클릭합니다.

  5. HorizontalPodAutoscaler 객체의 전체 구성을 표시하는 YAML 섹션을 검토합니다.

kubectl

다음 명령어를 실행합니다.

kubectl get hpa HPA_NAME -n NAMESPACE_NAME -o yaml

다음을 바꿉니다.

  • HPA_NAME: HorizontalPodAutoscaler 객체의 이름입니다.
  • NAMESPACE_NAME: HorizontalPodAutoscaler 객체의 네임스페이스입니다.

매니페스트를 가져온 후 다음 주요 섹션을 찾습니다.

  • spec(구성):
    • scaleTargetRef: HorizontalPodAutoscaler가 확장하도록 구성된 워크로드(예: 배포)입니다.
    • minReplicas 및 maxReplicas: 최소 및 최대 복제본 설정입니다.
    • metrics: 확장을 위해 구성된 측정항목(예: CPU 사용률 또는 커스텀 측정항목)
  • status(HorizontalPodAutoscaler의 실시간 상태):
    • currentMetrics: HorizontalPodAutoscaler에서 관찰한 최신 측정항목 값입니다.
    • currentReplicas 및 desiredReplicas: 현재 포드 수 및 HorizontalPodAutoscaler가 확장하려는 수입니다.
    • conditions: HorizontalPodAutoscaler의 상태를 표시합니다.
      • AbleToScale: HorizontalPodAutoscaler가 대상 및 측정항목을 찾을 수 있는지 여부를 나타냅니다.
      • ScalingActive: HorizontalPodAutoscaler가 확장을 계산하고 수행할 수 있는지 여부를 표시합니다.
      • ScalingLimited: HorizontalPodAutoscaler가 확장하려고 하지만 minReplicas 또는 maxReplicas 설정에 의해 제한되는지 여부를 표시합니다.

이벤트 로그 보기

HorizontalPodAutoscaler 객체를 더 자세히 파악하려면 다음 유형의 로그를 사용하세요.

  • Cloud Logging에서 HorizontalPodAutoscaler 이벤트 보기: 로그 필터를 사용하여 특정 클러스터의 모든 HorizontalPodAutoscaler 이벤트를 찾습니다. 예를 들면 다음과 같습니다.

    1. Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

      로그 탐색기로 이동

    2. 쿼리 창에 다음 쿼리를 입력합니다.

      resource.type="k8s_cluster"
      resource.labels.cluster_name="CLUSTER_NAME"
      resource.labels.location="LOCATION"
      logName="projects/PROJECT_ID/logs/events"
      jsonPayload.involvedObject.kind="HorizontalPodAutoscaler"
      

      다음을 바꿉니다.

      • CLUSTER_NAME: HorizontalPodAutoscaler가 속한 클러스터의 이름입니다.
      • LOCATION: 클러스터의 Compute Engine 리전 또는 영역(예: us-central1 또는 us-central1-a)
      • PROJECT_ID: 프로젝트 ID입니다.
    3. 쿼리 실행을 클릭하고 출력을 검토합니다.

  • 수평형 포드 자동 확장 이벤트 보기: 이 로그는 HorizontalPodAutoscaler가 권장사항을 계산하는 방법을 설명하는 구조화되고 사람이 읽을 수 있는 로그를 제공하여 의사 결정 프로세스에 대한 자세한 정보를 제공합니다.

HorizontalPodAutoscaler 구성 오류 문제 해결

다음 섹션에서는 잘못 입력된 필드, 잘못된 측정항목 타겟, 충돌하는 구성과 같은 HorizontalPodAutoscaler 매니페스트의 잘못된 구성을 설명합니다.

대상 워크로드를 찾을 수 없음

증상

Events 섹션에는 다음과 유사한 메시지가 포함된 FailedGetScale 조건이 있습니다.

the HorizontalPodAutoscaler controller was unable to get the target's current scale: WORKLOAD_TYPE.apps "TARGET_WORKLOAD" not found

이 출력에는 다음 값이 포함됩니다.

  • WORKLOAD_TYPE: 워크로드 유형(예: Deployment 또는 StatefulSet)입니다.
  • TARGET_WORKLOAD: 워크로드의 이름입니다.

원인

HorizontalPodAutoscaler 컨트롤러가 관리하도록 구성된 워크로드(예: 배포 또는 StatefulSet)를 찾을 수 없습니다. 이 문제는 HorizontalPodAutoscaler 매니페스트의 scaleTargetRef 필드가 잘못 구성되어 발생합니다. 지정된 리소스가 존재하지 않거나, 삭제되었거나, 맞춤법 오류가 있을 수 있습니다.

해결 방법

다음 해결 방법을 시도해 보세요.

  1. HorizontalPodAutoscaler 매니페스트의 scaleTargetRef 필드 확인: scaleTargetRef 필드의 name, kind, apiVersion 값이 대상 워크로드의 해당 메타데이터와 정확히 일치하는지 확인합니다. 워크로드 이름이 잘못된 경우 올바른 이름을 가리키도록 HorizontalPodAutoscaler의 scaleTargetRef 필드를 업데이트합니다.
  2. 워크로드가 있는지 확인: 대상 워크로드가 HorizontalPodAutoscaler와 동일한 네임스페이스에 있는지 확인합니다. kubectl get deployment DEPLOYMENT_NAME와 같은 명령어로 이를 확인할 수 있습니다. 워크로드를 의도적으로 삭제한 경우 해당 HorizontalPodAutoscaler 객체를 삭제하여 클러스터를 정리합니다. 워크로드를 다시 만들어야 하는 경우 HorizontalPodAutoscaler는 사용 가능해진 후 자동으로 워크로드를 찾고 오류가 해결됩니다.
  3. HorizontalPodAutoscaler와 워크로드가 동일한 네임스페이스에 있는지 확인: HorizontalPodAutoscaler와 대상 워크로드는 동일한 네임스페이스에 있어야 합니다. kubectl 명령어로 객체를 만들 때 네임스페이스를 지정하지 않으면 Kubernetes는 객체를 default 네임스페이스에 배치합니다. 이 동작은 HorizontalPodAutoscaler가 default 네임스페이스에 있고 워크로드가 다른 네임스페이스에 있거나 그 반대의 경우 불일치를 일으킬 수 있습니다. 두 객체의 네임스페이스를 확인하고 일치하는지 확인합니다.

HorizontalPodAutoscaler가 대상을 찾으면 AbleToScale 조건이 True가 되고 메시지가 the HorizontalPodAutoscaler controller was able to get the target's current scale로 변경됩니다.

잘못된 측정항목

증상

구성 문제로 인해 HorizontalPodAutoscaler가 필요한 복제본을 계산할 수 없는 경우 Events 섹션에 다음과 유사한 메시지와 함께 FailedComputeMetricsReplicas 이유가 표시됩니다.

invalid metrics (1 invalid out of 1)

원인

이 오류는 일반적으로 HorizontalPodAutoscaler 매니페스트에 정의한 target와 type 측정항목이 일치하지 않음을 의미합니다. 예를 들어 type을 Utilization로 지정했지만 averageUtilization 대신 averageValue의 목표 값을 제공했을 수 있습니다.

해결 방법

target 필드의 값이 type 측정항목과 일치하도록 HorizontalPodAutoscaler 매니페스트를 수정합니다.

  • type가 Utilization이면 target 필드의 값은 averageUtilization여야 합니다.
  • type가 AverageValue이면 target 필드의 값은 averageValue여야 합니다.

측정항목 라벨은 허용되지 않습니다.

증상

다음과 같은 오류가 표시됩니다.

unable to fetch metrics from external metrics API: googleapi: Error 400: Metric label: 'LABEL_NAME' is not allowed

이 출력에서 LABEL_NAME은 잘못된 라벨의 이름입니다.

원인

HorizontalPodAutoscaler 매니페스트가 metric.selector.matchLabels 섹션에 잘못된 라벨 키를 지정하고 Cloud Monitoring이 이 측정항목의 키를 인식하거나 허용하지 않습니다.

해결 방법

이 문제를 해결하려면 다음 단계를 따르세요.

  1. 오류 메시지에서 허용되지 않는 라벨 이름을 식별합니다.
  2. HorizontalPodAutoscaler 매니페스트의 metric.selector.matchLabels 섹션에서 이 라벨 키를 삭제하거나 수정하세요.
  3. 해당 측정항목에 대한 Cloud Monitoring 문서를 참조하여 유효하고 필터링 가능한 라벨 키를 찾습니다.

여러 HorizontalPodAutoscaler가 동일한 워크로드를 타겟팅함

증상

HorizontalPodAutoscaler의 상태 내에 이 충돌을 직접 나타내는 특정 Condition 또는 Reason가 없습니다. 대신 다음과 같은 증상이 발생할 수 있습니다.

  • 워크로드의 복제본 수가 예기치 않게 변동될 수 있습니다.
  • 확장 결정이 단일 HorizontalPodAutoscaler에 정의된 측정항목과 일치하지 않는 것처럼 보일 수 있습니다.
  • 이벤트를 볼 때 서로 다른 HorizontalPodAutoscaler 객체에서 교대로 또는 모순되는 SuccessfulRescale 이벤트가 표시될 수 있습니다.

원인

이 문제는 동일한 네임스페이스 내에 있는 두 개 이상의 HorizontalPodAutoscaler 객체가 spec.scaleTargetRef 필드에 정확히 동일한 워크로드를 지정하기 때문에 발생합니다. 각 HorizontalPodAutoscaler는 복제본 수를 독립적으로 계산하고 자체 측정항목 및 대상 집합을 기반으로 워크로드를 확장하려고 시도합니다. Kubernetes는 이 구성을 차단하지 않지만 HorizontalPodAutoscaler가 서로 경쟁하기 때문에 불규칙한 확장 조정이 발생합니다.

해결 방법

충돌을 방지하려면 단일 HorizontalPodAutoscaler 객체에 모든 확장 측정항목을 정의합니다. 각 HorizontalPodAutoscaler는 자체 spec.metrics 필드에서 확장 요구사항을 계산하므로 이를 병합하면 선택한 HorizontalPodAutoscaler 객체가 CPU 및 초당 요청 수와 같은 모든 요소를 함께 고려할 수 있습니다.

  1. 동일한 워크로드를 타겟팅하는 HorizontalPodAutoscaler를 식별하려면 각 HorizontalPodAutoscaler 객체의 YAML 매니페스트를 가져옵니다. 출력의 spec.scaleTargetRef 필드에 주의를 기울입니다.

    kubectl get hpa -n NAMESPACE_NAME -o yaml
    

    NAMESPACE_NAME을 HorizontalPodAutoscaler 객체의 네임스페이스로 바꿉니다.

    서로 다른 HorizontalPodAutoscaler 리소스가 scaleTargetRef 필드 내에서 apiVersion, kind, name에 대해 동일한 값을 갖는 인스턴스를 찾습니다.

  2. 측정항목을 단일 HorizontalPodAutoscaler 객체로 통합합니다.

    1. 유지할 HorizontalPodAutoscaler 객체 하나를 선택합니다. 이 HorizontalPodAutoscaler는 수정할 수 있습니다.
    2. 동일한 워크로드를 타겟팅하는 다른 각 HorizontalPodAutoscaler 객체의 매니페스트에서 spec.metrics 섹션을 검사합니다.
    3. 중복 HorizontalPodAutoscaler 객체의 spec.metrics 섹션에서 유지하려는 측정항목 정의를 복사합니다.
    4. 복사한 측정항목 정의를 유지하기로 결정한 HorizontalPodAutoscaler의 spec.metrics 배열에 붙여넣습니다.
  3. 변경사항을 적용합니다.

    kubectl apply -f MANIFEST_NAME
    

    MANIFEST_NAME을 유지하기로 결정한 HorizontalPodAutoscaler 매니페스트의 이름으로 바꿉니다.

  4. 동일한 워크로드를 타겟팅하는 다른 HorizontalPodAutoscaler 객체를 삭제합니다.

    kubectl delete hpa DUPLICATE_MANIFEST_NAME -n NAMESPACE_NAME
    

    DUPLICATE_MANIFEST_NAME을 삭제하려는 중복 HorizontalPodAutoscaler 객체의 이름으로 바꿉니다.

워크로드 및 서비스 오류 문제 해결

다음 섹션에서는 HorizontalPodAutoscaler 객체 자체가 아닌 대상 워크로드 또는 관련 서비스로 인해 발생하는 오류를 설명합니다.

확장 계산을 위한 리소스 요청 누락

증상

ScalingActive 조건은 False이고 Reason은 FailedGetResourceMetric입니다. 일반적으로 다음과 유사한 메시지도 표시됩니다.

the HorizontalPodAutoscaler was unable to compute the replica count

원인

HorizontalPodAutoscaler는 워크로드를 확장하기 위해 리소스 사용률을 백분율로 계산해야 하지만 포드 사양 내 하나 이상의 컨테이너에 해당 리소스(cpu 또는 memory)에 대한 resources.requests 정의가 누락되어 이 계산을 수행할 수 없습니다.

해결 방법

이 문제를 해결하려면 배포, StatefulSet 또는 기타 컨트롤러 내에서 포드 매니페스트를 업데이트하여 HorizontalPodAutoscaler가 포드의 모든 컨테이너에 대해 확장하려는 리소스(cpu 또는 memory)의 resources.requests 필드를 포함합니다. 예를 들면 다음과 같습니다.

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
# Multiple lines are omitted here
spec:
  containers:
  - name: example-container
    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"

포드 측정항목을 가져올 수 없음

증상

다음과 유사한 영구 메시지가 표시됩니다.

unable to fetch pod metrics for pod

일반적으로 측정항목 서버가 시작될 때 이 메시지가 일시적으로 표시됩니다.

원인

리소스 사용률 백분율(예: cpu 또는 memory)을 기준으로 확장하려면 HorizontalPodAutoscaler 객체에서 타겟팅하는 포드 내의 모든 컨테이너에 해당 특정 리소스에 대해 정의된 resources.requests 필드가 있어야 합니다. 그렇지 않으면 HorizontalPodAutoscaler는 필요한 계산을 수행할 수 없으며 해당 측정항목과 관련된 작업을 수행하지 않습니다.

해결 방법

이러한 오류 메시지가 계속 표시되고 포드가 워크로드에 맞게 확장되지 않는 경우 워크로드의 각 컨테이너에 대한 리소스 요청을 지정했는지 확인하세요.

여러 서비스가 동일한 대상을 선택함

증상

다음과 같은 오류가 표시됩니다.

multiple services selecting the same target of HPA_NAME: SERVICE_NAME

이 출력에는 다음 값이 포함됩니다.

  • HPA_NAME: HorizontalPodAutoscaler의 이름입니다.
  • SERVICE_NAME: 서비스 이름입니다.

원인

트래픽 기반 자동 확장이 구성되었지만 둘 이상의 Kubernetes 서비스가 HorizontalPodAutoscaler의 scaleTargetRef 필드를 타겟팅합니다. 트래픽 기반 자동 확장은 서비스와 자동 확장된 워크로드 간의 일대일 관계만 지원합니다.

해결 방법

이 문제를 해결하려면 하나의 서비스 라벨 선택기만 워크로드의 포드와 일치하는지 확인합니다.

  1. 워크로드의 포드 라벨을 찾습니다.

    kubectl get deployment HPA_TARGET_DEPLOYMENT \
        -n NAMESPACE \
        -o jsonpath='{.spec.template.metadata.labels}'
    

    다음을 바꿉니다.

    • HPA_TARGET_DEPLOYMENT: HorizontalPodAutoscaler가 타겟팅하는 배포의 이름입니다.
    • NAMESPACE: 배포의 네임스페이스입니다.

    출력은 다음과 비슷합니다.

    {"app":"my-app", "env":"prod"}
    
  2. 네임스페이스에 있는 모든 서비스의 spec.selector 필드를 검토하여 해당 라벨과 일치하는 모든 서비스를 찾습니다.

    kubectl get services -n NAMESPACE -o yaml
    

    선택기가 이전 단계의 라벨과 일치하는 모든 서비스를 식별합니다. 예를 들어 {"app": "my-app"} 및 {"app": "my-app", "env": "prod"}는 모두 예시 포드 라벨과 일치합니다.

  3. 다음 옵션 중 하나를 선택하여 충돌을 해결합니다.

    • 새로운 고유 라벨을 배포의 spec.template.metadata.labels 필드에 추가하여 의도한 서비스의 선택기를 고유하게 만듭니다. 그런 다음 이 새 라벨을 포함하도록 의도된 하나의 서비스의 spec.selector 필드를 업데이트합니다.
    • 충돌하는 다른 모든 서비스의 spec.selector 필드를 변경하여 다른 서비스 선택기를 더 제한적으로 만듭니다. 이렇게 하면 더 제한적이며 더 이상 워크로드의 포드와 일치하지 않습니다.
  4. 변경사항을 적용합니다.

    kubectl apply -f MANIFEST_NAME
    

    MANIFEST_NAME을 업데이트된 서비스 또는 배포 매니페스트가 포함된 YAML 파일의 이름으로 바꿉니다.

Metrics API 및 데이터 가용성 문제 해결

다음 섹션은 HorizontalPodAutoscaler가 Metrics API와 통신하거나 측정항목 백엔드를 쿼리하려고 할 때 발생하는 오류를 해결하는 데 도움이 됩니다.

커스텀 및 외부 측정항목 문제 해결

HorizontalPodAutoscaler가 기본 CPU 또는 메모리 이외의 소스에서 가져온 측정항목을 사용하는 경우 커스텀 또는 외부 측정항목 파이프라인 내에서 문제가 발생할 수 있습니다. 이 파이프라인은 다음 다이어그램과 같이 HorizontalPodAutoscaler 컨트롤러, Kubernetes Metrics API 서버, 측정항목 어댑터, 측정항목 소스(예: Cloud Monitoring 또는 Prometheus)로 구성됩니다.

HPA 컨트롤러, Kubernetes API 서버, 측정항목 어댑터, 측정항목 소스 구성요소를 보여주는 HPA 측정항목 파이프라인

증상

측정항목 파이프라인에서 발생하는 문제의 가장 일반적인 증상은 다음과 같습니다.

  • 측정항목 값이 <unknown>로 표시됩니다.
  • HorizontalPodAutoscaler 이벤트에 FailedGetExternalMetric 또는 FailedGetCustomMetric과 같은 오류가 표시됩니다.

원인

커스텀 또는 외부 측정항목 파이프라인에 문제가 있습니다.

해결 방법

다음 단계를 사용하여 파이프라인을 디버깅합니다.

  1. 측정항목 어댑터가 등록되어 있고 사용 가능한지 확인: 측정항목 어댑터는 측정항목을 제공하기 위해 기본 Kubernetes API 서버에 등록해야 합니다. 이 작업은 어댑터가 실행 중이고 API 서버에서 연결할 수 있는지 확인하는 가장 직접적인 방법입니다.

    kubectl get apiservice | grep -E 'NAME|metrics.k8s.io'
    

    출력에서 v1beta1.custom.metrics.k8s.io 또는 v1beta1.external.metrics.k8s.io 항목과 Available 열의 True 값이 표시됩니다. 예를 들면 다음과 같습니다.

    NAME                   SERVICE                      AVAILABLE   AGE
    v1beta1.metrics.k8s.io kube-system/metrics-server   True        18d
    
    • Available 열의 값이 False이거나 누락된 경우 어댑터가 비정상 종료되었거나 잘못 구성되었을 수 있습니다. kube-system 또는 custom-metrics 네임스페이스에서 어댑터의 포드 로그를 확인하여 권한, 측정항목 소스에 대한 네트워크 연결 또는 측정항목을 찾을 수 없음을 나타내는 메시지와 관련된 오류를 확인합니다.

    • 값이 True이면 다음 단계로 진행합니다.

  2. Metrics API 직접 쿼리: 어댑터를 사용할 수 있는 경우 HorizontalPodAutoscaler를 우회하고 Kubernetes API에 측정항목을 직접 요청합니다. 이 명령어는 API 서버에서 측정항목 어댑터, 데이터 소스에 이르는 전체 파이프라인을 테스트합니다.

    외부 측정항목을 쿼리하려면 다음 명령어를 실행합니다.

    kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/NAMESPACE_NAME/METRIC_NAME" | jq .
    

    커스텀 포드 측정항목을 쿼리하려면 다음 명령어를 실행합니다.

    kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/namespaces/NAMESPACE_NAME/pods/*/METRIC_NAME" | jq .
    

    다음을 바꿉니다.

    • NAMESPACE_NAME: 포드가 실행 중인 네임스페이스입니다.
    • METRIC_NAME: 쿼리하려는 커스텀 또는 외부 측정항목의 이름입니다. 예를 들면 requests_per_second 또는 queue_depth입니다.
  3. 명령어 출력 분석: 이전 명령어의 결과는 문제가 있는 위치를 알려줍니다. 출력과 일치하는 시나리오를 선택합니다.

    • 값이 있는 성공적인 JSON 응답: 측정항목 파이프라인이 올바르게 작동합니다. 이 문제는 HorizontalPodAutoscaler 매니페스트의 구성 문제일 수 있습니다. 측정항목 이름에 맞춤법 오류가 있거나 matchLabels가 잘못되었는지 확인합니다.
    • Error: Error from server (Service Unavailable): 이 오류는 일반적으로 네트워크 연결 문제를 나타내며, 네트워크 격리를 사용하는 클러스터의 방화벽 문제인 경우가 많습니다.

      1. 측정항목 어댑터 서비스를 식별합니다. 일반적으로 custom-metrics 또는 kube-system 네임스페이스에 있습니다.

        kubectl get service -n custom-metrics,kube-system | grep -E 'adapter|metrics'
        
      2. 어댑터가 리슨하는 포트를 찾습니다.

        kubectl get service ADAPTER_SERVICE -n ADAPTER_NAMESPACE -o yaml
        

        다음을 바꿉니다.

        • ADAPTER_SERVICE: 배포한 측정항목 어댑터와 연결된 Kubernetes 서비스의 이름입니다. 이 서비스는 이전 단계에서 찾은 서비스입니다. 이 서비스는 Kubernetes API 서버를 포함하여 클러스터의 다른 부분에 어댑터의 기능을 노출합니다.
        • ADAPTER_NAMESPACE: 어댑터 서비스가 있는 네임스페이스(예: custom-metrics 또는 kube-system)
      3. 클러스터 컨트롤 플레인의 인바운드 방화벽 규칙을 찾습니다.

        gcloud compute firewall-rules list \
            --filter="name~gke-CLUSTER_NAME-[0-9a-z]*-master"
        

        CLUSTER_NAME을 클러스터 이름으로 바꿉니다.

      4. 어댑터의 targetPort를 규칙에 추가합니다.

        1. 현재 규칙을 설명하여 기존 허용 포트를 확인합니다.

          gcloud compute firewall-rules describe FIREWALL_RULE_NAME
          

          FIREWALL_RULE_NAME을 Kubernetes 클러스터의 컨트롤 플레인에 대한 네트워크 트래픽을 제어하는 방화벽 규칙의 이름으로 바꿉니다.

        2. 규칙을 업데이트하여 어댑터 포트를 목록에 추가합니다.

          gcloud compute firewall-rules update FIREWALL_RULE_NAME \
              --allow tcp:443,tcp:10250,tcp:ADAPTER_PORT
          

          ADAPTER_PORT를 측정항목 어댑터가 리슨하는 네트워크 포트로 바꿉니다.

      5. Kubernetes 네트워크 정책이 측정항목 어댑터 포드로의 트래픽을 차단하지 않는지 확인합니다.

        kubectl get networkpolicy -n custom-metrics,kube-system
        

        정책을 검토하여 컨트롤 플레인 또는 API 서버에서 ADAPTER_PORT의 ADAPTER_SERVICE로의 인그레스 트래픽을 허용하는지 확인합니다.

    • 빈 목록 []: 이 출력은 어댑터가 실행 중이지만 특정 측정항목을 가져올 수 없음을 의미하며, 어댑터 구성 또는 측정항목 소스 자체에 문제가 있음을 나타냅니다.

      • 어댑터 포드 문제: 측정항목 어댑터 포드의 로그에서 API 호출, 인증 또는 측정항목 가져오기와 관련된 오류를 검사합니다. 로그를 검사하려면 다음을 수행합니다.

        1. 어댑터 포드의 이름을 찾습니다.

          kubectl get pods -n ADAPTER_NAMESPACE
          
        2. 로그를 확인합니다.

          kubectl logs ADAPTER_POD_NAME \
              -n ADAPTER_NAMESPACE
          

          다음을 바꿉니다.

          • ADAPTER_POD_NAME: 이전 단계에서 식별한 어댑터 포드의 이름입니다.
          • ADAPTER_NAMESPACE: 어댑터 포드가 있는 네임스페이스(예: custom-metrics 또는 kube-system)
      • 소스에 데이터 없음: 소스 시스템에 측정항목이 없을 수 있습니다. 측정항목 탐색기와 같은 모니터링 도구를 사용하여 측정항목이 존재하고 올바른 이름과 라벨이 있는지 확인합니다.

측정항목 버전을 찾을 수 없거나 어댑터를 사용할 수 없음

증상

다음과 같은 오류가 표시됩니다.

unable to fetch metrics from custom metrics API: no known available metric versions found

원인

이 오류는 측정항목 소스(예: Cloud Monitoring)의 문제가 아니라 클러스터 내의 통신 장애를 나타냅니다. 일반적인 원인은 다음과 같습니다.

  • Kubernetes API 서버를 일시적으로 사용할 수 없습니다(예: 클러스터 업그레이드 또는 컨트롤 플레인 복구 중).
  • 측정항목 어댑터 포드(예: custom-metrics-stackdriver-adapter)가 비정상이거나 실행 중이 아니거나 API 서버에 올바르게 등록되지 않았습니다.

해결 방법

이 문제는 일시적인 경우가 많습니다. 문제가 지속되면 다음 해결 방법을 시도해 보세요.

  1. Kubernetes 컨트롤 플레인 상태 확인:

    1. Google Cloud 콘솔에서 클러스터의 상태를 확인합니다.

      1. Kubernetes 클러스터 페이지로 이동합니다.

        Kubernetes 클러스터로 이동

    2. 클러스터의 상태 및 알림 열을 확인합니다.

    3. 알림을 클릭하여 업그레이드 또는 수리와 같은 진행 중인 작업을 찾습니다. 이 시간 동안 API 서버를 일시적으로 사용하지 못할 수 있습니다.

    4. Cloud 감사 로그에서 컨트롤 플레인 구성요소와 관련된 오류를 검토합니다. 이러한 로그를 보는 방법은 GKE 감사 로깅 정보를 참조하세요.

  2. 측정항목 어댑터 포드의 상태 및 로그 확인: 측정항목 어댑터 포드가 Running 상태이고 최근에 다시 시작되지 않았는지 확인합니다.

    kubectl get pods -n custom-metrics,kube-system -o wide
    

    포드 상태가 Running 이외의 상태이거나 재시작 횟수가 많으면 포드를 조사하여 근본 원인을 찾습니다. 문제 해결 팁은 Kubernetes 문서의 포드 디버그를 참조하세요.

  3. Metrics API가 등록되어 있고 사용 가능한지 확인:

    kubectl get apiservice | grep metrics.k8s.io
    

    측정항목 API가 정상인 경우 출력은 다음과 비슷합니다.

    NAME                            SERVICE                                             AVAILABLE   AGE
    v1beta1.custom.metrics.k8s.io   custom-metrics/custom-metrics-stackdriver-adapter   True        18d
    v1beta1.external.metrics.k8s.io custom-metrics/custom-metrics-stackdriver-adapter   True        18d
    v1beta1.metrics.k8s.io          kube-system/metrics-server                          True        18d
    

    AVAILABLE 열의 값이 False이면 전체 APIService 매니페스트의 Message 열에서 자세한 내용을 확인할 수 있습니다.

    다음 명령어를 사용하여 전체 매니페스트를 볼 수 있습니다.

    kubectl get apiservice API_SERVICE_NAME -o yaml
    

    thought API_SERVICE_NAME을 APIService 객체의 이름(예: v1beta1.custom.metrics.k8s.io)으로 바꿉니다.

측정항목 쿼리가 시계열을 반환하지 않음

증상

다음과 같은 오류가 표시됩니다.

unable to fetch metrics from custom or external metrics API: googleapi: Error
400: The supplied filter [...] query will not return any time series

원인

Cloud Monitoring으로 전송된 쿼리가 유효하지만 데이터를 반환하지 않았습니다. 즉, 필터와 일치하는 데이터 포인트가 없습니다(값이 0인 측정항목을 찾는 것과는 다름). 이 문제의 가장 가능성 높은 이유는 커스텀 측정항목을 생성하는 애플리케이션 또는 워크로드가 오류가 보고된 시간 동안 Cloud Monitoring에 데이터를 쓰지 않았기 때문입니다.

해결 방법

다음 해결 방법을 시도해 보세요.

  1. 구성 확인: HorizontalPodAutoscaler 객체의 측정항목 이름과 라벨이 애플리케이션에서 내보내는 이름과 라벨과 정확히 일치하는지 확인합니다.
  2. 권한 확인: 애플리케이션이 Cloud Monitoring에 측정항목을 게시하는 데 필요한 권한과 API 엔드포인트로 올바르게 구성되었는지 확인합니다.
  3. 애플리케이션 활동 확인: HorizontalPodAutoscaler 경고가 발생한 기간 동안 측정항목을 담당하는 애플리케이션이 작동 중이었고 Cloud Monitoring에 데이터를 전송하려고 시도했는지 확인합니다.
  4. 오류 조사: 동일한 기간의 애플리케이션 로그에서 연결 실패, 잘못된 사용자 인증 정보, 형식 문제와 같은 측정항목 전송과 관련된 명시적인 오류가 있는지 확인합니다.

정상적이지만 예상치 못한 확장 동작 문제 해결

다음 섹션에서는 HorizontalPodAutoscaler 구성이 유효하고 측정항목을 사용할 수 있지만 확장 작업이 예상대로 수행되지 않는 시나리오를 설명합니다.

HorizontalPodAutoscaler가 정상 상태이지만 확장되지 않음

증상

HorizontalPodAutoscaler가 정상 상태로 표시되고, 조건이 True를 보고하며, 이벤트에 오류가 표시되지 않습니다. 하지만 여전히 확장 작업을 수행하지 않습니다.

원인

이러한 예상 동작은 다음과 같은 여러 요인으로 인해 발생할 수 있습니다.

  • 복제본 한도: 현재 복제본 수가 이미 HorizontalPodAutoscaler 구성의 minReplicas 또는 maxReplicas 필드에서 설정한 경계에 있습니다.
  • 허용 기간: Kubernetes는 기본 10% 허용 기간을 사용하여 사소한 측정항목 변동에 대한 확장을 방지합니다. 확장은 현재 측정항목과 타겟 측정항목의 비율이 0.9~1.1 범위를 벗어나는 경우에만 발생합니다. 예를 들어 목표가 CPU 85% 이고 현재 사용량이 93%인 경우 비율은 약 1.094(93/85≈1.094)입니다. 이 값은 1.1보다 작으므로 HorizontalPodAutoscaler가 수평 확장되지 않습니다.
  • 준비되지 않은 포드: HorizontalPodAutoscaler는 확장 계산에 Ready 상태의 포드만 포함합니다. Pending 상태로 멈춰 있거나 Ready 상태가 되지 않는 포드(상태 점검 실패 또는 리소스 문제로 인해)는 무시되며 확장을 방해할 수 있습니다.
  • 동기화 기간 지연: HorizontalPodAutoscaler 컨트롤러는 측정항목을 주기적으로 확인합니다. 측정항목이 기준점을 초과하는 시점과 확장 작업이 시작되는 시점 사이에 15~30초의 지연이 발생하는 것은 정상입니다.
  • 새 측정항목 지연 시간: HorizontalPodAutoscaler에서 새 커스텀 측정항목을 처음 사용하는 경우 몇 분의 일회성 지연 시간이 발생할 수 있습니다. 이 지연은 첫 번째 데이터 포인트가 작성될 때 모니터링 시스템(예: Cloud Monitoring)이 새 시계열을 만들어야 하기 때문에 발생합니다.
  • 여러 측정항목 계산: 여러 측정항목을 구성하면 HorizontalPodAutoscaler가 각 측정항목에 필요한 복제본 수를 독립적으로 계산한 다음 계산된 가장 높은 값을 최종 복제본 수로 선택합니다. 이 동작으로 인해 워크로드는 가장 높은 요구사항이 있는 측정항목의 요구사항을 충족하도록 확장됩니다. 예를 들어 CPU 측정항목에서 복제본 9개가 필요하다고 계산하지만 초당 요청 수 측정항목에서 15개가 필요하다고 계산하는 경우 HorizontalPodAutoscaler는 배포를 복제본 15개로 확장합니다.

해결 방법

다음 해결 방법을 시도해 보세요.

  • 복제본 한도: HorizontalPodAutoscaler 매니페스트 또는 kubectl describe 명령어 출력에서 minReplicas 및 maxReplicas 값을 확인합니다. 필요한 확장이 제한되는 경우 이 한도를 조정합니다.
  • 허용 한도 기간: 기본 허용 한도 내에서 확장이 필요한 경우 다른 허용 한도 값을 구성합니다. 그렇지 않으면 측정항목이 0.9~1.1 비율을 벗어날 때까지 기다립니다.
  • 준비되지 않은 포드: 포드가 Pending 또는 Ready 상태가 아닌 이유를 조사하고 근본적인 문제(예: 리소스 제약 조건, 준비 프로브 실패)를 해결합니다. 문제 해결 팁은 Kubernetes 문서의 포드 디버그를 참조하세요.
  • 동기화 기간 지연 및 새 측정항목 지연 시간: 이러한 지연 시간은 정상입니다. 동기화 기간이 완료되거나 새 커스텀 측정항목 시계열이 생성될 때까지 기다립니다.
  • 여러 측정항목 계산: 의도된 동작입니다. 하나의 측정항목(예: 초당 요청 수)을 기준으로 수직 확장이 발생하는 경우 다른 측정항목의 낮은 계산(예: CPU)을 올바르게 재정의합니다.

HorizontalPodAutoscaler가 축소되지 않음

증상

HorizontalPodAutoscaler가 워크로드를 수직 확장하는 데 성공하지만 CPU 사용률과 같은 측정항목이 낮더라도 다시 축소하지 못합니다.

원인

이 동작은 불완전한 정보를 기반으로 빠르게 수직 확장 및 축소하거나 축소하는 것을 방지하도록 설계되었습니다. 주요 이유는 다음과 같습니다.

  • 여러 측정항목 사용: HorizontalPodAutoscaler는 가장 많은 복제본이 필요한 측정항목을 기준으로 확장됩니다. 측정항목이 여러 개 있는 경우 모든 측정항목에서 더 적은 복제본이 필요하다고 표시하지 않는 한 워크로드가 축소되지 않습니다. 높은 복제본 수를 요구하는 측정항목 하나가 있으면 다른 측정항목이 낮더라도 축소가 방지됩니다.
  • 사용할 수 없는 측정항목: 측정항목을 사용할 수 없게 되면(종종 <unknown>로 표시됨) HorizontalPodAutoscaler는 워크로드 축소를 보수적으로 거부합니다. 사용량이 실제로 0이거나 측정항목 파이프라인이 손상되어 측정항목이 누락되었는지 확인할 수 없습니다. 이 문제는 비율 기반 커스텀 측정항목(예: messages_per_second)에서 흔히 발생하며, 활동이 없을 때 보고 데이터 보고를 중지하여 HorizontalPodAutoscaler가 측정항목을 사용할 수 없는 것으로 간주하고 축소 작업을 중지할 수 있습니다.
  • 확장 정책의 축소 지연: HorizontalPodAutoscaler의 behavior 필드를 사용하면 확장 정책을 구성할 수 있습니다. 축소의 기본 정책에는 300초(5분)의 안정화 기간이 포함됩니다. 이 기간 동안에는 측정항목 값이 목표 기준점 미만으로 떨어지더라도 HorizontalPodAutoscaler가 복제본 수를 줄이지 않습니다. 이 기간은 급격한 변동을 방지하지만 축소 속도가 예상보다 느려질 수 있습니다.

해결 방법

다음 해결 방법을 시도해 보세요.

  1. 여러 측정항목과 사용할 수 없는 측정항목의 경우 문제를 일으키는 측정항목을 진단합니다.

    kubectl describe hpa HPA_NAME -n NAMESPACE_NAME
    

    출력의 Metrics 섹션에서 상태가 <unknown>인 측정항목을 찾고 Events 섹션에서 FailedGetCustomMetric 또는 FailedGetExternalMetric와 같은 경고를 찾습니다. 자세한 파이프라인 디버깅은 커스텀 및 외부 측정항목 문제 해결 섹션을 참조하세요.

  2. 사용할 수 없는 측정항목의 경우 트래픽이 적은 기간 동안 측정항목을 사용할 수 없게 되면(비율 기반 측정항목에서 일반적임) 다음 해결 방법 중 하나를 시도해 보세요.

    • 가능하면 비율 기반 측정항목 대신 게이지 기반 측정항목을 사용합니다. 큐의 총 메시지 수(예: subscription 또는 num_undelivered_messages)와 같은 게이지 측정항목은 값이 0인 경우에도 일관되게 값을 보고하므로 HorizontalPodAutoscaler가 안정적으로 확장 결정을 내릴 수 있습니다.
    • 측정항목 소스가 0 값을 보고하는지 확인합니다. 커스텀 측정항목을 제어하는 경우 데이터를 전혀 전송하지 않는 대신 비활성 기간 동안 0를 게시하도록 구성합니다.
  3. 확장 정책으로 인한 축소 지연의 경우 기본 5분 축소 안정화 기간이 너무 길면 맞춤설정합니다. HorizontalPodAutoscaler 매니페스트의 spec.behavior.scaleDown 섹션을 검사합니다. stabilizationWindowSeconds을 낮추면 측정항목이 감소한 후 자동 확장 처리가 더 빠르게 축소됩니다. 이러한 정책을 구성하는 방법에 대한 자세한 내용은 Kubernetes 문서의 확장 정책을 참조하세요.

HPA를 사용하여 GKE 워크로드를 0으로 축소하고 0에서 확장하는 문제 해결

이 섹션은 GKE 1.37 이상에서 HPA를 사용하여 0으로 축소하고 0에서 확장(minReplicas: 0)하도록 워크로드를 구성할 때 발생하는 문제를 진단하는 데 도움이 됩니다.

워크로드가 0으로 축소되지 않음

수요가 0으로 떨어질 때 워크로드가 하나 이상의 복제본에 남아 있는 경우 다음을 확인하세요.

  1. minReplicas 확인: HorizontalPodAutoscaler 매니페스트에 minReplicas: 0 필드 값 쌍이 설정되어 있는지 확인합니다.
  2. 측정항목 유형 확인: HPA는 CPU 또는 메모리(Resource) 측정항목만 사용하는 경우 0으로 확장할 수 없습니다. External 또는 Object 측정항목을 하나 이상 구성해야 합니다.
  3. 여러 측정항목 확인: HPA는 가장 많은 복제본 수가 필요한 측정항목을 기준으로 확장됩니다. 여러 측정항목을 구성하는 경우 모니터링되는 모든 측정항목이 0으로 평가되지 않으면 워크로드가 0으로 확장되지 않습니다.
  4. 축소 안정화 기간 대기: 기본적으로 GKE는 복제본을 1개에서 0개로 축소하기 전에 5분(scaleDown.stabilizationWindowSeconds: 300) 동안 수요가 지속적으로 0이 될 때까지 기다립니다.
  5. 사용할 수 없는 측정항목 확인: 측정항목 값이 <unknown>로 표시되면 HPA는 조기 축소를 방지하기 위해 축소 작업을 일시중지합니다. 자세한 내용은 수평형 포드 자동 확장 처리가 축소되지 않는 문제 해결을 참조하세요.

워크로드가 0에서 확장되지 않음

수요가 증가할 때 워크로드가 복제본 0개로 유지되는 경우 다음을 확인하세요.

  1. HorizontalPodAutoscaler 검사: kubectl describe hpa HPA_NAME 명령어를 실행하고 출력에서 다음 섹션을 확인합니다.

    • 측정항목 섹션: 측정항목 값이 0보다 크고 값이 <unknown>로 표시되지 않는지 확인합니다. 측정항목이 누락되었거나 업데이트되지 않는 경우 외부 소스(예: Pub/Sub)가 이벤트를 게시하고 있고 Cloud Monitoring이 이를 수신하고 있는지 확인합니다.
    • 조건 섹션:
      • 정상적인 복제본 0개 상태: 조건에 AbleToScale: True, ScalingActive: True, ScaledToZero: True(이유: ScaledToZero)가 표시되는지 확인합니다. 이 상태에서 GKE는 수요가 증가하면 워크로드를 자동으로 확장합니다.
      • 외부 재정의 감지됨: ScalingActive 조건의 값이 ScalingDisabledExternalScaleToZero 이유 또는 ScalingDisabledReplicaCountZero 이유와 함께 False인지 확인합니다. 이는 워크로드가 수동으로 0으로 확장되었음을 나타냅니다. 예를 들어 워크로드가 kubectl scale 명령어로 수동 확장되어 변경사항 충돌을 방지하기 위해 자동 확장이 일시중지되었습니다.
    • 해결 방법: 자동 확장을 재개하려면 배포를 하나 이상의 복제본으로 수동으로 다시 확장합니다.

      kubectl scale deployment DEPLOYMENT_NAME --replicas=1
      
  2. 콜드 스타트 지연 시간 확인: 워크로드가 느리게 시작되면 노드 프로비저닝으로 인해 지연이 발생할 수 있습니다. 0에서 확장할 때 대기 컴퓨팅 용량을 준비하려면 용량 버퍼를 사용하는 것이 좋습니다.

다음 단계

  • 문서에서 문제 해결 방법을 찾을 수 없으면 지원 받기를 참조하여 다음 주제에 대한 조언을 포함한 추가 도움을 요청하세요.