收集及查看 kube 狀態指標

本頁說明如何設定 Google Kubernetes Engine (GKE) 叢集，透過 Google Cloud Managed Service for Prometheus 將精選的 Kube 狀態 (包括 Pod 和 Deployment 的指標) 傳送至 Cloud Monitoring。本頁面也會說明這些指標寫入 Monitoring 時的格式，以及如何查詢指標。

事前準備

開始之前，請確認你已完成下列工作：

• 啟用 Google Kubernetes Engine API。
啟用 Google Kubernetes Engine API
• 如要使用 Google Cloud CLI 執行這項工作，請安裝並初始化 gcloud CLI。如果您先前已安裝 gcloud CLI，請執行 gcloud components update，取得最新版本。

需求條件

如要收集 Kube State Metrics，GKE 叢集必須符合下列條件：

• 叢集必須執行下列版本，具體取決於您要啟用的指標：
  • 如要啟用 JobSet 指標套件，叢集必須執行 1.32.1-gke.1357001 以上版本。從 1.32.1-gke.1357001 版開始，新建立的 GKE Standard 和 Autopilot 叢集預設會啟用 JobSet 指標套件。
  • kube_jobset_restarts 指標適用於 1.32 叢集 (1.32.4-gke.1767000 以上版本)，以及 1.33 叢集 (1.33.0-gke.1868000 以上版本)。
  • 如要啟用本頁面說明的任何其他指標套件，叢集必須執行 GKE 1.27.2-gke.1200 以上版本。從 GKE Standard 叢集的 1.29.2-gke.2000 版，以及 GKE Autopilot 叢集的 1.27.4-gke.900 版開始，系統預設會啟用 Kube 狀態指標套件。
• 叢集必須啟用系統指標。
• 叢集必須啟用 Google Cloud Managed Service for Prometheus 代管收集作業。新叢集會預設啟用 Google Cloud Managed Service for Prometheus 代管收集功能。

設定收集 Kube State Metrics

您可以使用 Google Cloud 控制台、gcloud CLI 或 Terraform 啟用 kube 狀態指標：

gcloud container clusters update CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --enable-managed-prometheus \
    --monitoring=SYSTEM,DAEMONSET,DEPLOYMENT,HPA,POD,STATEFULSET,STORAGE

配額

Kube 狀態指標會耗用 Cloud Monitoring API 的「每分鐘時間序列擷取要求數」配額。啟用 Kube State Metrics 前，請檢查該配額最近的尖峰用量。如果同一個專案中有多個叢集，或已接近配額上限，請先要求增加配額上限，再啟用任一可觀測性套件。

定價

Kube 狀態指標會使用 Google Cloud Managed Service for Prometheus，將指標載入 Cloud Monitoring。Cloud Monitoring 會根據擷取的樣本數，收取擷取這些指標的費用。不過，如果專案已啟用 GKE Enterprise 版本，則已註冊的叢集可免費使用這些指標。

詳情請參閱 Cloud Monitoring 定價。

指標格式

寫入 Cloud Monitoring 的所有 Kubernetes kube 狀態指標都會使用資源類型 prometheus_target。每個指標名稱都以 prometheus.googleapis.com/ 為前置字串，並加上後置字串來表示 Prometheus 指標類型，例如 /gauge、/histogram 或 /counter。否則，每個指標名稱都會與開放原始碼 Kubernetes 公開的指標名稱相同。

從 Cloud Monitoring 匯出

您可以使用 Cloud Monitoring API，從 Cloud Monitoring 匯出 kube 狀態指標。 由於所有 Kube State 指標都是使用 Google Cloud Managed Service for Prometheus 擷取，因此可以使用 Prometheus 查詢語言 (PromQL) 查詢 Kube State 指標。您也可以使用 Monitoring Query Language (MQL) 查詢這些指標。

查詢指標

查詢 kube 狀態指標時，您使用的名稱取決於是否使用 PromQL，或是以 Cloud Monitoring 為基礎的功能，例如 MQL 或 Metrics Explorer 選單導向介面。

下表顯示 kube 狀態指標的兩個版本，每個指標名稱各有一個版本：

