エージェント ポリシーを使用する（ベータ版）

この機能には、サービス固有の利用規約の「一般的なサービス規約」の「pre-GA サービス規約」が適用されます。 pre-GA の機能は「現状有姿」で利用できますが、サポートが制限される場合があります。 詳しくは、リリース ステージの説明をご覧ください。

エージェント ポリシーの作成と管理は、Google Cloud CLI の gcloud beta compute instances ops-agents policies コマンド グループを使用して行います。このグループのコマンドは、Compute Engine の VM Manager ツールスイートを使用して OS ポリシーを管理します。このポリシーでは、Google Cloud Observability エージェント（Ops エージェント、従来の Monitoring エージェント、従来の Logging エージェント）などのソフトウェア構成のデプロイとメンテナンスを自動化できます。

注: このドキュメントでは、ベータ版の compute instances ops-agents policies コマンドについて説明します。これらのコマンドは、一般提供リリースでも利用可能です。一般提供の compute instances ops-agents policies コマンドについては、エージェント ポリシー（一般提供）を使用するをご覧ください。2 つのリリースの違いと、ベータ版エージェント ポリシーを一般提供エージェント ポリシーに変換する方法については、Ops エージェントのエージェント ポリシーの概要をご覧ください。

エージェント ポリシーを作成する

Google Cloud CLI を使用してエージェント ポリシーを作成するには、次の操作を行います。

1. Google Cloud CLI をまだインストールしていない場合は、インストールします。

   このドキュメントでは、エージェント ポリシーを管理するための beta コマンド グループについて説明します。

2. gcloud CLI の beta コンポーネントをまだインストールしていない場合は、インストールします。

   gcloud components install beta
   

   beta コンポーネントがインストールされているかどうかを確認するには、次を実行します。

   gcloud components list
   

   以前に beta コンポーネントをインストールしたことがある場合は、最新バージョンを使用していることを確認してください。

   gcloud components update
   

3. 次のスクリプト set-permissions.sh をダウンロードして使用し、API を有効にし、Google Cloud CLI を使用するための適切な権限を設定します。

   スクリプトの詳細については、set-permissions.sh スクリプトをご覧ください。

   注: set-permissions.sh スクリプトは Linux 上で動作するように設計されています。別のオペレーティング システムでマシンを使用している場合は、Cloud Shell からスクリプトを実行します。

4. gcloud beta compute instances ops-agents policies create コマンドを使用して、ポリシーを作成します。コマンドの構文については、gcloud beta compute instances ops-agents policies create のドキュメントをご覧ください。

   コマンドの形式を設定する方法の例については、Google Cloud CLI ドキュメントの例セクションをご覧ください。

   このコマンド グループの他のコマンドと使用可能なオプションの詳細については、gcloud beta compute instances ops-agents policies のドキュメントをご覧ください。

エージェント ポリシーを使用するためのベスト プラクティス

ロールアウト中に本番環境システムへの影響を制御するには、インスタンス ラベルとゾーンを使用して、ポリシーを適用するインスタンスをフィルタリングすることをおすすめします。

Ops エージェントのポリシーを作成する場合は、VM に以前の Logging エージェントまたは Monitoring エージェントがインストールされていないことを確認します。同じ VM で Ops エージェントと以前のエージェントを実行すると、重複したログの取得や、指標の取得での競合が発生することがあります。必要に応じて、Ops エージェントをインストールするポリシーを作成する前に、Monitoring エージェントをアンインストールして、Logging エージェントをアンインストールします。

my_project というプロジェクト内の Debian 11 VM の段階的なロールアウト計画の例を次に示します。

フェーズ 1: ops-agents-policy-safe-rollout という名前のポリシーを作成し、ラベル env=test と app=myproduct を使用してすべての VM に Ops エージェントをインストールします。

gcloud beta compute instances \
    ops-agents policies create ops-agents-policy-safe-rollout \
    --agent-rules="type=ops-agent,version=current-major,package-state=installed,enable-autoupgrade=true" \
    --os-types=short-name=debian,version=11 \
    --group-labels=env=test,app=myproduct \
    --project=my_project

