terraform-google-alloy-db

This module handles Google Cloud Platform AlloyDB cluster creation and configuration with Automated Backup Policy, Primary node instance and Read Node Pools. The resource/resources that this module will create are:

• Creates an AlloyDB Cluster with/without automated backup policy
• Creates a Primary Instance
• Creates a pool of Read Instances

You can also create Cross Region Replica using this module. See example in cross_region_replica

Compatibility

This module is meant for use with Terraform 1.3+ and tested using Terraform 1.3+. If you find incompatibilities using Terraform >=1.3, please open an issue.

Version

Current version is 2.X. Upgrade guides:

• 0.1 -> 0.2
• 0.2 -> 1.0
• 1.X -> 2.0
• 2.X -> 3.0
• 3.X -> 4.0

Usage

• Functional examples are included in the examples directory.
• If you want to create a cluster with failover replicas and manage complete lifecycle (including failover and switchover) of primary and DR clusters using this module, follow the example in simple_example folder.
• If you are planning to create cluster/instance with private service connect follow example in private_service_connect.

Basic usage of this module is as follows:

module "alloy-db" {
  source               = "GoogleCloudPlatform/alloy-db/google"
  version              = "~> 4.0"

  project_id           = <"PROJECT_ID">
  cluster_id           = "alloydb-cluster"
  location             = "us-central1"
  cluster_initial_user = {
    user     = "<USER_NAME>"
    password = "<PASSWORD>"
  }
  network_self_link = "projects/${project_id}/global/networks/${network_name}"

  primary_instance = {
    instance_id = "primary-instance"
  }
}

• Usage of this module for creating a AlloyDB Cluster with the automated backup policy, a primary instance, zonal and regional read replica instances:

module "alloy-db" {
  source               = "GoogleCloudPlatform/alloy-db/google"
  version              = "~> 4.0"

  project_id           = <PROJECT_ID>
  cluster_id           = "alloydb-cluster-with-primary-instance"
  location             = "us-central1"
  cluster_display_name = "cluster-1"
  cluster_initial_user = {
    user     = "<USER_NAME>"
    password = "<PASSWORD>"
  }
  network_self_link = "projects/${project_id}/global/networks/${network_name}"

  automated_backup_policy = {
    location      = "us-central1"
    backup_window = "1800s"
    enabled       = true
    weekly_schedule = {
      days_of_week = ["FRIDAY"]
      start_times  = ["2:00:00:00"]
    }
    quantity_based_retention_count = 1
    labels = {
      test = "alloydb-cluster"
    }
  }
  primary_instance = null

  read_pool_instance = null

}

• Usage of this module for creating a AlloyDB Cluster with a primary instance and a read replica instance

module "alloy-db" {
  source               = "GoogleCloudPlatform/alloy-db/google"
  version              = "~> 4.0"
  project_id           = <PROJECT_ID>
  cluster_id           = "alloydb-cluster-with-primary-instance"
  location             = "us-central1"
  cluster_labels       = {}
  cluster_display_name = ""
  cluster_initial_user = {
    user     = "<USER_NAME>",
    password = "<PASSWORD>"
  }
  network_self_link = "projects/${project_id}/global/networks/${network_name}"

  automated_backup_policy = null

  primary_instance = {
    instance_id       = "primary-instance"
    instance_type     = "PRIMARY"
    machine_cpu_count = 2
    display_name      = "alloydb-primary-instance"
  }

  read_pool_instance = [
    {
      instance_id        = "cluster-1-rr-1"
      display_name       = "cluster-1-rr-1"
      node_count         = 1 # automatically zonal
      require_connectors = false
      ssl_mode           = "ALLOW_UNENCRYPTED_AND_ENCRYPTED"
    },
    {
      instance_id        = "cluster-1-rr-2"
      display_name       = "cluster-1-rr-2"
      node_count         = 2 # automatically regional
      require_connectors = false
      ssl_mode           = "ALLOW_UNENCRYPTED_AND_ENCRYPTED"
    }
  ]
}

Inputs

