使用自訂或外部指標自動調度 Pod 資源

本文說明如何擷取及使用自訂和外部指標，以水平擴展 Pod。

如要擷取指標，可以使用 GKE 代管指標轉接器。這項代管解決方案適用於 Cloud Monitoring 中可透過 PromQL 查詢的指標，以及在 Prometheus 格式的 HTTP 端點下公開的特定自訂 Pod 指標。

工作負載自動配置器接著可以使用這項資料，更有效率地調度工作負載資源。舉例來說，您可以使用這項功能監控佇列深度或快取使用率，然後允許自動配置器增加或減少 Pod 數量。以 vLLM 範例來說，vllm:gpu_cache_usage_perc 這項指標可用於追蹤快取使用率。

除了受管理指標介面卡，您也可以使用任何指標自動調度資源，方法是手動設定指標介面卡，將指標傳送至自動配置器。這個工作流程包括安裝第三方轉接程式 (例如 Stackdriver 轉接程式)，以及設定權限。舉例來說，請參閱「根據指標最佳化 Pod 自動調度資源」教學課程。

本文的其餘部分將著重於代管指標介面卡。

擷取指標

您可以使用受管理指標介面卡，透過下列方式擷取指標：

  • 您可以在叢集內擷取 Pod 發出的自訂 Pod 指標。這些指標可用於自動調整資源配置，不必透過 Cloud Monitoring 等監控系統傳輸。
  • 您可以使用 PromQL 查詢，擷取儲存在 Cloud Monitoring 中的自訂 Pod 指標。這些指標是由 Pod 發出，並匯出至 Cloud Monitoring，通常是使用 Google Cloud Managed Service for Prometheus。相較於先前的方法，這個做法可讓您使用 PromQL 功能，例如計算百分位數或讀取歷來值。
  • 您可以使用 PromQL 查詢，從 Cloud Monitoring 擷取外部指標。

擷取指標後，您可以在 HorizontalPodAutoscaler 物件中參照該指標。詳情請參閱「在水平 Pod 自動配置器中使用指標」一節。

如要概略瞭解如何根據指標自動調度資源，請參閱「根據指標自動調度工作負載資源」一文。

擷取叢集內的自訂指標

自訂指標來自您執行的服務或應用程式。 如需公開指標的範例，請參閱 vLLM 引擎公開的指標。

需求條件

Pod 的規定如下：

指標規定如下：

  • 指標必須由正在自動調整規模的工作負載中的 Pod 發出。
  • 指標必須可透過 HTTP 端點存取。端點路徑預設為 /metrics。
  • 指標格式必須符合 Prometheus 標準。
  • 僅支援量測計指標。
  • 根據預設，每個節點最多可公開 50 個不重複的指標。 如需公開更多指標，可以申請更多額外記憶體。
  • 如果您使用的是這項功能的預先發布版本，且 GKE 版本介於 1.36.4-gke.1247000 至 1.37.0-gke.3100000，則適用下列額外規定：
    • Pod 標籤選取器中的標籤名稱不得包含特殊字元。 只能使用 a 到 z 的字母 (不分大小寫)、數字、連字號和底線。
    • 使用依指標標籤篩選時，標籤鍵必須符合規則運算式 ^[a-zA-Z_][a-zA-Z0-9_]* (開頭為英文字母或底線，且只包含英文字母、數字或底線)。
    • 每個叢集最多可公開 20 個不重複的指標。

定義指標

  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 所在的命名空間。
    • 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 物件的命名空間。

    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 擷取自訂或外部指標

您可以從 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 查詢。

視您要擷取自訂指標還是外部指標，選擇下列其中一項設定：

  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 物件的命名空間，必須與要擴展的工作負載命名空間相符。
    • METRIC_NAME：HorizontalPodAutoscaler 物件使用的指標名稱。
    • PROMQL_QUERY：查詢指標的 PromQL 查詢。PromQL 查詢必須傳回向量，其中自動調度資源中的每個 Pod 各有一個項目，例如 Deployment 中的每個 Pod 各有一個項目。

    您可以在單一 AutoscalingMetric 資訊清單中定義多個指標，方法是在 metrics 陣列中新增其他 promql 項目。

    在這個資訊清單中，適用下列事項：

    • type: Pods 欄位表示指標是由 Pod 發出。

    • 選用：metricLabels 欄位是 PromQL 查詢結果中的標籤名稱，會列出資源詳細資料 (例如 Pod 名稱、命名空間或叢集資訊)。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 物件的命名空間，必須與要擴展的工作負載命名空間相符。
    • 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 物件的命名空間。

    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 物件的命名空間，必須與工作負載和 AutoscalingMetric 資源的命名空間相符。
    • DEPLOYMENT_NAME：要擴充的工作負載 Deployment 名稱。
    • MIN_REPLICAS：執行中 Pod 的數量下限。
    • MAX_REPLICAS：執行中的 Pod 數量上限。
    • NAME：您建立的 AutoscalingMetric 自訂資源名稱。
    • METRIC_NAME：在 AutoscalingMetric 資源中定義的指標名稱。
    • AVERAGE_VALUE：自動配置器調整工作負載資源時，所依據的目標指標值。

    建立自己的 HorizontalPodAutoscaler 物件時，請注意下列事項：

    • AutoscalingMetric、Deployment 和 HorizontalPodAutoscaler 物件必須位於相同命名空間。
    • 上述範例使用 type: AverageValue 欄位值組合。請注意，外部指標也支援 type: Value。
    • 上例僅以 Deployment 物件為例。您也可以自動調整 HorizontalPodAutoscaler 物件支援的任何物件，例如 ReplicaSet 物件。

  2. 套用 HorizontalPodAutoscaler 資訊清單：

    kubectl apply -f HPA_MANIFEST_FILE.yaml

    將 HPA_MANIFEST_FILE 替換成 YAML 檔案的名稱。

排解自動調度資源擷取的指標問題

如要排解擷取指標的問題，可以查看記錄或 AutoscalingMetric 自訂資源的狀態。

自動調度資源指標轉接器沒有任何副本

在 kube-system 中檢查 autoscaling-metrics-adapter 部署作業時，您可能會發現該部署作業的副本數為零。

根據預設，轉接程式會以零個副本執行，以節省叢集資源。 請放心，這是正常情況。如果叢集中有需要 PromQL 處理的 AutoscalingMetric 自訂資源，部署作業最多只會擴充至一個副本。

如果您使用 PromQL 查詢設定 AutoscalingMetric 物件，但轉接器未擴充，請確認物件已在叢集中成功建立。

查看記錄

如要找出負責從 Cloud Monitoring 取得指標的控制器問題，您可以查看其記錄。

您可以在 Google Cloud 控制台查看記錄：

  1. 前往「記錄檔探索工具」頁面：

    前往 Logs Explorer

  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 控制台的「指標探索器」頁面。

    前往 Metrics Explorer

  2. 在「查詢建立工具」窗格頂端，選取「PromQL」分頁標籤。

  3. 在查詢編輯器中，輸入要測試的 PromQL 查詢。

  4. 按一下「執行查詢」，即可在圖表上查看指標。

後續步驟