開始使用代管收集

本文件說明如何設定 Google Cloud Managed Service for Prometheus 和代管收集作業。這項設定是工作擷取作業的簡易範例，使用 Prometheus 部署來監控範例應用程式，並將收集到的指標儲存在 Monarch 中。

本文件說明如何執行下列操作：

• 設定環境和指令列工具。
• 為叢集設定代管集合。
• 設定資源，用於抓取目標和擷取指標。
• 遷移現有的 Prometheus 操作員自訂資源。

建議您使用受控收集，因為這麼做可簡化部署、調整、分割、設定和維護收集器的複雜度。GKE 和所有其他 Kubernetes 環境都支援代管收集。

代管收集作業會以 Daemonset 的形式執行 Prometheus 收集器，並只抓取位於同區節點的目標，確保可擴充性。您可以使用輕量自訂資源設定收集器，以便透過拉取收集功能擷取匯出工具，然後收集器會將擷取的資料推送至中央資料儲存庫 Monarch。 Google Cloud 絕不會直接存取叢集來拉取或擷取指標資料；收集器會將資料推送至Google Cloud。如要進一步瞭解代管和自行部署的資料收集作業，請參閱「使用 Managed Service for Prometheus 進行資料收集」和「使用代管和自行部署的收集器進行攝入和查詢」。

事前準備

本節說明本文所述工作所需的設定。

設定專案和工具

如要使用 Google Cloud Managed Service for Prometheus，您需要下列資源：

• 已啟用 Cloud Monitoring API 的 Google Cloud 專案。

  • 如果您沒有 Google Cloud 專案，請執行下列操作：

    1. 在 Google Cloud 控制台中，前往「New Project」(新增專案)：

       建立新專案

    2. 在「Project Name」欄位中輸入專案名稱，然後按一下「Create」。

    3. 前往「帳單」：

       前往「帳單」頁面

    4. 如果頁面頂端沒有顯示已選取的專案，請選取您剛建立的專案。

    5. 系統會提示您選擇現有的付款資料或是建立新的付款資料。

    新專案預設會啟用 Monitoring API。

  • 如果您已擁有 Google Cloud 專案，請確認 Monitoring API 已啟用：

    1. 前往「API 和服務」：

       前往「API 和服務」

    2. 選取專案。

    3. 點選「啟用 API 和服務」。

    4. 搜尋「監控」。

    5. 在搜尋結果中，點選「Cloud Monitoring API」。

    6. 如果畫面未顯示「API 已啟用」，請按一下「啟用」按鈕。

• Kubernetes 叢集。如果您沒有 Kubernetes 叢集，請按照 GKE 快速入門中的操作說明進行。

您也需要下列指令列工具：

• gcloud
• kubectl

gcloud 和 kubectl 工具是 Google Cloud CLI 的一部分。如要瞭解如何安裝這些元件，請參閱「管理 Google Cloud CLI 元件」。如要查看已安裝的 gcloud CLI 元件，請執行下列指令：

gcloud components list

設定環境

為避免重複輸入專案 ID 或叢集名稱，請執行下列設定：

• 請按照下列方式設定指令列工具：

  • 設定 gcloud CLI 以參照Google Cloud 專案的 ID：

    gcloud config set project PROJECT_ID
    

  • 設定 kubectl CLI 以使用叢集：

    kubectl config set-cluster CLUSTER_NAME
    

  如要進一步瞭解這些工具，請參閱下列資源：

  • gcloud CLI 總覽
  • kubectl 指令

設定命名空間

為範例應用程式中建立的資源建立 NAMESPACE_NAME Kubernetes 命名空間：

kubectl create ns NAMESPACE_NAME

設定受管理集合

您可以在 GKE 和非 GKE Kubernetes 叢集中使用代管集合。

啟用代管收集功能後，叢集內的元件會開始執行，但尚未產生任何指標。這些元件需要 PodMonitoring 或 ClusterPodMonitoring 資源，才能正確擷取指標端點。您必須使用有效的指標端點部署這些資源，或是啟用 GKE 內建的其中一個受管理的指標套件，例如 Kube 狀態指標。如需疑難排解資訊，請參閱擷取端問題。

啟用代管集合後，系統會在叢集中安裝下列元件：

• gmp-operator 部署作業，可為 Managed Service for Prometheus 部署 Kubernetes 操作員。
• rule-evaluator 部署，用於設定及執行警示和錄影規則。
• collector DaemonSet，只會從與各個收集器位於同一節點的 Pod 中擷取指標，藉此橫向擴大收集範圍。
• alertmanager StatefulSet，已設定為將觸發的快訊傳送至您偏好的通知管道。

如需 Managed Service for Prometheus 運算子參考說明文件，請參閱資訊清單頁面。

啟用代管集合：GKE

系統預設會為下列項目啟用代管集合：

• 執行 GKE 1.25 以上版本的 GKE Autopilot 叢集。

• GKE 標準叢集，執行 GKE 1.27 以上版本。您可以在建立叢集時覆寫這個預設值，請參閱「停用受管理的收集」。

如果您在 GKE 環境中執行，且該環境預設不會啟用代管集合，請參閱手動啟用代管集合。

當新的叢集內元件版本發布時，GKE 上的受管理集合會自動升級。