Name	Description	Type	Default	Required
allocated_ip_range	The name of the allocated IP range for the private IP AlloyDB cluster. For example: google-managed-services-default. If set, the instance IPs for this cluster will be created in the allocated range	string	null	no
automated_backup_policy	The automated backup policy for this cluster. If no policy is provided then the default policy will be used. The default policy takes one backup a day, has a backup window of 1 hour, and retains backups for 14 days	object({ location = optional(string) backup_window = optional(string) enabled = optional(bool) weekly_schedule = optional(object({ days_of_week = optional(list(string)) start_times = list(string) })), quantity_based_retention_count = optional(number) time_based_retention_count = optional(string) labels = optional(map(string)) backup_encryption_key_name = optional(string) })	null	no
cluster_display_name	Human readable display name for the Alloy DB Cluster	string	null	no
cluster_encryption_key_name	The fully-qualified resource name of the KMS key for cluster encryption. Each Cloud KMS key is regionalized and has the following format: projects/[PROJECT]/locations/[REGION]/keyRings/[RING]/cryptoKeys/[KEY_NAME]	string	null	no
cluster_id	The ID of the alloydb cluster	string	n/a	yes
cluster_initial_user	Alloy DB Cluster Initial User Credentials	object({ user = optional(string), password = string })	null	no
cluster_labels	User-defined labels for the alloydb cluster	map(string)	{}	no
cluster_type	The type of cluster. If not set, defaults to PRIMARY. Default value is PRIMARY. Possible values are: PRIMARY, SECONDARY	string	"PRIMARY"	no
continuous_backup_enable	Whether continuous backup recovery is enabled. If not set, defaults to true	bool	true	no
continuous_backup_encryption_key_name	The fully-qualified resource name of the KMS key. Cloud KMS key should be in same region as Cluster and has the following format: projects/[PROJECT]/locations/[REGION]/keyRings/[RING]/cryptoKeys/[KEY_NAME]	string	null	no
continuous_backup_recovery_window_days	The numbers of days that are eligible to restore from using PITR (point-in-time-recovery). Defaults to 14 days. The value must be between 1 and 35	number	14	no
database_version	The database engine major version. This is an optional field and it's populated at the Cluster creation time. This field cannot be changed after cluster creation. Possible valus: POSTGRES_14, POSTGRES_15	string	null	no
deletion_policy	Policy to determine if the cluster should be deleted forcefully. Deleting a cluster forcefully, deletes the cluster and all its associated instances within the cluster	string	null	no
location	Location where AlloyDb cluster will be deployed	string	n/a	yes
maintenance_update_policy	defines the policy for system updates	object({ maintenance_windows = object({ day = string start_time = object({ hours = number }) }) })	null	no
network_attachment_resource	The network attachment resource created in the consumer project to which the PSC interface will be linked. Needed for AllloyDB outbound connectivity. This is of the format: projects/{CONSUMER_PROJECT}/regions/{REGION}/networkAttachments/{NETWORK_ATTACHMENT_NAME}. The network attachment must be in the same region as the instance	string	null	no
network_self_link	Network ID where the AlloyDb cluster will be deployed. If network_self_link is set then psc_enabled should be set to false. The resource link should point to a VPC network in the same project as the cluster, where the cluster resources are created and accessed via Private IP. Any network used, including the default network (if none is specified), must have VPC peering enabled. Learn more at https://cloud.google.com/alloydb/docs/configure-connectivity	string	null	no
primary_cluster_name	Primary cluster name. Required for creating cross region secondary cluster. Not needed for primary cluster	string	null	no
primary_instance	Configure primary instance. Every AlloyDB cluster has one primary instance, providing a read or write access point to your data. See https://cloud.google.com/alloydb/docs/reference/rest/v1/projects.locations.clusters.instances for more details.	object({ instance_id = string, display_name = optional(string), database_flags = optional(map(string)) labels = optional(map(string)) annotations = optional(map(string)) gce_zone = optional(string) availability_type = optional(string) machine_cpu_count = optional(number, 2) machine_type = optional(string) ssl_mode = optional(string) require_connectors = optional(bool) query_insights_config = optional(object({ query_string_length = optional(number) record_application_tags = optional(bool) record_client_address = optional(bool) query_plans_per_minute = optional(number) })) enable_public_ip = optional(bool, false) enable_outbound_public_ip = optional(bool, false) cidr_range = optional(list(string)) })	n/a	yes
project_id	The ID of the project in which to provision resources.	string	n/a	yes
psc_allowed_consumer_projects	List of consumer projects that are allowed to create PSC endpoints to service-attachments to this instance. These should be specified as project numbers only.	list(string)	[]	no
psc_auto_connections	List of PSC auto connections. Each connection specifies the consumer network and project for automatic PSC endpoint creation.	list(object({ consumer_network = string consumer_project = string }))	[]	no
psc_enabled	Create an instance that allows connections from Private Service Connect endpoints to the instance. If psc_enabled is set to true, then network_self_link should be set to null, and you must create additional network resources detailed under examples/example_with_private_service_connect	bool	false	no
read_pool_instance	List of Read Pool Instances to be created	list(object({ instance_id = string display_name = string node_count = optional(number, 1) database_flags = optional(map(string)) machine_cpu_count = optional(number, 2) machine_type = optional(string) ssl_mode = optional(string) require_connectors = optional(bool) query_insights_config = optional(object({ query_string_length = optional(number) record_application_tags = optional(bool) record_client_address = optional(bool) query_plans_per_minute = optional(number) })) enable_public_ip = optional(bool, false) cidr_range = optional(list(string)) }))	[]	no
restore_cluster	restore cluster from a backup source. Only one of restore_backup_source or restore_continuous_backup_source should be set	object({ restore_backup_source = optional(object({ backup_name = string })) restore_continuous_backup_source = optional(object({ cluster = string point_in_time = string })) })	null	no
skip_await_major_version_upgrade	Set to true to skip awaiting on the major version upgrade of the cluster. Possible values: true, false. Default value: true	bool	true	no
subscription_type	The subscription type of cluster. Possible values are: TRIAL, STANDARD	string	"STANDARD"	no

Outputs

Name	Description
cluster	Cluster created
cluster_id	ID of the Alloy DB Cluster created
cluster_name	ID of the Alloy DB Cluster created
env_vars	Exported environment variables
primary_instance	Primary instance created
primary_instance_id	ID of the primary instance created
primary_instance_ip	The IP address of the primary AlloyDB instance
primary_psc_attachment_link	The private service connect (psc) attachment created for primary instance
primary_psc_dns_name	The DNS name of the instance for PSC connectivity created for primary instance
read_instance_ids	IDs of the read instances created
read_instance_ips	Replica IPs
read_psc_attachment_links	The private service connect (psc) attachment created read replica instances
read_psc_dns_names	The DNS names of the instances for PSC connectivity created for replica instances
replica_instances	Replica instances created

Requirements

These sections describe requirements for using this module.

Software

The following dependencies must be available:

• Terraform v1.3
• Terraform Provider for GCP plugin >= v6.26+

Service Account

A service account with the following roles must be used to provision the resources of this module:

• Cloud AlloyDB Admin: roles/alloydb.admin

APIs

A project with the following APIs enabled must be used to host the resources of this module:

• alloydb.googleapis.com

Contributing

Refer to the contribution guidelines for information on contributing to this module.

Security Disclosures

Please see our security disclosure process.