エージェントポリシーを管理する

エージェントポリシーを使用すると、ユーザーが指定した条件に一致する Compute Engine VM のフリート全体で Google Cloud Observability エージェントの自動インストールとメンテナンスを行えます。1 つのコマンドで Google Cloud プロジェクトのポリシーを作成し、その Google Cloud プロジェクトに関連付けられた既存の VM と新しい VM を管理できます。これにより、これらの VM 上のすべての Google Cloud Observability エージェントのインストールとオプションの自動アップグレードを適切に行うことができます。

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

サポートされているオペレーティングシステム

エージェントポリシーは、次の表に示すオペレーティングシステムを実行している Compute Engine VM インスタンスに適用できます。表のエージェント列は、gcloud beta compute instances ops-agents policies create 呼び出しに指定されたエージェントタイプにマッピングされます。

Logging エージェントは、エージェントタイプ logging のポリシーにマッピングされます。
Monitoring エージェントは、エージェントタイプ metrics のポリシーにマッピングされます。
Ops エージェントは、エージェントタイプ ops-agent のポリシーにマッピングされます。

オペレーティングシステム	Logging エージェント	Monitoring エージェント	Ops エージェント
CentOS 7
CentOS 8
Rocky Linux 8
RHEL 6
RHEL 7: rhel-7、rhel-7-6-sap-ha、rhel-7-7-sap-ha、rhel-7-9-sap-ha		¹
RHEL 8: rhel-8、rhel-8-4-sap-ha、rhel-8-6-sap-ha、rhel-8-8-sap-ha		¹
Debian 9（Stretch）
Debian 10（Buster）
Debian 11（Bullseye）
Ubuntu LTS 18.04（Bionic Beaver）: ubuntu-1804-lts、ubuntu-minimal-1804-lts
Ubuntu LTS 20.04（Focal Fossa）: ubuntu-2004-lts、ubuntu-minimal-2004-lts
Ubuntu LTS 22.04（Jammy Jellyfish）: ubuntu-2204-lts, ubuntu-minimal-2204-lts
SLES 12: sles-12、sles-12-sp5-sap
SLES 15: sles-15、sles-15-sp2-sap、sles-15-sp3-sap、sles-15-sp4-sap、sles-15-sp5-sap
OpenSUSE Leap 15: opensuse-leap（opensuse-leap-15-3-、 opensuse-leap-15-4-）
Windows Server: 2016、2019、2022、Core 2016、Core 2019、Core 2022

¹ Monitoring エージェントは、rhel-7-9-sap-ha、rhel-8-2-sap-ha または rhel-8-4-sap-ha ではサポートされていません。

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

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

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

このドキュメントでは、エージェントポリシーを管理するための beta コマンドグループについて説明します。
gcloud CLI の beta コンポーネントをまだインストールしていない場合は、インストールします。
```
gcloud components install beta
```
beta コンポーネントがインストールされているかどうかを確認するには、次を実行します。
```
gcloud components list
```
以前に beta コンポーネントをインストールしたことがある場合は、最新バージョンを使用していることを確認してください。
```
gcloud components update
```
スクリプト set-permissions.sh を使用して API を有効にし、Google Cloud CLI を使用するための適切な権限を設定します。

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

注: set-permissions.sh スクリプトは Linux 上で動作するように設計されています。別のオペレーティングシステムでマシンを使用している場合は、Cloud Shell からスクリプトを実行します。
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 というプロジェクトの CentOS 7 VM の段階的なロールアウトプランの例を次に示します。

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

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=centos,version=7 \
    --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 にインストールされていることを確認する必要があります。VM フリートに OS Config エージェントをインストールするには、次の操作を行います。

エージェントポリシーの作成セクションの set-permissions.sh スクリプトを実行済みであることを確認します。
OS Config エージェントをインストールする VM を特定し、CSV ファイルに記述します。たとえば、Google Kubernetes Engine、App Engine、またはその他の Google Cloud サービスで管理されていない VM のリストを取得して instances.csv というファイルに保存するには、次のコマンドを実行します。
```
  gcloud compute instances list \
      --filter="-labels.list(show="keys"):goog-" \
      --format="csv(name,zone)" \
      | grep -v -x -F -f  <(gcloud compute instances os-inventory list-instances \
          --format="csv(name,zone)") \
      | sed 's/$/,update/' > instances.csv
```
grep セクションでは、OS Config エージェントがすでにインストールされ、有効になっている VM が除外されます。goog- に基づく VM ラベルの除外では、GKE、App Engine　などで管理される Compute Engine VM が除外されます。

