cloud-monitoring-notification-channels-configuration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cloud Monitoring Notification Channels Configuration

Cloud Monitoring 通知渠道配置

Context Provided

提供的上下文

Terraform Only: Write the generated observability configuration ONLY as Terraform (
```
.tf
```
) files (e.g.,
```
notification_channels.tf
```
).
- Install Terraform ONLY if you are asked to deploy the channels AND there is no valid Terraform installation.
- If you are NOT asked to deploy the channels, DO NOT install Terraform.
Working Directory Inference: Determine the target path for
```
.tf
```
files using the following order:
1. If the user provides a path, use that exact path for the
```
.tf
```
  file.
2. If a path is not provided, search the workspace for existing
```
.tf
```
  files (preferring files that already define
```
google_monitoring_notification_channel
```
  or
```
google_monitoring_alert_policy
```
  resources, or existing directories in the strict preference order:
```
monitoring/
```
  , then
```
ops/
```
  , then
```
sre/
```
  ). If found, write
```
notification_channels.tf
```
  in that directory (or update the existing
```
.tf
```
  file when modifying an existing resource).
3. If a path is not provided and no
```
.tf
```
  files or target directories exist in the workspace, create and write to
```
monitoring/notification_channels.tf
```
  .
Google Cloud Prerequisites: When running
```
gcloud
```
CLI discovery commands or deploying configurations with the
```
terraform
```
CLI against a Google Cloud project, ensure the following prerequisites are met in order (do not execute these commands if the user only asks to generate or print Terraform HCL):
1. Target Project ID & Project Number:
  - Identify the target Google Cloud
```
{project_id}
```
    from the user's request or via
```
gcloud config get-value project
```
    . If neither is available, prompt the user to provide
```
{project_id}
```
    before continuing.
  - When the Google Cloud project number (
```
{project_number}
```
    ) is needed (such as constructing the Cloud Monitoring Service Agent identity for Pub/Sub channels):
    - Method A (Standard): Run
      gcloud projects describe {project_id} --format='value(projectNumber)'
      .
    - Method B (Ask User): If the command fails or you cannot retrieve the project number, ask the user to provide it.
2. Authentication: Authenticate the
```
gcloud
```
  CLI via
```
gcloud auth login
```
  and configure Application Default Credentials (ADC) for Terraform via
```
gcloud auth application-default login
```
  .
3. Project Configuration & Billing: Configure the target Google Cloud project via
```
gcloud config set project {project_id}
```
  (and ensure the project has an active billing account attached).
  - Recovery Actions: If
```
gcloud config set project {project_id}
```
    or
```
gcloud projects describe {project_id}
```
    fails, verify active credentials with
```
gcloud auth list
```
    , list accessible projects with
```
gcloud projects list
```
    , or prompt the user to confirm the project ID and access permissions. If deployment fails due to a missing or inactive billing account, stop deployment and instruct the user to link an active billing account (via
```
gcloud billing projects link {project_id} --billing-account={account_id}
```
    or in the Google Cloud console) before retrying.
4. IAM Permissions: Ensure the principal has permission to manage notification channels—either via the predefined Monitoring NotificationChannel Editor role (
```
roles/monitoring.notificationChannelEditor
```
  , plus
```
roles/monitoring.alertPolicyEditor
```
  when adding a channel to an existing alert policy) or via a custom IAM role containing the equivalent permissions (
```
monitoring.notificationChannels.get
```
  ,
```
monitoring.notificationChannels.list
```
  ,
```
monitoring.notificationChannels.create
```
  ,
```
monitoring.notificationChannels.update
```
  ,
```
monitoring.notificationChannels.delete
```
  , and
```
monitoring.alertPolicies.get
```
  /
```
monitoring.alertPolicies.update
```
  when updating an alert policy).
  - Recovery Actions: Users with a custom role granting these permissions do not need the predefined role name. If a
```
gcloud
```
    or
```
terraform
```
    command fails with
```
PERMISSION_DENIED
```
    (HTTP 403), stop execution, identify the missing
```
monitoring.notificationChannels.*
```
    or
```
monitoring.alertPolicies.*
```
    permission, and instruct the user to ask a project administrator to grant
```
roles/monitoring.notificationChannelEditor
```
    (or a custom role with the required permissions) to their principal.
