排解水平自動調度 Pod 資源問題

如果 Google Kubernetes Engine (GKE) 的水平自動調度 Pod 資源功能未正常運作,工作負載可能無法正確調度資源。這個問題可能會導致應用程式無法處理負載,進而造成效能問題或服務中斷。您可能會發現,即使 CPU 使用率很高,Pod 數量仍未增加、HorizontalPodAutoscaler 狀態中的指標值顯示為 <unknown>,或完全沒有執行調度資源作業。

本文說明如何診斷及解決水平 Pod 自動調度資源的常見問題,包括 HorizontalPodAutoscaler 的初始設定錯誤,以及指標管道中較複雜的故障。只要按照這些疑難排解步驟操作,就能確保應用程式根據需求有效率且可靠地調度資源。

對於設定 HorizontalPodAutoscaler 且需要確保應用程式正確擴充的應用程式開發人員來說,這項資訊非常重要。此外,平台管理員和操作員也能利用這項功能,排解指標管道或叢集設定的問題,避免影響所有自動調度資源的工作負載。如要進一步瞭解 Google Cloud 內容中提及的常見角色和工作範例,請參閱「常見的 GKE 使用者角色和工作」。

事前準備

  • 請務必搭配可擴充的工作負載 (例如 Deployment 和 StatefulSet) 使用 HorizontalPodAutoscaler 物件。您無法對無法調度資源的工作負載 (例如 DaemonSet) 使用水平自動調度 Pod 資源功能。
  • 如要取得在 GKE 中排解水平 Pod 自動調度資源問題所需的權限,包括檢查 HorizontalPodAutoscaler 物件和查看叢集記錄,請要求管理員在專案中授予您下列 IAM 角色:

    如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。

    您或許也能透過自訂角色或其他預先定義的角色,取得必要權限。

  • 設定 kubectl 指令列工具,與 GKE 叢集通訊:

    gcloud container clusters get-credentials CLUSTER_NAME \
        --location LOCATION \
        --project PROJECT_ID
    

    更改下列內容:

    • CLUSTER_NAME:叢集名稱。
    • LOCATION:叢集的 Compute Engine 區域或可用區 (例如 us-central1 或 us-central1-a)。
    • PROJECT_ID:您的 Google Cloud 專案 ID。

診斷 HorizontalPodAutoscaler 問題

如要診斷 HorizontalPodAutoscaler 的問題,請使用 kubectl 指令或 Google Cloud 控制台檢查狀態和設定。

說明 HorizontalPodAutoscaler

如要查看即時計算結果和最近的調度決策,請使用 kubectl describe hpa 指令:

kubectl describe hpa HPA_NAME -n NAMESPACE_NAME

更改下列內容:

  • HPA_NAME:HorizontalPodAutoscaler 物件的名稱。
  • NAMESPACE_NAME:HorizontalPodAutoscaler 物件的命名空間。

輸出結果會與下列內容相似:

Name:                                                  php-apache-hpa
Namespace:                                             default
Reference:                                             Deployment/php-apache
Metrics: ( current / target )
  resource cpu on pods (as a percentage of request):   1% (1m) / 50%
Min replicas:                                          1
Max replicas:                                          10
Conditions:
  Type            Status  Reason              Message
  ----            ------  ------              -------
  AbleToScale     True    ReadyForNewScale    recommended size matches current size
  ScalingActive   True    ValidMetricFound    the HorizontalPodAutoscaler was able to successfully calculate a replica count
Events:
  Type     Reason              Age   From                       Message
  ----     ------              ----  ----                       -------
  Normal   SuccessfulRescale   39m   horizontal-pod-autoscaler  New size: 4; reason: cpu resource utilization...
  Normal   SuccessfulRescale   26m   horizontal-pod-autoscaler  New size: 1; reason: cpu resource utilization...

輸出內容中的下列三個部分可協助您診斷問題:

  • Metrics:顯示目前的指標值與目標值的比較結果。<unknown> 指標值表示 HorizontalPodAutoscaler 尚未擷取指標,或指標管道已中斷。
  • Conditions:顯示 HorizontalPodAutoscaler 是否能擷取指標 (AbleToScale) 並執行資源調度計算 (ScalingActive)。如果任一條件的狀態為 False,則表示失敗。
  • Events:記錄 HorizontalPodAutoscaler 控制器最近的資源調度動作、警告和錯誤。通常是尋找特定錯誤訊息或原因的第一個地方,例如 FailedGetScale 或 FailedGetResourceMetric。

檢查 HorizontalPodAutoscaler 資訊清單

HorizontalPodAutoscaler 物件的 YAML 資訊清單可讓您查看設定和目前狀態的相關資訊。

如要查看 YAML 資訊清單,請選取下列其中一個選項:

