使用代理政策（正式版）

您可以使用 gcloud compute instances ops-agents policies 命令 （位于 Google Cloud CLI 中）或 ops-agent-policy Terraform 模块。 代理政策使用 Compute Engine 中的一套虚拟机管理器工具来管理操作系统政策，可以自动部署和维护软件配置，例如 Ops Agent。这些政策无法应用于旧版 Monitoring 代理或旧版 Logging 代理。

Google Analytics 代理政策 操作系统政策分配 OS Config API 中的资源。虽然有一个通用的 gcloud CLI， 用于管理操作系统政策分配的命令组 gcloud compute os-config os-policy-assignments、 gcloud compute instances ops-agents policies 命令组是专为代理 (Agent) 设计的 政策。

准备工作

ops-agent-policy Terraform 模块基于 gcloud compute instances ops-agents policies 命令。如需了解 Terraform 的运作方式，请参阅使用 Terraform。

在使用 Google Cloud CLI 或 Terraform 模块创建代理之前 请完成以下步骤：

  1. 如果您要使用 gcloud compute instances ops-agents policies 命令，并且尚未安装 Google Cloud CLI，请先安装该工具。

  2. 如果要使用 Terraform 模块，请执行以下操作：

    1. 如需了解如何安装 Terraform，请参阅安装和配置 Terraform。Cloud Shell 已安装 Terraform。

    2. 克隆包含 ops-agent-policy 模块的 terraform-google-cloud-operations 代码库：

      git clone https://github.com/terraform-google-modules/terraform-google-cloud-operations

  3. 下载并运行 prepare-for-ops-agents-policies.sh 脚本， 启用所需的 API 并设置适当的权限，以便使用 Google Cloud CLI 或 Terraform。

    有关脚本的信息，请参阅 prepare-for-ops-agents-policies.sh 脚本。

卸载旧版 Monitoring 代理和 Logging 代理

如果要为 Ops Agent 创建政策，请确保您的虚拟机没有安装旧版 Logging 代理或 Monitoring 代理。在同一虚拟机上运行 Ops Agent 和旧版代理可能会导致提取重复的日志或导致指标提取冲突。如有必要，在创建政策之前卸载 Monitoring 代理和卸载 Logging 代理以安装 Ops Agent。

验证 OS Config 代理是否已安装

您可能需要在早于 OS Config 的虚拟机上手动安装和配置 OS Config 代理。如需了解如何手动安装并验证 OS Config 代理，请参阅虚拟机管理器验证核对清单。

查找操作系统信息的值

如果您想将代理政策应用于特定操作系统或版本，则需要了解 OS Config 用于引用这些操作系统或版本的值。

如需查找虚拟机的 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 代理。

创建代理政策以管理 Ops Agent

命令行

如要创建代理政策，请使用 gcloud compute instances ops-agents policies create 命令。此命令的结构如下：

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 可用去。代理政策仅应用于指定可用区中的虚拟机；要在多个可用区中应用政策，您必须创建多个政策。
  • 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 选项的值传递给命令。

本部分介绍了政策描述文件的结构。 如需了解详情，请参阅政策说明文件示例。

YAML 政策说明文件的格式

代理政策的说明文件必须包含两个字段组：

  • agentsRule：告知代理政策是安装还是移除 Ops Agent，并指定要操作的 Ops Agent 版本。

  • instanceFilter：描述应用该政策的虚拟机。

agentsRule 字段组的结构

agentsRule 字段组具有以下结构：

agentsRule:
  packageState: installed|removed
  version: latest|2.*.*|2.x.y
  • packageState 字段用于告知政策 Ops Agent。有效值为 installed 和 removed。

  • version 字段指示要安装的 Ops Agent 版本，或 移除。您可以指定以下值：

    • latest 是最新版本的 Ops Agent。
    • 2.*.* 是 Ops Agent 主要版本 2 的最新版本。
    • 2.x.y 表示主要版本 2 的特定版本。

    如需了解 Ops Agent 的各个版本，请参阅该代理的 GitHub 代码库。

instanceFilter 字段组的结构

instanceFilter 字段组指示可用区中的虚拟机 。此字段组是 OS Config API 中的 OSPolicyAssignment 资源使用的 InstanceFilter 结构的 YAML 表示法。

instanceFilter 字段组采用以下结构之一：

  • 如需将代理政策应用于可用区中的所有虚拟机，请使用以下命令：

    instanceFilter:
  all: True

    如果您使用 all: True 过滤条件，则无法指定任何其他条件。

  • 如需将代理政策应用于可用区中的一组特定虚拟机，请使用以下项的任意组合来描述虚拟机：

    • 虚拟机上的标签（用于包含或排除）：
      • inclusionLabels:
      • exclusionLabels:
    • 操作系统：inventories:

    例如，以下过滤条件会将代理政策应用于具有指定操作系统且标签为“env=prod”且不带标签“app=web”的虚拟机：

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

    如需了解如何查找操作系统值，请参阅查找操作系统信息。