Discovery Tips:
- Listing Notification Channels: You MUST use
```
gcloud beta monitoring channels list --project={project_id}
```
  to list notification channels. Do NOT use any other
```
gcloud
```
  commands to list notification channels.
- Verifying Pub/Sub Topics: When configuring a Pub/Sub notification channel, run
```
scripts/verify_pubsub_topic.sh
```
```
{monitoring_project_id} {topic_name_or_path}
```
  to verify that:
  1. The Pub/Sub API (
```
pubsub.googleapis.com
```
    ) is enabled in the topic's project (supporting both same-project topics and cross-project topics specified as
```
projects/{topic_project_id}/topics/{topic_name}
```
    ).
  2. The topic exists and the monitoring project's Cloud Monitoring Service Agent (
```
service-{monitoring_project_number}@gcp-sa-monitoring-notification.iam.gserviceaccount.com
```
    ) holds
```
roles/pubsub.publisher
```
    on the topic or topic project.
  3. The topic does not define a message storage policy (
```
messageStoragePolicy
```
    /
```
message_storage_policy
```
    ) and does not have in-transit enforcement (
```
enforceInTransit
```
    /
```
enforce_in_transit
```
    ) enabled. DO NOT use a Pub/Sub topic that defines a message storage policy or enforces in-transit restrictions as a notification channel, because Cloud Monitoring cannot deliver messages to such topics.
Attribution: You MUST tag EVERY applicable command and Terraform resource below that you create, modify, or suggest to the user.
- Terraform HCL (
  user_labels
  ):
  - Every
    google_monitoring_notification_channel
    resource that you create MUST include the
    created-with-google-skill
    label in its
    user_labels
    block:
    terraform
```
user_labels = {
  created-with-google-skill = "cloud-monitoring-notification-channels-configuration"
}
```
  - When modifying an existing
    google_monitoring_alert_policy
    resource solely to add a notification channel, do not use
    created-with-google-skill
    (since this skill did not create the alerting policy). Instead, include the
    added-channel-with-google-skill
    label in its
    user_labels
    block (preserving any existing
    user_labels
    on the policy):
    terraform
```
user_labels = {
  added-channel-with-google-skill = "cloud-monitoring-notification-channels-configuration"
}
```
- Follow the instructions below based on the CLI tool being used:
  - gcloud: Prefix every
    gcloud
    invocation with the metrics environment variables. Set them inline on each command; shell state may not persist between commands:
    bash
```
CLOUDSDK_METRICS_ENVIRONMENT="google-skills google-skills/1.0 (skill:cloud-monitoring-notification-channels-configuration)" \
    gcloud <command> [flags]
```
  - Direct HTTP calls: For direct HTTP calls (e.g.
    curl
    ), you MUST pass the explicit
    -H "User-Agent: ..."
    header in the shell command syntax exactly like this:
    bash
```
curl -H "User-Agent: google-skills/1.0 (skill:cloud-monitoring-notification-channels-configuration)" ...
```
  - Terraform: Prefix every Terraform
    plan
    and
    apply
    invocation with the metrics environment variables. Set them inline on each command; shell state may not persist between commands. For example:
    bash
```
GOOGLE_TERRAFORM_USERAGENT_EXTENSION="google-skills/1.0 (skill:cloud-monitoring-notification-channels-configuration)" \
    terraform plan [flags]
```
- If the skill instructions provide an additional skill script name, include that script name in the attribution label. Using a
```
gcloud
```
  command inside
  scripts/verify_pubsub_topic.sh
  as an example:
  bash
```
CLOUDSDK_METRICS_ENVIRONMENT="google-skills google-skills/1.0 (skill:cloud-monitoring-notification-channels-configuration; script:verify_pubsub_topic)" \
    gcloud <command> [flags]
```
Execution Note (State Refresh Timeout Recovery): When running
```
terraform plan
```
or
```
terraform apply
```
, set a command timeout of 120 seconds. If the command does not complete within 120 seconds (indicating Terraform is stalling on a full state refresh across a large state file rather than normal execution), cancel the command and retry at most once by running
```
terraform plan
```
and
```
terraform apply
```
with
```
-target
```
scoped to the specific resources being created or updated (for example,
```
-target=google_monitoring_notification_channel.<resource_name>
```
and, if updating an alert policy,
```
-target=google_monitoring_alert_policy.<policy_name>
```
). If the targeted retry also times out after 120 seconds or fails, DO NOT retry again; stop execution and report the timeout or error to the user.

