管理代理政策

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

支持的操作系统

您可以向具有以下操作系统的 Compute Engine 实例应用代理政策。

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

操作系统 Logging 代理 Monitoring 代理 Ops Agent
CentOS 7
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
1
RHEL 8:
rhel-8、rhel-8-2-sap-ha、rhel-8-4-sap-ha、rhel-8-6-sap-ha、rhel-8-8-sap-ha
1
Debian 9 (Stretch)
Debian 10 (Buster)
Debian 11 (Bullseye)
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):
ubuntu-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
OpenSUSE Leap 15:
opensuse-leap(opensuse-leap-15-3-*、
opensuse-leap-15-4-*)
Windows Server:
2016、2019、2022、Core 2016、Core 2019、Core 2022

1 rhel-7-9-sap-harhel-8-2-sap-harhel-8-4-sap-ha 不支持 Monitoring 代理。

创建代理政策

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

  1. 如果您尚未安装 Google Cloud CLI,请进行安装。

    在 gcloud CLI 中,用于管理代理政策的命令组为 beta 版。

  2. 如果您尚未安装 gcloud CLI 的 beta 组件,请进行安装:

    gcloud components install beta
    

    如需检查您是否安装了 beta 组件,请运行以下命令:

    gcloud components list
    
    1. 如果您之前安装了 beta 组件,请确保您拥有最新版本:

      gcloud components update
      
  3. 使用以下脚本启用 API,并为使用 Google Cloud CLI 设置适当的权限:set-permissions.sh

    如需了解该脚本,请参阅set-permissions.sh 脚本的作用是什么?”

  4. 使用 gcloud beta compute instances ops-agents policies create 命令创建政策。如需了解该命令的语法,请参阅 gcloud beta compute instances ops-agents policies create 文档。

    如需查看有关如何设置命令格式的示例,请参阅 Google Cloud CLI 文档中的示例部分。

    如需详细了解可用的 gcloud CLI 命令和可用选项,请参阅 gcloud beta compute instances ops-agents policies 文档。

使用代理政策的最佳做法

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

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

以下是 CentOS 7 虚拟机分阶段发布计划的示例:

第 1 阶段:创建政策以在所有具有标签 env=testapp=myproduct 的虚拟机上安装 Ops Agent。

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=centos,version=7 \
    --group-labels=env=test,app=myproduct \
    --project=my_project

如需详细了解如何指定操作系统,请参阅 gcloud beta compute instances ops-agents policies create

第 2 阶段:更新该政策以定位 env=prodapp=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 代理,请完成以下步骤:

  1. 确保您已在创建代理政策部分中运行 set-permissions.sh 脚本。

  2. 确定您要安装 OS Config 代理的虚拟机,并将其列在一个 CSV 文件中。

    如需以 csv 格式获取所有非 Google 管理的(例如,通过 Google Kubernetes Engine 或 Google App Engine)的实例列表,请运行以下命令:

      gcloud compute instances list \
          --filter="-labels.list(show="keys"):goog-" \
          --format="csv(name,zone)" \
          | grep -v -x -F -f  <(gcloud compute instances os-inventory list-instances \
              --format="csv(name,zone)") \
          | sed 's/$/,update/' > instances.csv
    

    grep 部分会过滤掉已安装并启用了 OS Config 代理的虚拟机。 基于 goog- 的虚拟机标签排除项会过滤掉由 GKE、App Engine 等管理的 Compute Engine 虚拟机。

    如需进一步按可用区或标签过滤实例,请将 --filter 更改为类似如下所示的内容:

      "-labels.list(show="keys"):goog- AND zone:(ZONE_1,ZONE_2) AND labels.KEY_1:VALUE_1 AND labels.KEY_2=VALUE_2"
    
  1. 按照脚本中的说明下载并运行 mass-install-osconfig-agent.sh 脚本,以运行如下所示的命令:

       bash mass-install-osconfig-agent.sh --project project-id --input-file instances.csv
    

    此脚本会自动执行安装 OS Config 代理说明。

问题排查

操作代理政策命令失败

如果操作代理政策命令失败,则它们会显示相应的验证错误。按照错误消息的建议,通过修复命令参数和标志来更正这些错误。

