管理代理政策

如有任何疑问、需要支持或想要提供反馈,请通过 ops-agent-policy-feedback@google.com 与我们联系。

代理政策会在与用户指定的条件匹配的虚拟机之间自动安装和维护 Cloud Monitoring 和 Cloud Logging 代理。您可以通过一条命令创建用于管理现有虚拟机和新虚拟机的政策,从而确保正确安装这两个代理,并视情况自动升级。

创建代理政策

要使用 gcloud 命令行工具创建代理政策,请完成以下步骤:

  1. 如果您尚未这样做,请安装 Cloud SDK

    在 Cloud SDK 中,用于管理代理政策的命令组为 Alpha 版。

    1. 如需检查您是否安装了 gcloud 工具的 alpha 组件,请运行以下命令:

      gcloud components list
      
    2. 如果您没有安装 alpha 组件,请运行以下命令进行安装:

      gcloud components install alpha
      
  2. 使用以下脚本启用 API,并为使用 gcloud 命令行工具设置适当的权限:set-permissions.sh

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

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

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

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

使用代理政策的最佳做法

要控制发布时对生产系统的影响,建议使用实例标签和区域来过滤该政策适用的实例。

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

第 1 阶段:创建政策以定位带有标签 env=testapp=myproduct 的所有虚拟机。

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

第 2 阶段:更新该政策以定位 env=prodapp=myproduct,并且只影响一个地区。

gcloud alpha compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --group-labels=env=prod,app=myproduct \
    --zones=us-central1-c

第 3 阶段:更新该政策以清除地区过滤条件,以使其全球化发布。

gcloud alpha compute instances \
    ops-agents policies update ops-agents-policy-safe-rollout \
    --clear-zones

限制

为了使政策在早于 OS Config 的 Ubuntu 和 SLES 操作系统发行版或虚拟机上生效,您需要进行额外设置,以确保政策所依赖的 OS Config 代理已安装在虚拟机上。如需在一组虚拟机上安装 OS Config 代理,请完成以下步骤:

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

  2. 确定您要安装 OS Config 代理的虚拟机,并将其列出到一个 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)")
    

    grep 部分会过滤掉已安装并启用了 OS Config 代理的虚拟机。

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

      "-labels.list(show="keys"):goog- AND zone:(ZONE_1,ZONE_2) AND labels.KEY_1:VALUE_1 AND labels.KEY_2=VALUE_2"
    
  3. 按照脚本中的说明运行 mass-install-osconfig-agent.sh 脚本。此脚本会自动执行安装 OS Config 代理说明。

问题排查

操作代理政策命令失败

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

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

  • IAM 权限不足

    下面是一个错误示例:

    ERROR: (gcloud.alpha.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
    

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

系统会将 OS Config 代理部署到每个 Compute Engine 实例,以管理 Logging 和 Monitoring 代理的软件包。如果未安装底层 OS Config 代理,则此政策可能没有任何效果。要验证是否已安装 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

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

已安装 OS Config 代理,但没有安装 Ops 代理

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

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

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

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

如果连接到 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 代理问题排查页面,以调试特定问题。

提供反馈

如有任何疑问、需要支持或想要提供反馈,请通过 ops-agent-policy-feedback@google.com 与我们联系。您还可以使用 gcloud 反馈命令来报告您在使用命令时遇到的问题。

请使用以下脚本来收集相关信息,以帮助排查问题:diagnose.sh

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

启用调试级日志

在报告问题时启用 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:提供获取和列出政策的只读权限。

请参阅脚本备注中的示例用法。

diagnose.sh 脚本的作用是什么?

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

  • OS Config 代理版本

  • 底层 OS Config 访客政策

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

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