☁️ Google Cloud Monitoring Group Terraform Module

Provisions a single Cloud Monitoring Group (google_monitoring_group) — a dynamic, filter-based collection of monitored resources used to scope dashboards, alerting, and uptime checks to a logical group (e.g. "all production web servers") rather than one resource at a time. Targets hashicorp/google ~> 7.0, Terraform >= 1.12.0.

• 🎯 Closes the last remaining piece of the monitoring family's original Tier 2 gap list (CATALOG_COVERAGE.md: "all three remaining monitoring gaps from Tier 2's notes now closed except groups/google_monitoring_group").
• 🆔 NO CALLER-SUPPLIED NAME/GROUP_ID INPUT EXISTS. Unlike almost every other module in this catalog, this resource's identity is entirely server-assigned — the only identity-adjacent input is display_name, a mutable, non-authoritative, display-only label. There is deliberately no name/group_id variable in this module.
• 🔗 id and name are literally the same value for this resource — the live schema confirms id's format is {{name}}, not a distinct composed string the way id/self_link differ elsewhere in this catalog. Both are emitted; both will always match.
• ✅ Corrected cross-module relationship: the real, documented consumer of this module's name output is terraform-google-monitoring-uptime-check's resource_group.group_id input — that module's own "KNOWN CATALOG GAP" comment names this exact producer. NOT terraform-google-monitoring-alert-policy, which has no resource_group argument anywhere in its schema (independently re-verified during authoring).
• 🌳 Nested group hierarchy — parent_name accepts another instance of this same module's name output, mirroring the live schema's own "Monitoring Group Subgroup" Example Usage block.
• ⚠️ Silent zero-match risk — a syntactically valid filter that matches zero monitored resources plans and applies successfully, producing an empty group with no error anywhere.
• 🏷️ No labels and no self_link exist on this resource — both confirmed, schema-driven omissions predating GCP's common labels convention.

💡 Why it matters: a Monitoring Group's value is entirely a function of its filter actually matching the intended resources — a typo'd label key, an over-narrowed AND chain, or a resource type that no longer exists in the project all produce a group that creates successfully with zero members, silently defeating whatever uptime check or dashboard scopes to it.

If these Terraform modules have been helpful to you or your organization, I'd appreciate your support in any of the following ways:

• ⭐ Star this repository to help others discover this Terraform module.
• 🤝 Connect with me on LinkedIn: linkedin.com/in/microsoftexpert
• ☕ Buy me a coffee: buymeacoffee.com/microsoftexpert

Whether it's a star, a professional connection, or a coffee, every gesture helps keep these modules actively maintained and continually improving. Thank you for being part of the community!

graph LR
 PS["terraform-google-project-services"]:::external
 THIS["terraform-google-monitoring-group"]:::thisModule
 UC["terraform-google-monitoring-uptime-check"]:::keystoneSibling
 AP["terraform-google-monitoring-alert-policy (no resource_group field exists)"]:::noEdge
 SUB["second terraform-google-monitoring-group instance (nested subgroup)"]:::thisModule

 PS -. "enables monitoring.googleapis.com (informal prerequisite)".-> THIS
 THIS -- "name output -> resource_group.group_id, CLOSES known catalog gap" --> UC
 THIS -- "name output -> parent_name, nested group hierarchy" --> SUB

 classDef thisModule fill:#4285F4,color:#ffffff,stroke:#174EA6,stroke-width:1px;
 classDef keystoneSibling fill:#174EA6,color:#ffffff,stroke:#174EA6,stroke-width:1px;
 classDef external fill:#E8EAED,color:#202124,stroke:#9AA0A6,stroke-width:1px,stroke-dasharray: 3 3;
 classDef noEdge fill:#E8EAED,color:#202124,stroke:#EA4335,stroke-width:1px,stroke-dasharray: 3 3;

(Validated via the Mermaid Chart MCP — valid: true, diagramType: flowchart.) The solid edge into terraform-google-monitoring-uptime-check is the real, documented consumer relationship: this module's name output is exactly the string that module's resource_group.group_id input expects — that module's own variables.tf carries a "KNOWN CATALOG GAP — resource_group.group_id... google_monitoring_group is NOT yet a module in the catalog" comment that this module's authoring closes. terraform-google-monitoring-alert-policy is drawn deliberately, with no edge, and captioned "does not consume a monitoring group (no resource_group field exists on this resource)" — the scaffolding brief that seeded this module's authoring incorrectly assumed that relationship; it was independently re-verified this session to be false (that resource's conditions blocks support condition_absent, condition_monitoring_query_language, condition_threshold, condition_matched_log, condition_prometheus_query_language, condition_sql — none reference a Monitoring Group by id; its only "group"-adjacent field, aggregations.group_by_fields, groups time series by label during aggregation, an unrelated concept). The self-referential edge into a second instance of this same module illustrates the parent_name nested-group-hierarchy composition pattern. terraform-google-project-services (dashed) must have already enabled monitoring.googleapis.com.

