エージェント ポリシーを使用する(一般提供)

エージェント ポリシーの作成と管理は、Google Cloud CLI の gcloud compute instances ops-agents policies コマンド グループを使用して行います。このグループのコマンドは、Compute Engine の VM Manager ツールスイートを使用して OS ポリシーを管理します。これにより、Ops エージェントなどのソフトウェア構成のデプロイとメンテナンスが自動化されます。これらのポリシーは、以前の Monitoring エージェントまたは以前の Logging エージェントに適用できません。

gcloud compute instances ops-agents policies コマンド グループは、OS Config API の OS ポリシーの割り当てリソースを使用します。OS ポリシーの割り当てを管理するための一般的な gcloud CLI コマンド グループ(gcloud compute os-config os-policy-assignments)がありますが、gcloud compute instances ops-agents policies コマンド グループは、このドキュメントで説明するエージェント ポリシー専用に設計されています。

始める前に

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

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

  2. prepare-for-ops-agents-policies.sh スクリプトをダウンロードして実行し、必要な API を有効にして、Google Cloud CLI を使用するための適切な権限を設定します。

    スクリプトの詳細については、prepare-for-ops-agents-policies.sh スクリプトをご覧ください。

以前の Monitoring エージェントと Logging エージェントをアンインストールする

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

OS Config エージェントがインストールされていることを確認する

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

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

アクセス ポリシーを作成するには、gcloud compute instances ops-agents policiescreate コマンドを使用します。このコマンドの構造は次のとおりです。

gcloud compute instances ops-agents policies create POLICY_ID \
  --zone ZONE \
  --file path/to/policy-description-file.yaml \
  --project PROJECT_ID

このコマンドを使用する場合は、変数を次のように置き換えます。

  • POLICY_ID はポリシーの名前です。
  • ZONE は Compute Engine ゾーンです。エージェント ポリシーは、指定されたゾーンの VM にのみ適用されます。複数のゾーンにポリシーを適用するには、複数のポリシーを作成する必要があります。
  • path/to/policy-description-file.yaml は、ポリシーを記述する YAML ファイルのパスです。このファイルの構造については、エージェント ポリシーを記述するをご覧ください。
  • PROJECT_ID は、Google Cloud プロジェクトの ID です。

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

エージェント ポリシーを記述する

ポリシー情報を gcloud compute instances ops-agents policies create に渡すには、ポリシーを記述する YAML ファイルを作成し、そのファイルを --file オプションの値としてコマンドに渡します。

このセクションでは、policy-description ファイルの構造について説明します。詳細については、policy-description ファイルの例をご覧ください。

YAML policy-description ファイルの形式

エージェント ポリシーの説明ファイルには、次の 2 つのフィールド グループを含める必要があります。

  • agentsRule。エージェント ポリシーに、Ops エージェントのインストールまたは削除を指示し、処理する Ops エージェントのバージョンを指定します。

  • instanceFilter: ポリシーを適用する VM を記述します。

agentsRule フィールド グループの構造

agentsRule フィールド グループの構造は次のとおりです。

agentsRule:
  packageState: installed|removed
  version: latest|2.*.*|2.x.y
  • packageState フィールドは、Ops エージェントの目的の状態をポリシーに指示します。有効な値は installedremoved です。
  • version フィールドは、インストールまたは削除する Ops エージェントのバージョンを示します。指定できる値は次のとおりです。

    • latest は、Ops エージェントの最新バージョンです。
    • 2.*.* は、Ops エージェントのメジャー バージョン 2 の最新リリースです。
    • 2.x.y は、メジャー バージョン 2 の特定のリリースを示します。

    Ops エージェントの使用可能なバージョンについては、エージェントの GitHub リポジトリをご覧ください。

instanceFilter フィールド グループの構造

instanceFilter フィールド グループは、フィルタが適用されるゾーン内の VM を示します。このフィールド グループは、OS Config API の OSPolicyAssignment リソースで使用される InstanceFilter 構造の YAML 表現です。