控制台

  1. 前往 Google Cloud 控制台的「Object Browser」(物件瀏覽器) 頁面。

    前往「Object Browser」(物件瀏覽器) 頁面

  2. 在「Object Kinds」(物件種類) 清單中,選取「HorizontalPodAutoscaler」核取方塊,然後按一下「OK」(確定)。

  3. 前往「autoscaling」API 群組,然後點選「HorizontalPodAutoscaler」的展開箭頭。

  4. 按一下要檢查的 HorizontalPodAutoscaler 物件名稱。

  5. 查看「YAML」YAML部分,其中會顯示 HorizontalPodAutoscaler 物件的完整設定。

kubectl

執行下列指令:

kubectl get hpa HPA_NAME -n NAMESPACE_NAME -o yaml

更改下列內容:

  • HPA_NAME:HorizontalPodAutoscaler 物件的名稱。
  • NAMESPACE_NAME:HorizontalPodAutoscaler 物件的命名空間。

擷取資訊清單後,請找出下列重要部分:

  • spec (您的設定):
    • scaleTargetRef:HorizontalPodAutoscaler 設定要調度資源的工作負載 (例如 Deployment)。
    • minReplicas 和 maxReplicas:副本數量下限和上限設定。
    • metrics:為調度資源設定的指標 (例如 CPU 使用率或自訂指標)。
  • status (HorizontalPodAutoscaler 的即時狀態):
    • currentMetrics:HorizontalPodAutoscaler 觀察到的最新指標值。
    • currentReplicas 和 desiredReplicas:目前的 Pod 數量,以及 HorizontalPodAutoscaler 要調整到的數量。
    • conditions:顯示 HorizontalPodAutoscaler 的健康狀態:
      • AbleToScale:指出 HorizontalPodAutoscaler 是否能找到目標和指標。
      • ScalingActive:顯示 HorizontalPodAutoscaler 是否可以計算及執行資源調度。
      • ScalingLimited:指出 HorizontalPodAutoscaler 是否要調度資源,但受到 minReplicas 或 maxReplicas 設定限制。

查看事件記錄

如要深入瞭解 HorizontalPodAutoscaler 物件,請使用下列類型的記錄:

  • 在 Cloud Logging 中查看 HorizontalPodAutoscaler 事件:使用記錄檔篩選器,找出特定叢集的所有 HorizontalPodAutoscaler 事件。例如:

    1. 前往 Google Cloud 控制台的「Logs Explorer」頁面。

      前往 Logs Explorer

    2. 在查詢窗格中輸入下列查詢:

      resource.type="k8s_cluster"
      resource.labels.cluster_name="CLUSTER_NAME"
      resource.labels.location="LOCATION"
      logName="projects/PROJECT_ID/logs/events"
      jsonPayload.involvedObject.kind="HorizontalPodAutoscaler"
      

      更改下列內容:

      • CLUSTER_NAME:HorizontalPodAutoscaler 所屬叢集的名稱。
      • LOCATION:叢集的 Compute Engine 區域或可用區 (例如 us-central1 或 us-central1-a)。
      • PROJECT_ID:您的專案 ID。
    3. 點選「執行查詢」並查看輸出內容。

  • 查看水平自動調度 Pod 資源事件:這些記錄提供結構化、人類可讀的記錄,說明 HorizontalPodAutoscaler 如何計算建議,並詳細說明決策過程。

疑難排解 HorizontalPodAutoscaler 設定錯誤

以下各節將說明 HorizontalPodAutoscaler 資訊清單中的設定錯誤,例如欄位輸入錯誤、指標目標無效或設定衝突。

找不到目標工作負載

問題

Events 區段的條件為 FailedGetScale,訊息類似下列內容:

the HorizontalPodAutoscaler controller was unable to get the target's current scale: WORKLOAD_TYPE.apps "TARGET_WORKLOAD" not found

這項輸出內容包含下列值:

  • WORKLOAD_TYPE:工作負載類型,例如 Deployment 或 StatefulSet。
  • TARGET_WORKLOAD:工作負載的名稱。

原因

HorizontalPodAutoscaler 控制器找不到設定要管理的工作負載 (例如 Deployment 或 StatefulSet)。這是因為 HorizontalPodAutoscaler 資訊清單中的 scaleTargetRef 欄位設定錯誤。指定的資源可能不存在、已刪除或拼寫錯誤。

解析度

請嘗試下列解決方法:

  1. 驗證 HorizontalPodAutoscaler 資訊清單的 scaleTargetRef 欄位:確認 scaleTargetRef 欄位中的 name、kind 和 apiVersion 值與目標工作負載的對應中繼資料完全相符。如果工作負載名稱有誤,請更新 HorizontalPodAutoscaler 的 scaleTargetRef 欄位,指向正確的名稱。
  2. 確認工作負載存在:確認目標工作負載與 HorizontalPodAutoscaler 位於同一個命名空間。您可以使用 kubectl get deployment DEPLOYMENT_NAME 等指令檢查。如果您刻意刪除工作負載,請刪除對應的 HorizontalPodAutoscaler 物件,以清理叢集。如需重新建立工作負載,HorizontalPodAutoscaler 會在工作負載可用後自動找到,並解決錯誤。
  3. 確認 HorizontalPodAutoscaler 和工作負載位於相同命名空間:HorizontalPodAutoscaler 和目標工作負載必須位於相同命名空間。如果使用 kubectl 指令建立物件時,忘記指定命名空間,Kubernetes 會將物件放在 default 命名空間中。如果 HorizontalPodAutoscaler 位於 default 命名空間,而工作負載位於其他命名空間,或反之亦然,這種行為可能會導致不相符。檢查兩個物件的命名空間,確認兩者相符。

