커스텀 또는 외부 측정항목을 사용하여 Pod 자동 확장

Autopilot Standard

이 문서에서는 커스텀 측정항목과 외부 측정항목을 가져와서 사용하여 포드를 수평으로 확장하는 방법을 설명합니다.

측정항목을 가져오려면 GKE 관리 측정항목 어댑터를 사용하면 됩니다. 이 관리형 솔루션은 PromQL로 쿼리할 수 있는 Cloud Monitoring의 측정항목과 Prometheus 형식의 HTTP 엔드포인트 아래에 노출되는 특정 맞춤 Pod 측정항목 모두에 사용할 수 있습니다.

그러면 워크로드 자동 확장 처리기가 이 데이터를 사용하여 워크로드를 더 효율적으로 확장할 수 있습니다. 예를 들어 이 기능을 사용하여 대기열 깊이나 캐시 사용률을 모니터링한 다음 자동 확장 처리기가 포드 수를 늘리거나 줄이도록 허용할 수 있습니다. vLLM 예시에서 캐시 사용률을 추적하는 데 유용할 수 있는 측정항목은 vllm:gpu_cache_usage_perc입니다.

관리형 측정항목 어댑터 대신 측정항목을 사용하여 자동 확장하려면 자동 확장 처리로 측정항목을 전송하도록 측정항목 어댑터를 수동으로 구성하여 측정항목을 가져오면 됩니다. 이 워크플로에는 Stackdriver 어댑터와 같은 서드 파티 어댑터를 설치하고 권한을 구성하는 작업이 포함됩니다. 예를 들어 측정항목을 기준으로 포드 자동 확장 최적화 튜토리얼을 참고하세요.

이 문서의 나머지 부분에서는 관리 측정항목 어댑터에 중점을 둡니다.

측정항목 가져오기

관리 측정항목 어댑터를 사용하여 다음과 같은 방법으로 측정항목을 가져올 수 있습니다.

• 포드에서 내보낸 맞춤 포드 측정항목은 클러스터 내에서 가져올 수 있습니다. 이러한 측정항목은 Cloud Monitoring과 같은 모니터링 시스템을 거치지 않고 자동 확장에 사용할 수 있습니다.
• Cloud Monitoring에 저장된 맞춤 포드 측정항목은 PromQL 쿼리를 사용하여 가져올 수 있습니다. 이러한 측정항목은 포드에서 내보내지고 일반적으로 Google Cloud Managed Service for Prometheus를 사용하여 Cloud Monitoring으로 내보내집니다. 이전 방법과 비교할 때 이 접근 방식을 사용하면 백분위수 계산이나 과거 값 읽기와 같은 PromQL 기능을 사용할 수 있습니다.
• PromQL 쿼리를 사용하여 Cloud Monitoring에서 외부 측정항목을 가져올 수 있습니다.

측정항목을 가져온 후 HorizontalPodAutoscaler 객체에서 측정항목을 참조합니다. 자세한 내용은 수평형 포드 자동 확장 처리에서 측정항목 사용 섹션을 참고하세요.

측정항목을 기반으로 한 자동 확장에 대한 개요는 측정항목을 기준으로 워크로드 자동 확장 정보를 참고하세요.

클러스터 내에서 커스텀 측정항목 가져오기

커스텀 측정항목은 실행 중인 서비스 또는 애플리케이션에서 가져옵니다. 노출된 측정항목의 한 예는 vLLM 엔진에서 노출되는 측정항목을 참고하세요.

요구사항

포드 요구사항은 다음과 같습니다.

• GKE 1.37.0-gke.3100000 이상 이 기능은 GKE 버전 1.36.4-gke.1247000 이상의 미리보기에서도 사용할 수 있습니다.
• 성능 프로필과 함께 수평형 포드 자동 확장을 사용합니다.

측정항목의 요구사항은 다음과 같습니다.

