カスタム指標または外部指標を使用して Pod を自動スケーリングする

このドキュメントでは、カスタム指標と外部指標を取得して使用し、Pod を水平方向にスケーリングする方法について説明します。

指標を取得するには、GKE マネージド指標アダプターを使用します。このマネージド ソリューションは、PromQL でクエリできる Cloud Monitoring の指標と、Prometheus 形式の HTTP エンドポイントで公開される特定のカスタム Pod 指標の両方で使用できます。

ワークロード自動スケーラーは、このデータを使用してワークロードをより効率的にスケーリングできます。たとえば、この機能を使用してキューの深さやキャッシュの使用率をモニタリングし、自動スケーラーが Pod の数を増減できるようにします。vLLM の例では、キャッシュ使用率の追跡に役立つ指標は vllm:gpu_cache_usage_perc です。

マネージド指標アダプタの代わりに、任意の指標を使用して自動スケーリングを行うには、指標アダプタを手動で構成して指標をオートスケーラーに送信することで、指標を取得できます。このワークフローでは、Stackdriver アダプタなどのサードパーティ製アダプタをインストールし、権限を構成します。たとえば、指標に基づいて Pod の自動スケーリングを最適化するチュートリアルをご覧ください。

このドキュメントの残りの部分では、マネージド指標アダプタについて説明します。

指標を取得する

マネージド指標アダプタを使用して指標を取得するには、次の方法があります。

• Pod によって出力されたカスタム Pod 指標は、クラスタ内で取得できます。これらの指標は、Cloud Monitoring などのモニタリング システムを介することなく、自動スケーリングに使用できます。
• Cloud Monitoring に保存されているカスタム Pod 指標は、PromQL クエリを使用して取得できます。これらの指標は Pod によって出力され、通常は Google Cloud Managed Service for Prometheus を使用して Cloud Monitoring にエクスポートされます。このアプローチでは、以前の方法と比較して、パーセンタイルの計算や過去の値の読み取りなどの PromQL 機能を使用できます。
• 外部指標は、PromQL クエリを使用して Cloud Monitoring から取得できます。

指標を取得したら、HorizontalPodAutoscaler オブジェクトで指標を参照します。詳細については、水平 Pod 自動スケーラーで指標を使用するをご覧ください。

指標に基づく自動スケーリングの概要については、指標に基づくワークロードの自動スケーリングについてをご覧ください。

クラスタ内のカスタム指標を取得する

カスタム指標は、実行しているサービスまたはアプリケーションから取得されます。公開される指標の例については、vLLM Engine によって公開される指標をご覧ください。

要件

Pod の要件は次のとおりです。

• Rapid チャンネルのクラスタで GKE 1.35.1-gke.1396000 以降。
• パフォーマンス プロファイルで水平 Pod 自動スケーリングを使用している。

指標の要件は次のとおりです。

• 指標は、自動スケーリングされるワークロード内の Pod によって出力される必要があります。
• 指標は HTTP エンドポイントでアクセスできる必要があります。エンドポイント パスはデフォルトで /metrics です。
• 指標は Prometheus 標準に従ってフォーマットする必要があります。
• ゲージ指標のみがサポートされています。
• Pod ラベル セレクタのラベル名に特殊文字を含めることはできません。サポートされているのは、a ～ z の文字（小文字または大文字）、数字、ハイフン、アンダースコアのみです。
• 指標ラベルに基づくフィルタリングを使用する場合、ラベルキーは正規表現 ^[a-zA-Z_][a-zA-Z0-9_]*（英字またはアンダースコアで始まり、英字、数字、アンダースコアのみを含む）と一致する必要があります。
• クラスタごとに最大 20 個の一意の指標を公開できます。

指標を定義する

1. 公開する指標を選択します。ワークロードが公開し、前のセクションに記載されている要件を満たす指標であれば、どれでも選択できます。

   ワークロードが同じ名前で異なるラベルを持つ複数の指標を公開している場合は、ラベルフィルタを追加して、1 つだけが選択されるようにします。

2. 次のカスタム リソースを追加します。指標と Pod に固有の詳細は置き換えてください。

   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: Pod が存在する Namespace。
   • APP_LABEL_NAME と APP_LABEL_VALUE: 指標を出力する Pod に一致するラベル名と値。
   • METRIC_PORT: ポート番号。
   • METRIC_PATH: 指標のパス。サービスまたはアプリケーションで使用されているパスを確認します。このパスは通常 /metrics です。
   • METRIC_NAME: 公開する指標の名前。名前は正規表現 ^[a-z]([-a-z0-9]*[a-z0-9])? に一致し、長さが 63 文字以下である必要があります。この式は、最初の文字は小文字にする必要があり、それに続く文字はハイフン、小文字、数字でなければならないことを意味します。ただし、最後の文字をハイフンにすることはできません。

   • 省略可: METRIC_PROMETHEUS_NAME: Pod によって公開される Prometheus 指標名。このフィールドを使用して指標の名前を変更できます。たとえば、Pod によって公開された指標名が自動スケーラーで設定された名前の制限に準拠していない場合などです。

     名前の制限事項の詳細については、水平 Pod 自動スケーリングの制限事項をご覧ください。指標ラベルを使用して指標をフィルタリングすることもできます。

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 オブジェクトの Namespace。

   2. Status フィールドを確認します。エラーがリストされていない場合、オブジェクトは有効です。

   3. HPA Name フィールドの名前をコピーします。これは、HorizontalPodAutoscaler オブジェクトに追加する名前です。この名前の形式は autoscaling.gke.io|NAME|METRIC_NAME です。