オペレーティング システムの指定について詳しくは、gcloud beta compute instances ops-agents policies　create をご覧ください。

フェーズ 2: ラベル env=prod と app=myproduct を持つ単一ゾーンの VM をターゲットとするように、作成したポリシーを更新します。

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --group-labels=env=prod,app=myproduct \
    --zones=us-central1-c \

フェーズ 3: ゾーンのフィルタを消去して、ポリシーがグローバルに展開されるよう、ポリシーを更新します。

gcloud beta compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --clear-zones

OS Config より古い VM 上のポリシー

OS Config より古い VM には、OS Config エージェントを手動でインストールして構成する必要があります。OS Config エージェントを手動でインストールして検証する方法については、VM Manager の確認チェックリストをご覧ください。

ベータ版エージェントのポリシーのトラブルシューティング

このセクションでは、Ops エージェント、以前の Monitoring エージェント、以前の Logging エージェントのベータ版エージェント ポリシーに関する問題を解決する際に有用な情報を提供します。

ops-agents policy コマンドが失敗する

gcloud beta compute instances ops-agents policies コマンドが失敗すると、検証エラーがレスポンスに表示されます。このようなエラーは、エラー メッセージの内容に従いコマンドの引数とフラグを修正することで解決します。

検証エラーに加えて、次の条件を示すエラーが表示されることがあります。

• IAM 権限が不十分です
• OS Config API が有効になっていない
• 指定されたポリシーが存在しません

以降のセクションでは、これらの状態について詳しく説明します。

IAM 権限が不十分です

gcloud beta compute instances ops-agents policies コマンドが権限エラーで失敗した場合は、エージェント ポリシーを作成するで説明されている set-permissions.sh スクリプトを実行して OS Config ポリシーのロールを設定していることを確認してください。

• GuestPolicy 管理者（roles/osconfig.guestPolicyAdmin）: ゲストポリシーに対する完全アクセス権を付与します。
• GuestPolicy 編集者（roles/osconfig.guestPolicyEditor）: ユーザーはゲストポリシーを取得、更新、一覧表示できます。
• GuestPolicy 閲覧者（roles/osconfig.guestPolicyViewer）: ゲストポリシーを取得して一覧表示するための読み取り専用アクセス権を付与します。

set-permissions.sh スクリプトの詳細については、set-permissions.sh スクリプトをご覧ください。

OS Config API が有効になっていない

エラーの例を次に示します。

API [osconfig.googleapis.com] not enabled on project PROJECT_ID.
Would you like to enable and retry (this will take a few minutes)?
(y/N)?

y を入力して API を有効にするか、エージェント ポリシーの作成で説明されているように set-permissions.sh スクリプトを実行して、必要なすべての権限を付与します。エラー メッセージのプロンプトで「y」と入力した場合は、set-permissions.sh スクリプトを実行して必要な権限を設定する必要があります。

プロジェクトで OS Config API が有効になっていることを確認するには、次のコマンドを実行します。

gcloud services list --project PROJECT_ID | grep osconfig.googleapis.com

想定される出力は次のとおりです。

osconfig.googleapis.com    Cloud OS Config API

ポリシーが存在しません

エラーの例を次に示します。

NOT_FOUND: Requested entity was not found

このエラーは、ポリシーがまったく作成されていない、ポリシーが削除された、または指定されたポリシー ID が正しくないことを表している可能性があります。gcloud beta compute instances ops-agents policies describe、update、delete コマンドで使用される POLICY_ID が、既存のポリシーに対応していることを確認します。エージェント ポリシーの一覧を取得するには、gcloud beta compute instances ops-agents policies list コマンドを使用します。

ポリシーは作成されていますが、効果がないようです

OS Config エージェントは、各 Compute Engine インスタンスにデプロイされて、Logging エージェントと Monitoring エージェント用のパッケージを管理します。基盤となる OS Config エージェントがインストールされていない場合、このポリシーは効果がないように見える可能性があります。

