エージェント ポリシーの作成と管理は、Google Cloud CLI の gcloud beta compute instances ops-agents policies
コマンド グループを使用して行います。このグループのコマンドは、Compute Engine の VM Manager ツールスイートを使用して OS ポリシーを管理します。このポリシーでは、Google Cloud Observability エージェント(Ops エージェント、従来の Monitoring エージェント、従来の Logging エージェント)などのソフトウェア構成のデプロイとメンテナンスを自動化できます。
エージェント ポリシーを作成する
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
スクリプトをご覧ください。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 権限が不十分です
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 エージェントがインストールされているかを確認するには、次の手順を行います。
RDP または同様のツールを使用してインスタンスに接続し、Windows にログインします。
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
RDP または同様のツールを使用してインスタンスに接続し、Windows にログインします。
イベント ビューア アプリを開き、[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
スクリプトは次のことを行います。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 に書き込めるようになります。プロジェクトの OS Config メタデータを有効にして、各 VM の OS Config エージェントを有効にします。
オーナー以外のユーザーまたはサービス アカウントに、ポリシーの作成と管理に必要な次のいずれかの IAM ロールを付与します。プロジェクト オーナーは、ポリシーの作成と管理に対する完全アクセス権を持ちます。他のすべてのユーザーまたはサービス アカウントには、次のいずれかのロールを付与する必要があります。
- GuestPolicy 管理者(
roles/osconfig.guestPolicyAdmin
): ゲストポリシーに対する完全アクセス権を付与します。 - GuestPolicy 編集者(
roles/osconfig.guestPolicyEditor
): ユーザーがゲストポリシーを取得、更新、一覧表示できるようにします。 - GuestPolicy 閲覧者(
roles/osconfig.guestPolicyViewer
): ゲストポリシーを取得して一覧表示するための読み取り専用アクセス権を付与します。
スクリプトを実行する場合は、ロール名の
guestPolicy*
部分を指定するだけで済みます。このスクリプトは、名前のroles/osconfig.
部分を指定します。- GuestPolicy 管理者(
次の例は、スクリプトの一般的な呼び出しを示しています。詳しくは、スクリプト内のコメントをご覧ください。
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 モジュールの手順をご覧ください。