• 측정항목은 자동 확장되는 워크로드의 포드에서 내보내야 합니다.
• 측정항목은 HTTP 엔드포인트에서 액세스할 수 있어야 합니다. 엔드포인트 경로는 기본적으로 /metrics입니다.
• 측정항목은 Prometheus 표준에 따라 형식이 지정되어야 합니다.
• 게이지 측정항목만 지원됩니다.
• 기본적으로 노드당 최대 50개의 고유 측정항목을 노출할 수 있습니다. 더 많은 측정항목을 노출해야 하는 경우 추가 메모리 양을 늘려 요청할 수 있습니다.
• 이 기능의 미리보기 버전을 GKE 버전 1.36.4-gke.1247000~1.37.0-gke.3100000에서 사용하는 경우 다음 추가 요구사항이 적용됩니다.
  • 포드 라벨 선택기의 라벨 이름에는 특수문자를 포함할 수 없습니다. a~z 문자 (소문자 또는 대문자), 숫자, 하이픈, 밑줄만 지원됩니다.
  • 측정항목 라벨을 기반으로 필터링을 사용하는 경우 라벨 키는 정규 표현식 ^[a-zA-Z_][a-zA-Z0-9_]*(문자 또는 밑줄로 시작하고 문자, 숫자 또는 밑줄만 포함)과 일치해야 합니다.
  • 클러스터당 최대 20개의 고유 측정항목을 노출할 수 있습니다.

측정항목 정의

1. 노출할 측정항목을 선택합니다. 워크로드에서 노출되고 이전 섹션에 나열된 요구사항을 충족하는 측정항목을 선택할 수 있습니다.

   워크로드에서 이름은 같지만 라벨이 다른 측정항목을 여러 개 노출하는 경우 라벨 필터를 추가하여 측정항목이 하나만 선택되도록 합니다.

2. 다음 맞춤 리소스를 추가하고 측정항목 및 포드에 해당하는 세부정보를 대체합니다.

   apiVersion: autoscaling.gke.io/v1beta1
   kind: AutoscalingMetric
   metadata:
     name: NAME
     namespace: NAMESPACE
   spec:
     metrics:
     - pod:
         selector:
           matchLabels:
             APP_LABEL_NAME: APP_LABEL_VALUE
         containers:
         - endpoint:
             port: METRIC_PORT
             path: METRIC_PATH
           metrics:
           - gauge:
               name: METRIC_NAME
               prometheusMetricName: METRIC_PROMETHEUS_NAME
   

   워크로드에 맞게 다음을 바꿉니다.

   • NAME: AutoscalingMetric 객체의 이름입니다.
   • NAMESPACE: 포드가 있는 네임스페이스입니다.
   • APP_LABEL_NAME 및 APP_LABEL_VALUE: 측정항목을 내보내는 포드와 일치하는 라벨 이름과 값입니다.
   • METRIC_PORT: 포트 번호입니다.
   • METRIC_PATH: 측정항목의 경로입니다. 서비스 또는 애플리케이션에서 사용하는 경로를 확인합니다. 이 경로는 보통 /metrics입니다.
   • METRIC_NAME: 노출할 측정항목의 이름입니다. 이름은 ^[a-z]([-a-z0-9]*[a-z0-9])? 정규 표현식과 일치해야 하며 길이는 63자(영문 기준) 이하여야 합니다. 이 표현식은 첫 번째 문자가 소문자여야 하고 그 뒤에 오는 모든 문자는 하이픈, 소문자, 숫자여야 함을 의미합니다. 단, 마지막 문자는 하이픈이 될 수 없습니다.

   • 선택사항: METRIC_PROMETHEUS_NAME: 포드에서 노출된 Prometheus 측정항목 이름입니다. 이 필드를 사용하여 측정항목의 이름을 바꿀 수 있습니다. 예를 들어 포드에서 노출된 측정항목 이름이 자동 확장 처리기에서 설정한 이름 제한을 준수하지 않는 경우에 이름을 바꿀 수 있습니다.

     이름 제한에 대한 자세한 내용은 수평형 포드 자동 확장 처리의 제한사항을 참고하세요. 측정항목 라벨을 사용하여 측정항목을 필터링할 수도 있습니다.

