Cloud Monitoring 的 PromQL

GKE

如要在 Kubernetes 叢集中部署及執行資料來源同步器，請完成下列步驟：

1. 選擇要部署資料來源同步器的專案、叢集和命名空間。

   接著，請確認您已正確設定並授權資料來源同步器：

   • 如果您使用 GKE 適用的工作負載身分聯盟，請按照操作說明建立及授權服務帳戶。請務必將其繫結至要執行資料來源同步器的 Kubernetes 命名空間。
   • 如果您未使用 Workload Identity Federation for GKE，請確認您未修改預設的 Compute Engine 服務帳戶。

2. 判斷 Grafana 執行個體的網址，例如 Grafana Cloud 部署作業的 https://yourcompanyname.grafana.net，或是使用測試部署 YAML 設定的本機執行個體的 http://grafana.NAMESPACE_NAME.svc:3000。

   如果您在本機部署 Grafana，且叢集已設定為使用 TLS 保護所有叢集內流量，則必須在網址中使用 https://，並使用支援的 TLS 驗證選項進行驗證。

3. 選擇要用於 Cloud Monitoring 的 Grafana Prometheus 資料來源 (可以是新的或現有的資料來源)，然後找出並記下資料來源 UID。探索或設定資料來源時，您可以在網址的最後一部分找到資料來源 UID，例如：https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID. 請勿複製整個資料來源網址。僅複製網址中的專屬 ID。

4. 設定 Grafana 服務帳戶：建立服務帳戶，並為該帳戶產生權杖：

   1. 在 Grafana 導覽側欄中，依序點選「Administration」「Users and Access」「Service Accounts」。

   2. 按一下「Add service account」(新增服務帳戶) 建立服務帳戶，為服務帳戶命名，並在 Grafana 中授予「管理員」角色。如果您的 Grafana 版本允許更精細的權限，則可以使用「資料來源」>「寫入者」角色。

   3. 按一下「新增服務帳戶權杖」。

   4. 將權杖到期日設為「永不到期」，然後按一下「產生權杖」，接著將產生的權杖複製到剪貼簿，以便在下一步中做為 GRAFANA_SERVICE_ACCOUNT_TOKEN 使用。

5. 使用上一個步驟的結果，設定下列環境變數：

   # These values are required.
   PROJECT_ID=SCOPING_PROJECT_ID # The value from Step 1.
   GRAFANA_API_ENDPOINT=GRAFANA_INSTANCE_URL # The value from step 2. This is a URL.
   DATASOURCE_UIDS=GRAFANA_DATASOURCE_UID # The value from step 3. This is not a URL.
   GRAFANA_API_TOKEN=GRAFANA_SERVICE_ACCOUNT_TOKEN # The value from step 4.
   GCM_ENDPOINT_OVERRIDE=--gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
   

6. 執行下列指令，建立 CronJob，在初始化時重新整理資料來源，然後每 10 分鐘重新整理一次。如果您使用 GKE 的 Workload Identity Federation，則 NAMESPACE_NAME 的值應與先前繫結至服務帳戶的命名空間相同。

   curl https://raw.githubusercontent.com/GoogleCloudPlatform/prometheus-engine/v0.15.3/cmd/datasource-syncer/datasource-syncer.yaml \
   | sed 's|$DATASOURCE_UIDS|'"$DATASOURCE_UIDS"'|; s|$GRAFANA_API_ENDPOINT|'"$GRAFANA_API_ENDPOINT"'|; s|$GRAFANA_API_TOKEN|'"$GRAFANA_API_TOKEN"'|; s|$PROJECT_ID|'"$PROJECT_ID"'|;' s|$GCM_ENDPOINT_OVERRIDE|'"$GCM_ENDPOINT_OVERRIDE"'|; \
   | kubectl -n NAMESPACE_NAME apply -f -
   

7. 前往新設定的 Grafana 資料來源，確認 Prometheus 伺服器網址值開頭為 https://monitoring.s3nsapis.fr。你可能需要重新整理頁面。驗證完成後，請前往頁面底部，然後選取「儲存並測試」。您至少需要選取這個按鈕一次，才能確保 Grafana 中的標籤自動完成功能正常運作。

驗證服務帳戶憑證

如果 Kubernetes 叢集已啟用 Workload Identity Federation for GKE， 則可以略過本節。

在 GKE 上執行時，Cloud Monitoring 會根據 Compute Engine 預設服務帳戶，自動從環境中擷取憑證。根據預設，預設服務帳戶具備必要權限 monitoring.metricWriter 和 monitoring.viewer。如果您未使用 GKE 的 Workload Identity Federation，且先前已從預設節點服務帳戶移除任一角色，請先重新新增缺少的權限，再繼續操作。

設定 Workload Identity Federation for GKE 的服務帳戶

如果 Kubernetes 叢集未啟用 GKE 適用的工作負載身分聯盟，則可跳過本節。