A single keystone resource, no children — every argument is a flat scalar; the only optional nested block is the universal timeouts guard.

graph TD
 subgraph Inputs
 A["var.display_name"]
 B["var.filter"]
 C["var.parent_name"]
 D["var.is_cluster"]
 E["var.deletion_policy"]
 F["var.timeouts"]
 end

 R["google_monitoring_group.this"]:::thisModule

 A --> R
 B --> R
 C -.->|"optional, nested subgroup hierarchy"| R
 D --> R
 E --> R
 F -.->|"dynamic timeouts"| R

 R --> O1["output: id"]
 R --> O2["output: name"]

 O1 -. "id == name, always identical".- O2

 classDef thisModule fill:#4285F4,color:#ffffff,stroke:#174EA6,stroke-width:1px;

(Validated via the Mermaid Chart MCP — valid: true, diagramType: flowchart.) id and name are drawn as two outputs joined by a dotted "always identical" edge rather than as independent values, since the live schema confirms id's format is literally {{name}}.

Resource inventory:

Schema notes that bite (verified against the live v7.39.0 Argument/Attributes Reference via terraform-registry):

• No name/group_id argument exists anywhere in the Argument Reference. The full set is display_name, filter, parent_name, is_cluster, project (skipped per house rule), deletion_policy — nothing that lets a caller choose the resource's own identity. The group_id portion of name is entirely server-assigned.
• id and name are the same value. The Attributes Reference states id — "an identifier for the resource with format {{name}}" — verbatim; name is "A unique identifier for this group. The format is projects/{project_id_or_number}/groups/{group_id}." No other module in this catalog has this property.
• No self_link attribute. Only id and name are exported — the Monitoring Groups API has no distinct URL-form resource identity.
• No labels argument. Confirmed absent from the full Argument Reference — Cloud Monitoring Groups predate GCP's common labels convention and were never retrofitted (the same class of omission as terraform-google-compute-target-pool and terraform-google-compute-http-health-check, for a different underlying reason).
• filter has no plan-time validity check beyond non-empty. A syntactically valid filter that matches zero monitored resources plans and applies successfully — the group is created with zero members, not an error.
• is_cluster's documented interaction with filter is thin. The live docs state only "the system can perform additional analysis on groups that are clusters" — nothing further is confirmed, and this module does not invent an additional constraint.
• No deletion_protection boolean. deletion_policy (DELETE/ABANDON/PREVENT, provider default DELETE) is the only Terraform-side destroy guard this resource exposes.
• timeouts fully supported. create/update/delete each default to 20 minutes — the full universal-tail triad, no exceptions.

• roles/monitoring.editor — this module's seeded candidate: create, update, and delete Cloud Monitoring Groups (broader than group-scoped; it also covers other Monitoring resources). Unlike this module's four Monitoring siblings (terraform-google-monitoring-alert-policy, terraform-google-monitoring-dashboard, terraform-google-monitoring-uptime-check, terraform-google-monitoring-notification-channel, each of which found a dedicated, resource-specific predefined role), no dedicated groupsEditor-style role could be confirmed to exist through this pipeline's tooling (Google's predefined-role catalog is not part of the terraform-registry MCP or the provider schema). Reconfirm against Google's own IAM predefined-roles reference before granting broadly in a production project.

• monitoring.googleapis.com enabled on the target project (via terraform-google-project-services, applied before this module).

terraform-google-monitoring-group/
├── providers.tf # required_providers (hashicorp/google ~> 7.0) + required_version — no provider {} block
├── variables.tf # display_name, filter, parent_name, is_cluster, deletion_policy, timeouts (no labels)
├── main.tf # google_monitoring_group.this
├── outputs.tf # id, name (confirmed identical values; no self_link)
├── README.md # this file
├── SCOPE.md # lightweight cross-module contract
└── examples/ # runnable example matching the Quick Start below

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "Production web servers"
  filter       = "resource.type=\"gce_instance\" AND metadata.user_labels.\"env\"=\"prod\""
}

The caller's root module configures the google provider (project, region/zone, and authentication via ADC, Workload Identity Federation, or a service account key supplied out-of-band) — this module accepts none of those as variables.

Consumes