HorizontalPodAutoscaler 成功找到目標後,條件 AbleToScale 會變成 True,訊息也會變更為:the HorizontalPodAutoscaler controller was able to get the target's current scale。

無效指標

問題

如果 HorizontalPodAutoscaler 因設定問題而無法計算所需的副本數量,其 Events 區段會顯示 FailedComputeMetricsReplicas 原因,並顯示類似下列的訊息:

invalid metrics (1 invalid out of 1)

原因

這項錯誤通常表示指標 type 與您在 HorizontalPodAutoscaler 資訊清單中定義的 target 不相符。舉例來說,您可能指定了 Utilization 的 type,但提供的目標值是 averageValue,而非 averageUtilization。

解析度

修正 HorizontalPodAutoscaler 資訊清單,讓 target 欄位的值與指標 type 一致:

  • 如果 type 為 Utilization,則 target 欄位的值必須為 averageUtilization。
  • 如果 type 為 AverageValue,則 target 欄位的值必須為 averageValue。

不得使用指標標籤

問題

您會看到下列錯誤:

unable to fetch metrics from external metrics API: googleapi: Error 400: Metric label: 'LABEL_NAME' is not allowed

在這個輸出內容中,LABEL_NAME 是不正確的標籤名稱。

原因

HorizontalPodAutoscaler 資訊清單在 metric.selector.matchLabels 區段中指定了無效的標籤鍵,Cloud Monitoring 無法辨識或不允許這個指標鍵。

解析度

請按照下列步驟解決這個問題:

  1. 從錯誤訊息中找出不允許的標籤名稱。
  2. 請在 HorizontalPodAutoscaler 資訊清單的 metric.selector.matchLabels 部分中,移除或更正這個標籤鍵。
  3. 請參閱該指標的 Cloud Monitoring 說明文件,找出有效且可篩選的標籤鍵。

多個 HorizontalPodAutoscaler 指定相同的工作負載

問題

HorizontalPodAutoscaler 的狀態中沒有任何特定的 Condition 或 Reason 會直接指出這項衝突。而是可能觀察到下列症狀:

  • 工作負載的副本數量可能會意外波動。
  • 調度資源決策可能與任何單一 HorizontalPodAutoscaler 中定義的指標不符。
  • 查看事件時,您可能會看到來自不同 HorizontalPodAutoscaler 物件的交替或矛盾 SuccessfulRescale 事件。

原因

發生這個問題的原因是,同一命名空間內有多個 HorizontalPodAutoscaler 物件在 spec.scaleTargetRef 欄位中指定完全相同的工作負載。每個 HorizontalPodAutoscaler 都會獨立計算副本數量,並嘗試根據自己的指標和目標組合調度工作負載。Kubernetes 不會封鎖這項設定,但會導致不穩定的資源調度調整,因為 HorizontalPodAutoscaler 會互相競爭。

解析度

為避免衝突,請在單一 HorizontalPodAutoscaler 物件中定義所有資源調度指標。每個 HorizontalPodAutoscaler 都會根據自己的 spec.metrics 欄位計算資源調度需求,因此合併後,所選的 HorizontalPodAutoscaler 物件就能一併考量所有因素,例如 CPU 和每秒要求數:

  1. 如要找出哪些 HorizontalPodAutoscaler 指定相同的工作負載,請取得每個 HorizontalPodAutoscaler 物件的 YAML 資訊清單。請特別留意輸出內容中的 spec.scaleTargetRef 欄位。

    kubectl get hpa -n NAMESPACE_NAME -o yaml
    

    將 NAMESPACE_NAME 替換為 HorizontalPodAutoscaler 物件的命名空間。

    找出不同 HorizontalPodAutoscaler 資源在 scaleTargetRef 欄位中,apiVersion、kind 和 name 的值相同。

  2. 將指標整合至單一 HorizontalPodAutoscaler 物件:

    1. 請選擇要保留的 HorizontalPodAutoscaler 物件。您將修改這個 HorizontalPodAutoscaler。
    2. 檢查其他 HorizontalPodAutoscaler 物件 (目標為相同工作負載) 的資訊清單中的 spec.metrics 區段。
    3. 從重複 HorizontalPodAutoscaler 物件的 spec.metrics 區段,複製要保留的指標定義。
    4. 將這些複製的指標定義貼到您決定保留的 HorizontalPodAutoscaler 的 spec.metrics 陣列中。
  3. 套用變更:

    kubectl apply -f MANIFEST_NAME
    

    將 MANIFEST_NAME 替換為您決定保留的 HorizontalPodAutoscaler 資訊清單名稱。

  4. 刪除指定相同工作負載的其他 HorizontalPodAutoscaler 物件:

    kubectl delete hpa DUPLICATE_MANIFEST_NAME -n NAMESPACE_NAME
    

    將 DUPLICATE_MANIFEST_NAME 替換為要刪除的多餘 HorizontalPodAutoscaler 物件名稱。