GKE 上的受管理集合會使用授予預設 Compute Engine 服務帳戶的權限。如果您有政策修改預設節點服務帳戶的標準權限，可能需要新增 Monitoring Metric Writer 角色才能繼續。

手動啟用代管集合

如果您在 GKE 環境中執行，且該環境預設不會啟用代管收集功能，則可使用下列指令啟用代管收集功能：

• Cloud Monitoring 中的「Managed Prometheus 大量啟用叢集」資訊主頁。
• Google Cloud 控制台的「Kubernetes Engine」頁面。
• Google Cloud CLI。如要使用 gcloud CLI，您必須執行 GKE 1.21.4-gke.300 以上版本。

• Google Kubernetes Engine 適用的 Terraform。如要使用 Terraform 啟用 Managed Service for Prometheus，您必須執行 GKE 1.21.4-gke.300 以上版本。

gcloud config set project PROJECT_ID

gcloud container clusters create CLUSTER_NAME --zone ZONE --enable-managed-prometheus

停用代管集合

如要停用叢集的代管收集，您可以使用下列任一方法：

gcloud config set project PROJECT_ID

gcloud container clusters create CLUSTER_NAME --zone ZONE --no-enable-managed-prometheus

啟用代管集合：非 GKE Kubernetes

如果您是在非 GKE 環境中執行，則可以使用下列方式啟用代管收集功能：

• kubectl CLI。

• 在執行 1.12 以上版本的 GKE Enterprise 部署中，隨附的解決方案。

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/manifests/setup.yaml

kubectl apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/manifests/operator.yaml

部署範例應用程式

範例應用程式會在其 metrics 通訊埠上，發出 example_requests_total 計數器指標和 example_random_numbers 直方圖指標 (以及其他指標)。應用程式的資訊清單會定義三個備用資源。

如要部署範例應用程式，請執行下列指令：

kubectl -n NAMESPACE_NAME apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/examples/example-app.yaml

設定 PodMonitoring 資源

為了擷取範例應用程式所發出的指標資料，Managed Service for Prometheus 會使用目標抓取功能。設定抓取目標和擷取指標作業時會使用 Kubernetes 自訂資源，代管服務會使用 PodMonitoring 自訂資源 (CR)。

PodMonitoring CR 只會在 CR 部署的命名空間中刮除目標。如要擷取多個命名空間中的目標，請在每個命名空間中部署相同的 PodMonitoring CR。您可以執行 kubectl get podmonitoring -A，確認 PodMonitoring 資源已安裝在所需命名空間中。

如需所有 Managed Service for Prometheus CR 的參考說明文件，請參閱 prometheus-engine/doc/api reference。

下列資訊清單在 NAMESPACE_NAME 命名空間中定義 PodMonitoring 資源 prom-example。這項資源會使用 Kubernetes 標籤選取器，找出命名空間中所有標籤為 app.kubernetes.io/name 且值為 prom-example 的 Pod。系統會每 30 秒在 /metrics HTTP 路徑上，從名為 metrics 的通訊埠擷取符合條件的 Pod。

apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: prom-example
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: prom-example
  endpoints:
  - port: metrics
    interval: 30s

如要套用這項資源，請執行下列指令：

kubectl -n NAMESPACE_NAME apply -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/examples/pod-monitoring.yaml

您的受管理收集器現在會擷取相符的 Pod。如要查看刮除目標的狀態，請啟用目標狀態功能。

如要設定橫向收集，以便套用至所有命名空間中的一系列 Pod，請使用 ClusterPodMonitoring 資源。ClusterPodMonitoring 資源提供與 PodMonitoring 資源相同的介面，但不會將偵測到的 Pod 限制在特定命名空間內。

如果您在 GKE 上執行，可以執行下列操作：

• 如要使用 Cloud Monitoring 中的 PromQL 查詢範例應用程式擷取的指標，請參閱「使用 Cloud Monitoring 查詢」一文。
• 如要使用 Grafana 查詢範例應用程式擷取的指標，請參閱「使用 Grafana 或任何 Prometheus API 使用者查詢」一文。
• 如要瞭解如何篩選匯出的指標，並調整 prom-operator 資源，請參閱受管理收集的其他主題。

如果您是在 GKE 以外執行，則需要建立服務帳戶並授權該帳戶寫入指標資料，如以下章節所述。

明確提供憑證

在 GKE 上執行時，收集 Prometheus 伺服器會根據節點的服務帳戶，自動從環境中擷取憑證。在非 GKE Kubernetes 叢集中，憑證必須透過 gmp-public 命名空間中的 OperatorConfig 資源明確提供。

1. 將內容設定為目標專案：

   gcloud config set project PROJECT_ID
   

2. 建立服務帳戶：

   gcloud iam service-accounts create gmp-test-sa
   

3. 將必要權限授予服務帳戶：

   gcloud projects add-iam-policy-binding PROJECT_ID\
     --member=serviceAccount:gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com \
     --role=roles/monitoring.metricWriter
   

4. 建立並下載服務帳戶金鑰：

   gcloud iam service-accounts keys create gmp-test-sa-key.json \
     --iam-account=gmp-test-sa@PROJECT_ID.iam.gserviceaccount.com
   

