cloud-run-alert-configuration

Cloud Run 告警配置

使用 Terraform 和 PromQL（Cloud Monitoring）为 Cloud Run 实现生产级可观测性。本技能以 SRE 实践为基础，严格聚焦于可采取行动的用户影响和扩缩容边界。

---

署名

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

关键规则

• 提示词优先的快速路径（已指定名称时跳过发现）：
  • 如果用户提示词明确指定了目标 Cloud Run 服务、作业或 Worker Pool 名称（例如，'video-encoder'、'nightly-reconciliation'、'web-frontend'、'catalog-service'、'api-gateway'、'order-processor'），则完全跳过工作区 .tf 文件扫描（find_by_name、code_search、list_dir）和 gcloud CLI 发现命令。
  • 如果提示词中已提供目标名称，请勿运行 gcloud、terraform 或文件搜索工具。应改用 Terraform 变量参数化项目 ID（variable "scoping_project_id" { default = "my-gcp-project" }）和目标资源名称，并立即进入步骤 2（配置告警）。
• 自主发现（仅在未提供目标名称时）：
  • 切勿扫描根级单体仓库或无界目录：切勿在根工作区目录中运行 find_by_name 或 ls。
  • 优先检查配置：仅当提示词中未提供资源名称时，才检查当前工作目录中的 .tf 文件，查找 google_cloud_run_v2_service、google_cloud_run_service 或 google_cloud_run_v2_job。
  • 其次使用 CLI（平稳回退）：仅当提示词或本地 .tf 文件中都未配置资源时，才尝试运行 gcloud config get-value project 和 gcloud run services list。如果任何 gcloud 命令失败（例如，身份验证或元数据错误），或缺少 terraform，请立即停止运行 CLI 命令，并使用明确的变量默认值输出参数化 HCL。
• 工作负载路由：始终对目标工作负载进行分类，并遵循其对应的参考指南：
  • HTTP 服务遵循 services.md
  • Cloud Run 作业遵循 jobs.md
  • Worker Pool 遵循 worker_pools.md
• 明确默认值与用户覆盖：
  • 始终为目标工作负载参考文件中指定的所有常量使用明确的默认值（SLO 目标、延迟阈值、SLA、饱和上限、速率限制）。
  • 在最终摘要中说明所采用的默认值，并明确告知用户，可通过 Terraform 变量或提示词输入自定义或覆盖任何默认常量。
• 集中设置指标范围：在所有 Terraform google_monitoring_alert_policy 资源中，将 project = var.scoping_project_id 参数化，以便策略可面向单个项目或集中式 Cloud Monitoring Metrics Scope。
• PromQL duration（重测窗口）规则：
  • 回溯时间 ≤ 25h：设置 duration = "300s"（5m 缓冲），以吸收瞬时波动和扩容延迟（即时作业失败告警除外，此类告警使用 duration = "0s"）。
  • 回溯时间 > 25h（例如，3d/7d Slow Burn）：完全省略 duration（或设置为 0s）。Cloud Monitoring 不接受 duration 已设置且回溯时间 >25h 的 PromQL 查询（INVALID_ARGUMENT）。
• Terraform 标准与强制标签：
  • 在回复中直接使用 google_monitoring_alert_policy 和 condition_prometheus_query_language，输出整洁、完整的 .tf 配置。
  • 强制用户标签：每个 google_monitoring_alert_policy 资源都必须包含 user_labels 块，其中包含：

    user_labels = {
      created-with-google-skill = "cloud-run-alert-configuration"
    }
    

  • 包含 alert_strategy { auto_close = "604800s" }，并将 notification_channels = var.notification_channels 参数化。

工作流步骤

1. 发现与目标识别

• 快速路径（提示词中已指定目标）：如果用户提示词中指定了目标 Cloud Run 服务、作业或工作池，跳过所有发现命令和文件搜索，直接进入第 2 步。
• 发现备用路径（未指定目标）：仅当提示词中未提供资源名称时，检查本地 .tf 文件或运行 gcloud，以识别目标工作负载类型和名称。如果 gcloud 身份验证失败，立即回退到默认 Terraform 变量（var.scoping_project_id）。

2. 配置提醒

• 前往相应指南生成提醒策略：
  • HTTP 服务：打开 services.md。应用 请求的提醒策略或标准套件，涵盖可用性 SLO（5xx）、请求 延迟（P95/P99）、客户端错误（4xx）、容器实例饱和度、 容器 CPU/内存利用率、流量异常（骤降/激增）和计费 实例时间。
  • 批处理作业：打开 jobs.md。应用即时作业 执行失败提醒（duration = "0s"）。
  • 工作池：打开 worker_pools.md。 应用包含 4 项策略的标准套件（任务成功 SLO 快速/缓慢燃烧、 积压 ETD、消息年龄 SLA）。

3. Terraform 生成与审查

• 在回复中提供完整的 HCL 配置，明确参数化默认值，并包含必需的 user_labels 块（created-with-google-skill = "cloud-run-alert-configuration"）。
• 说明所应用的默认值，并提醒用户可以覆盖任何常量。
• 使用清晰易懂的语言说明 PromQL 逻辑和触发阈值。

---

其他资源

• Cloud Run 文档
• Cloud Monitoring PromQL 文档
• Terraform 中的 Google Cloud 提醒策略
• Google SRE 工作手册：基于 SLO 的提醒