Emits

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "All production web servers"
  filter       = "resource.type=\"gce_instance\" AND metadata.user_labels.\"env\"=\"prod\""
}

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "EU-region resources"
  filter       = "resource.metadata.region=\"europe-west2\""
}

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "Primary database host (pinned)"
  filter       = "resource.type=\"gce_instance\" AND resource.labels.instance_id=\"1234567890123456789\""
}

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "AWS EC2 fleet under Cloud Monitoring"
  filter       = "resource.type=\"aws_ec2_instance\" AND metadata.user_labels.\"env\"=\"prod\""
}

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "GKE node pool cluster"
  filter       = "resource.type=\"k8s_node\" AND resource.labels.cluster_name=\"prod-gke\""
  is_cluster   = true
}

module "parent_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "All production resources"
  filter       = "metadata.user_labels.\"env\"=\"prod\""
}

module "web_subgroup" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "Production web tier (subgroup)"
  filter       = "resource.type=\"gce_instance\" AND metadata.user_labels.\"tier\"=\"web\""

  # Nested group hierarchy: wires the parent's own `name` output into this module's
  # `parent_name` input, mirroring the live schema's own "Monitoring Group Subgroup" Example
  # Usage block verbatim.
  parent_name = module.parent_group.name
}

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name    = "Production uptime-check target group — protected"
  filter          = "resource.type=\"gce_instance\" AND metadata.user_labels.\"env\"=\"prod\""
  deletion_policy = "PREVENT"
}

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name    = "Deprecated staging group (being decommissioned out-of-band)"
  filter          = "metadata.user_labels.\"env\"=\"staging\""
  deletion_policy = "ABANDON"
}

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "Large fleet group — extended apply window"
  filter       = "resource.type=\"gce_instance\""

  timeouts = {
    create = "10m"
    update = "10m"
    delete = "10m"
  }
}

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "Production web servers (typo'd label)"
  # Typo: "evn" instead of "env" — this string is syntactically valid Cloud Monitoring filter
  # syntax, so validate/plan/apply all succeed. The resulting group has zero members.
  filter = "resource.type=\"gce_instance\" AND metadata.user_labels.\"evn\"=\"prod\""
}

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "GKE production namespace containers"
  filter       = "resource.type=\"k8s_container\" AND resource.labels.namespace_name=\"prod\""
}

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "Production Cloud SQL instances"
  filter       = "resource.type=\"cloudsql_database\" AND metadata.user_labels.\"env\"=\"prod\""
}

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "Production us-central1 web tier"
  filter = join(" AND ", [
    "resource.type=\"gce_instance\"",
    "resource.metadata.zone=starts_with(\"us-central1\")",
    "metadata.user_labels.\"tier\"=\"web\"",
    "metadata.user_labels.\"env\"=\"prod\"",
  ])
}

module "monitoring_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name = "Production web servers (renamed for clarity)"
  filter       = "resource.type=\"gce_instance\" AND metadata.user_labels.\"env\"=\"prod\""
}

module "project_services" {
  source = "git::https://github.com/microsoftexpert/terraform-google-project-services.git?ref=v1.0.0"

  # Enables monitoring.googleapis.com — applied before every other module in this composition.
}

module "production_web_group" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-group.git?ref=v1.0.0"

  display_name    = "Production web fleet"
  filter          = "resource.type=\"gce_instance\" AND metadata.user_labels.\"tier\"=\"web\" AND metadata.user_labels.\"env\"=\"prod\""
  deletion_policy = "PREVENT" # a production uptime check depends on this group's targeting

  depends_on = [module.project_services]
}

module "production_web_uptime_check" {
  source = "git::https://github.com/microsoftexpert/terraform-google-monitoring-uptime-check.git?ref=v1.0.0"

  display_name = "Production web fleet reachability"
  timeout      = "10s"

  tcp_check = {
    port = 443
  }

  # Real, confirmed cross-module composition: this module's own `name` output is exactly the
  # string terraform-google-monitoring-uptime-check's `resource_group.group_id` expects — CLOSING that
  # sibling module's own documented "KNOWN CATALOG GAP — resource_group.group_id" comment.
  resource_group = {
    resource_type = "INSTANCE"
    group_id      = module.production_web_group.name
  }

  depends_on = [module.production_web_group]
}

No name/group_id variable exists — the group's identity is entirely server-assigned. No labels variable exists — confirmed absent from this resource's live schema.

variable "display_name" {
  type = string
  # must be non-empty, enforced via validation {}
}

variable "filter" {
  type = string
  # must be non-empty, enforced via validation {}
  # zero-match risk is NOT enforceable — documented only
}

variable "parent_name" {
  type    = string
  default = null
}

variable "is_cluster" {
  type    = bool
  default = false
}

variable "deletion_policy" {
  type    = string
  default = "DELETE"
  # DELETE | ABANDON | PREVENT, enforced via validation {}
}

variable "timeouts" {
  type = object({
    create = optional(string)
    update = optional(string)
    delete = optional(string)
  })
  default = null
}