ゾーンまたはラベルでインスタンスをさらにフィルタリングするには、--filter フラグの値を次のような値に変更します。
```
  "-labels.list(show="keys"):goog- AND zone:(ZONE_1,ZONE_2) AND labels.KEY_1:VALUE_1 AND labels.KEY_2=VALUE_2"
```
Linux VM に OS Config エージェントをインストールするには、mass-install-osconfig-agent.sh スクリプトをダウンロードして実行します。

注: mass-install-osconfig-agent.sh スクリプトは OS Config エージェントのインストール手順を自動化しますが、OS Config エージェントをインストールできるのは Linux VM 上でのみです。Windows VM がある場合は、インストール手順を手動で実行します。
次のコマンドは、指定されたプロジェクトの instances.csv ファイルで指定された VM に OS Config エージェントをインストールします。
```
   bash mass-install-osconfig-agent.sh --project PROJECT_ID --input-file instances.csv
```
スクリプトの使用について詳しくは、スクリプトのコメントをご覧ください。

トラブルシューティング

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

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

検証エラーに加えて、次のエラーが表示される場合があります。

IAM 権限が不十分です

エラーの例を次に示します。
```
ERROR: (gcloud.beta.compute.instances.ops-agents.policies.command) PERMISSION_DENIED: Caller does not have required permission to command
```
エージェントポリシーの作成セクションで set-permissions.sh スクリプトを実行して、osconfig.guestPolicy 固有の IAM のロールを設定してください。

プロジェクトで十分な OS Config ゲストポリシーのロールが有効になっているかを確認するには、次のコマンドを実行します。この例のコマンドは、ユーザーが roles/osconfig.guestPolicyAdmin ロールを割り当てられているかを確認します。GCLOUD_MEMBER の値は、user:USER_EMAIL または serviceaccount:SERVICE_ACCOUNT_EMAIL の形式にする必要があります。
```
gcloud projects get-iam-policy PROJECT_ID \
    --filter=--member=GCLOUD_MEMBER \
    | grep "roles/osconfig.guestPolicyAdmin" -B 2
```
想定される出力は次のとおりです。
```
- members:
  - GCLOUD_MEMBER
  role: roles/osconfig.guestPolicyAdmin
```
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)?
```
エージェントポリシーの作成セクションで 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
```
これは、ポリシーがすでに削除されている可能性があることを示しています。describe、update、delete コマンドのポリシー ID が既存のポリシーにマッピングされていることを確認します。

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

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 エージェントがインストールされているかを確認するには、次の手順を行います。

RDP または同様のツールを使用してインスタンスに接続し、Windows にログインします。
PowerShell ターミナルを開き、次の PowerShell コマンドを実行します。管理者権限は必要ありません。
```
Get-Service google_osconfig_agent
```

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

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

SUSE および Ubuntu Compute Engine インスタンスには OS Config エージェントが事前インストールされていないため、OS Config エージェントのインストール手順に沿って OS Config エージェントをこれらの Compute Engine インスタンスにインストールする必要があります。

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

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

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

resource.type="gce_instance"
logName="projects/PROJECT_ID/logs/OSConfigAgent"

SSH を使用して個別の Compute Engine Linux インスタンスの 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"

RDP を使用して個別の Compute Engine Windows インスタンスの OS Config エージェントのログを表示するには、次の手順を行います。

RDP または同様のツールを使用してインスタンスに接続し、Windows にログインします。
Event Viewer アプリを開き、Windows Logs => Application で、Source が OSConfigAgent と等しいログを検索します。

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

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'

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

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

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` スクリプトの処理内容

プロジェクト ID、Identity and Access Management（IAM）ロール、メールアドレスまたはサービスアカウントにより、set-permissions.sh スクリプトは次のアクションを行います。

プロジェクトに対して Cloud Logging API、Cloud Monitoring API、OS Config API を有効にします。
Compute Engine のデフォルトのサービスアカウントに roles/logging.logWriter と roles/monitoring.metricWriter のロールを付与します。これにより、エージェントはログと指標を Logging API と Cloud Monitoring API に書き込めます。
プロジェクトの OS Config メタデータを有効にして、OS Config エージェントが VM で有効になるようにします。
指定された IAM ロールを gcloud ユーザーまたはサービスアカウントに付与します。プロジェクトオーナーは、ポリシーの作成と管理を行うための完全アクセス権を持っています。他のすべてのユーザーまたはサービスアカウントの場合は、プロジェクトオーナーが次のいずれかのロールを付与する必要があります。
- roles/osconfig.guestPolicyAdmin: あるポリシーに対する完全アクセス権を付与します。
- roles/osconfig.guestPolicyEditor: ユーザーによるポリシーの取得、更新、一覧表示を許可します。
- 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` スクリプトの処理内容

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

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

Terraform 統合

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

エージェント ポリシーを管理する

サポートされているオペレーティング システム

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

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