Cloud Monitoring 會使用 Cloud Monitoring API 擷取指標資料。如果叢集使用 GKE 適用的工作負載身分聯盟，您必須授予 Kubernetes 服務帳戶 Monitoring API 的權限。本節說明下列事項：

• 建立專屬Trusted Cloud by S3NS 服務帳戶。 SERVICE_ACCT_NAME.
• 將 Trusted Cloud 服務帳戶繫結至測試命名空間中的預設 Kubernetes 服務帳戶，NAMESPACE_NAME。
• 將必要權限授予 Trusted Cloud 服務帳戶。

建立及繫結服務帳戶

Cloud Monitoring 文件中的多個位置都會顯示這個步驟。如果您已在先前的作業中執行這個步驟，則不必重複執行。直接跳到「授權服務帳戶」一節。

下列指令序列會建立 SERVICE_ACCT_NAME 服務帳戶，並將其繫結至 NAMESPACE_NAME 命名空間中的預設 Kubernetes 服務帳戶：

gcloud config set project PROJECT_ID \
&&
gcloud iam service-accounts create SERVICE_ACCT_NAME \
&&
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE_NAME/default]" \
  SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
&&
kubectl annotate serviceaccount \
  --namespace NAMESPACE_NAME \
  default \
  iam.gke.io/gcp-service-account=SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com

如果您使用其他 GKE 命名空間或服務帳戶，請適當調整指令。

授權給服務帳戶

相關權限會歸類為角色，您可將角色授予主體，在本例中即為 Trusted Cloud服務帳戶。如要進一步瞭解 Monitoring 角色，請參閱存取權控管。

下列指令會授予 Trusted Cloud 服務帳戶 (SERVICE_ACCT_NAME) 讀取指標資料所需的 Monitoring API 角色。

如果您已在先前的作業中授予 Trusted Cloud 服務帳戶特定角色，就不必再次執行這項操作。

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
  --role=roles/monitoring.viewer \
&& \
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=serviceAccount:SERVICE_ACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator

對 GKE 適用的 Workload Identity 聯盟設定進行偵錯

如果無法順利使用 Workload Identity Federation for GKE，請參閱驗證 Workload Identity Federation for GKE 設定的說明文件，以及 Workload Identity Federation for GKE 疑難排解指南。

設定 GKE 適用的 Workload Identity Federation 時，最常見的錯誤來源是錯別字和部分複製貼上，因此我們強烈建議使用這些操作說明中程式碼範例內建的可編輯變數和可點選的複製貼上圖示。

實際工作環境中的 GKE 工作負載身分聯盟

本文所述範例會將 Trusted Cloud 服務帳戶繫結至預設 Kubernetes 服務帳戶，並授予 Trusted Cloud服務帳戶使用 Monitoring API 的所有必要權限。

在正式環境中，您可能需要採用更精細的方法，為每個元件建立服務帳戶，並授予最基本的權限。如要進一步瞭解如何設定服務帳戶來管理工作負載身分，請參閱「使用 GKE 適用的工作負載身分聯盟」。

其他地方

如要在 Google Kubernetes Engine 以外的環境中部署及執行資料來源同步器，請按照下列步驟操作：

1. 設定資料來源同步器使用的服務帳戶：

   1. 設定 gcloud 指令的預設專案：

      gcloud config set project PROJECT_ID
      

   2. 建立資料來源同步器要使用的服務帳戶：

      gcloud iam service-accounts create DS_SYNCER_SVCACCT_NAME
      

   3. 授予服務帳戶讀取指標資料的權限：

       gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
       --role=roles/monitoring.viewer \
       && \
       gcloud projects add-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com \
       --role=roles/iam.serviceAccountTokenCreator
      

   4. 為服務帳戶建立金鑰：

      gcloud iam service-accounts keys create DS_SYNCER_SVCACCT_KEYFILE_NAME.json \
      --iam-account DS_SYNCER_SVCACCT_NAME@PROJECT_ID.s3ns-system.iam.gserviceaccount.com
      

      這個目錄的路徑會用於後續步驟中設定環境變數。如要取得路徑，請執行 pwd 指令並記錄值：

      pwd
      DS_SYNCER_SVCACCT_KEYFILE_DIR
      

2. 找出 Grafana 執行個體的網址，例如 Grafana Cloud 部署作業的 https://yourcompanyname.grafana.net，或是本機測試執行個體的 https://localhost:3000。這個值會用於執行資料來源同步器的指令。

   如果您在本機部署 Grafana，以用於設定為使用 TLS 保護所有叢集內流量的 Kubernetes 叢集，則需要在網址中使用 https://，並在下一個步驟中，使用支援的 TLS 驗證選項進行驗證。

3. 在 Grafana 中新增 Prometheus 資料來源，以用於 Cloud Monitoring，並記錄資料來源的 UID：

   1. 依序點選「連結」>「資料來源」>「新增資料來源」。從時間序列資料庫清單中選取「Prometheus」。

   2. 在「Prometheus server URL」(Prometheus 伺服器網址) 欄位中，輸入下列值：

      https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/
      

   3. 按一下「儲存並測試」

      瀏覽器中資料來源頁面的網址包含資料來源使用者介面，例如 https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID.

   4. 記錄資料來源 UID。這個值會用於執行資料來源同步器的指令。請勿複製整個資料來源網址。 只複製網址中的專屬 ID，例如： ee0z3woqjah34e

      GRAFANA_DATASOURCE_UID
      