• PromQL 指標名稱：在 Google Cloud 控制台的 Cloud Monitoring 頁面使用 PromQL，或在 Cloud Monitoring API 的 PromQL 欄位中，請使用 PromQL 指標名稱。
• Cloud Monitoring 指標名稱：使用其他 Cloud Monitoring 功能時，請使用下表中的 Cloud Monitoring 指標名稱。這個名稱必須加上 prometheus.googleapis.com/ 前置字串，但表格中的項目已省略這個字串。

儲存空間指標

這個表格中的 Cloud Monitoring 指標名稱必須加上 prometheus.googleapis.com/ 前置字元。表格中的項目已省略該前置字串。

詳情請參閱「PersistentVolume 指標」和「PersistentVolumeClaim 指標」這兩篇文章。

Pod 指標

Pod 是一組一或多個容器，其中包含容器的執行方式規格，並共用儲存空間和網路資源。

Pod 指標表

您可以透過 Pod 指標監控 Pod 的行為並設定相關快訊。下表列出 kube 狀態指標套件提供的指標。

這個表格中的 Cloud Monitoring 指標名稱必須加上 prometheus.googleapis.com/ 前置字元。表格中的項目已省略該前置字串。

詳情請參閱「Pod 指標」。

廣告連播指標的查詢範例

如要判斷是否有無法排程的 Pod，請使用下列 PromQL 運算式：

sum(kube_pod_status_unschedulable{cluster="CLUSTER", namespace="NAMESPACE"})

如要針對命名空間中無法排程的 Pod 數量發出快訊，可以使用下列 PromQL 運算式：

sum(kube_pod_status_unschedulable{cluster="CLUSTER", namespace="NAMESPACE"}) > LIMIT

您可以使用 kube_pod_container_status_waiting_reason 指標，透過類似下列的 PromQL 運算式，為處於特定等待狀態的容器建立快訊：

max_over_time(kube_pod_container_status_waiting_reason{reason="REASON", cluster="CLUSTER", namespace="NAMESPACE"}[5m]) >= 1

REASON 的值會指定容器的等待狀態，例如：

• CrashLoopBackOff
• ImagePullBackOff
• ContainerCreating

如要針對處於任何等待狀態的容器建立快訊，請使用下列 PromQL 運算式：

max_over_time(kube_pod_container_status_waiting_reason{cluster="CLUSTER", namespace="NAMESPACE"}[5m]) >= 1

如要判斷有多少容器的完備性檢查失敗，請使用下列 PromQL 運算式

sum(kube_pod_container_status_ready) by (pod, container) == 0

本節中的部分查詢和警報運算式，改編自 GitHub 上 Prometheus 社群 Kubernetes Helm Charts 存放區的 kubernetes-apps.yaml 檔案。

互動式應對手冊

GKE 互動式應對手冊也會使用 Kube 狀態指標，協助排解無法排程或進入 CrashLoopBackOff 狀態的 Pod 問題。如要進一步瞭解這些故障模式，請參閱下列疑難排解文件：

• Pod 當機循環
• 無法排程的 Pod

如果未啟用 Kube State Metrics 套件，偵測 Pod 排程問題的主要方式是查詢「Failed Scheduling」記錄事件。啟用 kube state metrics 套件後，您可以使用 kube_pod_status_unschedulable 指標，這個指標的用途相同，但更容易彙整及繪製圖表。您可以透過這項指標，瞭解無法排程的 Pod 數量，以及問題的發生時間。

同樣地，GKE 系統指標 kubernetes.io/container/restart_count 可協助您偵測發生 CrashLoopBackOff 錯誤的 Pod。kube_pod_container_status_waiting_reason 指標也會列舉發生 CrashLoopBackOff 錯誤的 Pod，並協助您判斷 Pod 是否處於 CrashLookBackOff 以外的等待狀態，例如 ImagePullBackOff 和 ContainerCreating。

如要探索互動式教戰手冊，請按照下列步驟操作：

1. 在 Google Cloud 控制台中，前往「Dashboards」(資訊主頁)  頁面：

   前往「Dashboards」(資訊主頁)

   如果您是使用搜尋列尋找這個頁面，請選取子標題為「Monitoring」的結果。