排解工作負載和 Service 錯誤

以下各節說明由目標工作負載或其相關聯 Service 造成的錯誤,而非 HorizontalPodAutoscaler 物件本身。

缺少資源要求,無法計算資源調度

問題

ScalingActive 條件為 False,Reason 為 FailedGetResourceMetric。通常也會看到類似下方的訊息:

the HorizontalPodAutoscaler was unable to compute the replica count

原因

HorizontalPodAutoscaler 必須以百分比計算資源使用率,才能調度工作負載資源,但 Pod 規格中至少有一個容器缺少對應資源 (cpu 或 memory) 的 resources.requests 定義,因此無法執行這項計算。

解析度

如要解決這個問題,請更新 Deployment、StatefulSet 或其他控制器中的 Pod 資訊清單,為 HorizontalPodAutoscaler 嘗試在 Pod 中「所有」容器上擴充的資源 (cpu 或 memory) 加入 resources.requests 欄位。例如:

apiVersion: v1
kind: Pod
metadata:
  name: example-pod
# Multiple lines are omitted here
spec:
  containers:
  - name: example-container
    resources:
      requests:
        cpu: "100m"
        memory: "128Mi"

無法擷取 Pod 指標

問題

您會看到類似下列的持續訊息:

unable to fetch pod metrics for pod

指標伺服器啟動時,暫時顯示這則訊息是正常現象。

原因

如要根據資源使用率百分比 (例如 cpu 或 memory) 進行調度,HorizontalPodAutoscaler 物件指定的 Pod 內,每個容器都必須為該特定資源定義 resources.requests 欄位。否則,HorizontalPodAutoscaler 無法執行所需的計算,也不會採取與該指標相關的任何動作。

解析度

如果這些錯誤訊息持續出現,且您發現 Pod 未針對工作負載進行資源調度,請確認您已為工作負載中的每個容器指定資源要求。

多項服務選取相同目標

問題

您會看到下列錯誤:

multiple services selecting the same target of HPA_NAME: SERVICE_NAME

這項輸出內容包含下列值:

  • HPA_NAME:HorizontalPodAutoscaler 的名稱。
  • SERVICE_NAME:Service 的名稱。

原因

已設定依流量自動調度資源,但有多個 Kubernetes Service 指定 HorizontalPodAutoscaler 的 scaleTargetRef 欄位。流量型自動調度資源僅支援 Service 與自動調度資源工作負載之間的一對一關係。

解析度

如要修正這個問題,請確保只有一個 Service 的標籤選取器與工作負載的 Pod 相符:

  1. 找出工作負載的 Pod 標籤:

    kubectl get deployment HPA_TARGET_DEPLOYMENT \
        -n NAMESPACE \
        -o jsonpath='{.spec.template.metadata.labels}'
    

    更改下列內容:

    • HPA_TARGET_DEPLOYMENT:HorizontalPodAutoscaler 指定的 Deployment 名稱。
    • NAMESPACE:Deployment 的命名空間。

    輸出結果會與下列內容相似:

    {"app":"my-app", "env":"prod"}
    
  2. 查看命名空間中所有 Service 的 spec.selector 欄位,找出與這些標籤相符的所有 Service。

    kubectl get services -n NAMESPACE -o yaml
    

    找出選取器與上一步標籤相符的所有 Service。舉例來說,{"app": "my-app"} 和 {"app": "my-app", "env": "prod"} 都符合範例 Pod 標籤。

  3. 選擇下列其中一個選項,解決衝突:

    • 在 Deployment 的 spec.template.metadata.labels 欄位中新增不重複的標籤,讓預期 Service 的選取器不重複。接著,更新一個預定 Service 的 spec.selector 欄位,加入這個新標籤。
    • 變更所有「其他」衝突 Service 的 spec.selector 欄位,讓其他 Service 選取器更嚴格,不再與工作負載的 Pod 相符。
  4. 套用變更:

    kubectl apply -f MANIFEST_NAME
    

    將 MANIFEST_NAME 替換為 YAML 檔案名稱,該檔案應包含更新後的 Service 或 Deployment 資訊清單。

排解指標 API 和資料可用性問題

以下各節可協助您解決 HorizontalPodAutoscaler 嘗試與 Metrics API 通訊或查詢指標後端時發生的錯誤。

排解自訂和外部指標問題

