clusters

Creates, updates, deletes, gets or lists a clusters resource.

Overview

Name	clusters
Type	Resource
Id	google.alloydb.clusters

Fields

The following fields are returned by SELECT queries:

get

Successful response

Name	Datatype	Description
name	string	Output only. The name of the cluster resource with the format: * projects/{project}/locations/{region}/clusters/{cluster_id} where the cluster ID segment should satisfy the regex expression [a-z0-9-]+. For more details see https://google.aip.dev/122. The prefix of the cluster resource name is the name of the parent resource: * projects/{project}/locations/{region}
annotations	object	Annotations to allow client tools to store small amount of arbitrary data. This is distinct from labels. https://google.aip.dev/128
automatedBackupPolicy	object	The automated backup policy for this cluster. If no policy is provided then the default policy will be used. If backups are supported for the cluster, the default policy takes one backup a day, has a backup window of 1 hour, and retains backups for 14 days. For more information on the defaults, consult the documentation for the message type. (id: AutomatedBackupPolicy)
backupSource	object	Output only. Cluster created from backup. (id: BackupSource)
cloudsqlBackupRunSource	object	Output only. Cluster created from CloudSQL snapshot. (id: CloudSQLBackupRunSource)
clusterType	string	Output only. The type of the cluster. This is an output-only field and it's populated at the Cluster creation time or the Cluster promotion time. The cluster type is determined by which RPC was used to create the cluster (i.e. CreateCluster vs. CreateSecondaryCluster
continuousBackupConfig	object	Optional. Continuous backup configuration for this cluster. (id: ContinuousBackupConfig)
continuousBackupInfo	object	Output only. Continuous backup properties for this cluster. (id: ContinuousBackupInfo)
createTime	string (google-datetime)	Output only. Create time stamp
databaseVersion	string	Optional. The database engine major version. This is an optional field and it is populated at the Cluster creation time. If a database version is not supplied at cluster creation time, then a default database version will be used.
deleteTime	string (google-datetime)	Output only. Delete time stamp
displayName	string	User-settable and human-readable display name for the Cluster.
encryptionConfig	object	Optional. The encryption config can be specified to encrypt the data disks and other persistent data resources of a cluster with a customer-managed encryption key (CMEK). When this field is not specified, the cluster will then use default encryption scheme to protect the user data. (id: EncryptionConfig)
encryptionInfo	object	Output only. The encryption information for the cluster. (id: EncryptionInfo)
etag	string	For Resource freshness validation (https://google.aip.dev/154)
initialUser	object	Input only. Initial user to setup during cluster creation. Required. If used in RestoreCluster this is ignored. (id: UserPassword)
labels	object	Labels as key value pairs
maintenanceSchedule	object	Output only. The maintenance schedule for the cluster, generated for a specific rollout if a maintenance window is set. (id: MaintenanceSchedule)
maintenanceUpdatePolicy	object	Optional. The maintenance update policy determines when to allow or deny updates. (id: MaintenanceUpdatePolicy)
migrationSource	object	Output only. Cluster created via DMS migration. (id: MigrationSource)
network	string	Required. 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/{project}/global/networks/{network_id}. This is required to create a cluster. Deprecated, use network_config.network instead.
networkConfig	object	Metadata related to network configuration. (id: NetworkConfig)
primaryConfig	object	Output only. Cross Region replication config specific to PRIMARY cluster. (id: PrimaryConfig)
pscConfig	object	Optional. The configuration for Private Service Connect (PSC) for the cluster. (id: PscConfig)
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.
satisfiesPzs	boolean	Output only. Reserved for future use.
secondaryConfig	object	Cross Region replication config specific to SECONDARY cluster. (id: SecondaryConfig)
sslConfig	object	SSL configuration for this AlloyDB cluster. (id: SslConfig)
state	string	Output only. The current serving state of the cluster.
subscriptionType	string	Optional. Subscription type of the cluster.
tags	object	Optional. Input only. Immutable. Tag keys/values directly bound to this resource. For example: "123/environment": "production", "123/costCenter": "marketing"
trialMetadata	object	Output only. Metadata for free trial clusters (id: TrialMetadata)
uid	string	Output only. The system-generated UID of the resource. The UID is assigned when the resource is created, and it is retained until it is deleted.
updateTime	string (google-datetime)	Output only. Update time stamp

list

Successful response

Name	Datatype	Description
name	string	Output only. The name of the cluster resource with the format: * projects/{project}/locations/{region}/clusters/{cluster_id} where the cluster ID segment should satisfy the regex expression [a-z0-9-]+. For more details see https://google.aip.dev/122. The prefix of the cluster resource name is the name of the parent resource: * projects/{project}/locations/{region}
annotations	object	Annotations to allow client tools to store small amount of arbitrary data. This is distinct from labels. https://google.aip.dev/128
automatedBackupPolicy	object	The automated backup policy for this cluster. If no policy is provided then the default policy will be used. If backups are supported for the cluster, the default policy takes one backup a day, has a backup window of 1 hour, and retains backups for 14 days. For more information on the defaults, consult the documentation for the message type. (id: AutomatedBackupPolicy)
backupSource	object	Output only. Cluster created from backup. (id: BackupSource)
cloudsqlBackupRunSource	object	Output only. Cluster created from CloudSQL snapshot. (id: CloudSQLBackupRunSource)
clusterType	string	Output only. The type of the cluster. This is an output-only field and it's populated at the Cluster creation time or the Cluster promotion time. The cluster type is determined by which RPC was used to create the cluster (i.e. CreateCluster vs. CreateSecondaryCluster
continuousBackupConfig	object	Optional. Continuous backup configuration for this cluster. (id: ContinuousBackupConfig)
continuousBackupInfo	object	Output only. Continuous backup properties for this cluster. (id: ContinuousBackupInfo)
createTime	string (google-datetime)	Output only. Create time stamp
databaseVersion	string	Optional. The database engine major version. This is an optional field and it is populated at the Cluster creation time. If a database version is not supplied at cluster creation time, then a default database version will be used.
deleteTime	string (google-datetime)	Output only. Delete time stamp
displayName	string	User-settable and human-readable display name for the Cluster.
encryptionConfig	object	Optional. The encryption config can be specified to encrypt the data disks and other persistent data resources of a cluster with a customer-managed encryption key (CMEK). When this field is not specified, the cluster will then use default encryption scheme to protect the user data. (id: EncryptionConfig)
encryptionInfo	object	Output only. The encryption information for the cluster. (id: EncryptionInfo)
etag	string	For Resource freshness validation (https://google.aip.dev/154)
initialUser	object	Input only. Initial user to setup during cluster creation. Required. If used in RestoreCluster this is ignored. (id: UserPassword)
labels	object	Labels as key value pairs
maintenanceSchedule	object	Output only. The maintenance schedule for the cluster, generated for a specific rollout if a maintenance window is set. (id: MaintenanceSchedule)
maintenanceUpdatePolicy	object	Optional. The maintenance update policy determines when to allow or deny updates. (id: MaintenanceUpdatePolicy)
migrationSource	object	Output only. Cluster created via DMS migration. (id: MigrationSource)
network	string	Required. 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/{project}/global/networks/{network_id}. This is required to create a cluster. Deprecated, use network_config.network instead.
networkConfig	object	Metadata related to network configuration. (id: NetworkConfig)
primaryConfig	object	Output only. Cross Region replication config specific to PRIMARY cluster. (id: PrimaryConfig)
pscConfig	object	Optional. The configuration for Private Service Connect (PSC) for the cluster. (id: PscConfig)
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.
satisfiesPzs	boolean	Output only. Reserved for future use.
secondaryConfig	object	Cross Region replication config specific to SECONDARY cluster. (id: SecondaryConfig)
sslConfig	object	SSL configuration for this AlloyDB cluster. (id: SslConfig)
state	string	Output only. The current serving state of the cluster.
subscriptionType	string	Optional. Subscription type of the cluster.
tags	object	Optional. Input only. Immutable. Tag keys/values directly bound to this resource. For example: "123/environment": "production", "123/costCenter": "marketing"
trialMetadata	object	Output only. Metadata for free trial clusters (id: TrialMetadata)
uid	string	Output only. The system-generated UID of the resource. The UID is assigned when the resource is created, and it is retained until it is deleted.
updateTime	string (google-datetime)	Output only. Update time stamp

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	projectsId, locationsId, clustersId	view	Gets details of a single Cluster.
list	select	projectsId, locationsId	pageSize, pageToken, filter, orderBy	Lists Clusters in a given project and location.
create	insert	projectsId, locationsId	clusterId, requestId, validateOnly	Creates a new Cluster in a given project and location.
patch	update	projectsId, locationsId, clustersId	updateMask, requestId, validateOnly, allowMissing	Updates the parameters of a single Cluster.
delete	delete	projectsId, locationsId, clustersId	requestId, etag, validateOnly, force	Deletes a single Cluster.
restore_from_cloud_sql	exec	projectsId, locationsId		Restores an AlloyDB cluster from a CloudSQL resource.
export	exec	projectsId, locationsId, clustersId		Exports data from the cluster. Imperative only.
import	exec	projectsId, locationsId, clustersId		Imports data to the cluster. Imperative only.
upgrade	exec	projectsId, locationsId, clustersId		Upgrades a single Cluster. Imperative only.
promote	exec	projectsId, locationsId, clustersId		Promotes a SECONDARY cluster. This turns down replication from the PRIMARY cluster and promotes a secondary cluster into its own standalone cluster. Imperative only.
switchover	exec	projectsId, locationsId, clustersId		Switches the roles of PRIMARY and SECONDARY clusters without any data loss. This promotes the SECONDARY cluster to PRIMARY and sets up the original PRIMARY cluster to replicate from this newly promoted cluster.
restore	exec	projectsId, locationsId		Creates a new Cluster in a given project and location, with a volume restored from the provided source, either a backup ID or a point-in-time and a source cluster.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
clustersId	string
locationsId	string
projectsId	string
allowMissing	boolean
clusterId	string
etag	string
filter	string
force	boolean
orderBy	string
pageSize	integer (int32)
pageToken	string
requestId	string
updateMask	string (google-fieldmask)
validateOnly	boolean
view	string

SELECT examples

get

Gets details of a single Cluster.

SELECT
name,
annotations,
automatedBackupPolicy,
backupSource,
cloudsqlBackupRunSource,
clusterType,
continuousBackupConfig,
continuousBackupInfo,
createTime,
databaseVersion,
deleteTime,
displayName,
encryptionConfig,
encryptionInfo,
etag,
initialUser,
labels,
maintenanceSchedule,
maintenanceUpdatePolicy,
migrationSource,
network,
networkConfig,
primaryConfig,
pscConfig,
reconciling,
satisfiesPzs,
secondaryConfig,
sslConfig,
state,
subscriptionType,
tags,
trialMetadata,
uid,
updateTime
FROM google.alloydb.clusters
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND clustersId = '{{ clustersId }}' -- required
AND view = '{{ view }}';

list

Lists Clusters in a given project and location.

SELECT
name,
annotations,
automatedBackupPolicy,
backupSource,
cloudsqlBackupRunSource,
clusterType,
continuousBackupConfig,
continuousBackupInfo,
createTime,
databaseVersion,
deleteTime,
displayName,
encryptionConfig,
encryptionInfo,
etag,
initialUser,
labels,
maintenanceSchedule,
maintenanceUpdatePolicy,
migrationSource,
network,
networkConfig,
primaryConfig,
pscConfig,
reconciling,
satisfiesPzs,
secondaryConfig,
sslConfig,
state,
subscriptionType,
tags,
trialMetadata,
uid,
updateTime
FROM google.alloydb.clusters
WHERE projectsId = '{{ projectsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}'
AND filter = '{{ filter }}'
AND orderBy = '{{ orderBy }}';

INSERT examples

create

Creates a new Cluster in a given project and location.

INSERT INTO google.alloydb.clusters (
data__displayName,
data__labels,
data__databaseVersion,
data__networkConfig,
data__network,
data__etag,
data__annotations,
data__initialUser,
data__automatedBackupPolicy,
data__sslConfig,
data__encryptionConfig,
data__continuousBackupConfig,
data__secondaryConfig,
data__pscConfig,
data__maintenanceUpdatePolicy,
data__subscriptionType,
data__tags,
projectsId,
locationsId,
clusterId,
requestId,
validateOnly
)
SELECT 
'{{ displayName }}',
'{{ labels }}',
'{{ databaseVersion }}',
'{{ networkConfig }}',
'{{ network }}',
'{{ etag }}',
'{{ annotations }}',
'{{ initialUser }}',
'{{ automatedBackupPolicy }}',
'{{ sslConfig }}',
'{{ encryptionConfig }}',
'{{ continuousBackupConfig }}',
'{{ secondaryConfig }}',
'{{ pscConfig }}',
'{{ maintenanceUpdatePolicy }}',
'{{ subscriptionType }}',
'{{ tags }}',
'{{ projectsId }}',
'{{ locationsId }}',
'{{ clusterId }}',
'{{ requestId }}',
'{{ validateOnly }}'
RETURNING
name,
done,
error,
metadata,
response
;

Manifest

# Description fields are for documentation purposes
- name: clusters
  props:
    - name: projectsId
      value: string
      description: Required parameter for the clusters resource.
    - name: locationsId
      value: string
      description: Required parameter for the clusters resource.
    - name: displayName
      value: string
      description: >
        User-settable and human-readable display name for the Cluster.
        
    - name: labels
      value: object
      description: >
        Labels as key value pairs
        
    - name: databaseVersion
      value: string
      description: >
        Optional. The database engine major version. This is an optional field and it is populated at the Cluster creation time. If a database version is not supplied at cluster creation time, then a default database version will be used.
        
      valid_values: ['DATABASE_VERSION_UNSPECIFIED', 'POSTGRES_13', 'POSTGRES_14', 'POSTGRES_15', 'POSTGRES_16']
    - name: networkConfig
      value: object
      description: >
        Metadata related to network configuration.
        
    - name: network
      value: string
      description: >
        Required. 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/{project}/global/networks/{network_id}`. This is required to create a cluster. Deprecated, use network_config.network instead.
        
    - name: etag
      value: string
      description: >
        For Resource freshness validation (https://google.aip.dev/154)
        
    - name: annotations
      value: object
      description: >
        Annotations to allow client tools to store small amount of arbitrary data. This is distinct from labels. https://google.aip.dev/128
        
    - name: initialUser
      value: object
      description: >
        Input only. Initial user to setup during cluster creation. Required. If used in `RestoreCluster` this is ignored.
        
    - name: automatedBackupPolicy
      value: object
      description: >
        The automated backup policy for this cluster. If no policy is provided then the default policy will be used. If backups are supported for the cluster, the default policy takes one backup a day, has a backup window of 1 hour, and retains backups for 14 days. For more information on the defaults, consult the documentation for the message type.
        
    - name: sslConfig
      value: object
      description: >
        SSL configuration for this AlloyDB cluster.
        
    - name: encryptionConfig
      value: object
      description: >
        Optional. The encryption config can be specified to encrypt the data disks and other persistent data resources of a cluster with a customer-managed encryption key (CMEK). When this field is not specified, the cluster will then use default encryption scheme to protect the user data.
        
    - name: continuousBackupConfig
      value: object
      description: >
        Optional. Continuous backup configuration for this cluster.
        
    - name: secondaryConfig
      value: object
      description: >
        Cross Region replication config specific to SECONDARY cluster.
        
    - name: pscConfig
      value: object
      description: >
        Optional. The configuration for Private Service Connect (PSC) for the cluster.
        
    - name: maintenanceUpdatePolicy
      value: object
      description: >
        Optional. The maintenance update policy determines when to allow or deny updates.
        
    - name: subscriptionType
      value: string
      description: >
        Optional. Subscription type of the cluster.
        
      valid_values: ['SUBSCRIPTION_TYPE_UNSPECIFIED', 'STANDARD', 'TRIAL']
    - name: tags
      value: object
      description: >
        Optional. Input only. Immutable. Tag keys/values directly bound to this resource. For example: ``` "123/environment": "production", "123/costCenter": "marketing" ```
        
    - name: clusterId
      value: string
    - name: requestId
      value: string
    - name: validateOnly
      value: boolean

UPDATE examples

patch

Updates the parameters of a single Cluster.

UPDATE google.alloydb.clusters
SET 
data__displayName = '{{ displayName }}',
data__labels = '{{ labels }}',
data__databaseVersion = '{{ databaseVersion }}',
data__networkConfig = '{{ networkConfig }}',
data__network = '{{ network }}',
data__etag = '{{ etag }}',
data__annotations = '{{ annotations }}',
data__initialUser = '{{ initialUser }}',
data__automatedBackupPolicy = '{{ automatedBackupPolicy }}',
data__sslConfig = '{{ sslConfig }}',
data__encryptionConfig = '{{ encryptionConfig }}',
data__continuousBackupConfig = '{{ continuousBackupConfig }}',
data__secondaryConfig = '{{ secondaryConfig }}',
data__pscConfig = '{{ pscConfig }}',
data__maintenanceUpdatePolicy = '{{ maintenanceUpdatePolicy }}',
data__subscriptionType = '{{ subscriptionType }}',
data__tags = '{{ tags }}'
WHERE 
projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND clustersId = '{{ clustersId }}' --required
AND updateMask = '{{ updateMask}}'
AND requestId = '{{ requestId}}'
AND validateOnly = {{ validateOnly}}
AND allowMissing = {{ allowMissing}}
RETURNING
name,
done,
error,
metadata,
response;

DELETE examples

delete

Deletes a single Cluster.

DELETE FROM google.alloydb.clusters
WHERE projectsId = '{{ projectsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND clustersId = '{{ clustersId }}' --required
AND requestId = '{{ requestId }}'
AND etag = '{{ etag }}'
AND validateOnly = '{{ validateOnly }}'
AND force = '{{ force }}';

Lifecycle Methods

restore_from_cloud_sql

Restores an AlloyDB cluster from a CloudSQL resource.

EXEC google.alloydb.clusters.restore_from_cloud_sql 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required 
@@json=
'{
"cloudsqlBackupRunSource": "{{ cloudsqlBackupRunSource }}", 
"clusterId": "{{ clusterId }}", 
"cluster": "{{ cluster }}"
}';

export

Exports data from the cluster. Imperative only.

EXEC google.alloydb.clusters.export 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@clustersId='{{ clustersId }}' --required 
@@json=
'{
"gcsDestination": "{{ gcsDestination }}", 
"csvExportOptions": "{{ csvExportOptions }}", 
"sqlExportOptions": "{{ sqlExportOptions }}", 
"database": "{{ database }}"
}';

import

Imports data to the cluster. Imperative only.

EXEC google.alloydb.clusters.import 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@clustersId='{{ clustersId }}' --required 
@@json=
'{
"sqlImportOptions": "{{ sqlImportOptions }}", 
"csvImportOptions": "{{ csvImportOptions }}", 
"gcsUri": "{{ gcsUri }}", 
"database": "{{ database }}", 
"user": "{{ user }}"
}';

upgrade

Upgrades a single Cluster. Imperative only.

EXEC google.alloydb.clusters.upgrade 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@clustersId='{{ clustersId }}' --required 
@@json=
'{
"version": "{{ version }}", 
"requestId": "{{ requestId }}", 
"validateOnly": {{ validateOnly }}, 
"etag": "{{ etag }}"
}';

promote

Promotes a SECONDARY cluster. This turns down replication from the PRIMARY cluster and promotes a secondary cluster into its own standalone cluster. Imperative only.

EXEC google.alloydb.clusters.promote 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@clustersId='{{ clustersId }}' --required 
@@json=
'{
"requestId": "{{ requestId }}", 
"etag": "{{ etag }}", 
"validateOnly": {{ validateOnly }}
}';

switchover

Switches the roles of PRIMARY and SECONDARY clusters without any data loss. This promotes the SECONDARY cluster to PRIMARY and sets up the original PRIMARY cluster to replicate from this newly promoted cluster.

EXEC google.alloydb.clusters.switchover 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required, 
@clustersId='{{ clustersId }}' --required 
@@json=
'{
"requestId": "{{ requestId }}", 
"validateOnly": {{ validateOnly }}
}';

restore

Creates a new Cluster in a given project and location, with a volume restored from the provided source, either a backup ID or a point-in-time and a source cluster.

EXEC google.alloydb.clusters.restore 
@projectsId='{{ projectsId }}' --required, 
@locationsId='{{ locationsId }}' --required 
@@json=
'{
"backupSource": "{{ backupSource }}", 
"continuousBackupSource": "{{ continuousBackupSource }}", 
"clusterId": "{{ clusterId }}", 
"cluster": "{{ cluster }}", 
"requestId": "{{ requestId }}", 
"validateOnly": {{ validateOnly }}
}';