Linux

OS Config エージェントがインストールされているかを確認するには、次のコマンドを実行します。

gcloud compute ssh instance-id \
    --project project-id \
    -- sudo systemctl status google-osconfig-agent

出力例は以下のとおりです。

    google-osconfig-agent.service - Google OSConfig Agent
    Loaded: loaded (/lib/systemd/system/google-osconfig-agent.service; enabled; vendor preset:
    Active: active (running) since Wed 2020-01-15 00:14:22 UTC; 6min ago
    Main PID: 369 (google_osconfig)
     Tasks: 8 (limit: 4374)
    Memory: 102.7M
    CGroup: /system.slice/google-osconfig-agent.service
            └─369 /usr/bin/google_osconfig_agent

Windows

OS Config エージェントがインストールされているかを確認するには、次の手順を行います。

1. RDP または同様のツールを使用してインスタンスに接続し、Windows にログインします。

2. PowerShell ターミナルを開き、次の PowerShell コマンドを実行します。管理者権限は必要ありません。

   Get-Service google_osconfig_agent
   

出力例は以下のとおりです。

    Status   Name               DisplayName
    ------   ----               -----------
    Running  google_osconfig_a… Google OSConfig Agent

OS Config エージェントがインストールされていない場合は、VM Manager をサポートしていないオペレーティング システムを使用している可能性があります。Compute Engine のオペレーティング システムの詳細のドキュメントでは、各 Compute Engine オペレーティング システムでサポートされている VM Manager の機能について説明しています。

オペレーティング システムが VM Manager をサポートしている場合は、手動で OS Config エージェントをインストールできます。

OS Config エージェントはインストールされますが、Ops エージェントがインストールされません

OS Config エージェントがポリシーを適用したときにエラーが発生するかどうかを確認するには、OS Config エージェントのログを確認します。この確認は、ログ エクスプローラを使用するか、SSH または RDP を使用して個別の Compute Engine インスタンスをチェックすることで行えます。

ログ エクスプローラで OS Config エージェントのログを表示するには、次のフィルタを使用します。

resource.type="gce_instance"
logId(OSConfigAgent)

OS Config エージェントのログを表示する方法は次のとおりです。

CentOS, RHEL,
SLES, SUSE

次のコマンドを実行します。

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/messages \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

Debian, Ubuntu

次のコマンドを実行します。

gcloud compute ssh INSTANCE_ID \
    --project PROJECT_ID \
    -- sudo cat /var/log/syslog \
       | grep "OSConfigAgent\|google-fluentd\|stackdriver-agent"

Windows

1. RDP または同様のツールを使用してインスタンスに接続し、Windows にログインします。

2. イベント ビューア アプリを開き、[Windows Logs] > [Application] の順に選択し、Source が OSConfigAgent と等しいログを検索します。

OS Config サービスへの接続中にエラーが発生した場合は、エージェント ポリシーの作成で説明されているように set-permissions.sh スクリプトを実行して、OS Config メタデータを設定します。

OS Config メタデータが有効になっているかを確認するには、次のコマンドを実行します。

gcloud compute project-info describe \
    --project PROJECT_ID \
    | grep "enable-osconfig\|enable-guest-attributes" -A 1

想定される出力は次のとおりです。

- key: enable-guest-attributes
  value: 'TRUE'
- key: enable-osconfig
  value: 'TRUE'

オブザーバビリティ エージェントがインストールされていますが、正常に動作しません

特定のエージェントのデバッグについては、次のドキュメントをご覧ください。

• Ops エージェントをトラブルシューティングする
• 以前の Logging エージェントをトラブルシューティングする
• 以前の Monitoring エージェントをトラブルシューティングする

OS Config エージェントのデバッグレベルのログを有効にする

OS Config エージェントでデバッグレベルのロギングを有効にすると、問題を報告するときに役立ちます。

osconfig-log-level: debug メタデータを設定すると、OS Config エージェントのデバッグレベルのロギングを有効にできます。収集されたログには、調査に役立つ情報が記録されています。

プロジェクト全体のデバッグレベルのロギングを有効にするには、次のコマンドを実行します。

gcloud compute project-info add-metadata \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

1 つの VM に対するデバッグレベルのロギングを有効にするには、次のコマンドを実行します。

gcloud compute instances add-metadata INSTANCE_ID \
    --project PROJECT_ID \
    --metadata osconfig-log-level=debug

ヘルパー スクリプト

このセクションでは、このドキュメントで説明するヘルパー スクリプトに関する追加情報について説明します。

• set-permissions.sh スクリプトは次のことを行います。
• diagnose.sh スクリプトは次のことを行います。

set-permissions.sh スクリプトは次のことを行います。

set-permissions.sh スクリプトをダウンロードすると、このスクリプトを使用して、指定した引数に基づいて次の操作を実行できます。

• プロジェクトに対して Cloud Logging API、Cloud Monitoring API、OS Config API を有効にします。

• Identity and Access Management ロールのログ書き込み（roles/logging.logWriter）とモニタリング指標の書き込み（roles/monitoring.metricWriter）をCompute Engine のデフォルトのサービス アカウントに付与してください。これにより、エージェントはログと指標を Logging API と Cloud Monitoring API に書き込めるようになります。

• 各 VM の OS Config エージェントがアクティブになるように、プロジェクトの OS Config メタデータを有効にします。

• ポリシーの作成と管理に必要な、オーナー以外のユーザーまたはサービス アカウントに、次のいずれかの IAM ロールを付与します。プロジェクト オーナーは、ポリシーの作成と管理を行うための完全アクセス権を持っています。他のすべてのユーザーまたはサービス アカウントには、次のいずれかのロールを付与する必要があります。

  • GuestPolicy 管理者（roles/osconfig.guestPolicyAdmin）: ゲストポリシーに対する完全アクセス権を付与します。
  • GuestPolicy 編集者（roles/osconfig.guestPolicyEditor）: ユーザーはゲストポリシーを取得、更新、一覧表示できます。
  • GuestPolicy 閲覧者（roles/osconfig.guestPolicyViewer）: ゲストポリシーを取得して一覧表示するための読み取り専用アクセス権を付与します。

  スクリプトを実行する場合は、ロール名の guestPolicy* 部分を指定するだけで済みます。このスクリプトは、名前の roles/osconfig. 部分を指定します。

次の例は、スクリプトの一般的な呼び出しを示しています。詳細については、スクリプト自体のコメントをご覧ください。

API を有効にするには、デフォルトのサービス アカウントに必要なロールを付与し、プロジェクトの OS Config メタデータを有効にするには、次のようにスクリプトを実行します。

bash set-permissions.sh --project=PROJECT_ID

プロジェクトに対するオーナー（roles/owner）ロールを持たないユーザーに OS Config のいずれかのロールを付与するには、次のようにスクリプトを実行します。

bash set-permissions.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

さらに、デフォルト以外のサービス アカウントに OS Config ロールのいずれかを付与するには、次のようにスクリプトを実行します。

bash set-permissions.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-permission-role=guestPolicy[Admin|Editor|Viewer]

diagnose.sh スクリプトは次のことを行います。

プロジェクト ID、Compute Engine インスタンス ID、エージェント ポリシー ID を指定すると、diagnose.sh スクリプトがポリシーの問題を診断するために必要な情報を自動的に収集します。

• OS Config エージェントのバージョン
• 基盤となる OS Config ゲストポリシー
• この Compute Engine インスタンスに適用されるポリシー
• この Compute Engine インスタンスに pull されるエージェント Package Repository

スクリプトを呼び出すには、次のコマンドを実行します。

bash diagnose.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID 

Terraform 統合

Terraform のサポートは、Google Cloud CLI コマンドを基盤として構築されています。Terraform を使用してエージェント ポリシーを作成する方法については、Terraform モジュールの手順をご覧ください。