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

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

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

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

指標を取得する

指標は次の方法で取得できます。

  • Pod によって出力されたカスタム指標は、クラスタ内で取得できます。これらの指標は、Cloud Monitoring などのモニタリング システムを経由せずに自動スケーリングに使用できます。
  • Cloud Monitoring に保存されている Pod 指標は、PromQL クエリを使用して取得できます。これらの指標は Pod によって出力され、通常は Google Cloud Managed Service for Prometheusを使用して Cloud Monitoring にエクスポートされます。 この方法では、前の方法と比較して、パーセンタイルの計算や過去の値の読み取りなど、PromQL の機能を使用できます。
  • 外部指標は、PromQL クエリを使用して Cloud Monitoring から取得できます。
  • 指標アダプタを手動で構成して指標をオートスケーラーに送信することで、指標を取得できます。このワークフローでは、サードパーティのツールをインストールし、権限を構成します。たとえば、 指標に基づいて Pod の自動スケーリングを最適化するチュートリアルをご覧ください。

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

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

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

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

要件

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

  • Rapid チャンネルのクラスタで GKE 1.35.1-gke.1396000 以降。
  • パフォーマンス プロファイルで 水平 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 されます。指標は数秒ごとに読み取られ、ワークロード オートスケーラーに送信されます。

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 の指標は、自動スケーリングされるクラスタと同じ Cloud de Confiance by S3NS プロジェクト に存在する必要があります。

指標を定義する

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 によって出力されるカスタム指標には、指標が関連付けられている Pod を指定する 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 オブジェクトの Namespace。スケーリングするワークロードの Namespace と一致する必要があります。
    • 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 オブジェクトの 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 で実行されます。 これは想定された挙動です。Deployment は、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: カスタム リソースの 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 で、[**Metrics Explorer**] のページに移動します。

    Metrics Explorer に移動

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

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

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

次のステップ