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

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

측정항목을 가져오려면 관리형 측정항목 어댑터를 사용합니다. 이 관리형 솔루션은 PromQL로 쿼리할 수 있는 Cloud Monitoring의 측정항목과 모든 커스텀 측정항목에 사용할 수 있습니다. 커스텀 측정항목은 Prometheus 형식으로 HTTP 엔드포인트 아래의 포드에서 노출되는 측정항목입니다.

또는 측정항목을 사용하여 자동 확장하려면 측정항목 어댑터를 수동으로 구성하여 측정항목을 자동 확장 처리로 전송하여 측정항목을 가져올 수 있습니다. 이 워크플로에는 커스텀 측정항목 어댑터와 같은 서드 파티 어댑터를 설치하고 권한을 구성하는 작업이 포함됩니다. 예를 들어 측정항목에 기반한 포드 자동 확장 최적화 가이드를 참조하세요.

측정항목 가져오기

다음과 같은 방법으로 측정항목을 가져올 수 있습니다.

• 포드에서 내보낸 커스텀 측정항목은 클러스터 내에서 가져올 수 있습니다. 이러한 측정항목은 Cloud Monitoring과 같은 모니터링 시스템을 거치지 않고도 자동 확장에 사용할 수 있습니다.
• Cloud Monitoring에 저장된 포드 측정항목은 PromQL 쿼리를 사용하여 가져올 수 있습니다. 이러한 측정항목은 포드에서 내보내지고 Cloud Monitoring으로 내보내지며 일반적으로 Google Cloud Managed Service for Prometheus를 사용하여 내보내집니다. 이전 방법과 비교하여 이 접근 방식을 사용하면 백분위수 계산 또는 이전 값 읽기와 같은 PromQL 기능을 사용할 수 있습니다.
• 외부 측정항목은 PromQL 쿼리를 사용하여 Cloud Monitoring에서 가져올 수 있습니다.
• 측정항목 어댑터를 수동으로 구성하여 측정항목을 자동 확장 처리로 전송하여 측정항목을 가져올 수 있습니다. 이 워크플로에는 서드 파티 도구를 설치하고 권한을 구성하는 작업이 포함됩니다. 예를 들어 측정항목에 기반한 포드 자동 확장 최적화 가이드를 참조하세요.

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

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

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

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

요구사항

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

• 신속 채널의 클러스터가 있는 GKE 1.35.1-gke.1396000 이상
• 성능 프로필과 함께 수평형 포드 자동 확장 처리 사용

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

• 측정항목은 HTTP 엔드포인트에서 액세스할 수 있어야 합니다. 엔드포인트 경로는 기본적으로 /metrics입니다.
• 측정항목은 Prometheus 표준에 따라 형식이 지정되어야 합니다.
• 게이지 측정항목만 지원됩니다.
• 포드 라벨 선택기의 라벨 이름에는 특수문자를 포함할 수 없습니다. 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로 푸시됩니다. 측정항목은 몇 초마다 읽혀지고 워크로드 자동 확장 처리로 전송됩니다.

Cloud Monitoring에서 커스텀 측정항목 또는 외부 측정항목 가져오기

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의 측정항목은 자동 확장되는 클러스터와 동일한 Cloud de Confiance by S3NS 프로젝트 에 있어야 합니다.

측정항목 정의

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

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

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 필드는 측정항목이 포드에서 내보내짐을 나타냅니다.

   • 선택사항: 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 쿼리는 스칼라 값 또는 고유한 항목이 있는 벡터를 반환해야 합니다.

   promqlmetrics

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, 배포, HorizontalPodAutoscaler 객체는 동일한 네임스페이스에 있어야 합니다.
   • 이전 예시에서는 type: AverageValue 필드-값 쌍을 사용합니다. 외부 측정항목의 경우 type: Value도 지원됩니다.
   • 이전 예시에서는 배포 객체만 예시로 사용합니다. 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 커스텀 리소스가 클러스터에 있는 경우에만 복제본 1개로 확장됩니다.

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

로그 검토

Cloud Monitoring에서 측정항목을 가져오는 역할을 하는 컨트롤러와 관련된 문제를 찾으려면 로그를 검토하면 됩니다.

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

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. 콘솔 Cloud de Confiance 에서 측정항목 탐색기 페이지로 이동합니다.

   측정항목 탐색기로 이동

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

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

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

다음 단계

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