feat(alloydb): add support for advanced query insights (observability_config) (#3856)

* Implemented advanced query insight in alloydb module * Implemented readme example and test * Fix TOC
2026-04-11 13:57:38 +02:00
parent 8b2fb39efe
commit 55a847c008
4 changed files with 430 additions and 25 deletions
--- a/modules/alloydb/README.md
+++ b/modules/alloydb/README.md
@@ -8,19 +8,20 @@ Note that this module assumes that some options are the same for both the primar
 > [!WARNING]
 > If you use the `users` field, you terraform state will contain each user's password in plain text.

-<!-- TOC -->
-* [AlloyDB module](#alloydb-module)
-  * [Examples](#examples)
-    * [Simple example](#simple-example)
-    * [Read pool](#read-pool)
-    * [Cross region replication](#cross-region-replication)
-    * [PSC instance](#psc-instance)
-    * [Custom flags and users definition](#custom-flags-and-users-definition)
-    * [CMEK encryption](#cmek-encryption)
-  * [Variables](#variables)
-  * [Outputs](#outputs)
-  * [Fixtures](#fixtures)
-<!-- TOC -->
+<!-- BEGIN TOC -->
+- [Examples](#examples)
+  - [Simple example](#simple-example)
+  - [Read pool](#read-pool)
+  - [Read pool with advanced query insights](#read-pool-with-advanced-query-insights)
+  - [Cross region replication](#cross-region-replication)
+  - [Cross region replication with primary and secondary cluster read pool](#cross-region-replication-with-primary-and-secondary-cluster-read-pool)
+  - [PSC instance](#psc-instance)
+  - [Custom flags and users definition](#custom-flags-and-users-definition)
+  - [CMEK encryption](#cmek-encryption)
+- [Tag bindings](#tag-bindings)
+- [Variables](#variables)
+- [Outputs](#outputs)
+<!-- END TOC -->

 ## Examples

@@ -103,6 +104,84 @@ module "alloydb" {
 # tftest modules=1 resources=4 inventory=read_pool.yaml e2e
 ```

+### Read pool with advanced query insights
+
+This example demonstrates how to configure an AlloyDB cluster with a read pool and enable [advanced query insights](https://docs.cloud.google.com/alloydb/docs/advanced-query-insights-overview) for both the primary instance and the read pool instance.
+
+```hcl
+module "project" {
+  source          = "./fabric/modules/project"
+  billing_account = var.billing_account_id
+  parent          = var.folder_id
+  name            = "alloydb"
+  prefix          = var.prefix
+  services = [
+    "servicenetworking.googleapis.com",
+    "alloydb.googleapis.com",
+    "geminicloudassist.googleapis.com"
+  ]
+}
+
+module "vpc" {
+  source     = "./fabric/modules/net-vpc"
+  project_id = module.project.project_id
+  name       = "my-network"
+  # need only one - psa_config or subnets_psc
+  psa_configs = [{
+    ranges = { alloydb = "10.60.0.0/16" }
+  }]
+  subnets_psc = [{
+    ip_cidr_range = "10.0.3.0/24"
+    name          = "psc"
+    region        = var.region
+  }]
+}
+
+module "alloydb" {
+  source         = "./fabric/modules/alloydb"
+  project_id     = module.project.project_id
+  project_number = var.project_number
+  cluster_name   = "db"
+  instance_name  = "db"
+  location       = var.region
+  network_config = {
+    psa_config = {
+      network = module.vpc.id
+    }
+  }
+
+  read_pool = {
+    "regional-read-pool" = {
+      node_count = 2
+      observability_config = {
+        enabled                       = true
+        preserve_comments             = true
+        track_wait_events             = true
+        max_query_string_length       = 20480
+        record_application_tags       = true
+        query_plans_per_minute        = 30
+        track_active_queries          = true
+        assistive_experiences_enabled = true
+      }
+    }
+  }
+
+  observability_config = {
+    enabled                       = true
+    preserve_comments             = true
+    track_wait_events             = true
+    max_query_string_length       = 20480
+    record_application_tags       = true
+    query_plans_per_minute        = 30
+    track_active_queries          = true
+    assistive_experiences_enabled = true
+  }
+
+  deletion_protection = false
+}
+# tftest modules=3 resources=19 inventory=read_pool_with_advanced_query_insights.yaml e2e
+```
+
 ### Cross region replication

 ```hcl
@@ -347,7 +426,7 @@ module "alloydb" {
 | [instance_name](variables.tf#L211) | Name of primary instance. | <code>string</code> | ✓ |  |
 | [location](variables.tf#L223) | Region or zone of the cluster and instance. | <code>string</code> | ✓ |  |
 | [network_config](variables.tf#L268) | Network configuration for cluster and instance. Only one between psa_config and psc_config can be used. | <code>object&#40;&#123;&#8230;&#125;&#41;</code> | ✓ |  |
-| [project_id](variables.tf#L303) | The ID of the project where this instances will be created. | <code>string</code> | ✓ |  |
+| [project_id](variables.tf#L319) | The ID of the project where this instances will be created. | <code>string</code> | ✓ |  |
 | [annotations](variables.tf#L17) | Map FLAG_NAME=>VALUE for annotations which allow client tools to store small amount of arbitrary data. | <code>map&#40;string&#41;</code> |  | <code>null</code> |
 | [automated_backup_configuration](variables.tf#L23) | Automated backup settings for cluster. | <code>object&#40;&#123;&#8230;&#125;&#41;</code> |  | <code>&#123;&#125;</code> |
 | [availability_type](variables.tf#L61) | Availability type for the primary replica. Either `ZONAL` or `REGIONAL`. | <code>string</code> |  | <code>&#34;REGIONAL&#34;</code> |
@@ -366,14 +445,15 @@ module "alloydb" {
 | [labels](variables.tf#L217) | Labels to be attached to all instances. | <code>map&#40;string&#41;</code> |  | <code>null</code> |
 | [machine_config](variables.tf#L229) | AlloyDB machine config. | <code>object&#40;&#123;&#8230;&#125;&#41;</code> |  | <code>&#123;&#125;</code> |
 | [maintenance_config](variables.tf#L243) | Set maintenance window configuration. | <code>object&#40;&#123;&#8230;&#125;&#41;</code> |  | <code>&#123;&#125;</code> |
-| [prefix](variables.tf#L293) | Optional prefix used to generate instance names. | <code>string</code> |  | <code>null</code> |
-| [project_number](variables.tf#L308) | The project number of the project where this instances will be created. Only used for testing purposes. | <code>string</code> |  | <code>null</code> |
-| [query_insights_config](variables.tf#L314) | Query insights config. | <code>object&#40;&#123;&#8230;&#125;&#41;</code> |  | <code>&#123;&#125;</code> |
-| [read_pool](variables.tf#L325) | Map of read pool instances to create in the primary cluster. | <code>map&#40;object&#40;&#123;&#8230;&#125;&#41;&#41;</code> |  | <code>&#123;&#125;</code> |
-| [skip_await_major_version_upgrade](variables.tf#L370) | Set to true to skip awaiting on the major version upgrade of the cluster. | <code>bool</code> |  | <code>true</code> |
-| [subscription_type](variables.tf#L376) | The subscription type of cluster. Possible values are: 'STANDARD' or 'TRIAL'. | <code>string</code> |  | <code>&#34;STANDARD&#34;</code> |
-| [tag_bindings](variables.tf#L382) | Tag bindings for this service, in key => tag value id format. | <code>map&#40;string&#41;</code> |  | <code>&#123;&#125;</code> |
-| [users](variables.tf#L389) | Map of users to create in the primary instance (and replicated to other replicas). Set PASSWORD to null if you want to get an autogenerated password. The user types available are: 'ALLOYDB_BUILT_IN' or 'ALLOYDB_IAM_USER'. | <code>map&#40;object&#40;&#123;&#8230;&#125;&#41;&#41;</code> |  | <code>&#123;&#125;</code> |
+| [observability_config](variables.tf#L293) | Advanced query insights config for AlloyDB. Mutually exclusive with query_insights_config. | <code>object&#40;&#123;&#8230;&#125;&#41;</code> |  | <code>null</code> |
+| [prefix](variables.tf#L309) | Optional prefix used to generate instance names. | <code>string</code> |  | <code>null</code> |
+| [project_number](variables.tf#L324) | The project number of the project where this instances will be created. Only used for testing purposes. | <code>string</code> |  | <code>null</code> |
+| [query_insights_config](variables.tf#L330) | Query insights config. Mutually exclusive with observability_config. It will be ignored if observability_config is enabled. | <code>object&#40;&#123;&#8230;&#125;&#41;</code> |  | <code>&#123;&#125;</code> |
+| [read_pool](variables.tf#L341) | Map of read pool instances to create in the primary cluster. | <code>map&#40;object&#40;&#123;&#8230;&#125;&#41;&#41;</code> |  | <code>&#123;&#125;</code> |
+| [skip_await_major_version_upgrade](variables.tf#L397) | Set to true to skip awaiting on the major version upgrade of the cluster. | <code>bool</code> |  | <code>true</code> |
+| [subscription_type](variables.tf#L403) | The subscription type of cluster. Possible values are: 'STANDARD' or 'TRIAL'. | <code>string</code> |  | <code>&#34;STANDARD&#34;</code> |
+| [tag_bindings](variables.tf#L409) | Tag bindings for this service, in key => tag value id format. | <code>map&#40;string&#41;</code> |  | <code>&#123;&#125;</code> |
+| [users](variables.tf#L416) | Map of users to create in the primary instance (and replicated to other replicas). Set PASSWORD to null if you want to get an autogenerated password. The user types available are: 'ALLOYDB_BUILT_IN' or 'ALLOYDB_IAM_USER'. | <code>map&#40;object&#40;&#123;&#8230;&#125;&#41;&#41;</code> |  | <code>&#123;&#125;</code> |

 ## Outputs

--- a/modules/alloydb/main.tf
+++ b/modules/alloydb/main.tf
@@ -247,7 +247,7 @@ resource "google_alloydb_instance" "primary" {
  }

  dynamic "query_insights_config" {
-    for_each = var.query_insights_config != null ? [""] : []
+    for_each = var.query_insights_config != null && !try(var.observability_config.enabled, false) ? [""] : []
    content {
      query_string_length     = var.query_insights_config.query_string_length
      record_application_tags = var.query_insights_config.record_application_tags
@@ -255,6 +255,21 @@ resource "google_alloydb_instance" "primary" {
      query_plans_per_minute  = var.query_insights_config.query_plans_per_minute
    }
  }
+
+  dynamic "observability_config" {
+    for_each = try(var.observability_config.enabled, false) ? [""] : []
+    content {
+      enabled                 = var.observability_config.enabled
+      preserve_comments       = var.observability_config.preserve_comments
+      track_wait_events       = var.observability_config.track_wait_events
+      max_query_string_length = var.observability_config.max_query_string_length
+      record_application_tags = var.observability_config.record_application_tags
+      query_plans_per_minute  = var.observability_config.query_plans_per_minute
+      track_active_queries    = var.observability_config.track_active_queries
+      # track_client_address          = var.observability_config.track_client_address # There is a PR to add this feature to the provider. Tracking it here: https://github.com/GoogleCloudPlatform/magic-modules/pull/17067
+      assistive_experiences_enabled = var.observability_config.assistive_experiences_enabled
+    }
+  }
 }

 resource "google_alloydb_cluster" "secondary" {
@@ -510,7 +525,7 @@ resource "google_alloydb_instance" "read_pool_primary" {
  }

  dynamic "query_insights_config" {
-    for_each = each.value.query_insights_config != null ? [""] : []
+    for_each = each.value.query_insights_config != null && !try(each.value.observability_config.enabled, false) ? [""] : []
    content {
      query_string_length     = each.value.query_insights_config.query_string_length
      record_application_tags = each.value.query_insights_config.record_application_tags
@@ -519,6 +534,21 @@ resource "google_alloydb_instance" "read_pool_primary" {
    }
  }

+  dynamic "observability_config" {
+    for_each = try(each.value.observability_config.enabled, false) ? [""] : []
+    content {
+      enabled                 = each.value.observability_config.enabled
+      preserve_comments       = each.value.observability_config.preserve_comments
+      track_wait_events       = each.value.observability_config.track_wait_events
+      max_query_string_length = each.value.observability_config.max_query_string_length
+      record_application_tags = each.value.observability_config.record_application_tags
+      query_plans_per_minute  = each.value.observability_config.query_plans_per_minute
+      track_active_queries    = each.value.observability_config.track_active_queries
+      # track_client_address          = each.value.observability_config.track_client_address # There is a PR to add this feature to the provider. Tracking it here: https://github.com/GoogleCloudPlatform/magic-modules/pull/17067
+      assistive_experiences_enabled = each.value.observability_config.assistive_experiences_enabled
+    }
+  }
+
  depends_on = [google_alloydb_instance.primary]
 }

--- a/modules/alloydb/variables.tf
+++ b/modules/alloydb/variables.tf
@@ -290,6 +290,22 @@ variable "network_config" {
  }
 }

+variable "observability_config" {
+  description = "Advanced query insights config for AlloyDB. Mutually exclusive with query_insights_config."
+  type = object({
+    enabled                 = optional(bool, false)
+    preserve_comments       = optional(bool, false)
+    track_wait_events       = optional(bool, true)
+    max_query_string_length = optional(number, 10240)
+    record_application_tags = optional(bool, false)
+    query_plans_per_minute  = optional(number, 20)
+    track_active_queries    = optional(bool, false)
+    # track_client_address          = optional(bool, false) # There is a PR to add this feature to the provider. Tracking it here: https://github.com/GoogleCloudPlatform/magic-modules/pull/17067
+    assistive_experiences_enabled = optional(bool, false)
+  })
+  default = null
+}
+
 variable "prefix" {
  description = "Optional prefix used to generate instance names."
  type        = string
@@ -312,7 +328,7 @@ variable "project_number" {
 }

 variable "query_insights_config" {
-  description = "Query insights config."
+  description = "Query insights config. Mutually exclusive with observability_config. It will be ignored if observability_config is enabled."
  type = object({
    query_string_length     = optional(number, 1024)
    record_application_tags = optional(bool, true)
@@ -348,6 +364,17 @@ variable "read_pool" {
      record_client_address   = optional(bool, true)
      query_plans_per_minute  = optional(number, 5)
    }))
+    observability_config = optional(object({
+      enabled                 = optional(bool, false)
+      preserve_comments       = optional(bool, false)
+      track_wait_events       = optional(bool, true)
+      max_query_string_length = optional(number, 10240)
+      record_application_tags = optional(bool, false)
+      query_plans_per_minute  = optional(number, 20)
+      track_active_queries    = optional(bool, false)
+      # track_client_address          = optional(bool, false) # There is a PR to add this feature to the provider. Tracking it here: https://github.com/GoogleCloudPlatform/magic-modules/pull/17067
+      assistive_experiences_enabled = optional(bool, false)
+    }), null)
  }))
  nullable = false
  default  = {}
--- a/tests/modules/alloydb/examples/read_pool_with_advanced_query_insights.yaml
+++ b/tests/modules/alloydb/examples/read_pool_with_advanced_query_insights.yaml
@@ -0,0 +1,268 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+values:
+  module.alloydb.google_alloydb_cluster.primary:
+    annotations: null
+    cluster_id: db
+    cluster_type: PRIMARY
+    continuous_backup_config:
+    - enabled: true
+      encryption_config: []
+      recovery_window_days: 14
+    database_version: POSTGRES_15
+    deletion_policy: DEFAULT
+    deletion_protection: false
+    display_name: db
+    effective_labels:
+      goog-terraform-provisioned: 'true'
+    encryption_config: []
+    etag: null
+    initial_user: []
+    labels: null
+    location: europe-west8
+    maintenance_update_policy: []
+    network_config:
+    - allocated_ip_range: null
+    project: test-alloydb
+    psc_config: []
+    restore_backup_source: []
+    restore_backupdr_backup_source: []
+    restore_backupdr_pitr_source: []
+    restore_continuous_backup_source: []
+    secondary_config: []
+    skip_await_major_version_upgrade: true
+    subscription_type: STANDARD
+    terraform_labels:
+      goog-terraform-provisioned: 'true'
+    timeouts: null
+  module.alloydb.google_alloydb_instance.primary:
+    annotations: null
+    availability_type: REGIONAL
+    connection_pool_config: []
+    display_name: db
+    effective_labels:
+      goog-terraform-provisioned: 'true'
+    gce_zone: null
+    instance_id: db
+    instance_type: PRIMARY
+    labels: null
+    machine_config:
+    - cpu_count: 2
+    observability_config:
+    - assistive_experiences_enabled: true
+      enabled: true
+      max_query_string_length: 20480
+      preserve_comments: true
+      query_plans_per_minute: 30
+      record_application_tags: true
+      track_active_queries: true
+      track_wait_events: true
+    read_pool_config: []
+    terraform_labels:
+      goog-terraform-provisioned: 'true'
+    timeouts: null
+  module.alloydb.google_alloydb_instance.read_pool_primary["regional-read-pool"]:
+    annotations: null
+    connection_pool_config: []
+    display_name: regional-read-pool
+    effective_labels:
+      goog-terraform-provisioned: 'true'
+    gce_zone: null
+    instance_id: regional-read-pool
+    instance_type: READ_POOL
+    labels: null
+    machine_config:
+    - cpu_count: 2
+    observability_config:
+    - assistive_experiences_enabled: true
+      enabled: true
+      max_query_string_length: 20480
+      preserve_comments: true
+      query_plans_per_minute: 30
+      record_application_tags: true
+      track_active_queries: true
+      track_wait_events: true
+    read_pool_config:
+    - node_count: 2
+    terraform_labels:
+      goog-terraform-provisioned: 'true'
+    timeouts: null
+  module.project.google_project.project[0]:
+    auto_create_network: false
+    billing_account: 123456-123456-123456
+    deletion_policy: DELETE
+    effective_labels:
+      goog-terraform-provisioned: 'true'
+    folder_id: '1122334455'
+    labels: null
+    name: test-alloydb
+    org_id: null
+    project_id: test-alloydb
+    tags: null
+    terraform_labels:
+      goog-terraform-provisioned: 'true'
+    timeouts: null
+  module.project.google_project_iam_member.service_agents["alloydb"]:
+    condition: []
+    project: test-alloydb
+    role: roles/alloydb.serviceAgent
+  module.project.google_project_iam_member.service_agents["service-networking"]:
+    condition: []
+    project: test-alloydb
+    role: roles/servicenetworking.serviceAgent
+  module.project.google_project_service.project_services["alloydb.googleapis.com"]:
+    disable_dependent_services: false
+    disable_on_destroy: false
+    project: test-alloydb
+    service: alloydb.googleapis.com
+    timeouts: null
+  module.project.google_project_service.project_services["geminicloudassist.googleapis.com"]:
+    disable_dependent_services: false
+    disable_on_destroy: false
+    project: test-alloydb
+    service: geminicloudassist.googleapis.com
+    timeouts: null
+  module.project.google_project_service.project_services["servicenetworking.googleapis.com"]:
+    disable_dependent_services: false
+    disable_on_destroy: false
+    project: test-alloydb
+    service: servicenetworking.googleapis.com
+    timeouts: null
+  module.project.google_project_service_identity.default["alloydb.googleapis.com"]:
+    project: test-alloydb
+    service: alloydb.googleapis.com
+    timeouts: null
+  module.project.google_project_service_identity.default["servicenetworking.googleapis.com"]:
+    project: test-alloydb
+    service: servicenetworking.googleapis.com
+    timeouts: null
+  module.vpc.google_compute_global_address.psa_ranges["servicenetworking-googleapis-com-alloydb"]:
+    address: 10.60.0.0
+    address_type: INTERNAL
+    description: null
+    effective_labels:
+      goog-terraform-provisioned: 'true'
+    ip_version: null
+    labels: null
+    name: servicenetworking-googleapis-com-alloydb
+    prefix_length: 16
+    project: test-alloydb
+    purpose: VPC_PEERING
+    terraform_labels:
+      goog-terraform-provisioned: 'true'
+    timeouts: null
+  module.vpc.google_compute_network.network[0]:
+    auto_create_subnetworks: false
+    delete_bgp_always_compare_med: false
+    delete_default_routes_on_create: false
+    description: Terraform-managed.
+    enable_ula_internal_ipv6: null
+    name: my-network
+    network_firewall_policy_enforcement_order: AFTER_CLASSIC_FIREWALL
+    network_profile: null
+    params: []
+    project: test-alloydb
+    routing_mode: GLOBAL
+    timeouts: null
+  module.vpc.google_compute_network_peering_routes_config.psa_routes["servicenetworking.googleapis.com"]:
+    export_custom_routes: false
+    import_custom_routes: false
+    network: my-network
+    project: test-alloydb
+    timeouts: null
+  module.vpc.google_compute_route.gateway["directpath-googleapis"]:
+    description: Terraform-managed.
+    dest_range: 34.126.0.0/18
+    name: my-network-directpath-googleapis
+    network: my-network
+    next_hop_gateway: default-internet-gateway
+    next_hop_ilb: null
+    next_hop_instance: null
+    next_hop_vpn_tunnel: null
+    params: []
+    priority: 1000
+    project: test-alloydb
+    tags: null
+    timeouts: null
+  module.vpc.google_compute_route.gateway["private-googleapis"]:
+    description: Terraform-managed.
+    dest_range: 199.36.153.8/30
+    name: my-network-private-googleapis
+    network: my-network
+    next_hop_gateway: default-internet-gateway
+    next_hop_ilb: null
+    next_hop_instance: null
+    next_hop_vpn_tunnel: null
+    params: []
+    priority: 1000
+    project: test-alloydb
+    tags: null
+    timeouts: null
+  module.vpc.google_compute_route.gateway["restricted-googleapis"]:
+    description: Terraform-managed.
+    dest_range: 199.36.153.4/30
+    name: my-network-restricted-googleapis
+    network: my-network
+    next_hop_gateway: default-internet-gateway
+    next_hop_ilb: null
+    next_hop_instance: null
+    next_hop_vpn_tunnel: null
+    params: []
+    priority: 1000
+    project: test-alloydb
+    tags: null
+    timeouts: null
+  module.vpc.google_compute_subnetwork.psc["europe-west8/psc"]:
+    description: Terraform-managed subnet for Private Service Connect (PSC NAT).
+    ip_cidr_range: 10.0.3.0/24
+    ip_collection: null
+    ipv6_access_type: null
+    log_config: []
+    name: psc
+    network: my-network
+    params: []
+    project: test-alloydb
+    purpose: PRIVATE_SERVICE_CONNECT
+    region: europe-west8
+    reserved_internal_range: null
+    resolve_subnet_mask: null
+    role: null
+    send_secondary_ip_range_if_empty: null
+    timeouts: null
+  module.vpc.google_service_networking_connection.psa_connection["servicenetworking.googleapis.com"]:
+    deletion_policy: null
+    reserved_peering_ranges:
+    - servicenetworking-googleapis-com-alloydb
+    service: servicenetworking.googleapis.com
+    timeouts: null
+    update_on_creation_fail: null
+
+counts:
+  google_alloydb_cluster: 1
+  google_alloydb_instance: 2
+  google_compute_global_address: 1
+  google_compute_network_peering_routes_config: 1
+  google_compute_network: 1
+  google_compute_route: 3
+  google_compute_subnetwork: 1
+  google_project_iam_member: 2
+  google_project_service_identity: 2
+  google_project_service: 3
+  google_project: 1
+  google_service_networking_connection: 1
+  modules: 3
+  resources: 19
+
+outputs: {}