Cloud Monitoring の PromQL

GKE

Kubernetes クラスタにデータソース同期ツールをデプロイして実行するには、次の操作を行います。

1. データソース同期ツールをデプロイするプロジェクト、クラスタ、Namespace を選択します。

   次に、データソース同期ツールを適切に構成して認可していることを確認します。

   • Workload Identity Federation for GKE を使用している場合は、サービス アカウントを作成して認可する手順に沿って操作します。データソース同期ツールを実行する Kubernetes Namespace にバインドしてください。
   • Workload Identity Federation for GKE を使用していない場合は、デフォルトの Compute Engine サービス アカウントを変更していないことを確認します。

2. Grafana インスタンスの URL を特定します。たとえば、Grafana Cloud デプロイの場合は https://yourcompanyname.grafana.net、テストデプロイ YAML を使用して構成されたローカル インスタンスの場合は http://grafana.NAMESPACE_NAME.svc:3000 です。

   Grafana をローカルにデプロイし、TLS を使用してクラスタ内のすべてのトラフィックを保護するようにクラスタが構成されている場合は、URL で https:// を使用し、サポートされている TLS 認証オプションのいずれかを使用して認証を行う必要があります。

3. Cloud Monitoring に使用する Grafana Prometheus データソース（新規または既存のデータソース）を選択し、データソースの UID を探して書き留めます。データソースの UID は、データソースを確認または構成するときに URL の最後の部分に表示されます（例: https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID.）。データソースの URL 全体をコピーしないでください。URL の固有識別子のみをコピーします。

4. サービス アカウントを作成して、アカウントで使用するトークンを生成することで、Grafana サービス アカウントを設定します。

   1. Grafana のナビゲーション サイドバーで、[Administration] > [Users and Access] > [Service Accounts] をクリックします。

   2. [Add service account] をクリックしてサービス アカウントを作成します。名前を指定し、Grafana の「Admin」ロールを付与します。使用している Grafana のバージョンでより細かい権限が許可されている場合は、[Data Source] > [Writer] ロールを使用できます。

   3. [Add service account token] をクリックします。

   4. トークンの有効期限を「No expiration」に設定し、[Generate token] をクリックします。次に、生成されたトークンをクリップボードにコピーして、次のステップで 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. 次のコマンドを実行して、初期化時と 10 分ごとにデータソースを更新する CronJob を作成します。Workload Identity Federation for GKE を使用している場合、NAMESPACE_NAME の値は、以前にサービス アカウントにバインドした Namespace と同じにする必要があります。

   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 サーバー URL の値が https://monitoring.s3nsapis.fr で始まっていることを確認します。ページの更新が必要になることもあります。確認したら、ページの下部に移動し、[Save & test] を選択します。Grafana のラベルの予測入力が機能するように、このボタンを少なくとも 1 回選択する必要があります。

サービス アカウントの認証情報を確認する

Kubernetes クラスタで Workload Identity Federation for GKE が有効になっている場合は、このセクションをスキップできます。

GKE で実行すると、Cloud Monitoring は Compute Engine のデフォルトのサービス アカウントに基づいて環境から認証情報を自動的に取得します。デフォルトのサービス アカウントには、必要な権限である monitoring.metricWriter と monitoring.viewer がデフォルトで付与されています。Workload Identity Federation for GKE を使用しておらず、以前にいずれかのロールをデフォルトのノードサービス アカウントから削除している場合は、続行する前に、不足している権限を再度追加する必要があります。

Workload Identity Federation for GKE 用のサービス アカウントを構成する

Kubernetes クラスタで Workload Identity Federation for GKE が有効になっていない場合は、このセクションをスキップできます。

Cloud Monitoring は、Cloud Monitoring API を使用して指標データをキャプチャします。クラスタで Workload Identity Federation for GKE を使用している場合は、Kubernetes サービス アカウントに Monitoring API の権限を付与する必要があります。このセクションでは、次のことを説明します。

• 専用の Trusted Cloud by S3NS サービス アカウント SERVICE_ACCT_NAME を作成する。
• テスト用の名前空間 NAMESPACE_NAME のデフォルトの Kubernetes サービス アカウントに Trusted Cloud サービス アカウントをバインドする。
• 必要な権限を 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

