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

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

如要擷取指標，請使用受管理指標轉接程式。這項代管解決方案適用於 Cloud Monitoring 中可使用 PromQL 查詢的指標，以及所有自訂指標。自訂指標是 Pod 在 HTTP 端點下以 Prometheus 格式公開的指標。

或者，如要使用任何指標自動調度資源，您可以手動設定指標轉接程式，將指標傳送至自動調度器，藉此擷取指標。這項工作流程包括安裝第三方轉接程式 (例如自訂指標轉接程式)，以及設定權限。舉例來說，請參閱根據指標最佳化 Pod 自動調度教學課程。

擷取指標

您可以透過下列方式擷取指標：

• 您可以在叢集內擷取 Pod 發出的自訂指標。這些指標可用於自動調度，不必透過 Cloud Monitoring 等監控系統傳輸。
• 您可以使用 PromQL 查詢，擷取儲存在 Cloud Monitoring 中的 Pod 指標。這些指標是由 Pod 發出，並匯出至 Cloud Monitoring，通常是使用 Google Cloud Managed Service for Prometheus。相較於先前的做法，這種方法可讓您使用 PromQL 功能，例如計算百分位數或讀取歷史值。
• 您可以使用 PromQL 查詢，從 Cloud Monitoring 擷取外部指標。
• 您可以手動設定指標轉接器，將指標傳送至自動配置器，藉此擷取指標。這項工作流程包括安裝第三方工具和設定權限。舉例來說，請參閱根據指標最佳化 Pod 自動調度教學課程。

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

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

擷取叢集內的自訂指標

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

需求條件

Pod 的規定如下：

• GKE 1.35.1-gke.1396000 以上版本，且叢集位於搶鮮版。
• 搭配效能設定檔使用水平自動調度 Pod 資源。

指標必須符合下列條件：

• 指標必須可透過 HTTP 端點存取。端點路徑預設為 /metrics。
• 指標格式必須符合 Prometheus 標準。
• 系統僅支援測量指標。
• 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。系統每隔幾秒就會讀取指標，並傳送至工作負載自動調整程式。

從 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 物件，並定義要擷取的指標。

   自訂指標 (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 取得指標的控制器問題，可以查看其記錄。

您可以在 Cloud de Confiance 控制台中查看記錄：

1. 前往「Logs Explorer」頁面：

   前往 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. 前往 Cloud de Confiance 控制台的「Metrics Explorer」頁面。

   前往「Metrics Explorer」頁面

2. 在「查詢產生器」窗格頂端，選取「PromQL」分頁標籤。

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

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

後續步驟

• 如要瞭解如何根據指標自動調度資源，請參閱「根據指標自動調度工作負載資源」一文。
• 如要使用無法透過 PromQL 查詢定義的指標自動調度資源，請參閱根據指標調整 Pod 自動調度功能。