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

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

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

このセクションでは、Google Cloud SDK を使用してエージェント ポリシーを管理する方法について説明します。Terraform の使用方法については、Terraform 統合をご覧ください。

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 スクリプトをご覧ください。

  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: ラベル 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=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 権限が不十分です

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

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

ポリシーがすでに存在する

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

ALREADY_EXISTS: Requested entity already exists

このエラーは、同じ名前、プロジェクト ID、リージョンのポリシーがすでに存在することを意味します。gcloud beta compute instances ops-agents policies describe コマンドを使用して、このことを確認できます。

ポリシーが存在しません

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

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'

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

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

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 スクリプトは次のことを行います。

set-permissions.sh スクリプトをダウンロードしたら、指定した引数に基づいて、次のアクションを実行できます。

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

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 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。Terraform の仕組みについては、Terraform の使用をご覧ください。

エージェント ポリシーの Terraform サポートは、Google Cloud CLI コマンドを基盤として構築されています。Terraform を使用してエージェント ポリシーを作成する方法については、Terraform モジュールの agent-policy の手順をご覧ください。ポリシーの例は examples ディレクトリでも確認できます。