仅限 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 前置条件：针对 Google Cloud 项目运行
```
gcloud
```
CLI 发现命令或使用
```
terraform
```
CLI 部署配置时，请按以下顺序确保满足各项前置条件（如果用户仅要求生成或打印 Terraform HCL，则不要执行这些命令）：
1. 目标项目 ID 与项目编号：
  - 从用户请求或
```
gcloud config get-value project
```
    中识别目标 Google Cloud
```
{project_id}
```
    。如果两者均不可用，请在继续之前提示用户提供
```
{project_id}
```
    。
  - 当需要 Google Cloud 项目编号（
```
{project_number}
```
    ）时（例如，为 Pub/Sub 渠道构建 Cloud Monitoring Service Agent 身份）：
    - 方法 A（标准方式）：运行
      gcloud projects describe {project_id} --format='value(projectNumber)'
      。
    - 方法 B（询问用户）：如果命令失败或无法获取项目编号，请要求用户提供。
2. 身份验证：通过
```
gcloud auth login
```
  验证
```
gcloud
```
  CLI，并通过
```
gcloud auth application-default login
```
  为 Terraform 配置 Application Default Credentials（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 Agent (
```
service-{monitoring_project_number}@gcp-sa-monitoring-notification.iam.gserviceaccount.com
```
    ) 对该主题或主题所在项目拥有
```
roles/pubsub.publisher
```
    。
  3. 主题未定义消息存储策略 (
```
messageStoragePolicy
```
    /
```
message_storage_policy
```
    )，且未启用传输中强制执行 (
```
enforceInTransit
```
    /
```
enforce_in_transit
```
    )。不要将定义了消息存储策略或启用了传输中限制的主题用作通知渠道，因为 Cloud Monitoring 无法向此类主题传送消息。

归因标记：必须为下文创建、修改或建议给用户的每条适用命令和 Terraform 资源添加标记。

Terraform HCL (
user_labels
)：

创建的每个

google_monitoring_notification_channel

资源都必须在其

user_labels

块中包含

created-with-google-skill

标签：

terraform

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

当仅为了添加通知渠道而修改现有

google_monitoring_alert_policy

资源时，不要使用

created-with-google-skill

（因为此 skill 并未创建该告警策略）。相反，在其

user_labels

块中包含

added-channel-with-google-skill

标签（并保留策略上现有的

user_labels

）：

terraform

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

根据所使用的 CLI 工具遵循以下说明：
- gcloud： 为每次
```
gcloud
```
  调用添加指标环境变量前缀。在每条命令中内联设置；shell 状态可能在命令之间不会保留：
  bash
```
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: ..."
```
  请求头：
  bash
```
curl -H "User-Agent: google-skills/1.0 (skill:cloud-monitoring-notification-channels-configuration)" ...
```
- Terraform： 为每次 Terraform
```
plan
```
  和
```
apply
```
  调用添加指标环境变量前缀。在每条命令中内联设置；shell 状态可能在命令之间不会保留。例如：
  bash
```
GOOGLE_TERRAFORM_USERAGENT_EXTENSION="google-skills/1.0 (skill:cloud-monitoring-notification-channels-configuration)" \
    terraform plan [flags]
```

如果 skill 指令提供了额外的 skill 脚本名称，请将该脚本名称包含在归因标签中。例如，在

scripts/verify_pubsub_topic.sh

中使用

gcloud

命令：

bash

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 正在对大型状态文件执行完整状态刷新并因此停滞，而非正常执行），请取消该命令，并且最多重试一次：运行带
```
-target
```
的
```
terraform plan
```
和
```
terraform apply
```
，将范围限定到正在创建或更新的特定资源（例如
```
-target=google_monitoring_notification_channel.<resource_name>
```
，以及在更新告警策略时使用
```
-target=google_monitoring_alert_policy.<policy_name>
```
）。如果定向重试再次达到 120 秒超时或失败， 不要再次重试；停止执行并向用户报告超时或错误。

Generation

生成

Input Assumptions (checklist)

输入假设（检查清单）

