cloud-monitoring-notification-channels-configuration

Cloud Monitoring 通知渠道配置

归属信息

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读使用归属信息。对于直接在终端中执行的命令（绝不在生成的脚本、Terraform 或用户代码中），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-monitoring-notification-channels-configuration)" ，并将 agent-skills/1.0 (skill:cloud-monitoring-notification-channels-configuration) 添加到 User-Agent 标头中。

提供的上下文

• 仅使用 Terraform：仅将生成的可观测性配置写入 Terraform（.tf）文件（例如 notification_channels.tf）。

  • 只有在用户要求部署通知渠道且没有有效的 Terraform 安装时，才安装 Terraform。
  • 如果用户未要求部署通知渠道，不要安装 Terraform。

• 推断工作目录：按以下顺序确定 .tf 文件的目标路径：

  1. 如果用户提供了路径，则将该路径原样用于 .tf 文件。
  2. 如果用户未提供路径，则在工作区中搜索现有 .tf 文件（优先选择已定义 google_monitoring_notification_channel 或 google_monitoring_alert_policy 资源的文件；若没有，则严格按以下优先顺序查找现有目录：monitoring/、ops/、sre/）。如果找到，则在该目录中写入 notification_channels.tf（或在修改现有资源时更新现有 .tf 文件）。
  3. 如果用户未提供路径，且工作区中不存在 .tf 文件或目标目录，则创建并写入 monitoring/notification_channels.tf。

• Google Cloud 前提条件：运行 gcloud CLI 探索命令，或使用 terraform CLI 针对 Google Cloud 项目部署配置时，按顺序确保满足以下前提条件（如果用户只要求生成或打印 Terraform HCL，则不要执行这些命令）：

  1. 目标项目 ID 和项目编号：
     • 从用户请求中确定目标 Google Cloud {project_id}，或通过 gcloud config get-value project 获取。如果两者都不可用，则在继续之前请用户提供 {project_id}。
     • 需要 Google Cloud 项目编号（{project_number}）时（例如，为 Pub/Sub 渠道构建 Cloud Monitoring 服务代理身份），请执行以下操作：
       • 方法 A（标准方式）：运行 gcloud projects describe {project_id} --format='value(projectNumber)'。
       • 方法 B（询问用户）：如果命令失败或无法获取项目编号，请用户提供该编号。
  2. 身份验证：通过 gcloud auth login 对 gcloud CLI 进行身份验证，并通过 gcloud auth application-default login 为 Terraform 配置应用默认凭据（ADC）。
  3. 项目配置和结算：通过 gcloud config set project {project_id} 配置目标 Google Cloud 项目（并确保该项目已关联有效的结算账号）。
     • 恢复操作：如果 gcloud config set project {project_id} 或 gcloud projects describe {project_id} 失败，请通过 gcloud auth list 验证有效凭据，通过 gcloud projects list 列出可访问的项目，或请用户确认项目 ID 和访问权限。如果部署因缺少或未启用结算账号而失败，请停止部署，并告知用户先关联有效的结算账号（通过 gcloud billing projects link {project_id} --billing-account={account_id} 或 Google Cloud 控制台），然后再重试。
  4. IAM 权限：确保主体具有管理通知渠道的权限：可以通过预定义的 Monitoring NotificationChannel Editor 角色（roles/monitoring.notificationChannelEditor；向现有告警策略添加渠道时，还需 roles/monitoring.alertPolicyEditor），也可以通过包含等效权限的自定义 IAM 角色（monitoring.notificationChannels.get、monitoring.notificationChannels.list、monitoring.notificationChannels.create、monitoring.notificationChannels.update、monitoring.notificationChannels.delete，以及更新告警策略时所需的 monitoring.alertPolicies.get / monitoring.alertPolicies.update）。
     • 恢复操作：授予这些权限的自定义角色不必使用预定义角色名称。如果 gcloud 或 terraform 命令因 PERMISSION_DENIED（HTTP 403）而失败，请停止执行，找出缺失的 monitoring.notificationChannels.* 或 monitoring.alertPolicies.* 权限，并告知用户请项目管理员向其主体授予 roles/monitoring.notificationChannelEditor（或具有所需权限的自定义角色）。

• 探索提示：

  • 列出通知渠道：必须使用 gcloud beta monitoring channels list --project={project_id} 列出通知渠道。不要使用任何其他 gcloud 命令列出通知渠道。
  • 验证 Pub/Sub 主题：配置 Pub/Sub 通知渠道时，运行 scripts/verify_pubsub_topic.sh {monitoring_project_id} {topic_name_or_path}，以验证：
    1. 主题所在项目已启用 Pub/Sub API（pubsub.googleapis.com）（支持同一项目中的主题，以及以 projects/{topic_project_id}/topics/{topic_name} 指定的跨项目主题）。
    2. 主题存在，且监控项目的 Cloud Monitoring 服务代理（service-{monitoring_project_number}@gcp-sa-monitoring-notification.iam.gserviceaccount.com）在该主题或主题所属项目上拥有 roles/pubsub.publisher。
    3. 主题未定义消息存储策略（messageStoragePolicy / message_storage_policy），且未启用传输中强制限制（enforceInTransit / enforce_in_transit）。不要将定义了消息存储策略或强制实施传输中限制的 Pub/Sub 主题用作通知渠道，因为 Cloud Monitoring 无法向此类主题发送消息。