如果 HorizontalPodAutoscaler 依賴預設 CPU 或記憶體以外來源的指標,自訂或外部指標管道可能會發生問題。這個管道包含 HorizontalPodAutoscaler 控制器、Kubernetes 指標 API 伺服器、指標轉接器和指標來源 (例如 Cloud Monitoring 或 Prometheus),如下圖所示:

HPA 指標管道,顯示元件:HPA 控制器、Kubernetes API 伺服器、指標轉接器和指標來源。

問題

指標管道發生問題時,最常見的症狀如下:

  • 指標值會顯示為 <unknown>。
  • HorizontalPodAutoscaler 事件顯示 FailedGetExternalMetric 或 FailedGetCustomMetric 等錯誤。

原因

自訂或外部指標管道發生問題。

解析度

請按照下列步驟對管道進行偵錯:

  1. 檢查指標轉接器是否已註冊且可用:指標轉接器必須向主要 Kubernetes API 伺服器註冊,才能提供指標。這個動作是最直接的方法,可確認轉接器是否正在運作,且可由 API 伺服器連線:

    kubectl get apiservice | grep -E 'NAME|metrics.k8s.io'
    

    輸出內容應會顯示 v1beta1.custom.metrics.k8s.io 或 v1beta1.external.metrics.k8s.io 項目,且 Available 欄的值為 True。例如:

    NAME                   SERVICE                      AVAILABLE   AGE
    v1beta1.metrics.k8s.io kube-system/metrics-server   True        18d
    
    • 如果 Available 欄中的值為 False 或缺少值,表示轉接程式可能當機或設定錯誤。請檢查 kube-system 或 custom-metrics 命名空間中的轉接器 Pod 記錄,查看是否有權限、指標來源網路連線相關錯誤,或指出找不到指標的訊息。

    • 如果值為 True,請繼續下一個步驟。

  2. 直接查詢指標 API:如果轉接器可用,請略過 HorizontalPodAutoscaler,直接向 Kubernetes API 查詢指標。這個指令會測試整個管道,從 API 伺服器到指標轉接器,再到資料來源。

    如要查詢外部指標,請執行下列指令:

    kubectl get --raw "/apis/external.metrics.k8s.io/v1beta1/namespaces/NAMESPACE_NAME/METRIC_NAME" | jq .
    

    如要查詢自訂 Pod 指標,請執行下列指令:

    kubectl get --raw "/apis/custom.metrics.k8s.io/v1beta1/namespaces/NAMESPACE_NAME/pods/*/METRIC_NAME" | jq .
    

    更改下列內容:

    • NAMESPACE_NAME:Pod 執行的命名空間。
    • METRIC_NAME:要查詢的自訂或外部指標名稱。例如:requests_per_second 或 queue_depth。
  3. 分析指令輸出內容:先前指令的結果會指出問題所在。請根據輸出內容選擇相符的情境:

    • JSON 回應成功且有值:指標管道運作正常。問題可能出在 HorizontalPodAutoscaler 資訊清單的設定。請檢查指標名稱是否有拼寫錯誤,或 matchLabels 是否不正確。
    • Error: Error from server (Service Unavailable):這項錯誤通常表示網路連線問題,在採用網路隔離機制的叢集中,這通常是防火牆問題。

      1. 找出指標轉接器 Service。通常位於 custom-metrics 或 kube-system 命名空間:

        kubectl get service -n custom-metrics,kube-system | grep -E 'adapter|metrics'
        
      2. 找出轉接器監聽的通訊埠:

        kubectl get service ADAPTER_SERVICE -n ADAPTER_NAMESPACE -o yaml
        

        更改下列內容:

        • ADAPTER_SERVICE:與您部署的指標轉接器相關聯的 Kubernetes Service 名稱。這個 Service 是您在上一個步驟中找到的 Service。這項 Service 會將轉接器的功能公開給叢集的其他部分,包括 Kubernetes API 伺服器。
        • ADAPTER_NAMESPACE:轉接器服務所在的命名空間 (例如 custom-metrics 或 kube-system)。
      3. 找出叢集控制層的傳入防火牆規則:

        gcloud compute firewall-rules list \
            --filter="name~gke-CLUSTER_NAME-[0-9a-z]*-master"
        

        將 CLUSTER_NAME 替換為叢集名稱。

      4. 將轉接程式的 targetPort 新增至規則:

        1. 說明目前的規則,查看現有的允許通訊埠:

          gcloud compute firewall-rules describe FIREWALL_RULE_NAME
          

          將 FIREWALL_RULE_NAME 替換為防火牆規則名稱,該規則會控管傳送至 Kubernetes 叢集控制層的網路流量。

        2. 更新規則,將轉接器通訊埠新增至清單:

          gcloud compute firewall-rules update FIREWALL_RULE_NAME \
              --allow tcp:443,tcp:10250,tcp:ADAPTER_PORT
          

          將 ADAPTER_PORT 替換為指標轉接器監聽的網路通訊埠。

      5. 確認 Kubernetes 網路政策未封鎖傳送至指標轉接器 Pod 的流量:

        kubectl get networkpolicy -n custom-metrics,kube-system
        

        查看所有政策,確認政策允許從控制層或 API 伺服器,傳入輸入流量至 ADAPTER_PORT 上的 ADAPTER_SERVICE。

    • 空白清單 []:這個輸出內容表示轉接器正在執行,但無法擷取特定指標,表示轉接器的設定或指標來源本身有問題。

      • 轉接器 Pod 問題:檢查指標轉接器 Pod 的記錄,找出與 API 呼叫、驗證或指標擷取相關的錯誤。如要檢查記錄,請按照下列步驟操作:

        1. 找出轉接器 Pod 的名稱:

          kubectl get pods -n ADAPTER_NAMESPACE
          
        2. 查看記錄:

          kubectl logs ADAPTER_POD_NAME \
              -n ADAPTER_NAMESPACE
          

          更改下列內容:

          • ADAPTER_POD_NAME:您在上一個步驟中找到的轉接器 Pod 名稱。
          • ADAPTER_NAMESPACE:轉接器 Pod 所在的命名空間 (例如 custom-metrics 或 kube-system)。
      • 來源沒有資料:來源系統中可能沒有該指標。使用 Metrics Explorer 等監控工具,確認指標存在,且名稱和標籤正確。