instanceFilter フィールド グループには、次のいずれかの構造があります。

  • ゾーン内のすべての VM にエージェント ポリシーを適用するには、次のコマンドを使用します。

    instanceFilter:
      all: True
    

    all: True フィルタを使用する場合は、他の条件を指定できません。

  • ゾーン内の特定の VM セットにエージェント ポリシーを適用するには、次のいずれかの組み合わせを使用して VM を記述します。

    • VM のラベル(包含または除外):
      • inclusionLabels:
      • exclusionLabels:
    • オペレーティング システム: inventories:

    たとえば、次のフィルタは、ラベルが env=prod で、ラベルが app=web ではない、指定されたオペレーティング システムの VM にエージェント ポリシーを適用します。

    instanceFilter:
      inclusionLabels:
      - labels:
          env: prod
      exclusionLabels:
      - labels:
          app: web
      inventories:
      - osShortName: rhel
        osVersion: '7.*'
      - osShortName: debian
        osVersion: '11'
    

    VM の osShortName フィールドと osVersion フィールドの値を確認するには、次のコマンドを使用します。

    gcloud compute instances os-inventory describe INSTANCE_NAME \
    --zone ZONE | grep "^ShortName: "
    
    gcloud compute instances os-inventory describe INSTANCE_NAME \
    --zone ZONE | grep "^Version: "
    

    これらのコマンドを使用するには、OS Config エージェントが VM にインストールされている必要があります。

エージェント ポリシーのステータスを確認する

このセクションでは、作成されたポリシーのステータスと Ops エージェントのインストールを確認する方法について説明します。この情報は、エージェント ポリシーのトラブルシューティングにも役立ちます。

Compute Engine の [OS ポリシー] ページ

Compute Engine の [OS ポリシー] ページには、Ops エージェントを管理するエージェント ポリシーと、[VM インスタンス] タブの VM に関する情報が表示されます。例:

  • [状態] 列には、ポリシーが正常にインストールされたか(「準拠」)、インストール中か(「保留中」)、失敗した可能性があるか(「不明」)、または存在しないか(「ポリシーなし」)が表示されます。
  • [VM モニタリング] 列には、Ops エージェントが OS Config によって管理されているか(「モニタリング対象」)、管理されていないか(「モニタリング対象外」)が表示されます。

    ポリシーが「準拠」であるにもかかわらず、VM が「モニタリング対象外」と表示される場合は、Ops エージェントのインストールに問題がある可能性があります。たとえば、以前のエージェントがすでにインストールされている可能性があります。

Google Cloud コンソールで、[OS ポリシー] ページに移動します。

[OS ポリシー] に移動

検索バーを使用してこのページを検索する場合は、サブ見出しが [Compute Engine] の結果を選択します。

Compute Engine の [OS ポリシー] タブの [VM インスタンス] には、Google Cloud プロジェクト内のすべての OS ポリシーによって管理されているエージェントの情報が表示されます。これらのポリシーには goog-ops-agent-policy というラベルが付いています。

  • goog-ops-agent-policy インジケーターは、次の種類のポリシーを表します。
    • gcloud compute instances ops-agents policies コマンドを使用して作成されたポリシー。
    • VM の作成時に Ops エージェントのインストールをリクエストした際に、自動的に作成されるポリシー。
    • Terraform を使用して Ops エージェントを管理するために作成されたポリシー。

    ポリシーを区別するには、ページの [OS ポリシーの割り当て] タブを使用して、Google Cloud プロジェクト内のすべてのポリシー割り当てのポリシー ID を確認します。

  • この [VM モニタリング] 列には、手動インストールやベータ版エージェント ポリシーなど、他の方法による Ops エージェントのインストールは反映されません。

Cloud Monitoring の [VM インスタンス] ページ

Cloud Monitoring の [VM インスタンス] ページには、各 VM にインストールされているエージェントが示される [エージェント] 列があります。Ops エージェントの場合、インストールされているエージェントが最新バージョンよりも古い場合、インジケーターが表示されます。

Google Cloud コンソールで [VM インスタンス ダッシュボード] ページに移動します。

[VM インスタンス ダッシュボード] に移動

検索バーを使用してこのページを検索する場合は、小見出しが [Monitoring] の結果を選択します。

policy-description ファイルの例

このセクションでは、さまざまなシナリオの YAML policy-description ファイルの例を示します。次の例では、YAML を agent-policy-description.yaml というファイルに配置し、次のようなコマンドを使用して us-central1-a ゾーンにポリシーを作成することを前提としています。

gcloud compute instances ops-agents policies create POLICY_ID \
  --zone us-central1-a \
  --file agent-policy-description.yaml \
  --project PROJECT_ID

すべての VM にインストールする

us-central1-a ゾーンのすべての VM に最新バージョンの Ops エージェントをインストールするには、次のポリシーの説明を使用します。

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  all: True

すべての VM から削除する

us-central1-a ゾーンのすべての VM で最新バージョンの Ops エージェントを削除するには、次のポリシーの説明を使用します。

agentsRule:
  packageState: removed
  version: latest
instanceFilter:
  all: True

ラベルに基づいて VM にインストールする

us-central1-a ゾーンで「env=prod」または「app=web」というラベルが付いたすべての VM に最新バージョンの Ops エージェントをインストールするには、次のポリシーの説明を使用します。

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  inclusionLabels:
  - labels:
      env: prod
  - labels:
      app: web