除了验证错误,您可能会看到以下错误:

  • IAM 权限不足

    下面是一个错误示例:

    ERROR: (gcloud.beta.compute.instances.ops-agents.policies.XXX) PERMISSION_DENIED: Caller does not have required permission to XXX
    

    请确保运行创建代理政策部分中的 set-permissions.sh 脚本以设置 osconfig.guestPolicy 特定 IAM 角色。

    如需验证是否已为项目启用了足够的 OS Config 客机政策角色,您可以运行以下命令。在此示例中,该命令检查用户是否具有 roles/osconfig.guestPolicyAdmin 角色。GCLOUD_MEMBER 的格式应为 user:USER_EMAILserviceaccount:SERVICE_ACCOUNT_EMAIL

    gcloud projects get-iam-policy project-id \
        --filter=--member=gcloud-member \
        | grep "roles/osconfig.guestPolicyAdmin" -B 2
    

    预期输出为:

    - members:
      - gcloud-member
      role: roles/osconfig.guestPolicyAdmin
    
  • 未启用 Osconfig API

    下面是一个错误示例:

    API [osconfig.googleapis.com] not enabled on project [XXX].
    Would you like to enable and retry (this will take a few minutes)?
    (y/N)?
    

    请确保运行创建代理政策部分中的 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
    

    这表明政策已被删除。确保 describeupdatedelete 命令中的政策 ID 映射到现有政策。

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

系统会将 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

SUSE 和 Ubuntu Compute Engine 实例未预安装 OS Config 代理,因此您需要遵循 OS Config 代理安装说明在这些 Compute Engine 实例上安装 OS Config 代理。

已安装 OS Config 代理,但没有安装操作代理

如需验证 OS Config 代理应用政策时是否出现任何错误,您可以查看 OS Config 代理的日志。这可以通过日志浏览器或通过 SSH / RDP 连接到单个 Compute Engine 实例来完成。

要在日志浏览器中查看 OS Config 代理日志,请使用以下过滤条件:

resource.type="gce_instance"
logName="projects/project-id/logs/OSConfigAgent"

如需通过 SSH 查看各个 Compute Engine Linux 实例的 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"
    

如需通过 RDP 查看各个 Compute Engine Windows 实例的 OS Config 代理日志,请运行以下步骤:

  1. 使用 RDP 或类似工具连接到您的实例,然后登录到 Windows。

  2. Windows Logs => Application 下打开 Event Viewer 应用,搜索 Source 等于 OSConfigAgent 的日志。

如果连接到 OS Config 服务时出错,请确保运行创建代理政策部分中的 set-permissions.sh 脚本来设置元数据。

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

操作代理已安装,但无法正常运行

请参阅 Logging 代理Monitoring 代理问题排查页面,以调试特定问题。

启用调试级日志

在报告问题时启用 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 脚本的作用是什么?

如果已提供项目 ID、Identity and Access Management (IAM) 角色以及电子邮件地址或服务账号,则 set-permissions.sh 脚本会执行以下操作:

  • 为项目启用 Cloud Logging API、Cloud Monitoring API、OS Config API。

  • roles/logging.logWriterroles/monitoring.metricWriter 角色授予 Compute Engine 默认服务账号,以便代理可以将日志和指标写入 Logging 和 Cloud Monitoring API。

  • 为项目启用 OS Config 元数据,以便在虚拟机上激活 OS Config 代理。

  • 将指定的 IAM 角色授予 gcloud 用户或服务账号。项目所有者拥有创建和管理政策的完全访问权限。对于所有其他用户或服务账号,项目所有者必须授予以下角色之一:

    • roles/osconfig.guestPolicyAdmin:提供政策的完整访问权限。

    • roles/osconfig.guestPolicyEditor:允许用户获取、更新和列出政策。

    • roles/osconfig.guestPolicyViewer:提供获取和列出政策的只读权限。

    运行该脚本时,您只需要指定角色名称的 guestPolicy* 部分。该脚本会提供名称的 roles/osconfig. 部分。

对该脚本进行以下调用会启用 API、向默认服务账号授予必要的角色,以及启用 OS Config 元数据:

bash set-permissions.sh --project=PROJECT_ID

如需使用该脚本向没有项目的 roles/owner (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 脚本的作用是什么?

给定项目、Compute Engine 实例 ID 和操作代理政策 ID 后,diagnose.sh 脚本会自动收集必要的信息,以帮助诊断政策的问题:

  • OS Config 代理版本

  • 底层 OS Config 客机政策

  • 适用于此 Compute Engine 实例的政策

  • 拉取到 Compute Engine 实例的代理软件包代码库

Terraform 集成

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