Notification Channel Type: When creating a new notification channel, the user MUST provide the notification channel type to configure.
- If no type is provided (and the user is not attaching an existing notification channel to an alert policy), you MUST prompt the user to ask for a type before continuing.
Sensitive Credentials File: Some notification channels require the use of sensitive credentials in their configuration. You MUST verify that the user has a
```
secret.tfvars
```
file in the working directory. If the file does not exist, create one using the template provided in
```
assets/secret.tfvars
```
and notify the user that credentials should be stored there.

通知渠道类型：创建新通知渠道时，用户必须提供要配置的通知渠道类型。
- 如果未提供类型（且用户并非将现有通知渠道附加到告警策略），必须提示用户提供类型后再继续。
敏感凭据文件：某些通知渠道的配置需要使用敏感凭据。必须验证工作目录中是否存在
```
secret.tfvars
```
文件。如果该文件不存在，则使用
```
assets/secret.tfvars
```
中提供的模板创建一个文件，并告知用户应将凭据存储在该文件中。

Execution Steps

执行步骤

Open the reference file corresponding to the notification channel the user wants to configure:

Notification Channel Type Reference File
email email.md
sms sms.md
slack slack.md
pubsub pubsub.md
pagerduty pagerduty.md
webhook webhook.md
Follow the guidelines in the
```
Prerequisites
```
section (if any) to complete all requirements for the channel configuration.
If the reference file contains a
```
Required Credentials
```
section under
```
Specification
```
, you MUST confirm that the listed required credentials are configured in the
```
secret.tfvars
```
file.
- If any of the credentials are set to empty or not found in the file, you MUST prompt the user to provide them before proceeding.
Use the template provided in the
```
Terraform HCL
```
section under
```
Specification
```
inside the reference file replacing the specified variables as needed to write the new configuration into the output file. If the user explicitly specifies a
```
display_name
```
for the notification channel, set
```
display_name
```
to that exact string instead of the default
```
"<Type> Notification Channel (...)"
```
template string.

Notification Channel Type	Reference File
email	email.md
sms	sms.md
slack	slack.md
pubsub	pubsub.md
pagerduty	pagerduty.md
webhook	webhook.md

Adding a Channel to an Existing Alert Policy: When modifying an existing

google_monitoring_alert_policy

resource to use an existing

google_monitoring_notification_channel

resource (without creating a new channel), set

notification_channels

on the

google_monitoring_alert_policy

block and set the

added-channel-with-google-skill

label to

"cloud-monitoring-notification-channels-configuration"

in its

user_labels

block (preserving any existing

user_labels

terraform

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

打开用户要配置的通知渠道所对应的参考文件：

通知渠道类型参考文件
email email.md
sms sms.md
slack slack.md
pubsub pubsub.md
pagerduty pagerduty.md
webhook webhook.md
遵循
```
Prerequisites
```
部分中的指南（如果有），完成渠道配置的所有要求。
如果参考文件的
```
Specification
```
下包含
```
Required Credentials
```
部分，必须确认其中列出的所需凭据已配置在
```
secret.tfvars
```
文件中。
- 如果任何凭据为空或未在该文件中找到，必须提示用户提供后再继续。
使用参考文件
```
Specification
```
下
```
Terraform HCL
```
部分提供的模板，根据需要替换指定变量，以将新配置写入输出文件。如果用户明确为通知渠道指定了
```
display_name
```
，则将其设为该确切字符串，而不是默认模板字符串
```
"<Type> Notification Channel (...)"
```
。

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

将渠道添加到现有告警策略：修改现有

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

）：

terraform

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

Outputs & Formats

输出与格式

Write all channel configurations into a

notification_channels.tf

file under the directory chosen in the #context-provided section (or update the target

.tf

file when adding notification channels to an existing

google_monitoring_alert_policy

). Ensure every generated

google_monitoring_notification_channel

resource sets

created-with-google-skill

"cloud-monitoring-notification-channels-configuration"

user_labels

, and every modified

google_monitoring_alert_policy

resource sets

added-channel-with-google-skill

"cloud-monitoring-notification-channels-configuration"

user_labels

将所有渠道配置写入

#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"

。

cloud-monitoring-notification-channels-configuration

Original

Translation

Cloud Monitoring Notification Channels Configuration

Cloud Monitoring 通知渠道配置

Context Provided

提供的上下文

Generation

生成

Input Assumptions (checklist)

输入假设（检查清单）

Execution Steps

执行步骤

Outputs & Formats

输出与格式

Supporting Links

相关链接