找不到指標版本或轉接程式無法使用

問題

您會看到下列錯誤:

unable to fetch metrics from custom metrics API: no known available metric versions found

原因

這項錯誤表示叢集內通訊中斷,而非指標來源 (例如 Cloud Monitoring) 發生問題。常見原因包括:

  • Kubernetes API 伺服器暫時無法使用 (例如在叢集升級或控制層修復期間)。
  • 指標轉接器 Pod (例如 custom-metrics-stackdriver-adapter) 運作不正常、未執行,或未正確向 API 伺服器註冊。

解析度

這通常是暫時性問題。如果問題仍未解決,請嘗試下列解決方案:

  1. 檢查 Kubernetes 控制層的健康狀態:

    1. 在 Google Cloud 控制台查看叢集的健康狀態。

      1. 前往「Kubernetes clusters」(Kubernetes 叢集) 頁面。

        前往「Kubernetes clusters」(Kubernetes 叢集)

    2. 查看叢集的「狀態」和「通知」欄。

    3. 按一下「 通知」,查看是否有任何進行中的作業,例如升級或修復。在這段期間,API 伺服器可能會短暫無法使用。

    4. 查看 Cloud 稽核記錄,找出與控制層元件相關的錯誤。如要瞭解如何查看這些記錄,請參閱「GKE 稽核記錄資訊」。

  2. 檢查指標轉接器 Pod 的健康狀態和記錄:確認指標轉接器 Pod 處於 Running 狀態,且最近沒有重新啟動:

    kubectl get pods -n custom-metrics,kube-system -o wide
    

    如果 Pod 的狀態不是 Running,或重新啟動次數過多,請調查 Pod 以找出根本原因。如需疑難排解提示,請參閱 Kubernetes 說明文件中的「偵錯 Pod」。

  3. 確認 Metrics API 已註冊且可供使用:

    kubectl get apiservice | grep metrics.k8s.io
    

    如果 Metrics API 運作正常,輸出內容會與下列內容相似:

    NAME                            SERVICE                                             AVAILABLE   AGE
    v1beta1.custom.metrics.k8s.io   custom-metrics/custom-metrics-stackdriver-adapter   True        18d
    v1beta1.external.metrics.k8s.io custom-metrics/custom-metrics-stackdriver-adapter   True        18d
    v1beta1.metrics.k8s.io          kube-system/metrics-server                          True        18d
    

    如果 AVAILABLE 欄的值為 False,完整 APIService 資訊清單中的 Message 欄可能會提供更多詳細資料。

    您可以使用下列指令查看完整資訊清單:

    kubectl get apiservice API_SERVICE_NAME -o yaml
    

    將 API_SERVICE_NAME 替換為 APIService 物件的名稱,例如 v1beta1.custom.metrics.k8s.io。

指標查詢未傳回任何時間序列

問題

您會看到下列錯誤:

unable to fetch metrics from custom or external metrics API: googleapi: Error
400: The supplied filter [...] query will not return any time series

原因

傳送至 Cloud Monitoring 的查詢有效,但未傳回任何資料。這表示沒有符合篩選條件的資料點 (這與找到值為 0 的指標不同)。這個問題最可能的原因是,負責產生自訂指標的應用程式或工作負載在回報錯誤期間,並未將資料寫入 Cloud Monitoring。

解析度

