Google Kubernetes Engine (GKE)에서 수평형 포드 자동 확장이 예상대로 작동하지 않으면 워크로드가 올바르게 확장되지 않을 수 있습니다. 이 문제로 인해 애플리케이션이 부하를 처리하지 못하여 성능 문제나 서비스 중단이 발생할 수 있습니다. CPU가 높음에도 포드가 증가하지 않거나, HorizontalPodAutoscaler 상태에 측정항목 값이 <unknown>
로 표시되거나, 확장 작업이 전혀 발생하지 않을 수 있습니다.
이 페이지를 사용하여 HorizontalPodAutoscaler 객체의 초기 잘못된 구성부터 측정항목 파이프라인 내의 더 복잡한 오류에 이르기까지 수평형 포드 자동 확장과 관련된 일반적인 문제를 진단하고 해결하세요. 이 문제 해결 단계를 따르면 수요에 따라 애플리케이션이 효율적이고 안정적으로 확장되어 수평형 포드 자동 확장 처리 리소스를 효과적으로 사용할 수 있습니다.
이 정보는 HorizontalPodAutoscaler 객체를 구성하고 애플리케이션이 올바르게 확장되도록 해야 하는 애플리케이션 개발자에게 중요합니다. 또한 플랫폼 관리자와 운영자가 자동 확장된 모든 워크로드에 영향을 미치는 측정항목 파이프라인 또는 클러스터 구성 문제를 해결하는 데도 도움이 됩니다. Google Cloud 콘텐츠에서 참조하는 일반적인 역할과 예시 태스크에 대한 자세한 내용은 일반 GKE 사용자 역할 및 태스크를 참고하세요.
이미 증상이 나타났거나 오류 메시지가 표시된 경우 다음 표를 사용하여 적절한 안내를 확인하세요.
증상 | 가능한 해결 방법 |
---|---|
확장되지 않지만 HorizontalPodAutoscaler 조건이 True 입니다. |
정상이지만 응답하지 않는 HorizontalPodAutoscaler 문제 해결 |
HorizontalPodAutoscaler 이벤트에 특정 오류 메시지가 표시됨 | 일반적인 수평형 포드 자동 확장 처리 오류 문제 해결 |
측정항목 <unknown> |
맞춤 및 외부 측정항목 문제 해결하기 |
축소되지 않음 | 수평형 포드 자동 확장 처리가 축소되지 않는 문제 해결 |
시작하기 전에
- 배포 및 StatefulSet과 같이 확장 가능한 워크로드와 함께 HorizontalPodAutoscaler 객체를 사용해야 합니다. DaemonSets와 같이 확장할 수 없는 워크로드에는 수평형 포드 자동 확장을 사용할 수 없습니다.
-
HorizontalPodAutoscaler 객체를 검사하고 클러스터 로그를 보는 등 GKE에서 수평 Pod 자동 확장 문제를 해결하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
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 설명
HorizontalPodAutoscaler의 실시간 계산 및 최근 확장 결정 사항을 확인하려면 kubectl describe hpa
명령어를 사용하세요. 이 명령어는 HorizontalPodAutoscaler 객체의 요약과 문제 진단에 유용한 Events
로그를 제공합니다.
kubectl describe hpa HPA_NAME -n NAMESPACE_NAME
다음을 바꿉니다.
HPA_NAME
: HorizontalPodAutoscaler 객체의 이름입니다.NAMESPACE_NAME
: HorizontalPodAutoscaler 객체의 네임스페이스입니다.
출력은 다음과 비슷합니다.
Name: php-apache-hpa
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
: 이 섹션에는 현재 측정항목 값이 타겟과 비교되어 표시됩니다. 여기에서 HorizontalPodAutoscaler가 데이터를 수신하는지 확인합니다.<unknown>
측정항목 값은 HorizontalPodAutoscaler가 측정항목을 가져오지 않았거나 측정항목 파이프라인이 중단되었음을 나타냅니다.Conditions
: 이 상위 수준 상태 확인은 HorizontalPodAutoscaler가 측정항목 (AbleToScale
)을 가져오고 확장 계산 (ScalingActive
)을 실행할 수 있는지를 보여줍니다. 이러한 조건 중 하나에서False
상태는 실패를 나타냅니다.Events
: 이 섹션에는 HorizontalPodAutoscaler 컨트롤러의 최근 확장 작업, 경고, 오류가 기록됩니다. 이러한 로그는 문제의 원인을 파악하는 데 도움이 되는FailedGetScale
또는FailedGetResourceMetric
와 같은 특정 오류 메시지나 이유를 확인할 수 있는 첫 번째 위치인 경우가 많습니다.
배포에서 HorizontalPodAutoscaler 상태 확인
배포에 사용되는 HorizontalPodAutoscaler 객체의 상태를 확인하려면 Google Cloud 콘솔을 사용하세요.
Google Cloud 콘솔에서 워크로드 페이지로 이동합니다.
배포 이름을 클릭합니다.
세부정보 탭으로 이동하여 자동 확장 섹션을 찾습니다.
상태 행의 값을 검토합니다.
- 녹색 체크표시는 HorizontalPodAutoscaler가 구성되어 있고 측정항목을 읽을 수 있음을 의미합니다.
- 주황색 삼각형은 HorizontalPodAutoscaler가 구성되었지만 측정항목을 읽는 데 문제가 있음을 의미합니다. 이는 커스텀 측정항목 또는 외부 측정항목에서 흔히 발생하는 문제입니다. 이 문제를 해결하려면 측정항목을 사용할 수 없는 이유를 진단하세요. 자세한 내용은 맞춤 측정항목 및 외부 측정항목 문제 해결 섹션을 참고하세요.
StatefulSet과 같은 다른 워크로드 유형의 경우 또는 자세한 내용을 확인하려면 HorizontalPodAutoscaler 객체의 매니페스트를 확인하세요.
HorizontalPodAutoscaler의 매니페스트 확인
HorizontalPodAutoscaler 객체의 YAML 매니페스트를 사용하면 구성 및 현재 상태에 관한 정보를 볼 수 있습니다.
YAML 매니페스트를 보려면 다음 옵션 중 하나를 선택합니다.
콘솔
Google Cloud 콘솔에서 객체 브라우저 페이지로 이동합니다.
객체 종류 목록에서 HorizontalPodAutoscaler 체크박스를 선택하고 확인을 클릭합니다.
autoscaling API 그룹으로 이동한 다음 HorizontalPodAutoscaler의 확장 프로그램 화살표를 클릭합니다.
검사할 HorizontalPodAutoscaler 객체의 이름을 클릭합니다.
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에서 수평형 포드 자동 확장 처리 이벤트 보기: 로그 필터를 사용하여 특정 클러스터의 모든 수평형 포드 자동 확장 처리 이벤트를 찾습니다. 예를 들면 다음과 같습니다.
Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.
쿼리 창에 다음 쿼리를 입력합니다.
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입니다.
쿼리 실행을 클릭하고 출력을 검토합니다.
수평형 포드 자동 확장 처리 이벤트 보기: 이러한 로그는 HorizontalPodAutoscaler가 추천을 계산하는 방법을 설명하는 구조화된 사람이 읽을 수 있는 로그를 제공하여 의사결정 프로세스에 대한 자세한 통계를 제공합니다.
정상이지만 응답하지 않는 HorizontalPodAutoscaler 문제 해결
이 섹션에서는 HorizontalPodAutoscaler가 정상적으로 표시되고 상태 또는 이벤트에 오류가 보고되지 않는데도 확장 작업을 트리거하지 않는 이유를 진단하는 데 도움이 됩니다.
증상:
HorizontalPodAutoscaler가 정상으로 표시되고, 조건에 True
가 보고되며, 이벤트에 오류가 표시되지 않습니다. 하지만 여전히 확장 작업을 수행하지는 않습니다.
원인:
다음과 같은 여러 요인으로 인해 예상된 동작이 발생할 수 있습니다.
- 복제본 한도: 현재 복제본 수가 HorizontalPodAutoscaler 구성의
minReplicas
또는maxReplicas
필드에 설정된 경계에 도달했습니다. - 허용 범위: Kubernetes는 사소한 측정항목 변동에 따른 확장을 방지하기 위해 기본 10% 허용 범위를 사용합니다. 현재 측정항목과 타겟 측정항목의 비율이 0.9~1.1 범위를 벗어나는 경우에만 확장됩니다. 예를 들어 타겟이 CPU 85% 이고 현재 사용량이 93%인 경우 비율은 약 1.094 (93/85≈1.094)입니다. 이 값이 1.1보다 작으므로 수평형 포드 자동 확장 처리가 확장되지 않습니다.
- 준비되지 않은 포드: 수평형 포드 자동 확장 처리에는
Ready
상태의 포드만 확장 계산에 포함됩니다.Pending
상태로 멈춰 있거나 상태 점검 실패 또는 리소스 문제로 인해Ready
이 되지 않는 포드는 무시되며 확장을 방해할 수 있습니다. - 동기화 기간 지연: HorizontalPodAutoscaler 컨트롤러가 주기적으로 측정항목을 확인합니다. 측정항목이 기준점을 초과한 후 확장 작업이 시작되기까지 15~30초의 지연이 발생하는 것은 정상입니다.
- 새 측정항목 지연 시간: HorizontalPodAutoscaler가 새 맞춤 측정항목을 처음 사용하는 경우 몇 분의 일회성 지연 시간이 발생할 수 있습니다. 이 지연은 모니터링 시스템 (예: Cloud Monitoring)이 첫 번째 데이터 포인트가 작성될 때 새 시계열을 만들어야 하기 때문에 발생합니다.
- 다중 측정항목 계산: 여러 측정항목을 구성하면 수평형 포드 자동 확장 처리가 각 측정항목에 필요한 복제본 수를 독립적으로 계산한 다음 계산된 값 중 가장 높은 값을 최종 복제본 수로 선택합니다. 이러한 동작으로 인해 워크로드는 요구사항이 가장 높은 측정항목의 요구사항을 충족하도록 확장됩니다. 예를 들어 CPU 측정항목에서 복제본 9개가 필요하다고 계산했지만 초당 요청 수 측정항목에서 15개가 필요하다고 계산한 경우 수평형 포드 자동 확장 처리는 배포를 복제본 15개로 확장합니다.
해결 방법:
다음 해결 방법을 시도해 보세요.
- 복제본 한도: HorizontalPodAutoscaler 매니페스트 또는
kubectl describe
명령어의 출력에서minReplicas
및maxReplicas
값을 확인합니다. 필요한 확장 방해 시 이러한 한도를 조정합니다. - 허용 범위: 기본 허용 범위 내에서 조정이 필요한 경우 다른 허용 범위 값을 구성합니다. 그렇지 않으면 측정항목이 0.9~1.1 비율을 벗어날 때까지 기다립니다.
- 준비되지 않은 포드: 포드가
Pending
이거나Ready
이 아닌 이유를 조사하고 기본 문제를 해결합니다 (예: 리소스 제약 조건, 준비 상태 프로브 실패). 문제 해결 팁은 Kubernetes 문서의 포드 디버그를 참고하세요. - 동기화 기간 지연 및 새 측정항목 지연 시간: 이러한 지연 시간은 정상입니다. 동기화 기간이 완료되거나 새 맞춤 측정항목 시계열이 생성될 때까지 기다립니다.
- 여러 측정항목 계산: 이는 의도된 동작입니다. 초당 요청 수와 같은 하나의 측정항목을 기반으로 스케일업이 발생하는 경우 CPU와 같은 다른 측정항목의 낮은 계산을 올바르게 재정의합니다.
일반적인 수평형 포드 자동 확장 처리 오류 문제 해결
다음 섹션에서는 HorizontalPodAutoscaler의 상태를 검사할 때 발생할 수 있는 특정 오류 메시지 및 이벤트 이유에 대한 해결 방법을 제공합니다. 일반적으로 이러한 메시지는 kubectl describe hpa
명령어의 출력에 있는 Events
섹션에서 확인할 수 있습니다.
수평형 포드 자동 확장 처리 구성 오류 문제 해결
잘못된 필드 입력이나 충돌하는 구성과 같은 HorizontalPodAutoscaler 매니페스트의 잘못된 구성으로 인해 이 섹션에 오류가 발생합니다.
오류: 잘못된 측정항목
HorizontalPodAutoscaler 내의 측정항목 구성이 구문상 잘못되었거나 일관되지 않으면 이 오류가 표시될 수 있습니다.
증상:
구성 문제로 인해 HorizontalPodAutoscaler가 필요한 복제본을 계산할 수 없는 경우 Events
섹션에 FailedComputeMetricsReplicas
이유가 표시되고 다음과 비슷한 메시지가 표시됩니다.
invalid metrics (1 invalid out of 1)
원인:
이 오류는 일반적으로 HorizontalPodAutoscaler 매니페스트에 정의한 측정항목 type
와 target
간에 불일치가 있음을 의미합니다. 예를 들어 Utilization
의 type
을 지정했지만 averageUtilization
대신 averageValue
의 타겟 값을 제공했을 수 있습니다.
해결 방법:
target
필드의 값이 측정항목 type
와 일치하도록 HorizontalPodAutoscaler 매니페스트를 수정합니다.
type
이Utilization
이면target
필드의 값은averageUtilization
이어야 합니다.type
이AverageValue
이면target
필드의 값은averageValue
이어야 합니다.
오류: 동일한 타겟을 선택하는 서비스가 여러 개 있음
HorizontalPodAutoscaler의 서비스 구성이 잘못된 트래픽 기반 자동 확장을 사용하는 경우 이 오류가 표시될 수 있습니다.
증상:
다음 오류가 표시됩니다.
multiple services selecting the same target of HPA_NAME: SERVICE_NAME
이 출력에는 다음 값이 포함됩니다.
HPA_NAME
: HorizontalPodAutoscaler의 이름입니다.SERVICE_NAME
: 서비스 이름입니다.
원인:
트래픽 기반 자동 확장이 구성되었지만 둘 이상의 Kubernetes 서비스가 HorizontalPodAutoscaler의 scaleTargetRef
필드를 타겟팅하고 있습니다. 트래픽 기반 자동 확장은 서비스와 자동 확장된 워크로드 간의 일대일 관계만 지원합니다.
해결 방법:
이 문제를 해결하려면 하나의 서비스 라벨 선택기만 워크로드의 포드와 일치하는지 확인하세요.
워크로드의 포드 라벨을 찾습니다.
kubectl get deployment HPA_TARGET_DEPLOYMENT \ -n NAMESPACE \ -o jsonpath='{.spec.template.metadata.labels}'
다음을 바꿉니다.
HPA_TARGET_DEPLOYMENT
: HorizontalPodAutoscaler가 타겟팅하는 배포의 이름입니다.NAMESPACE
: 배포의 네임스페이스입니다.
출력은 다음과 비슷합니다.
{"app":"my-app", "env":"prod"}
네임스페이스의 모든 서비스에 대해
spec.selector
필드를 검토하여 이러한 라벨과 일치하는 모든 서비스를 찾습니다.kubectl get services -n NAMESPACE -o yaml
선택기가 이전 단계의 라벨과 일치하는 모든 서비스를 식별합니다. 예를 들어
{"app": "my-app"}
및{"app": "my-app", "env": "prod"}
모두 예시 포드 라벨과 일치합니다.다음 옵션 중 하나를 선택하여 충돌을 해결합니다.
- Deployment의
spec.template.metadata.labels
필드에 고유한 새 라벨을 추가하여 원하는 서비스의 선택자를 고유하게 만듭니다. 그런 다음 의도한 하나의 서비스spec.selector
필드를 업데이트하여 이 새 라벨을 포함합니다. - 충돌하는 모든 기타 서비스의
spec.selector
필드를 변경하여 다른 서비스 선택기를 더 제한적으로 만들어 워크로드의 포드와 더 이상 일치하지 않도록 합니다.
- Deployment의
변경사항을 적용합니다.
kubectl apply -f MANIFEST_NAME
MANIFEST_NAME
을 업데이트된 서비스 또는 배포 매니페스트가 포함된 YAML 파일의 이름으로 바꿉니다.
오류: 라벨이 허용되지 않음
증상:
다음 오류가 표시됩니다.
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에서 측정항목에 이 키를 인식하거나 허용하지 않습니다.
해결 방법:
이 문제를 해결하려면 다음 단계를 따르세요.
- 오류 메시지에서 허용되지 않는 라벨 이름을 확인합니다.
- HorizontalPodAutoscaler 매니페스트의
metric.selector.matchLabels
섹션에서 이 라벨 키를 삭제하거나 수정하세요. - 해당 측정항목에 대한 Cloud Monitoring 문서를 참고하여 필터링 가능한 유효한 라벨 키를 찾습니다.
문제: 동일한 워크로드를 타겟팅하는 여러 HorizontalPodAutoscaler
동일한 워크로드를 관리하도록 여러 HorizontalPodAutoscaler 객체를 구성하면 충돌이 발생하고 예측할 수 없는 확장 동작이 발생합니다.
증상:
HorizontalPodAutoscaler의 상태에는 이 충돌을 직접 나타내는 특정 Condition
또는 Reason
이 없습니다. 대신 다음과 같은 증상이 나타날 수 있습니다.
- 워크로드의 복제본 수가 예기치 않게 변동될 수 있습니다.
- 확장 결정이 단일 HorizontalPodAutoscaler에 정의된 측정항목과 일치하지 않는 것처럼 보일 수 있습니다.
- 이벤트를 볼 때 서로 다른 HorizontalPodAutoscaler 객체에서 번갈아 가거나 모순되는
SuccessfulRescale
이벤트가 표시될 수 있습니다.
원인:
이 문제는 동일한 네임스페이스 내의 두 개 이상의 HorizontalPodAutoscaler 객체가 spec.scaleTargetRef
필드에 정확히 동일한 워크로드를 지정하기 때문에 발생합니다. 각 HorizontalPodAutoscaler는 복제본 수를 독립적으로 계산하고 자체 측정항목 및 타겟을 기반으로 워크로드를 확장하려고 시도합니다. Kubernetes는 이 구성을 차단하지 않지만 HorizontalPodAutoscaler가 서로 경쟁하므로 불안정한 확장 조정이 발생합니다.
해결 방법:
충돌을 방지하려면 단일 HorizontalPodAutoscaler 객체에 모든 확장 측정항목을 정의하세요. 각 HorizontalPodAutoscaler는 자체 spec.metrics
필드에서 확장 요구사항을 계산하므로 이를 병합하면 선택한 HorizontalPodAutoscaler 객체가 CPU 및 초당 요청 수와 같은 모든 요소를 함께 고려할 수 있습니다.
동일한 워크로드를 타겟팅하는 HorizontalPodAutoscaler를 식별하려면 각 HorizontalPodAutoscaler 객체의 YAML 매니페스트를 가져옵니다. 출력의
spec.scaleTargetRef
필드에 주의하세요.kubectl get hpa -n NAMESPACE_NAME -o yaml
NAMESPACE_NAME
을 HorizontalPodAutoscaler 객체의 네임스페이스로 바꿉니다.scaleTargetRef
필드 내에서 서로 다른 HorizontalPodAutoscaler 리소스의apiVersion
,kind
,name
값이 동일한 인스턴스를 찾습니다.측정항목을 단일 HorizontalPodAutoscaler 객체로 통합합니다.
- 유지할 HorizontalPodAutoscaler 객체를 하나 선택합니다. 이 HorizontalPodAutoscaler를 수정합니다.
- 동일한 워크로드를 타겟팅하는 다른 HorizontalPodAutoscaler 객체의 매니페스트에서
spec.metrics
섹션을 검사합니다. - 중복된 HorizontalPodAutoscaler 객체의
spec.metrics
섹션에서 유지할 측정항목 정의를 복사합니다. - 복사한 측정항목 정의를 유지하기로 결정한 HorizontalPodAutoscaler의
spec.metrics
배열에 붙여넣습니다.
변경사항을 적용합니다.
kubectl apply -f MANIFEST_NAME
MANIFEST_NAME
을 유지하기로 결정한 HorizontalPodAutoscaler 매니페스트의 이름으로 바꿉니다.동일한 워크로드를 타겟팅하는 다른 HorizontalPodAutoscaler 객체를 삭제합니다.
kubectl delete hpa DUPLICATE_MANIFEST_NAME -n NAMESPACE_NAME
DUPLICATE_MANIFEST_NAME
을 삭제하려는 중복 HorizontalPodAutoscaler 객체의 이름으로 바꿉니다.
워크로드 및 타겟 오류 문제 해결
이 섹션의 오류는 HorizontalPodAutoscaler 객체 자체가 아닌 배포, StatefulSet 또는 포드가 확장되어 발생합니다.
오류: 타겟의 현재 크기를 가져올 수 없음
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
필드의 문제로 인해 발생합니다. 지정된 리소스가 존재하지 않거나, 삭제되었거나, 철자 오류가 있을 수 있습니다.
해결 방법:
다음 해결 방법을 시도해 보세요.
- HorizontalPodAutoscaler의 매니페스트에서
scaleTargetRef
필드 확인:scaleTargetRef
필드의name
,kind
,apiVersion
값이 타겟 워크로드의 해당 메타데이터와 정확히 일치하는지 확인합니다. 워크로드 이름이 잘못된 경우 HorizontalPodAutoscaler의scaleTargetRef
필드를 업데이트하여 올바른 이름을 가리키도록 합니다. - 워크로드가 있는지 확인: 대상 워크로드가 HorizontalPodAutoscaler와 동일한 네임스페이스에 있는지 확인합니다.
kubectl get deployment DEPLOYMENT_NAME
와 같은 명령어를 사용하여 이를 확인할 수 있습니다. 워크로드를 의도적으로 삭제한 경우 해당 HorizontalPodAutoscaler 객체를 삭제하여 클러스터를 정리합니다. 워크로드를 다시 만들어야 하는 경우 HorizontalPodAutoscaler는 워크로드가 사용 가능해지면 자동으로 이를 찾아 오류가 해결됩니다. - HorizontalPodAutoscaler와 워크로드가 동일한 네임스페이스에 있는지 확인: HorizontalPodAutoscaler와 대상 워크로드가 동일한 네임스페이스에 있어야 합니다.
kubectl
명령어로 객체를 만들 때 네임스페이스를 지정하지 않으면 Kubernetes가 객체를default
네임스페이스에 배치합니다. 이 동작은 HorizontalPodAutoscaler가default
네임스페이스에 있고 워크로드가 다른 네임스페이스에 있는 경우 또는 그 반대의 경우 불일치를 일으킬 수 있습니다. 두 객체의 네임스페이스를 확인하고 일치하는지 확인합니다.
HorizontalPodAutoscaler가 타겟을 성공적으로 찾으면 AbleToScale
조건이 True
로 바뀌고 메시지가 the
HorizontalPodAutoscaler controller was able to get the target's current scale
로 변경됩니다.
오류: 복제본 수를 계산할 수 없음
수평형 포드 자동 확장 처리에서 리소스 사용률을 기반으로 확장을 계산해야 하지만 포드에서 필요한 기준 정보가 부족한 경우 이 오류가 표시될 수 있습니다.
증상:
ScalingActive
조건은 FailedGetResourceMetric
의 Reason
를 사용하는 False
입니다. 일반적으로 다음과 유사한 메시지도 표시됩니다.
the HorizontalPodAutoscaler was unable to compute the replica count
원인:
수평형 포드 자동 확장 처리는 워크로드를 확장하기 위해 리소스 사용률을 백분율로 계산해야 하지만 포드 사양 내에 있는 하나 이상의 컨테이너에 해당 리소스 (cpu
또는 memory
)에 대한 resources.requests
정의가 누락되어 이 계산을 수행할 수 없습니다.
해결 방법:
이 문제를 해결하려면 HorizontalPodAutoscaler가 포드의 모든 컨테이너에서 확장하려고 하는 리소스 (cpu
또는 memory
)의 resources.requests
필드를 포함하도록 Deployment, StatefulSet 또는 기타 컨트롤러 내에서 포드 매니페스트를 업데이트하세요. 예를 들면 다음과 같습니다.
apiVersion: v1
kind: Pod
metadata:
name: example-pod
spec:
containers:
- name: example-container
...
resources:
requests:
cpu: "100m"
memory: "128Mi"
오류: 포드의 포드 측정항목을 가져올 수 없음
HorizontalPodAutoscaler가 확장 결정을 내리는 데 필요한 측정항목을 가져오는 데 문제가 있는 경우 이 오류가 표시될 수 있습니다. 포드 리소스 정의와 관련된 경우가 많습니다.
증상:
다음과 유사한 메시지가 지속적으로 표시됩니다.
unable to fetch pod metrics for pod
일반적으로 측정항목 서버가 시작될 때 이 메시지가 일시적으로 표시됩니다.
원인:
리소스 사용률 백분율 (예: cpu
또는 memory
)을 기반으로 확장하려면 HorizontalPodAutoscaler 객체에서 타겟팅하는 포드 내의 모든 컨테이너에 해당 특정 리소스에 대해 정의된 resources.requests
필드가 있어야 합니다.
그렇지 않으면 HorizontalPodAutoscaler는 필요한 계산을 수행할 수 없으며 해당 측정항목과 관련된 작업을 수행하지 않습니다.
해결 방법:
이러한 오류 메시지가 계속 표시되고 포드가 워크로드에 맞게 확장되지 않는 경우 워크로드의 각 컨테이너에 대한 리소스 요청을 지정했는지 확인하세요.
측정항목 API 및 데이터 가용성 오류 문제 해결
다음 섹션에서는 HorizontalPodAutoscaler가 측정항목 API에서 데이터를 가져오려고 할 때 발생하는 오류를 해결하는 방법을 설명합니다. 이러한 문제는 측정항목 API를 사용할 수 없는 내부 클러스터 통신 실패부터 측정항목 제공자가 거부하는 잘못된 쿼리 (400
수준 HTTP 오류로 표시되는 경우가 많음)에 이르기까지 다양합니다.
오류: 사용 가능한 측정항목 버전이 없음
증상:
다음 오류가 표시됩니다.
unable to fetch metrics from custom metrics API: no known available metric versions found
원인:
이 오류는 측정항목 소스 (예: Cloud Monitoring)의 문제가 아니라 클러스터 내 통신 장애를 나타냅니다. 일반적인 원인은 다음과 같습니다.
- Kubernetes API 서버를 일시적으로 사용할 수 없습니다 (예: 클러스터 업그레이드 또는 컨트롤 플레인 복구 중).
- 측정항목 어댑터 포드 (예:
custom-metrics-stackdriver-adapter
)가 비정상이거나 실행되지 않거나 API 서버에 올바르게 등록되지 않았습니다.
해결 방법:
이 문제는 일시적인 경우가 많습니다. 문제가 지속되면 다음 해결 방법을 시도해 보세요.
Kubernetes 컨트롤 플레인 상태 확인:
Google Cloud 콘솔에서 클러스터의 상태와 상태를 확인합니다.
Kubernetes 클러스터 페이지로 이동합니다.
클러스터의 상태 및 알림 열을 확인합니다.
알림을 클릭하여 업그레이드나 수리와 같은 진행 중인 작업을 확인합니다. 이 시간 동안 API 서버를 잠시 사용할 수 없을 수 있습니다.
컨트롤 플레인 구성요소와 관련된 오류가 있는지 Cloud 감사 로그를 검토합니다. 이러한 로그를 보는 방법에 대한 자세한 내용은 GKE 감사 로깅 정보를 참고하세요.
측정항목 어댑터 포드의 상태 및 로그 확인: 측정항목 어댑터 포드가
Running
상태이고 최근에 다시 시작되지 않았는지 확인합니다.kubectl get pods -n custom-metrics,kube-system -o wide
Pod의 상태가
Running
가 아니거나 다시 시작 횟수가 많은 경우 Pod를 조사하여 근본 원인을 찾습니다. 문제 해결 도움말은 Kubernetes 문서의 포드 디버그를 참고하세요.측정항목 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
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에 데이터를 쓰지 않았기 때문입니다.
해결 방법:
다음 해결 방법을 시도해 보세요.
- 구성 확인: HorizontalPodAutoscaler 객체의 측정항목 이름과 라벨이 애플리케이션에서 내보내는 측정항목 이름과 라벨과 정확히 일치하는지 확인합니다.
- 권한 확인: 애플리케이션이 Cloud Monitoring에 측정항목을 게시하는 데 필요한 권한과 API 엔드포인트로 올바르게 구성되어 있는지 확인합니다.
- 애플리케이션 활동 확인: 측정항목을 담당하는 애플리케이션이 Horizontal Pod Autoscaler 경고가 발생한 기간 동안 작동하고 Cloud Monitoring으로 데이터를 전송하려고 시도했는지 확인합니다.
- 오류 조사: 동일한 기간의 애플리케이션 로그에서 연결 실패, 잘못된 사용자 인증 정보, 형식 문제와 같은 측정항목 배출과 관련된 명시적 오류가 있는지 확인합니다.
커스텀 및 외부 측정항목 문제 해결
HorizontalPodAutoscaler가 기본 CPU 또는 메모리 이외의 소스에서 가져온 측정항목을 사용하는 경우 맞춤 또는 외부 측정항목 파이프라인 내에서 문제가 발생할 수 있습니다. 이 파이프라인은 다음 다이어그램에 표시된 대로 HorizontalPodAutoscaler 컨트롤러, Kubernetes 측정항목 API 서버, 측정항목 어댑터, 측정항목 소스 (예: Cloud Monitoring 또는 Prometheus)로 구성됩니다.
이 섹션에서는 측정항목 어댑터에서 측정항목 소스까지 이 파이프라인을 디버그하는 방법을 자세히 설명합니다.
증상:
측정항목 파이프라인의 문제에 대한 가장 일반적인 증상은 다음과 같습니다.
- 측정항목 값이
<unknown>
로 표시됩니다. - HorizontalPodAutoscaler 이벤트에
FailedGetExternalMetric
또는FailedGetCustomMetric
과 같은 오류가 표시됩니다.
원인:
맞춤 또는 외부 측정항목 파이프라인에 문제가 있습니다.
해결 방법:
다음 단계를 따라 파이프라인을 디버그하세요.
측정항목 어댑터가 등록되어 있고 사용 가능한지 확인: 측정항목을 제공하려면 측정항목 어댑터가 기본 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
이면 다음 단계로 진행합니다.
측정항목 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
입니다.
명령어 출력 분석: 이전 명령어의 결과는 문제가 있는 위치를 알려줍니다. 출력과 일치하는 시나리오를 선택하세요.
- 값이 있는 성공적인 JSON 응답: 측정항목 파이프라인이 올바르게 작동하고 있습니다. 이 문제는 HorizontalPodAutoscaler 매니페스트의 구성 문제일 수 있습니다. 측정항목 이름에 맞춤법 오류가 있거나
matchLabels
이 잘못되었는지 확인합니다. Error: Error from server (Service Unavailable)
: 이 오류는 일반적으로 네트워크 연결 문제를 나타내며, 네트워크 격리를 사용하는 클러스터에서는 방화벽 문제인 경우가 많습니다.측정항목 어댑터 서비스를 식별합니다. 일반적으로
custom-metrics
또는kube-system
네임스페이스에 있습니다.kubectl get service -n custom-metrics,kube-system | grep -E 'adapter|metrics'
어댑터가 리슨하는 포트를 찾습니다.
kubectl get service ADAPTER_SERVICE -n ADAPTER_NAMESPACE -o yaml
다음을 바꿉니다.
ADAPTER_SERVICE
: 배포한 측정항목 어댑터와 연결된 Kubernetes 서비스의 이름입니다. 이 서비스는 이전 단계에서 찾은 서비스입니다. 이 서비스는 Kubernetes API 서버를 비롯한 클러스터의 다른 부분에 어댑터의 기능을 노출합니다.ADAPTER_NAMESPACE
: 어댑터 서비스가 상주하는 네임스페이스입니다 (예:custom-metrics
또는kube-system
).
클러스터의 컨트롤 플레인에 대한 인바운드 방화벽 규칙을 찾습니다.
gcloud compute firewall-rules list \ --filter="name~gke-CLUSTER_NAME-[0-9a-z]*-master"
CLUSTER_NAME
을 클러스터 이름으로 바꿉니다.어댑터의
targetPort
를 규칙에 추가합니다.현재 규칙을 설명하여 허용된 기존 포트를 확인합니다.
gcloud compute firewall-rules describe FIREWALL_RULE_NAME
FIREWALL_RULE_NAME
을 Kubernetes 클러스터의 컨트롤 플레인으로 향하는 네트워크 트래픽을 관리하는 방화벽 규칙의 이름으로 바꿉니다.어댑터 포트를 목록에 추가하도록 규칙을 업데이트합니다.
gcloud compute firewall-rules update FIREWALL_RULE_NAME \ --allow tcp:443,tcp:10250,tcp:ADAPTER_PORT
ADAPTER_PORT
를 측정항목 어댑터가 리슨하는 네트워크 포트로 바꿉니다.
Kubernetes 네트워크 정책이 측정항목 어댑터 포드로의 트래픽을 차단하지 않는지 확인합니다.
kubectl get networkpolicy -n custom-metrics,kube-system
정책을 검토하여 컨트롤 플레인 또는 API 서버에서
ADAPTER_PORT
의ADAPTER_SERVICE
로의 인그레스 트래픽을 허용하는지 확인합니다.
빈 목록
[]
: 이 출력은 어댑터가 실행 중이지만 특정 측정항목을 가져올 수 없음을 의미하며, 어댑터의 구성 또는 측정항목 소스 자체에 문제가 있음을 나타냅니다.어댑터 포드 문제: 측정항목 어댑터 포드 또는 포드의 로그를 검사하여 API 호출, 인증 또는 측정항목 가져오기와 관련된 오류를 확인합니다. 로그를 검사하려면 다음 단계를 따르세요.
어댑터 포드의 이름을 찾습니다.
kubectl get pods -n ADAPTER_NAMESPACE
로그를 확인합니다.
kubectl logs ADAPTER_POD_NAME \ -n ADAPTER_NAMESPACE
다음을 바꿉니다.
ADAPTER_POD_NAME
: 이전 단계에서 식별한 어댑터 포드의 이름입니다.ADAPTER_NAMESPACE
: 어댑터 포드가 상주하는 네임스페이스입니다 (예:custom-metrics
또는kube-system
).
소스에 데이터가 없음: 소스 시스템에 측정항목이 없을 수 있습니다. 측정항목 탐색기와 같은 모니터링 도구를 사용하여 측정항목이 존재하고 이름과 라벨이 올바른지 확인합니다.
- 값이 있는 성공적인 JSON 응답: 측정항목 파이프라인이 올바르게 작동하고 있습니다. 이 문제는 HorizontalPodAutoscaler 매니페스트의 구성 문제일 수 있습니다. 측정항목 이름에 맞춤법 오류가 있거나
수평형 포드 자동 확장 처리가 축소되지 않는 문제 해결
이 섹션에서는 HorizontalPodAutoscaler가 예상대로 워크로드를 축소하지 않는 이유를 파악하는 데 도움이 됩니다.
증상:
HorizontalPodAutoscaler가 워크로드를 성공적으로 수직 확장하지만 CPU 사용률과 같은 측정항목이 낮은 경우에도 다시 축소하지 못합니다.
원인:
이 동작은 불완전한 정보를 기반으로 빠르게 확장 및 축소하거나 축소하는 것을 방지하도록 설계되었습니다. 두 가지 주요 이유는 다음과 같습니다.
- 여러 측정항목 사용: 수평형 포드 자동 확장 처리기는 가장 많은 복제본이 필요한 측정항목을 기반으로 확장합니다. 측정항목이 여러 개인 경우 모든 측정항목에서 복제본 수가 적어도 된다고 표시하지 않는 한 워크로드가 축소되지 않습니다. 하나의 측정항목에 높은 복제본 수가 필요한 경우 다른 측정항목이 낮더라도 축소되지 않습니다.
- 사용할 수 없는 측정항목: 측정항목을 사용할 수 없게 되면 (
<unknown>
로 표시되는 경우가 많음) 수평형 포드 자동 확장 처리는 워크로드를 축소하지 않습니다. 사용량이 실제로 0인지 아니면 측정항목 파이프라인이 중단되었는지 확인할 수 없습니다. 이 문제는 활동이 없을 때 데이터 보고를 중지하여 수평형 포드 자동 확장 처리에서 측정항목을 사용할 수 없는 것으로 간주하고 축소 작업을 중지할 수 있는 비율 기반 맞춤 측정항목 (예:messages_per_second
)에서 흔히 발생합니다. - 확장 정책의 축소 지연 시간: HorizontalPodAutoscaler의
behavior
필드를 사용하면 확장 정책을 구성할 수 있습니다. 축소의 기본 정책에는 300초 (5분)의 안정화 기간이 포함됩니다. 이 기간에는 측정항목 값이 목표 기준점 아래로 떨어지더라도 HorizontalPodAutoscaler가 복제본 수를 줄이지 않습니다. 이 기간으로 인해 급격한 변동이 방지되지만 축소 속도가 예상보다 느려질 수 있습니다.
해결 방법:
다음 해결 방법을 시도해 보세요.
여러 측정항목과 사용할 수 없는 측정항목의 경우 문제를 일으키는 측정항목을 진단합니다.
kubectl describe hpa HPA_NAME -n NAMESPACE_NAME
출력의
Metrics
섹션에서 상태가<unknown>
인 측정항목을 찾고Events
섹션에서FailedGetCustomMetric
또는FailedGetExternalMetric
와 같은 경고를 찾습니다. 자세한 파이프라인 디버깅은 맞춤 측정항목 및 외부 측정항목 문제 해결 섹션을 참고하세요.사용할 수 없는 측정항목의 경우 트래픽이 적은 기간에 측정항목을 사용할 수 없게 되면 (비율 기반 측정항목에서 흔히 발생) 다음 해결 방법 중 하나를 시도해 보세요.
- 가능한 경우 비율 기반 측정항목 대신 게이지 기반 측정항목을 사용합니다. 게이지 측정항목 (예:
subscription
또는num_undelivered_messages
)은 값이0
인 경우에도 일관되게 값을 보고하므로 수평형 포드 자동 확장 처리가 안정적으로 확장 결정을 내릴 수 있습니다. - 측정항목 소스가 0 값을 보고하는지 확인합니다. 맞춤 측정항목을 관리하는 경우 데이터가 전혀 전송되지 않는 대신 비활성 기간에
0
를 게시하도록 구성합니다.
- 가능한 경우 비율 기반 측정항목 대신 게이지 기반 측정항목을 사용합니다. 게이지 측정항목 (예:
확장 정책의 축소 지연의 경우 축소의 기본 5분 안정화 기간이 너무 길면 맞춤설정합니다. HorizontalPodAutoscaler 매니페스트의
spec.behavior.scaleDown
섹션을 검사합니다. 측정항목이 감소한 후 자동 확장 처리가 더 빠르게 축소되도록stabilizationWindowSeconds
를 낮출 수 있습니다. 이러한 정책 구성에 대한 자세한 내용은 Kubernetes 문서의 확장 정책을 참고하세요.
다음 단계
문서에서 문제 해결 방법을 찾을 수 없으면 지원 받기를 참조하여 다음 주제에 대한 조언을 포함한 추가 도움을 요청하세요.
- Cloud Customer Care에 문의하여 지원 케이스를 엽니다.
- StackOverflow에서 질문하고
google-kubernetes-engine
태그를 사용하여 유사한 문제를 검색해 커뮤니티의 지원을 받습니다.#kubernetes-engine
Slack 채널에 가입하여 더 많은 커뮤니티 지원을 받을 수도 있습니다. - 공개 Issue Tracker를 사용하여 버그나 기능 요청을 엽니다.