4. 設定 Grafana 服務帳戶：建立服務帳戶，並為服務帳戶產生權杖，以供使用：

   1. 在 Grafana 導覽側欄中，依序點選「Administration」「Users and Access」「Service Accounts」。

   2. 按一下「新增服務帳戶」建立服務帳戶，為帳戶命名，並在 Grafana 中授予「管理員」角色。

   3. 按一下「新增服務帳戶權杖」。

   4. 將權杖到期日設為「永不過期」，然後按一下「產生權杖」，接著將產生的權杖複製到下列可編輯的變數。這個值會用於執行資料來源同步器的指令。

      GRAFANA_SERVICE_ACCOUNT_TOKEN
      

5. 執行資料來源同步器。您可以使用 Docker 從預先建構的容器映像檔執行同步器，也可以從來源建構程式碼並手動執行。資料來源同步器是 Go 應用程式，因此您必須安裝 Go，才能從來源建構同步器。

   Docker

   使用容器映像檔 gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0，從 Docker 執行資料來源同步器。如要進行測試，可以手動執行同步器。 確認連線正常運作後，由於存取權杖的效期為一小時，您必須使用自動化機制 (例如 cron 工作)，每 10 分鐘執行一次資料來源同步器，確保連線不會中斷。

   使用下列 Docker 指令執行資料來源同步器：

   docker run --network container:grafana -v "DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json:/app/DS_SYNCER_SVCACCT_KEYFILE_NAME.json" gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0
   -datasource-uids=UID_OF_GRAFANA_DATASOURCE
   -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN
   -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE
   -project-id=PROJECT_ID
   -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json
   -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
   

   如要建立 cron 工作來執行資料來源同步器，請按照下列步驟操作：

   1. 編輯 Cron 資料表：

      cron -e
      

   2. 新增每 10 分鐘執行上述指令的項目：

      */10 * * * * * docker run --network container:grafana -v "DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json:/app/<KEY_ID>" gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0 -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
      

   如要進一步瞭解執行資料來源同步器時可用的指令列選項，請參閱 README 文件。

   原始碼

   1. 如要自行建構資料來源同步器，請按照下列步驟操作：

      1. 建立目錄來存放程式碼，然後切換至該目錄：

         mkdir data-source-syncer-code
         
         cd data-source-syncer-code
         

         這個目錄的路徑會用於後續步驟中設定環境變數。如要取得路徑，請執行 pwd 指令，並將路徑記錄在可編輯的變數中：

         pwd
         PATH_TO_LOCAL_REPO_COPY
         

      2. 從目前版本的存放區複製程式碼：

         git clone -b 'v0.15.3' --single-branch https://github.com/GoogleCloudPlatform/prometheus-engine
         

      3. 前往 datasource-syncer 目錄並建構程式碼：

         cd prometheus-engine/cmd/datasource-syncer
         
         go build main.go
         

   2. 執行資料來源同步器。如要進行測試，可以手動執行同步器。確認連線正常運作後，由於存取權杖的有效時間為一小時，您必須使用自動化機制 (例如 cron 工作)，每 10 分鐘執行一次資料來源同步器，確保連線不會中斷。

      如要手動執行資料來源同步器，請使用下列指令：

      main -datasource-uids=UID_OF_GRAFANA_DATASOURCE
      -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN
      -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE
      -project-id=PROJECT_ID
      -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json
      -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
      

      如要建立 cron 工作來執行資料來源同步器，請按照下列步驟操作：

      1. 編輯 Cron 資料表：

          cron -e
         

      2. 新增每 10 分鐘執行上述指令的項目：

          */10 * * * * * main -datasource-uids=UID_OF_GRAFANA_DATASOURCE -grafana-api-token=GRAFANA_SERVICE_ACCOUNT_TOKEN -grafana-api-endpoint=URL_OF_GRAFANA_INSTANCE -project-id=PROJECT_ID -query.credentials-file=DS_SYNCER_SVCACCT_KEYFILE_DIR/DS_SYNCER_SVCACCT_KEYFILE_NAME.json -gcm-endpoint-override="https://monitoring.s3nsapis.fr/v1/projects/PROJECT_ID/location/global/prometheus/"
         

      如要進一步瞭解執行資料來源同步器時可用的指令列選項，請參閱 README 文件。

6. 前往新設定的 Grafana 資料來源，確認 Prometheus 伺服器網址值開頭為 https://monitoring.s3nsapis.fr。你可能需要重新整理頁面。驗證完成後，請前往頁面底部，然後按一下「儲存並測試」。您必須至少點選一次這個按鈕，才能確保 Grafana 中的標籤自動完成功能正常運作。