/cloud-monitoring-notification-channels-configuration

name: cloud-monitoring-notification-channels-configuration
metadata:
  version: "1.0.0"
  category: CloudObservabilityAndMonitoring
description: >-
  Generates Terraform HCL configurations for Cloud Monitoring notification
  channels (`google_monitoring_notification_channel`) and adds notification
  channels to alerting policies (`google_monitoring_alert_policy`) in Google
  Cloud projects. Use when creating or configuring email, SMS, Slack, PagerDuty,
  Pub/Sub, or webhook notification channels, verifying Pub/Sub topic
  compatibility (including cross-project topics, message storage policies, and
  in-transit enforcement) and publishing permissions for the Cloud Monitoring
  Service Agent, or adding notification channels to existing alert policies.
  Don't use for authoring or editing alerting policy conditions, selecting
  metric descriptors, or writing PromQL or Monitoring Filter queries.

Cloud Monitoring Notification Channels Configuration

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 ch