Workload Identity Federation for GKE の構成をデバッグする

Workload Identity Federation for GKE の動作に問題がある場合は、Workload Identity Federation for GKE の設定の確認と Workload Identity Federation for GKE のトラブルシューティング ガイドをご覧ください。

Workload Identity Federation for GKE の構成で最も一般的なエラーの原因は入力ミスや、部分的なコピー / 貼り付けです。これらの手順のコードサンプルに埋め込まれた編集可能な変数と、クリック可能なコピー / 貼り付けアイコンを使用することを強くおすすめします。

本番環境での Workload Identity Federation for GKE

このドキュメントの例では、 Trusted Cloud サービス アカウントをデフォルトの Kubernetes サービス アカウントにバインドし、Monitoring API を使用するために必要なすべての権限を Trusted Cloudサービス アカウントに付与しています。

本番環境では、各コンポーネントのサービス アカウントを最小権限で使用し、よりきめ細かいアプローチを使用する必要があります。Workload Identity 管理のサービス アカウントを構成する方法の詳細については、Workload Identity Federation for 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 インスタンスの URL を確認します。たとえば、Grafana Cloud デプロイの場合は https://yourcompanyname.grafana.net、ローカル テスト インスタンスの場合は https://localhost:3000 です。この値は、データソース同期ツールを実行するコマンドで使用されます。

   TLS を使用してクラスタ内のすべてのトラフィックを保護するように構成された Kubernetes クラスタに対して Grafana をローカルにデプロイする場合は、URL で https:// を使用し、次のステップで、サポートされている TLS 認証オプションのいずれかで認証を行う必要があります。

3. Grafana で、Cloud Monitoring に使用する Prometheus データソースを追加し、データソースの UID を記録します。

   1. [接続] > [データソース] > [Add a new data source] をクリックします。時系列データベースのリストから [Prometheus] を選択します。

   2. [Prometheus server URL] フィールドに次の値を入力します。

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

   3. [Save and test] をクリックします。

      データソース ページのブラウザの URL には、データソース UI が含まれています（例: https://yourcompanyname.grafana.net/connections/datasources/edit/GRAFANA_DATASOURCE_UID.）。

   4. データソースの UID を記録します。この値は、データソース同期ツールを実行するコマンドで使用されます。データソースの URL 全体をコピーしないでください。URL の固有識別子のみをコピーします。これは ee0z3woqjah34e のような値です。

      GRAFANA_DATASOURCE_UID
      

4. サービス アカウントを作成して、サービス アカウントで使用するトークンを生成することで、Grafana サービス アカウントを設定します。

   1. Grafana のナビゲーション サイドバーで、[Administration] | [Users and Access] | [Service Accounts] をクリックします。

   2. [Add service account] をクリックしてサービス アカウントを作成します。名前を指定し、Grafana で「管理者」ロールを付与します。

   3. [Add service account token] をクリックします。

   4. トークンの有効期限を「No expiration」に設定し、[Generate token] をクリックします。次生成されたトークンを次の編集可能な変数にコピーします。この値は、データソース同期ツールを実行するコマンドで使用されます。

      GRAFANA_SERVICE_ACCOUNT_TOKEN
      

5. データソース同期ツールを実行します。Docker を使用してビルド済みのコンテナ イメージから同期ツールを実行することも、ソースからコードをビルドして手動で実行することもできます。データソース同期ツールは Go アプリケーションであるため、ソースから同期ツールをビルドするには Go をインストールする必要があります。

   Docker

   コンテナ イメージ gke.gcr.io/prometheus-engine/datasource-syncer:v0.15.3-gke.0 を使用して、Docker からデータソース同期ツールを実行します。テストでは、同期ツールを手動で実行できます。アクセス トークンの有効期間は 1 時間であるため、接続が機能していることを確認したら、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. データソース同期ツールを実行します。テストでは、同期ツールを手動で実行できます。アクセス トークンの有効期間は 1 時間であるため、接続が機能していることを確認したら、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 サーバー URL の値が https://monitoring.s3nsapis.fr で始まっていることを確認します。ページの更新が必要になることもあります。確認したら、ページの下部に移動し、[Save & test] をクリックします。Grafana のラベルの予測入力が機能するように、このボタンを少なくとも 1 回クリックする必要があります。