5. 將金鑰檔案新增為非 GKE 叢集的密鑰：

   kubectl -n gmp-public create secret generic gmp-test-sa \
     --from-file=key.json=gmp-test-sa-key.json
   

6. 開啟 OperatorConfig 資源進行編輯：

   kubectl -n gmp-public edit operatorconfig config
   

   1. 將粗體文字新增至資源：

      apiVersion: monitoring.googleapis.com/v1
      kind: OperatorConfig
      metadata:
        namespace: gmp-public
        name: config
      collection:
        credentials:
          name: gmp-test-sa
          key: key.json
      

      請務必將這些憑證新增至 rules 部分，以便管理規則評估作業。

   2. 儲存檔案並關閉編輯器。套用變更後，系統會重新建立 Pod，並開始使用指定的服務帳戶對指標後端進行驗證。

   受管理的收藏內容其他主題

   本節將說明如何執行下列操作：

   • 啟用目標狀態功能，方便進行偵錯。
   • 使用 Terraform 設定目標刮除作業。
   • 篩選要匯出至受管理服務的資料。
   • 擷取 Kubelet 和 cAdvisor 指標。
   • 轉換現有的 Prom 操作員資源，以便與代管服務搭配使用。
   • 在 GKE 外部執行代管集合。

   啟用目標狀態功能

   Managed Service for Prometheus 提供一種方法，可檢查收集器是否正確偵測及擷取目標。這個目標狀態報告是用來偵錯嚴重問題的工具。強烈建議您只在需要調查即時問題時啟用這項功能。在大型叢集中開啟目標狀態回報功能，可能會導致運算子記憶體不足，並發生當機迴圈。

   您可以將 OperatorConfig 資源中的 features.targetStatus.enabled 值設為 true，藉此查看 PodMonitoring 或 ClusterPodMonitoring 資源中的目標狀態，如下所示：

       apiVersion: monitoring.googleapis.com/v1
       kind: OperatorConfig
       metadata:
         namespace: gmp-public
         name: config
       features:
         targetStatus:
           enabled: true
   

   幾秒後，每個有效的 PodMonitoring 或 ClusterPodMonitoring 資源 (已設定) 都會顯示 Status.Endpoint Statuses 欄位。

   如果您在 NAMESPACE_NAME 命名空間中擁有名為 prom-example 的 PodMonitoring 資源，可以執行下列指令來查看狀態：

   kubectl -n NAMESPACE_NAME describe podmonitorings/prom-example
   

   輸出內容如下：

   API Version:  monitoring.googleapis.com/v1
   Kind:         PodMonitoring
   ...
   Status:
     Conditions:
       ...
       Status:                True
       Type:                  ConfigurationCreateSuccess
     Endpoint Statuses:
       Active Targets:       3
       Collectors Fraction:  1
       Last Update Time:     2023-08-02T12:24:26Z
       Name:                 PodMonitoring/custom/prom-example/metrics
       Sample Groups:
         Count:  3
         Sample Targets:
           Health:  up
           Labels:
             Cluster:                     CLUSTER_NAME
             Container:                   prom-example
             Instance:                    prom-example-589ddf7f7f-hcnpt:metrics
             Job:                         prom-example
             Location:                    REGION
             Namespace:                   NAMESPACE_NAME
             Pod:                         prom-example-589ddf7f7f-hcnpt
             project_id:                  PROJECT_ID
           Last Scrape Duration Seconds:  0.020206416
           Health:                        up
           Labels:
             ...
           Last Scrape Duration Seconds:  0.054189485
           Health:                        up
           Labels:
             ...
           Last Scrape Duration Seconds:  0.006224887
   

   輸出內容包含下列狀態欄位：

   • 當 Managed Service for Prometheus 確認並處理 PodMonitoring 或 ClusterPodMonitoring 時，Status.Conditions.Status 會設為 true。
   • Status.Endpoint Statuses.Active Targets 會顯示 Managed Service for Prometheus 在這個 PodMonitoring 資源的所有收集器中計算的抓取目標數量。在範例應用程式中，prom-example 部署有三個副本，且每個副本都有單一指標目標，因此值為 3。如果有異常目標，系統會顯示 Status.Endpoint Statuses.Unhealthy Targets 欄位。
   • 如果 Managed Service for Prometheus 可存取所有代管收集器，Status.Endpoint Statuses.Collectors Fraction 會顯示 1 值 (代表 100%)。
   • Status.Endpoint Statuses.Last Update Time 會顯示上次更新的時間。如果上次更新時間與所需的檢索間隔時間相差太多，可能表示目標或叢集有問題。
   • Status.Endpoint Statuses.Sample Groups 欄位會顯示樣本目標，並依收集器插入的常見目標標籤分組。在未偵測到目標的情況下，這個值可用於偵錯。如果所有目標都正常運作且正在收集，則 Health 欄位的預期值為 up，而 Last Scrape Duration Seconds 欄位的值則為一般目標的通常時間長度。

   如要進一步瞭解這些欄位，請參閱 Managed Service for Prometheus API 說明文件。

   下列任一情況可能表示設定有問題：

   • PodMonitoring 資源中沒有 Status.Endpoint Statuses 欄位。
   • Last Scrape Duration Seconds 欄位的值過舊。
   • 您看到的目標太少。
   • Health 欄位的值表示目標為 down。

   如要進一步瞭解如何偵錯目標探索問題，請參閱疑難排解說明文件中的「擷取端問題」。

   設定授權的刮除端點

   如果刮除目標需要授權，您可以設定收集器使用正確的授權類型，並提供任何相關的機密資料。

   Google Cloud Managed Service for Prometheus 支援下列授權類型：

   • mTLS
   • BasicAuth
   • HTTP 授權標頭
   • OAuth 2

   mTLS

   mTLS 通常會在零信任環境中設定，例如 Istio 服務網格或 Cloud Service Mesh。

   如要啟用使用 mTLS 保護的刮除端點，請將 PodMonitoring 資源中的 Spec.Endpoints[].Scheme 欄位設為 https。雖然我們不建議這麼做，但您可以將 PodMonitoring 資源中的 Spec.Endpoints[].tls.insecureSkipVerify 欄位設為 true，藉此略過驗證憑證授權單位。或者，您也可以設定 Managed Service for Prometheus，讓系統從機密資源載入憑證和金鑰。

   舉例來說，下列 Secret 資源包含用戶端 (cert)、私密金鑰 (key) 和憑證授權單位 (ca) 憑證的金鑰：

   kind: Secret
   metadata:
     name: secret-example
   stringData:
     cert: ********
     key: ********
     ca: ********
   

   授予 Managed Service for Prometheus 收集器存取該 Secret 資源的權限：

   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: secret-example-read
   rules:
   - resources:
     - secrets
     apiGroups: [""]
     verbs: ["get", "list", "watch"]
     resourceNames: ["secret-example"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: gmp-system:collector:secret-example-read
     namespace: default
   roleRef:
     name: secret-example-read
     kind: Role
     apiGroup: rbac.authorization.k8s.io
   subjects:
   - name: collector
     namespace: gmp-system
     kind: ServiceAccount
   

   在 GKE Autopilot 叢集中，這會顯示如下：

   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: secret-example-read
   rules:
   - resources:
     - secrets
     apiGroups: [""]
     verbs: ["get", "list", "watch"]
     resourceNames: ["secret-example"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: gmp-system:collector:secret-example-read
     namespace: default
   roleRef:
     name: secret-example-read
     kind: Role
     apiGroup: rbac.authorization.k8s.io
   subjects:
   - name: collector
     namespace: gke-gmp-system
     kind: ServiceAccount
   

   如要設定使用先前密鑰資源的 PodMonitoring 資源，請修改資源以新增 scheme 和 tls 區段：

   apiVersion: monitoring.googleapis.com/v1
   kind: PodMonitoring
   metadata:
     name: prom-example
   spec:
     selector:
       matchLabels:
         app.kubernetes.io/name: prom-example
     endpoints:
     - port: metrics
       interval: 30s
       scheme: https
       tls:
         ca:
           secret:
             name: secret-example
             key: ca
         cert:
           secret:
             name: secret-example
             key: cert
         key:
           secret:
             name: secret-example
             key: key
   

   如需所有 Managed Service for Prometheus mTLS 選項的參考說明文件，請參閱 API 參考說明文件。

   BasicAuth

   如要啟用使用 BasicAuth 保護的刮除端點，請使用使用者名稱和密碼設定 PodMonitoring 資源中的 Spec.Endpoints[].BasicAuth 欄位。如需其他 HTTP 授權標頭類型，請參閱 HTTP 授權標頭。

   例如，以下密鑰資源包含用於儲存密碼的金鑰：

   kind: Secret
   metadata:
     name: secret-example
   stringData:
     password: ********
   

   授予 Managed Service for Prometheus 收集器存取該 Secret 資源的權限：

   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: secret-example-read
   rules:
   - resources:
     - secrets
     apiGroups: [""]
     verbs: ["get", "list", "watch"]
     resourceNames: ["secret-example"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: gmp-system:collector:secret-example-read
     namespace: default
   roleRef:
     name: secret-example-read
     kind: Role
     apiGroup: rbac.authorization.k8s.io
   subjects:
   - name: collector
     namespace: gmp-system
     kind: ServiceAccount
   

   在 GKE Autopilot 叢集中，這會顯示如下：

   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: secret-example-read
   rules:
   - resources:
     - secrets
     apiGroups: [""]
     verbs: ["get", "list", "watch"]
     resourceNames: ["secret-example"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: gmp-system:collector:secret-example-read
     namespace: default
   roleRef:
     name: secret-example-read
     kind: Role
     apiGroup: rbac.authorization.k8s.io
   subjects:
   - name: collector
     namespace: gke-gmp-system
     kind: ServiceAccount
   

   如要設定 PodMonitoring 資源，以便使用先前的 Secret 資源和 foo 的使用者名稱，請修改資源以新增 basicAuth 區段：

   apiVersion: monitoring.googleapis.com/v1
   kind: PodMonitoring
   metadata:
     name: prom-example
   spec:
     selector:
       matchLabels:
         app.kubernetes.io/name: prom-example
     endpoints:
     - port: metrics
       interval: 30s
       basicAuth:
         username: foo
         password:
           secret:
             name: secret-example
             key: password
   

   如需所有 Managed Service for Prometheus BasicAuth 選項的參考說明文件，請參閱 API 參考說明文件。

   HTTP 授權標頭

   如要啟用使用 HTTP 授權標頭保護的刮除端點，請在 PodMonitoring 資源中設定 Spec.Endpoints[].Authorization 欄位，並提供類型和憑證。如為 BasicAuth 端點，請改用 BasicAuth 設定。

   例如，下列 Secret 資源包含用於儲存憑證的金鑰：

   kind: Secret
   metadata:
     name: secret-example
   stringData:
     credentials: ********
   

   授予 Managed Service for Prometheus 收集器存取該 Secret 資源的權限：

   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: secret-example-read
   rules:
   - resources:
     - secrets
     apiGroups: [""]
     verbs: ["get", "list", "watch"]
     resourceNames: ["secret-example"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: gmp-system:collector:secret-example-read
     namespace: default
   roleRef:
     name: secret-example-read
     kind: Role
     apiGroup: rbac.authorization.k8s.io
   subjects:
   - name: collector
     namespace: gmp-system
     kind: ServiceAccount
   

   在 GKE Autopilot 叢集中，這會顯示如下：

   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: secret-example-read
   rules:
   - resources:
     - secrets
     apiGroups: [""]
     verbs: ["get", "list", "watch"]
     resourceNames: ["secret-example"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: gmp-system:collector:secret-example-read
     namespace: default
   roleRef:
     name: secret-example-read
     kind: Role
     apiGroup: rbac.authorization.k8s.io
   subjects:
   - name: collector
     namespace: gke-gmp-system
     kind: ServiceAccount
   

   如要設定 PodMonitoring 資源，以便使用先前的 Secret 資源和 Bearer 類型，請修改資源，新增 authorization 區段：

   apiVersion: monitoring.googleapis.com/v1
   kind: PodMonitoring
   metadata:
     name: prom-example
   spec:
     selector:
       matchLabels:
         app.kubernetes.io/name: prom-example
     endpoints:
     - port: metrics
       interval: 30s
       authorization:
         type: Bearer
         credentials:
           secret:
             name: secret-example
             key: credentials
   

   如需所有 Managed Service for Prometheus HTTP 授權標頭選項的參考說明文件，請參閱 API 參考說明文件。

   OAuth 2

   如要啟用使用 OAuth 2 保護的刮除端點，您必須在 PodMonitoring 資源中設定 Spec.Endpoints[].OAuth2 欄位。

   舉例來說，下列 Secret 資源包含用於儲存用戶端秘密的金鑰：

   kind: Secret
   metadata:
     name: secret-example
   stringData:
     clientSecret: ********
   

   授予 Managed Service for Prometheus 收集器存取該 Secret 資源的權限：

   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: secret-example-read
   rules:
   - resources:
     - secrets
     apiGroups: [""]
     verbs: ["get", "list", "watch"]
     resourceNames: ["secret-example"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: gmp-system:collector:secret-example-read
     namespace: default
   roleRef:
     name: secret-example-read
     kind: Role
     apiGroup: rbac.authorization.k8s.io
   subjects:
   - name: collector
     namespace: gmp-system
     kind: ServiceAccount
   

   在 GKE Autopilot 叢集中，這會顯示如下：

   apiVersion: rbac.authorization.k8s.io/v1
   kind: Role
   metadata:
     name: secret-example-read
   rules:
   - resources:
     - secrets
     apiGroups: [""]
     verbs: ["get", "list", "watch"]
     resourceNames: ["secret-example"]
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: RoleBinding
   metadata:
     name: gmp-system:collector:secret-example-read
     namespace: default
   roleRef:
     name: secret-example-read
     kind: Role
     apiGroup: rbac.authorization.k8s.io
   subjects:
   - name: collector
     namespace: gke-gmp-system
     kind: ServiceAccount
   

   如要設定 PodMonitoring 資源，以便使用先前的 Secret 資源，其中客戶 ID 為 foo，權杖網址為 example.com/token，請修改資源以新增 oauth2 區段：

   apiVersion: monitoring.googleapis.com/v1
   kind: PodMonitoring
   metadata:
     name: prom-example
   spec:
     selector:
       matchLabels:
         app.kubernetes.io/name: prom-example
     endpoints:
     - port: metrics
       interval: 30s
       oauth2:
         clientID: foo
         clientSecret:
           secret:
             name: secret-example
             key: password
         tokenURL: example.com/token
   

   如需所有 Managed Service for Prometheus OAuth 2 選項的參考說明文件，請參閱 API 參考說明文件。

   使用 Terraform 設定目標刮除

   您可以使用 kubernetes_manifest Terraform 資源類型或 kubectl_manifest Terraform 資源類型，自動建立及管理 PodMonitoring 和 ClusterPodMonitoring 資源，這兩種資源類型都允許您指定任意自訂資源。

   如要瞭解如何搭配使用 Google Cloud 與 Terraform，請參閱「搭配使用 Terraform 與 Google Cloud」。

   篩選已匯出的指標

   如果您收集的資料量很大，建議您避免將部分時間序列傳送至 Managed Service for Prometheus，以降低成本。您可以使用 Prometheus 重新標示規則，搭配允許清單的 keep 動作或拒絕清單的 drop 動作，即可完成這項操作。如果是代管集合，則這項規則會放在 PodMonitoring 或 ClusterPodMonitoring 資源的 metricRelabeling 部分。

   舉例來說，下列指標重新命名規則會篩除任何以 foo_bar_、foo_baz_ 或 foo_qux_ 開頭的指標：

     metricRelabeling:
     - action: drop
       regex: foo_(bar|baz|qux)_.+
       sourceLabels: [__name__]
   

   Cloud Monitoring 的「指標管理」頁面提供的資訊可協助您控制可計費指標的支出金額，且不會影響可觀察性。「指標管理」頁面會回報下列資訊：

   • 以位元組和樣本為基礎的計費作業量，跨指標網域和個別指標。
   • 指標的標籤和基數資料。
   • 每個指標的讀取次數。
   • 在警告政策和自訂資訊主頁中使用指標。
   • 指標寫入錯誤率。

   您也可以使用「指標管理」頁面排除不需要的指標，省下擷取這些指標的成本。 如要進一步瞭解「指標管理」頁面，請參閱「查看及管理指標使用情形」一文。

   如需其他降低費用的建議，請參閱「費用控管和歸因」。

   擷取 Kubelet 和 cAdvisor 指標

   Kubelet 會公開自身的指標，以及在其節點上執行的容器的 cAdvisor 指標。您可以編輯 OperatorConfig 資源，設定受管理的收集作業，以便擷取 Kubelet 和 cAdvisor 指標。如需操作說明，請參閱 Kubelet 和 cAdvisor 的匯出器說明文件。

   轉換現有的 Prometheus 操作員資源

   您通常可以將現有的 prometheus-operator 資源轉換為 Managed Service for Prometheus 的 PodMonitoring 和 ClusterPodMonitoring 代管收集作業資源。

   舉例來說，ServiceMonitor 資源可定義一組服務的監控作業。PodMonitoring 資源會提供 ServiceMonitor 資源提供的欄位子集。您可以按照下表所述對應欄位，將 ServiceMonitor CR 轉換為 PodMonitoring CR：

   monitoring.coreos.com/v1 ServiceMonitor	相容性	monitoring.googleapis.com/v1 PodMonitoring
   .ServiceMonitorSpec.Selector	相同	.PodMonitoringSpec.Selector
   .ServiceMonitorSpec.Endpoints[]	.TargetPort 對應至 .Port .Path：相容 .Interval：相容 .Timeout：相容	.PodMonitoringSpec.Endpoints[]
   .ServiceMonitorSpec.TargetLabels	PodMonitor 必須指定： .FromPod[].From Pod 標籤 .FromPod[].To 目標標籤	.PodMonitoringSpec.TargetLabels

   以下是 ServiceMonitor CR 範例，其中粗體字內容會在轉換中取代，斜體字內容則會直接對應：

   apiVersion: monitoring.coreos.com/v1
   kind: ServiceMonitor
   metadata:
     name: example-app
   spec:
     selector:
       matchLabels:
         app: example-app
     endpoints:
     - targetPort: web
       path: /stats
       interval: 30s
     targetLabels:
     - foo
   

   以下是類似的 PodMonitoring CR，假設您的服務及其 Pod 已標示 app=example-app。如果這項假設不適用，您就必須使用基礎 Service 資源的標籤選取器。

   轉換中已取代粗體字體的內容：

   apiVersion: monitoring.googleapis.com/v1
   kind: PodMonitoring
   metadata:
     name: example-app
   spec:
     selector:
       matchLabels:
         app: example-app
     endpoints:
     - port: web
       path: /stats
       interval: 30s
     targetLabels:
       fromPod:
       - from: foo # pod label from example-app Service pods.
         to: foo
   

   您可以隨時繼續使用現有的 Prometheus 操作員資源和部署設定，方法是使用自行部署的收集器，而非代管收集器。您可以查詢從兩種收集器類型傳送的指標，因此建議您為現有的 Prometheus 部署使用自行部署的收集器，並為新的 Prometheus 部署使用代管收集器。

   保留標籤

   Managed Service for Prometheus 會自動將下列標籤新增至所有收集的指標。這些標籤可用於在 Monarch 中明確識別資源：

   • project_id：與指標相關聯的 Google Cloud 專案 ID。
   • location：資料儲存的實際位置 (Google Cloud region)。這個值通常是 GKE 叢集的區域。如果資料是從 AWS 或內部部署收集，則這個值可能是最近的 Google Cloud 區域。
   • cluster：與指標相關聯的 Kubernetes 叢集名稱。
   • namespace：與指標相關聯的 Kubernetes 命名空間名稱。
   • job：Prometheus 目標的工作標籤 (如果已知)；規則評估結果可能為空白。
   • instance：Prometheus 目標的執行個體標籤 (如果已知)；規則評估結果可能為空白。

   雖然不建議在 Google Kubernetes Engine 上執行時這樣做，但您可以將 project_id、location 和 cluster 標籤新增為 args，藉此覆寫 operator.yaml 中的部署資源。如果您使用任何保留的標籤做為指標標籤，Managed Service for Prometheus 會自動加上前置字串 exported_，重新標示這些標籤。這項行為與上游 Prometheus 處理與保留標籤的衝突的方式相符。

   PodMonitoring 和 ClusterPodMonitoring 應用程式標籤

   在下列情況下，App Hub 應用程式標籤會附加至 Google Cloud Managed Service for Prometheus 指標：

   • 工作負載在 Google Kubernetes Engine 叢集 (版本 1.30 以上) 上執行，且工作負載的控制器類型為下列任一項：

     • apps.k8s.io/{Deployment,StatefulSet,DaemonSet}
     • batch.k8s.io/CronJob

   • 在 Cloud Run 上使用 OpenTelemetry。

   • 在 Google Kubernetes Engine 上使用 OpenTelemetry，並遵循 OTLP Kubernetes Ingest 指南。特別是，您必須更新 collector.yaml 檔案，才能設定 top_level_controller_{name,type} 屬性。

   在先前的設定中，Managed Service for Prometheus 會擷取服務探索資料或作業名稱，然後使用重新標記功能填入並將 top_level_controller_{name,type} 標籤新增至 targetLabels.metadata。

   Prometheus 的 Managed Service 會使用 App Hub API 判斷是否存在 App Hub 應用程式。找到應用程式後，系統會在追蹤資料中加入下列應用程式專屬標籤：

   • metric.labels.apphub_application_{container,id,location}
   • metric.labels.apphub_workload_{criticality_type,environment_type,id}

   壓縮設定

   如果您有許多 PodMonitoring 資源，可能會用盡 ConfigMap 空間。如要解決這個問題，請在 OperatorConfig 資源中啟用 gzip 壓縮功能：

     apiVersion: monitoring.googleapis.com/v1
     kind: OperatorConfig
     metadata:
       namespace: gmp-public
       name: config
     features:
       config:
         compression: gzip
   

   為代管集合啟用垂直 Pod 自動調度資源功能 (VPA)

   如果叢集中的收集器 Pod 發生記憶體不足 (OOM) 錯誤，或是收集器的預設資源要求和限制無法滿足您的需求，您可以使用垂直 Pod 自動調度功能來動態分配資源。

   在 OperatorConfig 資源上設定 scaling.vpa.enabled: true 欄位後，作業員會在叢集中部署 VerticalPodAutoscaler 資訊清單，讓收集器 Pod 的資源要求和限制可根據使用情形自動設定。

   如要在 Managed Service for Prometheus 中為收集器 Pod 啟用 VPA，請執行下列指令：

   kubectl -n gmp-public patch operatorconfig/config -p '{"scaling":{"vpa":{"enabled":true}}}' --type=merge
   

   如果指令順利完成，運算子會為收集器 Pod 設定垂直 Pod 自動調整大小功能。記憶體不足錯誤會導致資源限制立即增加。如果沒有 OOM 錯誤，收集器 Pod 的資源要求和限制通常會在 24 小時內進行第一次調整。

   嘗試啟用 VPA 時，您可能會收到以下錯誤訊息：

   vertical pod autoscaling is not available - install vpa support and restart the operator

   如要解決這項錯誤，您必須先在叢集層級啟用垂直 Pod 自動調度資源功能：

   1. 前往Google Cloud 控制台的「Kubernetes Engine - 叢集」頁面。

      在 Google Cloud 控制台中，前往「Kubernetes clusters」(Kubernetes 叢集) 頁面：

      前往「Kubernetes clusters」(Kubernetes 叢集)

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

   2. 選取要修改的叢集。

   3. 在「Automation」部分中，編輯「Vertical Pod Autoscaling」選項的值。

   4. 勾選「Enable Vertical Pod Autoscaling」核取方塊，然後按一下「Save changes」。這項變更會重新啟動叢集。在這個程序中，運算子會重新啟動。

   5. 重試下列指令：kubectl -n gmp-public patch operatorconfig/config -p '{"scaling":{"vpa":{"enabled":true}}}' --type=merge，為 Managed Service for Prometheus 啟用 VPA。

   如要確認 OperatorConfig 資源是否已成功編輯，請使用 kubectl -n gmp-public edit operatorconfig config 指令開啟該資源。如果成功，您的 OperatorConfig 會包含以下粗體文字：

   apiVersion: monitoring.googleapis.com/v1
   kind: OperatorConfig
   metadata:
     namespace: gmp-public
     name: config
   scaling:
     vpa:
       enabled: true
   

   如果您已在叢集層級啟用垂直 Pod 自動調度功能，但仍看到 vertical pod autoscaling is not available - install vpa support and restart the operator 錯誤，則 gmp-operator Pod 可能需要重新評估叢集設定。如果您執行的是標準叢集，請執行下列指令重新建立 Pod：

   kubectl -n gmp-system rollout restart deployment/gmp-operator
   

   gmp-operator pod 重新啟動後，請按照上述步驟再次修補 OperatorConfig。

   如果您正在執行 Autopilot 叢集，請與支援團隊聯絡，以便協助您重新啟動叢集。

   垂直 pod 自動調度資源功能最適合用於擷取固定數量的樣本，並平均分配至各個節點。如果指標負載不規則或波動，或是節點之間的指標負載差異極大，VPA 可能就不是有效的解決方案。

   詳情請參閱「GKE 中的垂直 Pod 自動調度」。

   設定 statsd_exporter 和其他匯出工具，以便集中回報指標

   如果您使用 Prometheus 的 statsd_exporter、Istio 的 Envoy、SNMP 匯出程式、Prometheus Pushgateway、kube-state-metrics，或是有其他類似的匯出程式，可代表在環境中執行的其他資源進行中介並回報指標，則需要進行一些小幅變更，讓匯出程式能夠與 Managed Service for Prometheus 搭配運作。

   如需設定這些匯出工具的操作說明，請參閱疑難排解一節中的這則附註。

   拆解

   如要停用使用 gcloud 或 GKE UI 部署的受管理收集，請採取下列任一做法：

   • 執行下列指令：

     gcloud container clusters update CLUSTER_NAME --disable-managed-prometheus
     

   • 使用 GKE UI：

     1. 在 Google Cloud 控制台中選取「Kubernetes Engine」，然後選取「叢集」。

     2. 找出要停用代管收集的叢集，然後按一下該叢集的名稱。

     3. 在「Details」分頁中，向下捲動至「Features」，然後使用編輯按鈕將狀態變更為「Disabled」。

   如要停用使用 Terraform 部署的受管理集合，請在 google_container_cluster 資源的 managed_prometheus 區段中指定 enabled = false。

   如要停用使用 kubectl 部署的管理收集，請執行下列指令：

   kubectl delete -f https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/manifests/operator.yaml
   

   停用代管收集作業後，叢集就會停止將新資料傳送至 Managed Service for Prometheus。這項操作不會刪除系統中已儲存的任何現有指標資料。

   停用受管理的收集時，也會刪除 gmp-public 命名空間及其內的所有資源，包括該命名空間中安裝的匯出程式。

   在 GKE 外執行代管集合

   在 GKE 環境中，您可以執行代管集合，而無須進一步設定。在其他 Kubernetes 環境中，您必須明確提供憑證、用於包含指標的 project-id 值、用於儲存指標的 location 值 (Google Cloud 區域)，以及用於儲存收集器執行所在叢集名稱的 cluster 值。

   由於 gcloud 無法在 Google Cloud 環境外運作，因此您必須改用 kubectl 部署。與 gcloud 不同，使用 kubectl 部署代管集合時，系統不會在推出新版本時自動升級叢集。請務必留意版本頁面的最新版本，並手動升級，方法是使用新版本重新執行 kubectl 指令。

   您可以修改 operator.yaml 中的 OperatorConfig 資源，如「明確提供憑證」一文所述，藉此提供服務帳戶金鑰。您可以將 project-id、location 和 cluster 值新增為 args，並將其加入 operator.yaml 中的部署資源。

   建議您根據讀取內容的預期租用模式，選擇 project-id。請根據您日後打算如何使用指標範圍來組織讀取項目，選擇儲存指標的專案。如果您不介意，可以將所有內容都放入一個專案。

   針對 location，建議您選擇與部署位置最近的 Google Cloud 區域。所選 Google Cloud 區域離部署位置越遠，寫入延遲就會越長，且可能受到網路問題的影響。您可以參考這份跨多個雲端的地區清單。如果您不介意，可以將所有內容都放在同一個 Google Cloud 區域。您無法將 global 設為位置。

   針對 cluster，建議您選擇部署操作員的叢集名稱。

   設定正確後，OperatorConfig 應如下所示：

       apiVersion: monitoring.googleapis.com/v1
       kind: OperatorConfig
       metadata:
         namespace: gmp-public
         name: config
       collection:
         credentials:
           name: gmp-test-sa
           key: key.json
       rules:
         credentials:
           name: gmp-test-sa
           key: key.json
   

   部署資源應如下所示：

   apiVersion: apps/v1
   kind: Deployment
   ...
   spec:
     ...
     template:
       ...
       spec:
         ...
         containers:
         - name: operator
           ...
           args:
           - ...
           - "--project-id=PROJECT_ID"
           - "--cluster=CLUSTER_NAME"
           - "--location=REGION"
   

   這個範例假設您已將 REGION 變數設為 us-central1 等值。

   在 Google Cloud 以外執行 Managed Service for Prometheus 會產生資料傳輸費用。將資料轉移至 Google Cloud會產生費用，從其他雲端轉移資料也可能會產生費用。您可以透過 OperatorConfig 啟用網路上的 gzip 壓縮功能，盡可能降低這些成本。將粗體文字新增至資源：

       apiVersion: monitoring.googleapis.com/v1
       kind: OperatorConfig
       metadata:
         namespace: gmp-public
         name: config
       collection:
         compression: gzip
         ...
   

   進一步閱讀：受管理集合自訂資源

   如需所有 Managed Service for Prometheus 自訂資源的參考文件，請參閱 prometheus-engine/doc/api reference。

   後續步驟

   • 在 Cloud Monitoring 中使用 PromQL 查詢 Prometheus 指標。
   • 使用 Grafana 查詢 Prometheus 指標。
   • 使用 Cloud Monitoring 中的 PromQL 快訊。
   • 設定受管理的規則評估。
   • 設定常用的匯出工具。