2. 按一下「GCP」類別，篩選資訊主頁清單。
3. 在清單中按一下「GKE Interactive Playbook」資訊主頁的名稱。

部署指標

Deployment 是一種控制器，可更新 Pod 等資源的狀態，以管理推出和關閉等事件。

部署指標表

您可以透過 Deployment 指標監控及發出控制器行為的快訊。下表列出 kube 狀態指標套件提供的指標：

這個表格中的 Cloud Monitoring 指標名稱必須加上 prometheus.googleapis.com/ 前置字元。表格中的項目已省略該前置字串。

詳情請參閱部署指標。

部署指標的範例查詢

您可以依叢集、命名空間和 Deployment 名稱篩選 Deployment 指標，為個別 Deployment 建立圖表和警報政策。

舉例來說，如要比較單一 Deployment 中可用的副本數量與預期副本數量，可以使用下列 PromQL 查詢，在單一圖表上繪製這兩項指標：

kube_deployment_spec_replicas{cluster="CLUSTER", namespace="NAMESPACE", deployment=DEPLOYMENT"}

kube_deployment_status_replicas_available{cluster="CLUSTER", namespace="NAMESPACE", deployment=DEPLOYMENT"}

如要在 Deployment 失敗或停滯時發出快訊，可以使用下列 PromQL 運算式：

(
  kube_deployment_spec_replicas{cluster="CLUSTER", namespace="NAMESPACE", deployment="DEPLOYMENT"}
    >
  kube_deployment_status_replicas_available{cluster="CLUSTER", namespace="NAMESPACE", deployment="DEPLOYMENT"}
) and (
  changes(kube_deployment_status_replicas_updated{cluster="CLUSTER", namespace="NAMESPACE", deployment="DEPLOYMENT"}[10m])
    ==
  0
)

本節中的部分查詢和警報運算式，改編自 GitHub 上 Prometheus 社群 Kubernetes Helm Charts 存放區的 kubernetes-apps.yaml 檔案。

StatefulSet 指標

StatefulSet 是一種控制器，可管理有狀態應用程式的一組 Pod 的部署和資源調度作業。這個控制器會管理 Pod 的順序和獨特性。

StatefulSet 指標表

您可以透過 StatefulSet 指標監控及發出控制器行為的快訊。下表列出 kube 狀態指標套件提供的指標：

這個表格中的 Cloud Monitoring 指標名稱必須加上 prometheus.googleapis.com/ 前置字元。表格中的項目已省略該前置字串。

詳情請參閱「StatefulSet 指標」。

StatefulSet 指標的查詢範例

您可以依叢集、命名空間和 StatefulSet 名稱篩選 StatefulSet 指標，為個別 StatefulSet 建立圖表和快訊政策。

舉例來說，如要比較單一 StatefulSet 中可用的副本數量與預期副本數量，可以使用下列 PromQL 查詢，在單一圖表上繪製這兩項指標：

kube_statefulset_replicas{cluster="CLUSTER", namespace="NAMESPACE", statefulset="STATEFULSET"}

kube_statefulset_status_replicas_ready{cluster="CLUSTER", namespace="NAMESPACE", statefulset="STATEFULSET"}

如要在 StatefulSet 發布作業失敗或停滯時發出快訊，可以使用下列 PromQL 運算式：

(
  kube_statefulset_replicas{cluster="CLUSTER", namespace="NAMESPACE", statefulset="STATEFULSET"}
    >
  kube_statefulset_status_replicas_ready{cluster="CLUSTER", namespace="NAMESPACE", statefulset="STATEFULSET"}
) and (
  changes(kube_statefulset_status_replicas_updated{cluster="CLUSTER", namespace="NAMESPACE", statefulset="STATEFULSET"}[10m])
    ==
  0
)

本節中的部分查詢和警報運算式，改編自 GitHub 上 Prometheus 社群 Kubernetes Helm Charts 存放區的 kubernetes-apps.yaml 檔案。

DaemonSet 指標

DaemonSet 是一種控制器，可確保一組節點執行 Pod 的副本。舉例來說，將節點新增至叢集時，DaemonSet 會將 Pod 新增至節點。這個控制器可確保特定程序在每個節點上執行。

DaemonSet 指標表

您可以透過 DaemonSet 指標監控及提醒控制器行為。下表列出 kube 狀態指標套件提供的指標：

這個表格中的 Cloud Monitoring 指標名稱必須加上 prometheus.googleapis.com/ 前置字元。表格中的項目已省略該前置字串。

詳情請參閱「DaemonSet 指標」。

DaemonSet 指標的範例查詢

您可以依叢集、命名空間和 DaemonSet 名稱篩選 DaemonSet 指標，為個別 DaemonSet 建立圖表和警報政策。

舉例來說，如要比較單一 DaemonSet 中可用的副本數量與預期副本數量，您可以使用下列 PromQL 查詢，在單一圖表上繪製這兩項指標：

kube_daemonset_status_updated_number_scheduled{cluster="CLUSTER", namespace="NAMESPACE", daemonsetset=DAEMONSET"}

kube_daemonset_status_desired_number_scheduled{cluster="CLUSTER", namespace="NAMESPACE", daemonset=DAEMONSET"}

如要針對失敗或停滯的 DaemonSet 推出作業發出快訊，可以使用下列 PromQL 運算式：

(
  (
    kube_daemonset_status_number_misscheduled{cluster="CLUSTER", namespace="NAMESPACE", daemonset="DAEMONSET"}
      !=
    0
  ) or (
    kube_daemonset_status_updated_number_scheduled{cluster="CLUSTER", namespace="NAMESPACE", daemonset="DAEMONSET"}
      !=
    kube_daemonset_status_desired_number_scheduled{cluster="CLUSTER", namespace="NAMESPACE", daemonset="DAEMONSET"}
  )
) and (
  changes(kube_daemonset_status_updated_number_scheduled{cluster="CLUSTER", namespace="NAMESPACE", daemonset="DAEMONSET"}[5m])
    ==
  0
)

本節中的部分查詢和警報運算式，改編自 GitHub 上 Prometheus 社群 Kubernetes Helm Charts 存放區的 kubernetes-apps.yaml 檔案。

HorizontalPodAutoscaler 指標

HorizontalPodAutoscaler (HPA) 是一種控制器，會定期變更工作負載 (例如 Deployment 或 StatefulSet) 中的 Pod 數量，以回應 CPU 或記憶體使用率等指標。變更工作負載可用的 Pod 數量，可確保工作負載保持回應能力，同時兼顧效率。

如要進一步瞭解 HPA，請參閱「查看水平 Pod 自動配置器的詳細資料」。

HPA 指標表

您可以透過 HorizontalPodAutoscaler 指標監控及接收控制器行為的相關快訊。下表列出 kube 狀態指標套件提供的指標：

這個表格中的 Cloud Monitoring 指標名稱必須加上 prometheus.googleapis.com/ 前置字元。表格中的項目已省略該前置字串。

詳情請參閱「Horizontal Pod Autoscaler 指標」。

HPA 指標的查詢範例

舉例來說，如要判斷 HPA 是否即將達到副本數量上限，可以繪製下列比率：

kube_horizontalpodautoscaler_status_current_replicas{cluster="CLUSTER", namespace="NAMESPACE", horizontalpodautoscaler="HPA"} /
kube_horizontalpodautoscaler_spec_max_replicas{cluster="CLUSTER", namespace="NAMESPACE", horizontalpodautoscaler="HPA"}

當 HPA 以副本數量上限執行時，您可能需要提高 Pod 數量上限規格。您可以使用下列 PromQL 運算式建立快訊，在發生這種情況時收到通知：

kube_horizontalpodautoscaler_status_current_replicas{cluster="CLUSTER", namespace="NAMESPACE", horizontalpodautoscaler="HPA"}
  ==
kube_horizontalpodautoscaler_spec_max_replicas{cluster="CLUSTER", namespace="NAMESPACE", horizontalpodautoscaler="HPA"}

您也可以比較 kube_horizontalpodautoscaler_status_current_replicas 和 kube_horizontalpodautoscaler_status_desired_replicas 指標的值，判斷目前和所需副本數量之間是否有差異。如果出現差異，可能表示叢集有資源限制。下列 PromQL 運算式會尋找目前備用資源數量與所需、最少和最多備用資源數量之間的差異，以及目前備用資源數量的變化：

(kube_horizontalpodautoscaler_status_desired_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"}
  !=
kube_horizontalpodautoscaler_status_current_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"})
  and
(kube_horizontalpodautoscaler_status_current_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"}
  >
kube_horizontalpodautoscaler_spec_min_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"})
  and
(kube_horizontalpodautoscaler_status_current_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"}
  <
kube_horizontalpodautoscaler_spec_max_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"})
  and
changes(kube_horizontalpodautoscaler_status_current_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"}[15m]) == 0

kube_horizontalpodautoscaler_status_condition 指標上的 condition 和 status 標籤也有助於偵測 HPA 何時遇到各種故障模式。例如：

• ScalingLimited 條件和 true 狀態表示 HPA 受限於副本數量下限或上限：

  kube_horizontalpodautoscaler_status_condition{status="true", condition="ScalingLimited"} == 1

• 如果條件為 AbleToScale 且狀態為 false，表示 HPA 在擷取或更新比例時發生問題：

  kube_horizontalpodautoscaler_status_condition{status="false", condition="AbleToScale"} == 1

• 條件 ScalingActive 和狀態 false 表示 HPA 已停用或無法計算新的規模：

  kube_horizontalpodautoscaler_status_condition{status="false", condition="ScalingActive"} == 1

本節中的部分查詢和警報運算式，改編自 GitHub 上 Prometheus 社群 Kubernetes Helm Charts 存放區的 kubernetes-apps.yaml 檔案。

JobSet 指標

Jobset 是工作負載 API，可讓您以單元形式管理一組 Kubernetes Job。JobSet 最常見的用途是分散式訓練，但您也可以用來執行批次工作負載。

如要進一步瞭解 JobSet，請參閱 JobSet 說明文件。

JobSet 指標表

您可以透過 JobSet 指標監控 JobSet 的行為並接收快訊。 下表列出 kube 狀態指標套件提供的指標：

這個表格中的 Cloud Monitoring 指標名稱必須加上 prometheus.googleapis.com/ 前置字元。表格中的項目已省略該前置字串。

JobSet 指標的範例查詢

您可以依叢集、命名空間和 JobSet 名稱篩選 JobSet 指標，為個別 JobSet 建立圖表和警報政策。

舉例來說，如要比較 READY 狀態的副本數量與單一 JobSet 中的預期副本數量，請使用下列 PromQL 查詢，在單一圖表上繪製這兩項指標：

kube_jobset_specified_replicas{cluster="CLUSTER", namespace="NAMESPACE", jobset_name="JOBSET_NAME"}

kube_jobset_ready_replicas{cluster="CLUSTER", namespace="NAMESPACE", jobset_name="JOBSET_NAME"}

如要針對 JobSet 推出作業失敗或無法使用發出快訊，可以使用下列 PromQL 運算式：

kube_jobset_specified_replicas{cluster="CLUSTER", namespace="NAMESPACE", jobset_name="JOBSET_NAME"}
  >
kube_jobset_ready_replicas{cluster="CLUSTER", namespace="NAMESPACE", jobset_name="JOBSET_NAME"}

kube_jobset_status_condition 指標上的 condition 標籤也有助於偵測 JobSet 何時遇到各種失敗模式，例如：

• Failed 條件表示 JobSet 執行失敗：

  kube_jobset_status_condition{jobset_name="JOBSET_NAME, condition="Failed"} == 1

• Suspended 條件表示 JobSet 已暫停：

  kube_jobset_status_condition{jobset_name="JOBSET_NAME, condition="Suspended"} == 1

本節中的部分查詢和警報運算式，改編自 GitHub 上 Prometheus 社群 Kubernetes Helm Charts 存放區的 kubernetes-apps.yaml 檔案。