3. 다음 명령어를 사용하여 매니페스트를 적용합니다.

   kubectl apply -f FILE_NAME_AUTOSCALING_METRIC.yaml
   

   FILE_NAME_AUTOSCALING_METRIC을 YAML 파일 이름으로 바꿉니다.

4. 측정항목 정의를 확인하고 HorizontalPodAutoscaler 객체에 사용할 측정항목 이름을 가져옵니다.

   1. AutoscalingMetric 커스텀 리소스에 대해 kubectl describe 명령어를 실행합니다.

      kubectl describe autoscalingmetric NAME -n NAMESPACE
      

      다음을 바꿉니다.

      • NAME: AutoscalingMetric 객체의 이름입니다.
      • NAMESPACE: AutoscalingMetric 객체의 네임스페이스입니다.

   2. Status 필드를 확인합니다. 오류가 나열되지 않으면 객체가 유효합니다.

   3. HPA Name 필드의 이름을 복사합니다. HorizontalPodAutoscaler 객체에 추가하는 이름입니다. 이 이름의 형식은 autoscaling.gke.io|NAME|METRIC_NAME입니다.

이제 측정항목이 AutoscalingMetric 객체에 정의됩니다. 이 측정항목으로 자동 확장하려면 HorizontalPodAutoscaler 객체에서 이를 참조해야 합니다. 자세한 내용은 HorizontalPodAutoscaler 객체에서 측정항목 사용 섹션을 참고하세요.

커스텀 리소스를 추가하면 측정항목이 자동 확장 API로 푸시됩니다. 측정항목은 몇 초마다 읽혀 워크로드 자동 확장기에 전송됩니다.

측정항목 라벨을 사용하여 측정항목 필터링

측정항목 라벨을 사용한 측정항목 필터링은 GKE 1.36.0-gke.1759000 이상에서 사용할 수 있습니다.

워크로드에서 내보낸 측정항목에는 라벨이 포함되는 경우가 많습니다. 라벨은 값에 측정기준을 추가할 수 있는 키-값 쌍입니다. 예를 들어 메서드와 환경별로 분류된 HTTP 엔드포인트에 대한 요청 수를 집계하는 측정항목은 라벨을 사용하여 이 컨텍스트를 지정할 수 있습니다. 이 예시는 다음과 같을 수 있습니다.

http_requests_total{method="GET", env="prod"} 11111
http_requests_total{method="PUT", env="staging"} 22222

라벨 필터를 사용하면 측정항목 사양이 하나의 측정항목과 정확히 일치하도록 할 수 있습니다. 예를 들어 앞의 예에서 첫 번째 측정항목만 선택하려면 AutoscalingMetric gauge 측정항목에 다음 사양을 사용합니다.

apiVersion: autoscaling.gke.io/v1beta1
kind: AutoscalingMetric
metadata:
  name: filter-sample
spec:
  # Several lines are omitted here.
      metrics:
      - gauge:
          name: http_requests_total
          filter:
            matchLabels:
              method: GET
              env: prod

matchLabels 키-값 쌍의 키는 정규 표현식 ^[a-zA-Z_][a-zA-Z0-9_]*와 일치해야 합니다. 즉, 문자 또는 밑줄로 시작하고 문자, 숫자 또는 밑줄만 포함해야 합니다.

Cloud Monitoring에서 맞춤 또는 외부 측정항목 가져오기

미리보기

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제품 또는 서비스 약관'이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

Cloud Monitoring에서 측정항목을 가져와 워크로드를 확장할 수 있습니다. GKE는 Cloud Monitoring에서 다음 두 가지 유형의 측정항목을 가져오는 것을 지원합니다.