指標は AutoscalingMetric オブジェクトで定義されるようになりました。この指標を使用して自動スケーリングを行うには、HorizontalPodAutoscaler オブジェクトでこの指標を参照する必要があります。詳細については、HorizontalPodAutoscaler オブジェクトの指標を使用するをご覧ください。

カスタム リソースを追加すると、指標が自動スケーリング API に push されます。指標は数秒ごとに読み取られ、ワークロード オートスケーラーに送信されます。

指標ラベルを使用した指標のフィルタリング

指標ラベルを使用した指標のフィルタリングは、GKE 1.36.0-gke.1759000 以降で使用できます。

ワークロードから出力される指標には、ラベルが含まれていることがよくあります。ラベルは、値にディメンションを追加できる Key-Value ペアです。たとえば、メソッドと環境でスライスされた HTTP エンドポイントへのリクエスト数をカウントする指標は、ラベルを使用してこのコンテキストを指定できます。この例は次のようになります。

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

ラベルフィルタを使用すると、指標仕様が 1 つの指標と正確に一致するようにできます。たとえば、前の例の最初の指標のみを選択するには、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 からカスタム指標または外部指標を取得する

Cloud Monitoring から指標を取得して、ワークロードをスケーリングできます。GKE は、Cloud Monitoring から次の 2 種類の指標を取得することをサポートしています。

• カスタム指標: このタイプを使用して、クラスタ ワークロードによって出力された指標に、パーセンタイルの計算や履歴値の読み取りなどの PromQL 機能が適用されます。
• 外部指標: このタイプを使用して、クラスタ外のエンティティ（Pub/Sub サブスクリプションの保留中のメッセージ数など）に基づいてスケーリングします。

それ以外の場合は、クラスタからカスタム指標を取得します。

要件

• GKE バージョン 1.36.2-gke.2771000 以降。
• 指標は Cloud Monitoring に保存する必要があります。たとえば、Google Cloud Managed Service for Prometheus を使用できます。
• クラスタごとに最大 100 個の指標がサポートされます。この上限は、カスタム指標と外部指標の両方の合計です。
• Cloud Monitoring の指標は、自動スケーリングされるクラスタと同じ Google Cloud プロジェクトに存在する必要があります。

指標を定義する

YAML ファイルを使用して、特定の PromQL クエリなどの指標を定義します。

カスタム指標または外部指標を取得するかどうかに応じて、次のいずれかの構成を選択します。

1. AutoscalingMetric オブジェクトを作成し、取得する指標を定義します。

   カスタム指標（Pod）

   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 オブジェクトの Namespace。スケーリングするワークロードの Namespace と一致する必要があります。
   • METRIC_NAME: HorizontalPodAutoscaler オブジェクトが使用する指標の名前。
   • PROMQL_QUERY: 指標をクエリする PromQL クエリ。PromQL クエリは、自動スケーリングされたリソース内の Pod ごとに 1 つのエントリを含むベクトルを返す必要があります（Deployment 内の Pod ごとに 1 つのエントリなど）。

   metrics 配列に promql エントリを追加することで、1 つの AutoscalingMetric マニフェストで複数の指標を定義できます。

   このマニフェストでは、次のようになります。

   • type: Pods フィールドは、指標が Pod によって出力されることを示します。

   • 省略可: metricLabels フィールドは、リソースの詳細（Pod 名、Namespace、クラスタ情報など）を一覧表示する PromQL クエリ結果のラベル名です。Pod によって出力されるカスタム指標には、podName フィールドと一致するラベルを含める必要があります。このラベルは、指標が関連付けられている Pod を指定します。このラベルは、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 オブジェクトの Namespace。スケーリングするワークロードの Namespace と一致する必要があります。
   • METRIC_NAME: HPA が使用する指標の名前。
   • PROMQL_QUERY: 指標をクエリする PromQL クエリ。PromQL クエリは、スカラー値または一意のエントリを含むベクトルを返す必要があります。

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 オブジェクトの Namespace。

   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: Pod の指標

   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 オブジェクトの Namespace。ワークロードと AutoscalingMetric リソースの Namespace と一致する必要があります。
   • DEPLOYMENT_NAME: スケーリングするワークロードの Deployment の名前。
   • MIN_REPLICAS: 実行中の Pod の最小数。
   • MAX_REPLICAS: 実行中の Pod の最大数。
   • NAME: 作成した AutoscalingMetric カスタム リソースの名前。
   • METRIC_NAME: AutoscalingMetric リソースで定義された指標の名前。
   • AVERAGE_VALUE: オートスケーラーがワークロードをスケーリングするターゲット指標値。

   独自の HorizontalPodAutoscaler オブジェクトを作成する場合は、次の点に注意してください。

   • AutoscalingMetric、Deployment、HorizontalPodAutoscaler オブジェクトは同じ Namespace に存在する必要があります。
   • 上記の例では、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 Deployment を調べると、レプリカ数が 0 になっていることがわかります。

デフォルトでは、アダプタはレプリカ数 0 で実行され、クラスタ リソースを節約します。これは想定された挙動です。PromQL 処理を必要とする AutoscalingMetric カスタム リソースがクラスタに存在する場合、デプロイは 1 つのレプリカにのみスケールアップします。

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: カスタム リソースの 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 コンソールで、Metrics Explorer のページに移動します。

   Metrics Explorer に移動

2. [クエリビルダー] ペインの上部で、[PromQL] タブを選択します。

3. クエリエディタに、テストする PromQL クエリを入力します。

4. [クエリを実行] をクリックして、グラフに指標を表示します。

次のステップ

• 指標に基づく自動スケーリングの概要については、指標に基づくワークロードの自動スケーリングについてをご覧ください。
• PromQL クエリで定義できない指標を使用して自動スケーリングを行うには、指標に基づいて Pod の自動スケーリングを最適化するをご覧ください。