請嘗試下列解決方法:

  1. 驗證設定:確認 HorizontalPodAutoscaler 物件中的指標名稱和標籤,與應用程式發出的名稱和標籤完全一致。
  2. 檢查權限:確認應用程式已正確設定,具備將指標發布至 Cloud Monitoring 的必要權限和 API 端點。
  3. 確認應用程式活動:確認負責指標的應用程式在 HorizontalPodAutoscaler 警告發生期間正常運作,並嘗試將資料傳送至 Cloud Monitoring。
  4. 調查錯誤:檢查同一時間範圍內的應用程式記錄,找出與指標發送相關的明確錯誤,例如連線失敗、憑證無效或格式問題。

排解健康狀態良好但非預期的調度資源行為

以下各節說明 HorizontalPodAutoscaler 設定有效且指標可用,但資源調度動作未如預期執行的情況。

HorizontalPodAutoscaler 狀態良好,但無法調度資源

問題

HorizontalPodAutoscaler 似乎健康狀態良好,其條件報告 True,且事件中未顯示任何錯誤。不過,系統仍不會採取任何資源調度動作。

原因

有幾個因素會導致這種預期行為:

  • 副本限制:目前的副本數量已達到 HorizontalPodAutoscaler 設定中 minReplicas 或 maxReplicas 欄位設定的邊界。
  • 容許範圍:Kubernetes 預設會使用 10% 的容許範圍,避免因指標微幅波動而調整資源。只有在目前指標與目標指標的比率超出 0.9 到 1.1 的範圍時,才會進行資源調度。舉例來說,如果目標是 85% CPU,而目前用量為 93%,則比率約為 1.094 (93/85≈1.094)。由於這個值小於 1.1,HorizontalPodAutoscaler 不會向上調度資源。
  • 未就緒的 Pod:HorizontalPodAutoscaler 只會將狀態為 Ready 的 Pod 納入資源調度計算。如果 Pod 卡在 Pending 狀態,或因健康狀態檢查失敗或資源問題而無法進入 Ready 狀態,系統會忽略這些 Pod,且可能無法進行資源調度。
  • 同步處理週期延遲:HorizontalPodAutoscaler 控制器會定期檢查指標。指標超過門檻到開始調度資源之間,延遲 15 到 30 秒是正常現象。
  • 新指標延遲時間:HorizontalPodAutoscaler 首次使用新的自訂指標時,可能會出現一次幾分鐘的延遲。之所以會發生這種延遲,是因為監控系統 (例如 Cloud Monitoring) 必須在寫入第一個資料點時建立新的時間序列。
  • 多項指標計算:設定多項指標時,HorizontalPodAutoscaler 會獨立計算每項指標所需的副本數量,然後選擇最高的計算值做為最終副本數量。由於這種行為,工作負載會擴充,以滿足需求最高的指標。舉例來說,如果 CPU 指標計算出需要 9 個副本,但每秒要求數指標計算出需要 15 個副本,HorizontalPodAutoscaler 會將 Deployment 擴充至 15 個副本。

解析度

請嘗試下列解決方法:

  • 副本限制:檢查 HorizontalPodAutoscaler 資訊清單或 kubectl describe 指令輸出內容中的 minReplicas 和 maxReplicas 值。如果這些限制導致無法進行必要調度資源,請調整限制。
  • 容許範圍:如需在預設容許範圍內調度資源,請設定不同的容許值。否則,請等待指標超出 0.9 到 1.1 的比率範圍。
  • 未就緒的 Pod:調查 Pod 為何處於 Pending 狀態或未處於 Ready 狀態,並解決根本問題 (例如資源限制、readiness 探測失敗)。如需疑難排解提示,請參閱 Kubernetes 說明文件中的「偵錯 Pod」。
  • 同步週期延遲和新指標延遲:這些延遲屬於正常現象。 等待同步處理期完成,或建立新的自訂指標時間序列。
  • 多項指標計算:這是預期行為。如果系統根據某項指標 (例如每秒要求數) 向上調度資源,則會正確覆寫另一項指標 (例如 CPU) 的較低計算結果。

HorizontalPodAutoscaler 無法縮減

問題

HorizontalPodAutoscaler 成功擴充工作負載,但即使 CPU 使用率等指標偏低,也無法縮減工作負載。

原因

這項行為旨在防止根據不完整的資訊快速擴充及縮減資源,或縮減資源。主要原因如下:

  • 使用多項指標:HorizontalPodAutoscaler 會根據需要最多副本的指標進行調度資源。如果您有多項指標,除非「所有」指標都指出需要減少副本數量,否則工作負載不會縮減。只要有一項指標需要大量副本,即使其他指標偏低,也無法縮減資源。
  • 無法使用的指標:如果任何指標無法使用 (通常顯示為 <unknown>),HorizontalPodAutoscaler 會保守地拒絕縮減工作負載。系統無法判斷指標遺失的原因,究竟是因為用量確實為零,還是指標管道中斷。這類問題常見於以速率為基礎的自訂指標 (例如 messages_per_second),這類指標在沒有活動時可能會停止回報資料,導致 HorizontalPodAutoscaler 認為指標無法使用,並停止縮減作業。
  • 縮減資源延遲時間 (來自資源調度政策):HorizontalPodAutoscaler 的 behavior 欄位可讓您設定資源調度政策。縮減資源的預設政策包含 300 秒 (五分鐘) 的穩定期。在這段期間,即使指標值低於目標門檻,HorizontalPodAutoscaler 也不會減少副本數量。這個時間範圍可防止快速波動,但可能會導致縮減速度比預期慢。