• 맞춤 측정항목: 이 유형을 사용하여 백분위수를 계산하거나 이전 값을 읽는 등 PromQL 기능을 클러스터 워크로드에서 내보낸 측정항목에 적용합니다.
• 외부 측정항목: Pub/Sub 구독의 대기 중인 메시지 수와 같이 클러스터 외부의 항목을 기반으로 확장하려면 이 유형을 사용합니다.

그렇지 않으면 클러스터에서 맞춤 측정항목을 가져옵니다.

요구사항

• GKE 버전 1.36.2-gke.2771000 이상
• 측정항목은 Cloud Monitoring에 저장해야 합니다. 예를 들어 Google Cloud Managed Service for Prometheus를 사용할 수 있습니다.
• 클러스터당 최대 100개의 측정항목이 지원됩니다. 이 한도는 맞춤 측정항목과 외부 측정항목의 합계입니다.
• Cloud Monitoring의 측정항목은 자동 확장되는 클러스터와 동일한 Google Cloud 프로젝트에 있어야 합니다.

측정항목 정의

YAML 파일을 사용하여 특정 PromQL 쿼리를 비롯한 측정항목을 정의합니다.

참고: 클러스터 리소스를 절약하기 위해 자동 확장 측정항목 어댑터는 기본적으로 복제본이 0개로 실행됩니다. PromQL 쿼리가 포함된 AutoscalingMetric 객체를 적용하면 어댑터가 하나의 복제본으로 확장됩니다.

맞춤 측정항목 또는 외부 측정항목을 가져오는지에 따라 다음 구성 중 하나를 선택합니다.

1. AutoscalingMetric 객체를 만들고 가져올 측정항목을 정의합니다.

   맞춤 측정항목 (팟)

   apiVersion: autoscaling.gke.io/v1beta1
   kind: AutoscalingMetric
   metadata:
     name: NAME
     namespace: NAMESPACE
   spec:
     metrics:
       - promql:
           name: METRIC_NAME
           query: PROMQL_QUERY
           type: Pods # Specifies that the metric is associated with Pods.
           # metricLabels are optional, default to the labels used by Google
           # Cloud Managed Service for Prometheus. The defaults are used
           # below.
           metricLabels:
             podName: "pod"
             namespace: "namespace"
             clusterName: "cluster"
             location: "location"
             projectId: "project_id"
   

   다음을 바꿉니다.

   • NAME: AutoscalingMetric 객체의 이름입니다.
   • NAMESPACE: AutoscalingMetric 객체의 네임스페이스입니다. 확장하려는 워크로드의 네임스페이스와 일치해야 합니다.
   • METRIC_NAME: HorizontalPodAutoscaler 객체가 사용하는 측정항목의 이름입니다.
   • PROMQL_QUERY: 측정항목을 쿼리하는 PromQL 쿼리입니다. PromQL 쿼리는 자동 확장된 리소스의 포드당 하나의 항목이 있는 벡터를 반환해야 합니다(예: 배포의 포드당 하나의 항목).

   metrics 배열에 promql 항목을 추가하여 단일 AutoscalingMetric 매니페스트에 두 개 이상의 측정항목을 정의할 수 있습니다.

   이 매니페스트에서는 다음이 적용됩니다.

   • type: Pods 필드는 측정항목이 Pod에서 내보내짐을 나타냅니다.

   • 선택사항: metricLabels 필드는 리소스 세부정보 (예: 포드 이름, 네임스페이스 또는 클러스터 정보)를 나열하는 PromQL 쿼리 결과의 라벨 이름입니다. 포드에서 내보낸 맞춤 측정항목에는 측정항목이 연결된 포드를 지정하는 podName 필드와 일치하는 라벨이 포함되어야 합니다. 이 라벨은 Google Cloud Managed Service for Prometheus를 사용하여 Cloud Monitoring에 측정항목을 전송할 때 자동으로 구성됩니다.

     이 필드가 AutoscalingMetric 객체에 지정되지 않은 경우 다음 기본값이 라벨에서 정보를 찾는 데 사용됩니다. 이러한 기본값은 Google Cloud Managed Service for Prometheus에서 구성한 것과 동일한 라벨 이름입니다.

     • podName: "pod"
     • namespace: "namespace"
     • clusterName: "cluster"
     • location: "location"
     • projectId: "project_id"

   외부 측정항목

   apiVersion: autoscaling.gke.io/v1beta1
   kind: AutoscalingMetric
   metadata:
     name: NAME
     namespace: NAMESPACE
   spec:
     metrics:
       - promql:
           name: METRIC_NAME
           query: PROMQL_QUERY
           type: External  # Optional, default is 'External'
   

   다음을 바꿉니다.

   • NAME: AutoscalingMetric 객체의 이름입니다.
   • NAMESPACE: AutoscalingMetric 객체의 네임스페이스입니다. 확장하려는 워크로드의 네임스페이스와 일치해야 합니다.
   • METRIC_NAME: HPA가 사용하는 측정항목의 이름입니다.
   • PROMQL_QUERY: 측정항목을 쿼리하는 PromQL 쿼리입니다. PromQL 쿼리는 스칼라 값 또는 고유한 항목이 있는 벡터를 반환해야 합니다.

   참고: metrics 배열에 promql 항목을 추가하여 단일 AutoscalingMetric 매니페스트에서 두 개 이상의 측정항목을 정의할 수 있습니다.