No self_link row — confirmed absent from this resource's live schema. No output is secret-bearing.

• No caller-supplied name/group_id input — its own clearly-labeled finding. The group's identity (both id and name) is generated entirely by the API at creation time. This is a genuinely unusual shape relative to almost every other module in this catalog, where a caller chooses (or at least influences) the resource's own name. Any composition that needs a stable reference to this group must consume this module's name output — it cannot be predicted or hardcoded before the first apply.
• id and name are the same value for this resource. The live schema's Attributes Reference confirms id's format is literally {{name}}. Both outputs are provided for house-convention consistency; either can be used interchangeably.
• No labels and no self_link exist on this resource — both confirmed, schema-driven omissions. Cloud Monitoring Groups predate GCP's common labels convention and were never retrofitted; the Monitoring Groups API has no distinct URL-form resource identity.
• The corrected consumer relationship with terraform-google-monitoring-uptime-check. The scaffolding brief that originally seeded this module's authoring incorrectly assumed terraform-google-monitoring-alert-policy consumed a group via a resource_group field — independently re-verified this session to be false. The real, already-documented consumer is terraform-google-monitoring-uptime-check's resource_group.group_id, whose own variables.tf carries an explicit "KNOWN CATALOG GAP" comment naming this exact producer.
• filter zero-match risk. A syntactically valid filter matching zero monitored resources plans and applies successfully — the group is created with zero members, not an error. Consistent with the established house precedent on terraform-google-log-based-metric, terraform-google-scc-notification-config, and terraform-google-log-view. Cannot be caught by validate/plan/apply in this plan-only library.
• is_cluster/filter documentation-boundary honesty note. Google documents only "the system can perform additional analysis on groups that are clusters" for is_cluster — nothing further. This module deliberately does not invent an additional constraint or cross-field validation connecting is_cluster to filter beyond what is literally stated.
• deletion_policy judgment call. Left at the provider's own "DELETE" default — this resource has no separate deletion_protection boolean, mirroring terraform-google-service-networking-connection/terraform-google-managed-instance-group's reasoning rather than terraform-google-compute-target-pool's "PREVENT"-by-default precedent (that resource sits directly on a live traffic-routing path; a monitoring group does not). See Design Principles for the full rationale.
• IAM propagation lag. roles/monitoring.editor grants made immediately before this module applies can take up to ~60 seconds to propagate, per the house-wide note.

cd terraform-google-monitoring-group
terraform init -backend=false
terraform validate
terraform fmt -check

Pin the module source to ?ref=v1.0.0 — never a branch. This library is plan-only from an authoring session; a human applies from CI with valid Workload Identity Federation or ADC credentials.

terraform validate confirms internal type and reference consistency (the deletion_policy closed-enum validation {} block, display_name/filter non-empty checks, correct resource/output wiring). terraform fmt -check confirms canonical formatting. Neither — nor any plan run from this authoring session — can catch:

• A filter that syntactically validates but matches zero monitored resources — the single most important limitation of this module's testing. Only a real apply against a live Monitoring Workspace, followed by a membership check (gcloud monitoring groups list-members or the Console), proves a group's filter actually matches the intended resources.
• A parent_name string that does not correspond to any real, existing group (if supplied as a plain string rather than via module.<name>.name) — rejected only by the API at apply time.
• Quota or org-policy rejections (e.g. a project-level Monitoring Group quota limit).

Only a real apply/plan against a live project — out of this library's plan-only scope — proves a group's membership is what the caller intended.

$ terraform output

id = "projects/casey-prod-web/groups/0123456789012345"
name = "projects/casey-prod-web/groups/0123456789012345"

• google_monitoring_group provider resource reference
• terraform-google-project-services (must enable monitoring.googleapis.com before this module applies)
• terraform-google-monitoring-uptime-check (the real, confirmed consumer of this module's name output via resource_group.group_id — see 🔌 Cross-Module Contract and example 15; this module's authoring closes that module's own documented "KNOWN CATALOG GAP")
• terraform-google-monitoring-alert-policy (does not consume a monitoring group — no resource_group field exists on this resource; drawn in the family DAG above with no edge, for context only)
• terraform-google-log-based-metric, terraform-google-scc-notification-config, terraform-google-log-view (the sibling modules whose filter-shaped arguments document the identical zero-match silent-misconfiguration risk this module's own filter shares)
• terraform-google-service-networking-connection, terraform-google-managed-instance-group (the deletion_policy = "DELETE"-by-default precedent this module follows)
• terraform-google-compute-target-pool, terraform-google-server-tls-policy, terraform-google-client-tls-policy (the deletion_policy = "PREVENT"-by-default precedent this module deliberately does NOT follow, and why)
• This module's SCOPE.md