解析度

請嘗試下列解決方法:

  1. 如果有多個指標和無法使用的指標,請診斷造成問題的指標:

    kubectl describe hpa HPA_NAME -n NAMESPACE_NAME
    

    在輸出結果中,查看 Metrics 區段中是否有任何狀態為 <unknown> 的指標,並在 Events 區段中查看是否有 FailedGetCustomMetric 或 FailedGetExternalMetric 等警告。如要進一步偵錯管道,請參閱「排解自訂和外部指標問題」一節。

  2. 如果指標在流量偏低期間無法使用 (常見於比率指標),請嘗試下列任一解決方案:

    • 盡可能使用以量測計為基礎的指標,而非以比率為基礎的指標。計量指標 (例如佇列中的訊息總數,例如 subscription 或 num_undelivered_messages) 會持續回報值,即使該值為 0 也一樣,讓 HorizontalPodAutoscaler 能夠可靠地做出調度資源決策。
    • 請確認指標來源回報的值為零。如果您控管自訂指標,請將其設定為在閒置期間發布 0,而不是完全不傳送資料。
  3. 如果縮減政策的縮減延遲時間過長 (預設為五分鐘),請自訂穩定時間範圍。檢查 HorizontalPodAutoscaler 資訊清單的 spec.behavior.scaleDown 區段。您可以降低stabilizationWindowSeconds,讓自動配置器在指標下降後更快縮減資源。如要進一步瞭解如何設定這些政策,請參閱 Kubernetes 說明文件中的「Scaling Policies」(資源調度政策)。

排解使用 HPA 將 GKE 工作負載資源調度至零或從零調度的問題

在 GKE 1.37 以上版本中,您可以使用 HPA 將工作負載縮減至零或從零擴充 (minReplicas: 0)。本節說明如何診斷設定這類工作負載時發生的問題。

工作負載不會縮減為零

如果需求降至零時,工作負載仍有一或多個副本,請檢查下列事項:

  1. 檢查 minReplicas:確認 HorizontalPodAutoscaler 資訊清單中已設定 minReplicas: 0 欄位值組合。
  2. 檢查指標類型:如果 HPA 僅使用 CPU 或記憶體 (Resource) 指標,就無法將資源調度率降至零。您至少須設定一個 External 或 Object 指標。
  3. 檢查多項指標:HPA 會根據需要最多副本數的指標進行調度資源。如果您設定多項指標,除非每項監控指標的評估結果均為零,否則工作負載不會縮減至零。
  4. 等待縮減穩定時間範圍:根據預設,GKE 會等待五分鐘 (scaleDown.stabilizationWindowSeconds: 300) 的連續零需求,然後才將一個副本縮減為零。
  5. 檢查是否有無法使用的指標:如果任何指標的值顯示為 <unknown>,HPA 會暫停縮減作業,避免過早縮減。詳情請參閱「排解水平 Pod 自動配置器無法縮減資源的問題」。

工作負載不會從零開始擴充

如果需求增加時,工作負載仍維持零個副本,請檢查下列事項:

  1. 檢查 HorizontalPodAutoscaler:執行 kubectl describe hpa HPA_NAME 指令,並檢查輸出內容中的下列部分:

    • 「指標」部分:確認指標值大於零,且不顯示為 <unknown>。如果指標遺失或未更新,請確認外部來源 (例如 Pub/Sub) 是否正在發布事件,以及 Cloud Monitoring 是否正在接收事件。
    • 「條件」部分:
      • 健康的零副本狀態:確認條件顯示 AbleToScale: True、ScalingActive: True 和 ScaledToZero: True (原因為 ScaledToZero)。在這種狀態下,GKE 會在需求增加時自動調度資源來擴充工作負載。
      • 偵測到外部覆寫:檢查 ScalingActive 條件的值是否為 False,且原因為 ScalingDisabledExternalScaleToZero 或 ScalingDisabledReplicaCountZero,這表示工作負載已手動縮減為零。舉例來說,如果使用 kubectl scale 指令手動調度工作負載資源,系統會暫停自動調度資源,以免發生不一致的變更。
    • 解決方法:如要繼續自動調度資源,請手動將 Deployment 資源調度回一或多個副本:

      kubectl scale deployment DEPLOYMENT_NAME --replicas=1
      
  2. 檢查冷啟動延遲時間:如果工作負載啟動速度緩慢,節點佈建作業可能會增加延遲時間。為確保從零開始擴充時,有備用運算資源可用,建議使用運算資源緩衝區。

後續步驟