• 归属标注：对于下文由你创建、修改或建议给用户的每一条适用命令和每个 Terraform 资源，都必须添加标记。

  • Terraform HCL（user_labels）：

    • 你创建的每个 google_monitoring_notification_channel 资源都必须在其 user_labels 块中包含 created-with-google-skill 标签：

      user_labels = {
        created-with-google-skill = "cloud-monitoring-notification-channels-configuration"
      }
      

    • 如果仅为了添加通知渠道而修改现有的 google_monitoring_alert_policy 资源， 不要使用 created-with-google-skill（因为此技能并未创建该告警策略）。 请在其 user_labels 块中包含 added-channel-with-google-skill 标签 （保留策略中已有的任何 user_labels）：

      user_labels = {
        added-channel-with-google-skill = "cloud-monitoring-notification-channels-configuration"
      }
      

  • 根据所用的 CLI 工具遵循以下说明：

    • **gcloud：**每次调用 gcloud 时，都要在命令前添加指标环境变量。 在每条命令中以内联方式设置；不同命令之间的 shell 状态可能无法保留：

      CLOUDSDK_METRICS_ENVIRONMENT="google-skills google-skills/1.0 (skill:cloud-monitoring-notification-channels-configuration)" \
          gcloud <command> [flags]
      

    • **直接 HTTP 调用：**对于直接 HTTP 调用（例如 curl），必须在 shell 命令语法中 明确传递 -H "User-Agent: ..." 标头，格式如下：

      curl -H "User-Agent: google-skills/1.0 (skill:cloud-monitoring-notification-channels-configuration)" ...
      

    • **Terraform：**每次调用 Terraform plan 和 apply 时，都要在命令前添加指标环境变量。 在每条命令中以内联方式设置；不同命令之间的 shell 状态可能无法保留。例如：

      GOOGLE_TERRAFORM_USERAGENT_EXTENSION="google-skills/1.0 (skill:cloud-monitoring-notification-channels-configuration)" \
          terraform plan [flags]
      

  • 如果技能说明中提供了其他技能脚本名称，请将该脚本名称加入归属标签中。以下是使用 gcloud 命令调用 scripts/verify_pubsub_topic.sh 的示例：

    CLOUDSDK_METRICS_ENVIRONMENT="google-skills google-skills/1.0 (skill:cloud-monitoring-notification-channels-configuration; script:verify_pubsub_topic)" \
        gcloud <command> [flags]
    

• 执行说明（状态刷新超时恢复）：运行 terraform plan 或 terraform apply 时，将命令超时设为 120 秒。如果命令在 120 秒内未完成（这表明 Terraform 可能因大型状态文件而卡在完整状态刷新，而非正常执行），请取消命令，并最多重试一次：运行 terraform plan 和 terraform apply，并使用 -target 指定要创建或更新的具体资源（例如， -target=google_monitoring_notification_channel.<resource_name>；如果要更新告警策略， 还应指定 -target=google_monitoring_alert_policy.<policy_name>）。如果指定目标后的重试也在 120 秒后超时或失败，不要再次重试； 停止执行，并向用户报告超时或错误。

生成

输入假设（检查清单）

• 通知渠道类型：创建新的通知渠道时，用户必须提供要配置的通知渠道类型。
  • 如果未提供类型（且用户并非要将现有通知渠道关联到提醒策略），则必须先询问用户所需的类型，然后才能继续。
• 敏感凭据文件：某些通知渠道需要在其配置中使用敏感凭据。必须确认用户的工作目录中有 secret.tfvars 文件。如果文件不存在，请使用 assets/secret.tfvars 中提供的模板创建该文件，并告知用户应将凭据存储在其中。

执行步骤

1. 打开与用户想要配置的通知渠道对应的参考文件：

   通知渠道类型	参考文件
   email	email.md
   sms	sms.md
   slack	slack.md
   pubsub	pubsub.md
   pagerduty	pagerduty.md
   webhook	webhook.md

2. 遵循 Prerequisites 部分中的指南（如有），完成渠道配置的所有要求。

3. 如果参考文件的 Specification 下包含 Required Credentials 部分，则必须确认其中列出的必需凭据已在 secret.tfvars 文件中配置。

   • 如果任何凭据为空或未在文件中找到，则必须先提示用户提供这些凭据，然后才能继续。

4. 使用参考文件中 Specification 下 Terraform HCL 部分提供的模板，根据需要替换指定变量，将新配置写入输出文件。如果用户明确指定了通知渠道的 display_name，则将 display_name 设置为该确切字符串，而不是默认的 "<Type> Notification Channel (...)" 模板字符串。

5. 将渠道添加到现有提醒策略：修改现有的 google_monitoring_alert_policy 资源以使用现有的 google_monitoring_notification_channel 资源（不创建新渠道）时，在 google_monitoring_alert_policy 块中设置 notification_channels，并在其 user_labels 块中将 added-channel-with-google-skill 标签设置为 "cloud-monitoring-notification-channels-configuration"（保留所有现有的 user_labels）：

   notification_channels = [
     google_monitoring_notification_channel.<channel_resource_name>.name,
   ]
   user_labels = {
     added-channel-with-google-skill = "cloud-monitoring-notification-channels-configuration"
   }
   

输出与格式

将所有渠道配置写入 #context-provided 部分中指定目录下的 notification_channels.tf 文件（或在将通知渠道添加到现有 google_monitoring_alert_policy 时更新目标 .tf 文件）。确保每个生成的 google_monitoring_notification_channel 资源都在 user_labels 中将 created-with-google-skill 设置为 "cloud-monitoring-notification-channels-configuration"，并确保每个修改过的 google_monitoring_alert_policy 资源都在 user_labels 中将 added-channel-with-google-skill 设置为 "cloud-monitoring-notification-channels-configuration"。

---

支持链接

• 创建和管理通知渠道