您可以在 Google Cloud CLI 中使用 gcloud compute instances ops-agents policies
命令组来创建和管理代理政策。该组中的命令使用 Compute Engine 中的虚拟机管理器 套件来管理 操作系统政策,从而自动部署和维护 Ops Agent 等软件配置。这些政策不能应用于旧版 Monitoring 代理或旧版 Logging 代理。
gcloud compute instances ops-agents policies
命令组使用 OS Config API 中的操作系统政策分配资源。虽然有一个用于管理操作系统政策分配的常规 gcloud CLI 命令组
gcloud compute os-config os-policy-assignments
,但 gcloud compute instances ops-agents policies
命令组是专为本文档中介绍的代理政策设计的。
准备工作
在使用 Google Cloud CLI 创建代理政策之前,请完成以下步骤:
如果您尚未安装 Google Cloud CLI,请进行安装。
下载并运行
prepare-for-ops-agents-policies.sh
脚本,以启用所需的 API 并设置适当的权限,以便使用 Google Cloud CLI。如需了解该脚本,请参阅
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 代理,请参阅虚拟机管理器验证核对清单。
创建代理政策以管理 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'
如需查找虚拟机的
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 的安装情况。此信息还可以帮助您对代理政策进行问题排查。
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。
- 使用
- 此受虚拟机监控列不反映 Ops Agent 通过其他方式安装,例如手动安装或 Beta 版代理政策。
Cloud Monitoring 虚拟机实例页面
Cloud Monitoring 中的虚拟机实例页面包含一个代理列,其中列出了每个虚拟机上安装的代理;对于 Ops Agent,该页面还包含一个指示早于最新版本的已安装代理的指示器。
在 Google Cloud 控制台中,进入虚拟机实例信息中心页面:
如果您使用搜索栏查找此页面,请选择子标题为监控的结果。
政策说明文件示例
本部分提供了一些适用于各种场景的 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
在所有虚拟机上安装
如需在 us-central1-a
区域中的所有虚拟机上安装最新版本的 Ops Agent,请使用以下政策说明:
agentsRule:
packageState: installed
version: latest
instanceFilter:
all: True
从所有虚拟机中移除
如需在 us-central1-a
区域中的所有虚拟机上移除最新版本的 Ops Agent,请使用以下政策说明:
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
操作进行匹配。
在基于其他标签的虚拟机上安装
如需在运行 Debian 11 的 us-central1-a
可用区中的所有虚拟机(带有“env=prod”和“app=web6”标签的虚拟机)上安装最新版本的 Ops Agent,请使用以下政策说明:
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,请使用以下政策说明:
agentsRule:
packageState: installed
version: 2.*.*
instanceFilter:
inventories:
- osShortName: rhel
osVersion: '7.*'
- osShortName: debian
osVersion: '11'
排查 Google Analytics(分析)代理政策问题
本部分提供的信息可帮助您解决 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 政策角色:
-
OSPolicyAssignment Admin
(
roles/osconfig.osPolicyAssignmentAdmin
):提供对操作系统政策分配的完整访问权限。
-
OSPolicyAssignment Editor
(
roles/osconfig.osPolicyAssignmentEditor
):允许用户获取、更新和列出操作系统政策分配。
-
OSPolicyAssignment Viewer
(
roles/osconfig.osPolicyAssignmentViewer
):提供获取和列出操作系统政策分配的只读权限。
如需详细了解 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 代理,请执行以下步骤:
使用 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 代理,但未安装 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
使用 RDP 或类似工具连接到您的实例,然后登录到 Windows。
打开“事件查看器”应用,然后选择 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
脚本后,您可以根据您提供的参数,使用该脚本执行以下操作:
为项目启用 Cloud Logging API、Cloud Monitoring API 和 OS Config API。
如果尚未启用 OS Config API,它会以功能受限模式启用,这足以管理代理政策。如需了解详情,请参阅价格。
向 Compute Engine 默认服务帐号授予 Identity and Access Management 角色 Logs Writer (
roles/logging.logWriter
) 和 Monitoring Metric Writer (roles/monitoring.metricWriter
),以便代理可以将日志和指标写入 Logging 和 Cloud Monitoring API。为项目启用 OS Config 元数据,以使每个虚拟机上的 OS Config 代理处于活跃状态。
向非所有者用户或服务帐号授予创建和管理政策所需的以下 IAM 角色之一。项目所有者拥有创建和管理政策的完整访问权限;所有其他用户或服务帐号必须获授予以下角色之一:
-
OSPolicyAssignment Admin
(
roles/osconfig.osPolicyAssignmentAdmin
):提供对操作系统政策分配的完整访问权限。
-
OSPolicyAssignment Editor
(
roles/osconfig.osPolicyAssignmentEditor
):允许用户获取、更新和列出操作系统政策分配。
-
OSPolicyAssignment Viewer
(
roles/osconfig.osPolicyAssignmentViewer
):提供获取和列出操作系统政策分配的只读权限。
运行该脚本时,您可以将 OSPolicyAssignment 角色指定为
admin
、editor
或viewer
。该脚本会将这些值映射到roles/osconfig.osPolicyAssignment*
角色名称。-
OSPolicyAssignment Admin
(
以下示例展示了对该脚本的一些常见调用。 如需了解详情,请参阅脚本本身的注释。
如需启用 API、向默认服务帐号授予必要的角色,并为项目启用 OS Config 元数据,请按如下方式运行脚本:
bash prepare-for-ops-agents-policies.sh --project=PROJECT_ID
如需另外向没有项目的 Owner (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 代理版本
- 底层操作系统政策分配
- 适用于此 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
) 下配置了虚拟机管理器,则可能会产生费用。