Terraform

如需创建完全自定义的代理政策，请使用 modules 中的 ops-agent-policy 模块 terraform-google-cloud-operations 代码库的目录中。 此模块需要与 gcloud compute instances ops-agents policies create 命令相同的信息。如需查看用于描述代理政策的所有字段的说明， 选择命令行标签页。

terraform-google-cloud-operations 仓库中的 examples 目录包含一些文件，这些文件会为您提供 ops-agent-policy 模块所需的许多变量。如需了解详情，请参阅 政策配置示例。

如需了解如何应用或移除 Terraform 配置，请参阅基本 Terraform 命令。如需了解 Terraform 的运作方式，请参阅使用 Terraform。

验证代理政策的状态

本部分介绍如何检查所创建政策的状态以及 Ops Agent 的安装情况。这些信息还有助于排查代理政策方面的问题。

Compute Engine 操作系统政策页面

Compute Engine 操作系统政策页面介绍了用于管理 Ops Agent 的代理政策以及虚拟机实例标签页上的虚拟机。例如：

  • 状态列指示政策是否已成功安装（“合规”）、进行中（“待处理”）、可能失败（“未知”）或缺失（“无政策”）。
  • 虚拟机受监控列指示 Ops Agent 是由 OS Config 管理（“受监控”）还是不由其管理（“不受监控”）。

    如果政策为“合规”，但虚拟机显示“不受监控”，则 Ops Agent 安装可能存在问题。例如，您可能已安装旧版代理。

在 Google Cloud 控制台中，转到操作系统政策页面：

进入操作系统政策

如果您使用搜索栏查找此页面，请选择子标题为 Compute Engine 的结果。

Compute Engine 操作系统政策标签页上的虚拟机实例会显示 Google Cloud 项目中由所有操作系统政策管理的代理的相关信息。这些政策在图中标为 goog-ops-agent-policy。

  • goog-ops-agent-policy 指示符包含多种类型的政策：
    • 使用 gcloud compute instances ops-agents policies 命令创建的政策。
    • 在创建虚拟机时请求安装 Ops Agent 的情况下由系统为您创建的政策。
    • 使用 Terraform 创建的用于管理 Ops Agent 的政策。

    如需区分政策，请使用页面上的操作系统政策分配任务标签页来查看 Google Cloud 项目中所有政策分配任务的政策 ID。

  • 此虚拟机受监控列既不通过其他方式（如手动安装）也不通过 Beta 版代理政策反映 Ops Agent 的安装情况。

Cloud Monitoring 虚拟机实例页面

Cloud Monitoring 中的虚拟机实例页面包含一个代理列，其中列出了每个虚拟机上安装的代理，而 Ops Agent 则包含一个指示已安装代理是否早于最新版本的指示符。

在 Google Cloud 控制台中，进入虚拟机实例信息中心页面：

进入虚拟机实例信息中心

如果您使用搜索栏查找此页面，请选择子标题为监控的结果。

政策配置示例

本部分介绍了使用 Google Cloud SDK 或 Terraform 设置代理政策的示例。

命令行

政策说明文件示例

本部分提供了一些适用于各种场景的 YAML 政策说明文件示例。这些示例假定您将 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

在所有虚拟机上安装

如需在集群中的所有虚拟机上安装最新版本的 Ops Agent， us-central1-a 可用区，请使用以下政策说明：

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

从所有虚拟机中移除

如需从 Google Cloud 控制台中的所有虚拟机中移除最新版本的 Ops Agent， us-central1-a 可用区，请使用以下政策说明：

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

根据标签在虚拟机上安装

如需在 us-central1-a 可用区中标签为“env=prod”或“app=web”的所有虚拟机上安装最新版本的 Ops Agent，请使用以下政策说明：

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

如果您指定多个 labels: 条目以包含或排除，那么当存在任何标签时，虚拟机将会匹配；也就是说，要包含或排除的标签集作为逻辑 OR 运算（而非逻辑 AND 运算）进行匹配。

在基于其他标签的虚拟机上安装

如需在集群中的所有虚拟机上安装最新版本的 Ops Agent， 运行 Debian 11 的 us-central1-a 可用区（带“env=prod”标签的除外） 和“app=web6”部分，请使用以下政策说明：

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