対象または対象外にするために複数の labels: エントリを指定した場合、ラベルが存在すれば VM が一致します。つまり、対象か対象外かを指定するために使用するラベルのセットは、論理 AND 演算ではなく、論理 OR 演算として照合されます。

他のラベルに基づいて VM にインストールする

us-central1-a ゾーンで Debian 11 を実行しているすべての VM に最新バージョンの Ops エージェントをインストールするには(env=prod と app=web6 のラベルが付いた VM を除く)、次のポリシーの説明を使用します。

agentsRule:
  packageState: installed
  version: latest
instanceFilter:
  exclusionLabels:
  - labels:
      env: prod
      app: web6
  inventories:
  - osShortName: debian
    osVersion: '11'

1 つの labels: エントリで複数の Key-Value ペアを指定して、対象か対象外かを指定した場合、すべてのラベルが存在すれば VM が一致します。つまり、ラベルは論理 OR 演算ではなく、論理 AND 演算として照合されます。

オペレーティング システムに基づいて VM にインストールする

us-central1-a ゾーンで Debian 11 または RHEL 7.* を実行しているすべての VM に Ops エージェントの最新バージョン 2 をインストールするには、次のポリシーの説明を使用します。

agentsRule:
  packageState: installed
  version: 2.*.*
instanceFilter:
  inventories:
  - osShortName: rhel
    osVersion: '7.*'
  - osShortName: debian
    osVersion: '11'

一般提供のエージェント ポリシーのトラブルシューティング

このセクションでは、Ops エージェントの一般提供のエージェント ポリシーに関する問題を解決する際に役立つ情報を提供します。エージェント ポリシーのステータスを確認するに記載されている情報も役立つ場合があります。

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

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

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

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

IAM 権限が不十分

gcloud compute instances ops-agents policies コマンドが権限エラーで失敗した場合は、始める前にで説明されているように prepare-for-ops-agents-policies.sh スクリプトを実行して、OS Config ポリシーのロールを設定していることを確認します。

prepare-for-ops-agents-policies.sh スクリプトの詳細については、prepare-for-ops-agents-policies.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 を有効にするか、始める前にで説明されている prepare-for-ops-agents-policies.sh スクリプトを実行して、必要なすべての権限を付与します。エラー メッセージのプロンプトで「y」を入力しても、prepare-for-ops-agents-policies.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 compute instances ops-agents policies describeupdate、または delete コマンドで使用される POLICY_ID が既存のポリシーに対応していることを確認します。エージェント ポリシーのリストを取得するには、gcloud 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 ログ] > [Application] を選択して、SourceOSConfigAgent と等しいログを検索します。

OS Config サービスへの接続中にエラーが発生した場合は、始める前にで説明されているように、prepare-for-ops-agents-policies.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 エージェントがインストールされているが、正常に動作しない

Ops エージェントの問題のデバッグの詳細については、Ops エージェントのトラブルシューティングをご覧ください。

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

ヘルパー スクリプト

このセクションでは、このドキュメントで示したヘルパー スクリプトについて詳しく説明します。

prepare-for-ops-agents-policies.sh スクリプト

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

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

    OS Config API がまだ有効になっていない場合は、限定機能モードで有効になります。エージェント ポリシーの管理には、このモードで十分です。詳細は、料金をご覧ください。

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

  • プロジェクトの OS Config メタデータを有効にして、各 VM の OS Config エージェントを有効にします。

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

    スクリプトを実行するときに、OSPolicyAssignment ロールを admineditor、または viewer として指定できます。このスクリプトは、これらの値を roles/osconfig.osPolicyAssignment* ロール名にマッピングします。

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

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

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID

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

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-user=USER_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

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

bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID \
  --iam-service-account=SERVICE_ACCT_EMAIL \
  --iam-policy-access=[admin|editor|viewer]

diagnose_policies.sh スクリプト

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

  • OS Config エージェントのバージョン
  • 基盤となる OS ポリシーの割り当て
  • この Compute Engine インスタンスに適用される OS ポリシーの割り当て
  • この Compute Engine インスタンスの説明

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

bash diagnose_policies.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID \
  --zone=ZONE

料金

gcloud compute instances ops-agents policies コマンドは、VM ManagerOS ポリシーの割り当てリソースを使用して実装されます。始める前にで説明した prepare-for-ops-agents-policies.sh スクリプトは、VM Manager を機能制限モード(OSCONFIG_Bで設定します。エージェント ポリシーの作成と管理を行うには、このモードで十分です。制限モードでの VM Manager の使用は無料です。

VM Manager をフル機能モード(OSCONFIG_C)で構成した場合は、費用が発生する可能性があります。