2. Cloud Monitoring에서 PromQL 쿼리를 확인하여 예상되는 측정항목이 반환되는지 확인합니다. 나중에 예상치 못한 동작을 해결하는 것보다 설정할 때 쿼리를 확인하는 것이 더 쉽습니다.

   쿼리를 확인하려면 PromQL 쿼리 확인 섹션을 참고하세요.

3. 클러스터에 AutoscalingMetric 매니페스트를 적용합니다.

   kubectl apply -f MANIFEST_FILE.yaml
   

   MANIFEST_FILE를 YAML 파일 이름으로 바꿉니다.

4. 측정항목 정의를 확인하고 HorizontalPodAutoscaler 객체에 사용할 측정항목 이름을 가져옵니다.

   1. AutoscalingMetric 커스텀 리소스에 대해 kubectl describe 명령어를 실행합니다.

      kubectl describe autoscalingmetric NAME -n NAMESPACE
      

      다음을 바꿉니다.

      • NAME: AutoscalingMetric 객체의 이름입니다.
      • NAMESPACE: AutoscalingMetric 객체의 네임스페이스입니다.

   2. Status 필드를 확인합니다. 오류가 나열되지 않으면 객체가 유효합니다.

   3. HPA Name 필드의 이름을 복사합니다. HorizontalPodAutoscaler 객체에 추가하는 이름입니다. 이 이름의 형식은 autoscaling.gke.io|NAME|METRIC_NAME입니다.

이제 측정항목이 AutoscalingMetric 객체에 정의됩니다. 이 측정항목으로 자동 확장하려면 HorizontalPodAutoscaler 객체에서 이를 참조해야 합니다. 자세한 내용은 HorizontalPodAutoscaler 객체에서 측정항목 사용 섹션을 참고하세요.

HorizontalPodAutoscaler 객체에서 측정항목 사용