如果您在单个 labels: 条目下指定多个键值对以进行包含或排除，那么当所有标签都存在时，虚拟机会匹配；也就是说，标签作为逻辑 AND 运算（而非逻辑 OR 运算）进行匹配。

在基于操作系统的虚拟机上安装

如需在 us-central1-a 可用区中运行 Debian 11 或 RHEL 7.* 的所有虚拟机上安装最新版本的 Ops Agent 2，请使用以下政策说明：

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

Terraform

本部分介绍了 terraform-google-cloud-operations 仓库的 examples 目录中的示例。这些示例 包含用于配置 ops-agent-policy 模块。您还可以复制并修改 示例。例如，以下示例都安装了 Ops Agent；您可以修改这些示例，以便改为删除该代理。

如需了解如何应用或移除 Terraform 配置，请参阅基本 Terraform 命令。

示例：ops_agent_policy_install_all

此示例会在 Google Cloud 项目中的所有符合条件的虚拟机上安装最新版本的 Ops Agent。

运行 terraform plan 或 terraform apply 命令时，系统会提示您输入以下值：

  • PROJECT_ID：您的 Google Cloud 项目的 ID

示例：ops_agent_policy_install_all_in_region

此示例会在给定区域（例如 us-west1）中的所有符合条件的虚拟机上安装最新版本的 Ops Agent。区域包含 多个可用区，在本示例中为 us-west-1a、us-west-1b 和 us-west-1c。

运行 terraform plan 或 terraform apply 命令时，系统会提示您输入以下内容 值：

  • PROJECT_ID：您的 Google Cloud 项目的 ID
  • REGION：要在其中在虚拟机上安装代理的区域

示例：ops_agent_policy_install_all_in_zone

此示例会在给定区域（例如 us-central1-a）中的所有符合条件的虚拟机上安装最新版本的 Ops Agent。

运行 terraform plan 或 terraform apply 命令时，系统会提示您输入以下内容 值：

  • PROJECT_ID：您的 Google Cloud 项目的 ID
  • ZONE：要在其中在虚拟机上安装代理的可用区

排查 GA 代理政策问题

本部分提供的信息可帮助您解决 Ops Agent 的 Google Analytics 代理政策。验证代理政策的状态中描述的信息可能也很实用。

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 describe、update 或 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 代理，那么您使用的操作系统可能不支持虚拟机管理器。Compute Engine 操作系统详细信息文档介绍了每个 Compute Engine 操作系统所支持的虚拟机管理器功能。

如果操作系统支持虚拟机管理器，那么您可以手动安装 OS Config 代理。

已安装 OS Config 代理，但没有安装 Ops Agent

如需验证 OS Config 代理应用政策时是否出现任何错误，您可以查看 OS Config 代理的日志。为此，您可以使用 Logs Explorer 或使用 SSH 或 RDP 检查各个 Compute Engine 实例。

要在 Logs Explorer 中查看 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 日志 > 应用，并搜索 Source 等于 OSConfigAgent 的日志。

如果连接到 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 Agent 已安装，但无法正常运行

如需详细了解如何调试 Ops Agent 问题，请参阅排查 Ops Agent 问题。

为 OS Config 代理启用调试级日志

对于报告问题而言，在 OS Config 代理中启用调试级日志记录非常有用。

您可以通过设置 osconfig-log-level: debug 元数据为 OS Config 代理启用调试级日志记录。收集的日志包含更多信息，可以帮助您进行调查。

如需为整个项目启用调试级日志记录，请运行以下命令：

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

如需为一个虚拟机启用调试级日志记录，请运行以下命令：

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 脚本后，您可以使用该脚本根据您提供的参数执行以下操作：

以下示例展示了该脚本的一些常见调用。如需了解详情，请参阅脚本本身的注释。

如需启用 API，请向默认服务账号授予必要的角色，并为项目启用 OS Config 元数据，请按如下所示运行脚本：

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

要另外向执行下列操作的用户授予某个 OS Config 角色： 不具备项目的 Owner (roles/owner) 角色，请以如下身份运行脚本： 如下：

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 代理版本
  • 底层操作系统政策分配
  • 适用于此 Compute Engine 实例的操作系统政策分配
  • 此 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 命令是使用虚拟机管理器中的操作系统政策分配任务资源实现。准备工作中描述的 prepare-for-ops-agents-policies.sh 脚本可在受限功能模式 (OSCONFIG_B) 下设置虚拟机管理器，该模式足以创建和管理代理政策。没有费用 如何在受限模式下使用虚拟机管理器

如果您已在完整功能模式 (OSCONFIG_C) 下配置了虚拟机管理器，则可能会产生费用。