google.cloud.gcp_alloydb_cluster module – Creates a GCP Alloydb.Cluster resource

Note

This module is part of the google.cloud collection (version 1.13.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install google.cloud. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: google.cloud.gcp_alloydb_cluster.

Synopsis
Requirements
Parameters
Notes
Examples
Return Values

Synopsis

A managed alloydb cluster.

Requirements

The below requirements are needed on the host that executes this module.

python >= 3.8
requests >= 2.18.4
google-auth >= 2.25.1

Parameters

Parameter	Comments
access_token string	The access token used to authenticate.
annotations dictionary	Annotations to allow client tools to store small amount of arbitrary data. This is distinct from labels. https://google.aip.dev/128 An object containing a list of “key”: value pairs. Example: { “name”: “wrench”, “mass”: “1.3kg”, “count”: “3” }.
auth_kind string / required	The type of credential used. Choices: `"accesstoken"` `"application"` `"machineaccount"` `"serviceaccount"`
automated_backup_policy dictionary	The automated backup policy for this cluster. AutomatedBackupPolicy is disabled by default.
backup_window string	The length of the time window during which a backup can be taken. If a backup does not succeed within this time window, it will be canceled and considered failed. The backup window must be at least 5 minutes long. There is no upper bound on the window. If not set, it will default to 1 hour. A duration in seconds with up to nine fractional digits, terminated by ‘s’. Example: “3.5s”.
enabled boolean	Whether automated backups are enabled. Choices: `false` `true`
encryption_config dictionary	EncryptionConfig describes the encryption config of a cluster or a backup that is encrypted with a CMEK (customer-managed encryption key).
kms_key_name string	The fully-qualified resource name of the KMS key. Each Cloud KMS key is regionalized and has the following format: projects/[PROJECT]/locations/[REGION]/keyRings/[RING]/cryptoKeys/[KEY_NAME].
labels dictionary	Labels to apply to backups created using this configuration.
location string	The location where the backup will be stored. Currently, the only supported option is to store the backup in the same region as the cluster.
quantity_based_retention dictionary	Quantity-based Backup retention policy to retain recent backups. Conflicts with ‘time_based_retention’, both can’t be set together.
count integer	The number of backups to retain.
time_based_retention dictionary	Time-based Backup retention policy. Conflicts with ‘quantity_based_retention’, both can’t be set together.
retention_period string	The retention period. A duration in seconds with up to nine fractional digits, terminated by ‘s’. Example: “3.5s”.
weekly_schedule dictionary	Weekly schedule for the Backup.
days_of_week list / elements=string	The days of the week to perform a backup. At least one day of the week must be provided.
start_times list / elements=dictionary / required	The times during the day to start a backup. At least one start time must be provided. The start times are assumed to be in UTC and to be an exact hour (e.g., 04:00:00).
hours integer	Hours of day in 24 hour format. Should be from 0 to 23. An API may choose to allow the value “24:00:00” for scenarios like business closing time.
minutes integer	Minutes of hour of day. Currently, only the value 0 is supported.
nanos integer	Fractions of seconds in nanoseconds. Currently, only the value 0 is supported.
seconds integer	Seconds of minutes of the time. Currently, only the value 0 is supported.
cluster_id string / required	The ID of the alloydb cluster.
cluster_type string	The type of cluster. If not set, defaults to PRIMARY. Choices: `"PRIMARY"` ← (default) `"SECONDARY"`
continuous_backup_config dictionary	The continuous backup config for this cluster. If no policy is provided then the default policy will be used. The default policy takes one backup a day and retains backups for 14 days.
enabled boolean	Whether continuous backup recovery is enabled. If not set, defaults to true. Choices: `false` `true` ← (default)
encryption_config dictionary	EncryptionConfig describes the encryption config of a cluster or a backup that is encrypted with a CMEK (customer-managed encryption key).
kms_key_name string	The fully-qualified resource name of the KMS key. Each Cloud KMS key is regionalized and has the following format: projects/[PROJECT]/locations/[REGION]/keyRings/[RING]/cryptoKeys/[KEY_NAME].
recovery_window_days integer	The numbers of days that are eligible to restore from using PITR. To support the entire recovery window, backups and logs are retained for one day more than the recovery window. If not set, defaults to 14 days.
database_version string	The database engine major version. This is an optional field and it’s populated at the Cluster creation time. Note: Changing this field to a higer version results in upgrading the AlloyDB cluster which is an irreversible change.
display_name string	User-settable and human-readable display name for the Cluster.
encryption_config dictionary	EncryptionConfig describes the encryption config of a cluster or a backup that is encrypted with a CMEK (customer-managed encryption key).
kms_key_name string	The fully-qualified resource name of the KMS key. Each Cloud KMS key is regionalized and has the following format: projects/[PROJECT]/locations/[REGION]/keyRings/[RING]/cryptoKeys/[KEY_NAME].
env_type string	Specifies which Ansible environment you’re running this module within. This should not be set unless you know what you’re doing. This only alters the User Agent string for any API requests.
etag string	For Resource freshness validation (https://google.aip.dev/154).
initial_user dictionary	Initial user to setup during cluster creation.
password string / required	The initial password for the user.
user string	The database username.
labels dictionary	User-defined labels for the alloydb cluster.
location string / required	The location where the alloydb cluster should reside.
maintenance_update_policy dictionary	MaintenanceUpdatePolicy defines the policy for system updates.
maintenance_windows list / elements=dictionary	Preferred windows to perform maintenance. Currently limited to 1.
day string / required	Preferred day of the week for maintenance, e.g. MONDAY, TUESDAY, etc. Choices: `"MONDAY"` `"TUESDAY"` `"WEDNESDAY"` `"THURSDAY"` `"FRIDAY"` `"SATURDAY"` `"SUNDAY"`
start_time dictionary / required	Preferred time to start the maintenance operation on the specified day. Maintenance will start within 1 hour of this time.
hours integer / required	Hours of day in 24 hour format. Should be from 0 to 23.
minutes integer	Minutes of hour of day. Currently, only the value 0 is supported.
nanos integer	Fractions of seconds in nanoseconds. Currently, only the value 0 is supported.
seconds integer	Seconds of minutes of the time. Currently, only the value 0 is supported.
network_config dictionary	Metadata related to network configuration.
allocated_ip_range string	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.
network string	The resource link for the VPC network in which cluster resources are created and from which they are accessible via Private IP. The network must belong to the same project as the cluster. It is specified in the form: “projects/{projectNumber}/global/networks/{network_id}”.
project string	The Google Cloud Platform project to use.
psc_config dictionary	Configuration for Private Service Connect (PSC) for the cluster.
psc_enabled boolean	Create an instance that allows connections from Private Service Connect endpoints to the instance. Choices: `false` `true`
service_owned_project_number integer	The project number that needs to be allowlisted on the network attachment to enable outbound connectivity, if the network attachment is configured to ACCEPT_MANUAL connections. In case the network attachment is configured to ACCEPT_AUTOMATIC, this project number does not need to be allowlisted explicitly.
restore_backup_source dictionary	The source when restoring from a backup. Conflicts with ‘restore_continuous_backup_source’, both can’t be set together.
backup_name string / required	The name of the backup that this cluster is restored from.
restore_continuous_backup_source dictionary	The source when restoring via point in time recovery (PITR). Conflicts with ‘restore_backup_source’, both can’t be set together.
cluster string / required	The name of the source cluster that this cluster is restored from.
point_in_time string / required	The point in time that this cluster is restored to, in RFC 3339 format.
scopes list / elements=string	Array of scopes to be used.
secondary_config dictionary	Configuration of the secondary cluster for Cross Region Replication. This should be set if and only if the cluster is of type SECONDARY.
primary_cluster_name string / required	Name of the primary cluster must be in the format ‘projects/{project}/locations/{location}/clusters/{cluster_id}’.
service_account_contents jsonarg	The contents of a Service Account JSON file, either in a dictionary or as a JSON string that represents it.
service_account_email string	An optional service account email address if machineaccount is selected and the user does not wish to use the default email.
service_account_file path	The path of a Service Account JSON file if serviceaccount is selected as type.
state string	Whether the resource should exist in GCP. Choices: `"present"` ← (default) `"absent"`
subscription_type string	The subscrition type of cluster. Choices: `"TRIAL"` `"STANDARD"`

Notes

Note

API Reference: https://cloud.google.com/alloydb/docs/reference/rest/v1/projects.locations.clusters/create
AlloyDB Guide: https://cloud.google.com/alloydb/docs/
For authentication, you can set auth_kind using the GCP_AUTH_KIND env variable.
For authentication, you can set service_account_file using the GCP_SERVICE_ACCOUNT_FILE env variable.
For authentication, you can set service_account_contents using the GCP_SERVICE_ACCOUNT_CONTENTS env variable.
For authentication, you can set service_account_email using the GCP_SERVICE_ACCOUNT_EMAIL env variable.
For authentication, you can set access_token using the GCP_ACCESS_TOKEN env variable.
For authentication, you can set scopes using the GCP_SCOPES env variable.
Environment variables values will only be used if the playbook values are not set.
The service_account_email, service_account_file, service_account_file and access_token options are mutually exclusive.

Examples

- name: Create basic alloydb cluster
  google.cloud.gcp_alloydb_cluster:
    cluster_id: "{{ resource_name }}"
    state: present
    location: us-central1
    network_config:
      network: "projects/{{ gcp_project_number }}/global/networks/{{ resource_name }}"
    initial_user:
      user: pgroot
      password: Test123Test
    project: "{{ gcp_project }}"
    auth_kind: "{{ gcp_cred_kind }}"
    service_account_file: "{{ gcp_cred_file }}"

################################################################################

- name: Create primary alloydb cluster
  google.cloud.gcp_alloydb_cluster:
    cluster_id: "{{ resource_name }}-primary"
    state: present
    location: us-central1
    cluster_type: PRIMARY
    network_config:
      network: "projects/{{ gcp_project }}/global/networks/default"
    project: "{{ gcp_project }}"
    auth_kind: "{{ gcp_cred_kind }}"
    service_account_file: "{{ gcp_cred_file }}"
  register: _primary

- name: Create secondary cluster attached to primary
  google.cloud.gcp_alloydb_cluster:
    cluster_id: "{{ resource_name }}-secondary"
    state: present
    location: us-central1
    cluster_type: SECONDARY
    network_config:
      network: "projects/{{ gcp_project }}/global/networks/default"
    secondary_config:
      primary_cluster_name: "{{ _primary.name }}"
    project: "{{ gcp_project }}"
    auth_kind: "{{ gcp_cred_kind }}"
    service_account_file: "{{ gcp_cred_file }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
backupSource dictionary	Cluster created from backup. Returned: success
backupName string	The name of the backup resource. Returned: when set
changed boolean	Whether the resource was changed. Returned: always
continuousBackupInfo dictionary	ContinuousBackupInfo describes the continuous backup properties of a cluster. Returned: success
earliestRestorableTime string	The earliest restorable time that can be restored to. Output only field. Returned: success
enabledTime string	When ContinuousBackup was most recently enabled. Set to null if ContinuousBackup is not enabled. Returned: success
encryptionInfo dictionary	Output only. The encryption information for the WALs and backups required for ContinuousBackup. Returned: success
encryptionType string	Output only. Type of encryption. Returned: success
kmsKeyVersions list / elements=string	Output only. Cloud KMS key versions that are being used to protect the database or the backup. Returned: success
schedule list / elements=string	Days of the week on which a continuous backup is taken. Output only field. Ignored if passed into the request. Returned: success
encryptionInfo dictionary	EncryptionInfo describes the encryption information of a cluster or a backup. Returned: success
encryptionType string	Output only. Type of encryption. Returned: success
kmsKeyVersions list / elements=string	Output only. Cloud KMS key versions that are being used to protect the database or the backup. Returned: success
migrationSource dictionary	Cluster created via DMS migration. Returned: success
hostPort string	The host and port of the on-premises instance in host:port format. Returned: when set
referenceId string	Place holder for the external source identifier(e.g DMS job name) that created the cluster. Returned: when set
sourceType string	Type of migration source. Returned: when set
name string	The name of the cluster resource. Returned: success
reconciling boolean	Output only. Reconciling (https://google.aip.dev/128#reconciliation). Set to true if the current state of Cluster does not match the user’s intended state, and the service is actively updating the resource to reconcile them. This can happen due to user-triggered updates or system actions like failover or maintenance. Returned: success
state string	Output only. The current serving state of the cluster. Returned: success
trialMetadata dictionary	Contains information and all metadata related to TRIAL clusters. Returned: success
endTime string	End time of the trial cluster. Returned: when set
graceEndTime string	Grace end time of the trial cluster. Returned: when set
startTime string	Start time of the trial cluster. Returned: when set
upgradeTime string	Upgrade time of the trial cluster to standard cluster. Returned: when set
uid string	The system-generated UID of the resource. Returned: success

Authors

Google Inc. (@googlecloudplatform)

Collection links

© 2012–2018 Michael DeHaan
© 2018–2025 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/projects/ansible/latest/collections/google/cloud/gcp_alloydb_cluster_module.html