1. HorizontalPodAutoscaler 객체를 만듭니다. HorizontalPodAutoscaler 측정항목 유형은 AutoscalingMetric 커스텀 리소스에 정의된 type 필드의 값과 일치해야 합니다. 측정항목 유형에 따라 다음 구성 중 하나를 선택합니다.

   옵션 1: 외부 측정항목

   apiVersion: autoscaling/v2
   kind: HorizontalPodAutoscaler
   metadata:
     name: HPA_NAME
     namespace: NAMESPACE
   spec:
     scaleTargetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: DEPLOYMENT_NAME
     minReplicas: MIN_REPLICAS
     maxReplicas: MAX_REPLICAS
     metrics:
       - type: External
         external:
           metric:
             name: autoscaling.gke.io|NAME|METRIC_NAME
           target:
             type: AverageValue
             averageValue: AVERAGE_VALUE
   

   옵션 2: 포드 측정항목

   apiVersion: autoscaling/v2
   kind: HorizontalPodAutoscaler
   metadata:
     name: HPA_NAME
     namespace: NAMESPACE
   spec:
     scaleTargetRef:
       apiVersion: apps/v1
       kind: Deployment
       name: DEPLOYMENT_NAME
     minReplicas: MIN_REPLICAS
     maxReplicas: MAX_REPLICAS
     metrics:
       - type: Pods
         pods:
           metric:
             name: autoscaling.gke.io|NAME|METRIC_NAME
           target:
             type: AverageValue  # This is the only supported target type
             averageValue: AVERAGE_VALUE
   

   다음을 바꿉니다.

   • HPA_NAME: HorizontalPodAutoscaler 객체의 이름입니다.
   • NAMESPACE: HorizontalPodAutoscaler 객체의 네임스페이스입니다. 워크로드 및 AutoscalingMetric 리소스의 네임스페이스와 일치해야 합니다.
   • DEPLOYMENT_NAME: 확장할 워크로드 배포의 이름입니다.
   • MIN_REPLICAS: 실행 중인 최소 포드 수입니다.
   • MAX_REPLICAS: 실행 중인 최대 포드 수입니다.
   • NAME: 생성한 AutoscalingMetric 커스텀 리소스의 이름입니다.
   • METRIC_NAME: AutoscalingMetric 리소스에 정의된 측정항목의 이름입니다.
   • AVERAGE_VALUE: 자동 확장 처리가 워크로드를 확장하는 타겟 측정항목 값입니다.

   자체 HorizontalPodAutoscaler 객체를 만들 때는 다음 사항에 유의하세요.

   • AutoscalingMetric, Deployment, HorizontalPodAutoscaler 객체는 동일한 네임스페이스에 있어야 합니다.
   • 앞의 예에서는 type: AverageValue 필드-값 쌍을 사용합니다. 외부 측정항목에도 type: Value이 지원됩니다.
   • 앞의 예시에서는 Deployment 객체를 예시로만 사용합니다. ReplicaSet 객체와 같이 HorizontalPodAutoscaler 객체에서 지원하는 객체를 자동 확장할 수도 있습니다.

2. HorizontalPodAutoscaler 매니페스트를 적용합니다.

   kubectl apply -f HPA_MANIFEST_FILE.yaml
   

   HPA_MANIFEST_FILE를 YAML 파일 이름으로 바꿉니다.

자동 확장을 위해 가져온 측정항목 문제 해결

측정항목 가져오기 문제를 해결하려면 로그 또는 AutoscalingMetric 커스텀 리소스의 상태를 검토하세요.

자동 확장 측정항목 어댑터의 복제본이 0개입니다.

kube-system에서 autoscaling-metrics-adapter 배포를 검사하면 복제본이 0개인 것을 확인할 수 있습니다.

기본적으로 어댑터는 클러스터 리소스를 절약하기 위해 복제본이 0개로 실행됩니다. 이는 정상적인 동작입니다. PromQL 처리가 필요한 AutoscalingMetric 커스텀 리소스가 클러스터에 있는 경우 배포는 하나의 복제본으로만 확장됩니다.

PromQL 쿼리로 AutoscalingMetric 객체를 구성했지만 어댑터가 확장되지 않은 경우 객체가 클러스터에서 성공적으로 생성되었는지 확인합니다.

로그 검토

Cloud Monitoring에서 측정항목을 가져오는 컨트롤러의 문제를 찾으려면 로그를 검토하세요.

Google Cloud 콘솔에서 로그를 볼 수 있습니다.

1. 로그 탐색기 페이지로 이동

   로그 탐색기로 이동

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

   resource.type="k8s_container"
   resource.labels.namespace_name="kube-system"
   resource.labels.container_name="autoscaling-metrics-adapter"
   

또는 kubectl를 사용하여 로그를 보려면 다음 명령어를 실행합니다.

