使用代理政策

代理政策会在与用户指定的条件匹配的一组 Compute Engine 虚拟机中自动安装并维护 Google Cloud Observability 代理。您可以通过一条命令为某个 Google Cloud 项目创建政策，以管理与该 Google Cloud 项目关联的现有虚拟机和新虚拟机，从而确保在这些虚拟机上正确安装或卸载所有 Google Cloud Observability 代理，并视情况自动升级。

您可以在 Google Cloud CLI 中使用 gcloud beta compute instances ops-agents policies 命令组来创建和管理代理政策。该组中的命令使用 Compute Engine 中的虚拟机管理器套件来管理操作系统政策，可以自动部署和维护软件配置，例如 Google Cloud Observability 代理：Ops Agent、旧版 Monitoring 代理和旧版 Logging 代理。

支持的操作系统

您可以向运行下表中所示操作系统的 Compute Engine 虚拟机实例应用代理政策：

操作系统	Ops Agent （正式版和 Beta 版^† 政策）	Logging 代理（仅限 Beta 版^† 政策）	Monitoring 代理（仅限 Beta 版^† 政策）
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 11 (Bullseye)
基于 Debian 11 (Bullseye) 的 Deep Learning VM Image
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)： buntu-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、sles-15-sp6-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

^† 在 Beta 版代理政策中，代理列会映射到为 gcloud beta compute instances ops-agents policies create 调用指定的代理类型：

Ops Agent 会映射到代理类型 ops-agent。
Logging 代理会映射到代理类型 logging。
Monitoring 代理会映射到代理类型 metrics。

^‡ rhel-7-9-sap-ha、rhel-8-2-sap-ha 或 rhel-8-4-sap-ha 不支持 Monitoring 代理。

创建代理政策

如需使用 Google Cloud CLI 创建代理政策，请完成以下步骤：

如果您尚未安装 Google Cloud CLI，请进行安装。

本文档介绍了用于管理代理政策的 beta 命令组。
如果您尚未安装 gcloud CLI 的 beta 组件，请进行安装：
```
gcloud components install beta
```
如需检查您是否安装了 beta 组件，请运行以下命令：
```
gcloud components list
```
如果您之前安装了 beta 组件，请确保您拥有最新版本：
```
gcloud components update
```
下载并使用以下脚本以启用 API，并为使用 Google Cloud CLI 设置适当的权限：set-permissions.sh。

如需了解该脚本，请参阅 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 文档。

使用代理政策的最佳做法

如需在发布期间控制对生产系统的影响，我们建议您使用实例标签和可用区来过滤该政策适用的实例。

以下举例说明了 my_project 项目中的 Debian 11 虚拟机的分阶段发布计划：

第 1 阶段：创建名为 ops-agents-policy-safe-rollout 的政策以在所有具有标签 env=test 和 app=myproduct 的虚拟机上安装旧版 Logging 代理和 Monitoring 代理。

gcloud beta compute instances \
    ops-agents policies create ops-agents-policy-safe-rollout \
    --agent-rules="type=logging,version=current-major,package-state=installed,enable-autoupgrade=true;type=metrics,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 的虚拟机。

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 的虚拟机政策

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

排查 Beta 版代理政策问题

本部分提供的信息可帮助您解决 Ops Agent、旧版 Monitoring 代理以及旧版 Logging 代理的 Beta 版代理政策问题。

`ops-agents policy` 命令失败

当 gcloud beta compute instances ops-agents policies 命令失败时，响应会显示验证错误。按照错误消息的建议，通过修复命令参数和标志来更正这些错误。

除了验证错误之外，您可能还会看到指示以下情况的错误：

IAM 权限不足
未启用 OS Config API
指定的政策不存在

下面几个部分将详细介绍这些情况。

IAM 权限不足

如果 gcloud beta compute instances ops-agents policies 命令因权限错误而失败，请确保您已按照创建代理政策中的说明运行 set-permissions.sh 脚本来设置 OS Config 政策角色：

GuestPolicy Admin (roles/osconfig.guestPolicyAdmin)：提供对客机政策的完整访问权限。
GuestPolicy Editor (roles/osconfig.guestPolicyEditor)：允许用户获取、更新和列出客机政策。
GuestPolicy Viewer (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 代理，那么您使用的操作系统可能不支持虚拟机管理器。Compute Engine 操作系统详细信息文档介绍了每个 Compute Engine 操作系统所支持的虚拟机管理器功能。

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

已安装 OS Config 代理，但没有安装 Logging 代理

如需验证 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

使用 RDP 或类似工具连接到您的实例，然后登录到 Windows。
打开事件查看器应用，然后选择 Windows 日志 > 应用，并搜索 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'

Observability 代理已安装，但无法正常运行

如需了解如何调试特定代理，请参阅以下文档：

为 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

帮助程序脚本

本部分提供有关本文档中描述的帮助程序脚本的其他信息：

set-permissions.sh 脚本
diagnose.sh 脚本

`set-permissions.sh` 脚本

下载 set-permissions.sh 脚本后，您可以使用该脚本根据您提供的参数执行以下操作：

为项目启用 Cloud Logging API、Cloud Monitoring API、OS Config API。
为 Compute Engine 默认服务账号授予 Identity and Access Management 角色 Logs Writer (roles/logging.logWriter) 和 Monitoring Metric Writer (roles/monitoring.metricWriter)，以便代理可以将日志和指标写入 Logging API 和 Cloud Monitoring API。
为项目启用 OS Config 元数据，以使每个虚拟机上的 OS Config 代理处于活跃状态。
将以下 IAM 角色之一授予给创建和管理政策所需的非所有者用户或服务账号。项目所有者拥有对创建和管理政策的完全访问权限；所有其他用户或服务账号必须获得以下角色之一：
- GuestPolicy Admin (roles/osconfig.guestPolicyAdmin)：提供对客机政策的完整访问权限。
- GuestPolicy Editor (roles/osconfig.guestPolicyEditor)：允许用户获取、更新和列出客机政策。
- GuestPolicy Viewer (roles/osconfig.guestPolicyViewer)：提供获取和列出客机政策的只读权限。
运行该脚本时，您只需要指定角色名称的 guestPolicy* 部分。该脚本会提供名称的 roles/osconfig. 部分。

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

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

bash set-permissions.sh --project=PROJECT_ID

如需向没有项目的 Owner (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 实例的代理软件包代码库

如需调用该脚本，请运行以下命令：

bash diagnose.sh --project-id=PROJECT_ID \ 
  --gce-instance-id=INSTANCE_ID \
  --policy-id=POLICY_ID

Terraform 集成

Terraform 支持以 Google Cloud CLI 命令为基础构建。如需使用 Terraform 创建代理政策，请按照 Terraform 模块说明进行操作。

使用代理政策

支持的操作系统

创建代理政策

使用代理政策的最佳做法

早于 OS Config 的虚拟机政策

排查 Beta 版代理政策问题

ops-agents policy 命令失败

IAM 权限不足

未启用 OS Config API

政策不存在

政策已创建，但似乎没有任何效果

Linux

Windows

已安装 OS Config 代理，但没有安装 Logging 代理

CentOS、RHEL、SLES、SUSE

Debian、Ubuntu

Windows

Observability 代理已安装，但无法正常运行

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

帮助程序脚本

set-permissions.sh 脚本

diagnose.sh 脚本

Terraform 集成

`ops-agents policy` 命令失败

CentOS、RHEL、
SLES、SUSE

`set-permissions.sh` 脚本

`diagnose.sh` 脚本