kubectl logs deployment.apps/autoscaling-metrics-adapter -n kube-system

AutoscalingMetric 상태 검토

AutoscalingMetric 커스텀 리소스의 상태를 검토하여 구성 오류를 찾을 수 있습니다.

1. AutoscalingMetric 커스텀 리소스를 검사합니다.

   kubectl describe autoscalingmetric NAME -n NAMESPACE
   

   다음을 바꿉니다.

   • NAME: 생성한 AutoscalingMetric 커스텀 리소스의 이름입니다.
   • NAMESPACE: 커스텀 리소스의 네임스페이스입니다.

2. 구성된 측정항목에 관한 자세한 내용은 Status 필드를 참고하세요. 이 세부정보에는 구성 오류에 관한 경고와 HorizontalPodAutoscaler 객체에 표시되어야 하는 측정항목의 정확한 이름이 포함됩니다.

   다음은 유효한 상태의 예입니다.

   Name:         sample-metric
   Namespace:    default
   Labels:       <none>
   Annotations:  <none>
   API Version:  autoscaling.gke.io/v1beta1
   Kind:         AutoscalingMetric
   Metadata:
     Creation Timestamp:  2026-08-10T14:41:58Z
     Generation:          1
     Resource Version:    1786372918604351020
     UID:                 c3f012a9-8f25-4399-ac91-12ae8f4426d7
   Spec:
     Metrics:
       Promql:
         Name:   pubsub_unacked
         Query:  sum(pubsub_subscription_num_undelivered_messages)
         Type:   External
   Status:
     Metric Statuses:
       Hpa Name:  autoscaling.gke.io|sample-metric|pubsub_unacked
       Name:      pubsub_unacked
   Events:        <none>
   

   다음은 구성 오류가 있는 상태의 예시입니다.

   Name:         bad-metric
   Namespace:    default
   Labels:       <none>
   Annotations:  <none>
   API Version:  autoscaling.gke.io/v1beta1
   Kind:         AutoscalingMetric
   Metadata:
     Creation Timestamp:  2026-08-10T14:42:40Z
     Generation:          1
     Resource Version:    1786372960414079010
     UID:                 a47d3ed4-f6f2-4c2c-9341-0de4e9752c3c
   Spec:
     Metrics:
       Promql:
         Name:   duplicate_metric
         Query:  sum(up)
         Type:   External
       Promql:
         Name:   duplicate_metric
         Query:  avg(up)
         Type:   External
   Status:
     Metric Statuses:
       Errors:
         Multiple metrics defined with the same name.
       Name:  duplicate_metric
   Events:    <none>
   

PromQL 쿼리 확인

PromQL 쿼리를 사용하여 Cloud Monitoring에서 측정항목을 가져오는 경우 쿼리 문제가 측정항목 검색 오류를 일으키거나 예기치 않은 값이 검색될 수 있습니다. 예를 들어 1~100의 값이 백분율로 반환될 것으로 예상했지만 0~1의 값이 대신 반환되면 자동 확장 결과가 예상치 못한 방식으로 작동합니다.

Cloud Monitoring에서 PromQL 쿼리를 테스트하여 예상되는 측정항목이 반환되는지 확인할 수 있습니다.

쿼리를 확인하려면 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 측정항목 탐색기 페이지로 이동합니다.

   측정항목 탐색기로 이동

2. 쿼리 빌더 창 상단에서 PromQL 탭을 선택합니다.

3. 쿼리 편집기에 테스트할 PromQL 쿼리를 입력합니다.

4. 쿼리 실행을 클릭하여 차트에 측정항목을 표시합니다.

다음 단계

• 측정항목을 기반으로 한 자동 확장에 대한 개요는 측정항목을 기준으로 워크로드 자동 확장 정보를 참고하세요.
• PromQL 쿼리로 정의할 수 없는 측정항목을 사용하여 자동 확장하려면 측정항목을 기반으로 포드 자동 확장 최적화를 참고하세요.