clusters

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

Overview

Name	clusters
Type	Resource
Id	aws.docdb_elastic.clusters

Fields

The following fields are returned by SELECT queries:

get_cluster

Name	Datatype	Description
admin_user_name	string	The name of the elastic cluster administrator.
auth_type	string	The authentication type for the elastic cluster. (PLAIN_TEXT, SECRET_ARN)
backup_retention_period	integer	The number of days for which automatic snapshots are retained.
cluster_arn	string	The ARN identifier of the elastic cluster.
cluster_endpoint	string	The URL used to connect to the elastic cluster.
cluster_name	string	The name of the elastic cluster.
create_time	string	The time when the elastic cluster was created in Universal Coordinated Time (UTC).
kms_key_id	string	The KMS key identifier to use to encrypt the elastic cluster.
preferred_backup_window	string	The daily time range during which automated backups are created if automated backups are enabled, as determined by backupRetentionPeriod.
preferred_maintenance_window	string	The weekly time range during which system maintenance can occur, in Universal Coordinated Time (UTC). Format: ddd:hh24:mi-ddd:hh24:mi
shard_capacity	integer	The number of vCPUs assigned to each elastic cluster shard. Maximum is 64. Allowed values are 2, 4, 8, 16, 32, 64.
shard_count	integer	The number of shards assigned to the elastic cluster. Maximum is 32.
shard_instance_count	integer	The number of replica instances applying to all shards in the cluster. A shardInstanceCount value of 1 means there is one writer instance, and any additional instances are replicas that can be used for reads and to improve availability.
shards	array	The total number of shards in the cluster.
status	string	The status of the elastic cluster. (CREATING, ACTIVE, DELETING, UPDATING, VPC_ENDPOINT_LIMIT_EXCEEDED, IP_ADDRESS_LIMIT_EXCEEDED, INVALID_SECURITY_GROUP_ID, INVALID_SUBNET_ID, INACCESSIBLE_ENCRYPTION_CREDS, INACCESSIBLE_SECRET_ARN, INACCESSIBLE_VPC_ENDPOINT, INCOMPATIBLE_NETWORK, MERGING, MODIFYING, SPLITTING, COPYING, STARTING, STOPPING, STOPPED, MAINTENANCE, INACCESSIBLE_ENCRYPTION_CREDENTIALS_RECOVERABLE)
subnet_ids	array	The Amazon EC2 subnet IDs for the elastic cluster.
vpc_security_group_ids	array	A list of EC2 VPC security groups associated with thie elastic cluster.

list_clusters

Name	Datatype	Description
cluster_arn	string	The ARN identifier of the elastic cluster.
cluster_name	string	The name of the elastic cluster.
status	string	The status of the elastic cluster. (CREATING, ACTIVE, DELETING, UPDATING, VPC_ENDPOINT_LIMIT_EXCEEDED, IP_ADDRESS_LIMIT_EXCEEDED, INVALID_SECURITY_GROUP_ID, INVALID_SUBNET_ID, INACCESSIBLE_ENCRYPTION_CREDS, INACCESSIBLE_SECRET_ARN, INACCESSIBLE_VPC_ENDPOINT, INCOMPATIBLE_NETWORK, MERGING, MODIFYING, SPLITTING, COPYING, STARTING, STOPPING, STOPPED, MAINTENANCE, INACCESSIBLE_ENCRYPTION_CREDENTIALS_RECOVERABLE)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_cluster	select	cluster_arn, region		Returns information about a specific elastic cluster.
list_clusters	select	region	maxResults, nextToken	Returns information about provisioned Amazon DocumentDB elastic clusters.
create_cluster	insert	region, adminUserName, adminUserPassword, authType, clusterName, shardCapacity, shardCount		Creates a new Amazon DocumentDB elastic cluster and returns its cluster structure.
update_cluster	update	cluster_arn, region		Modifies an elastic cluster. This includes updating admin-username/password, upgrading the API version, and setting up a backup window and maintenance window
delete_cluster	delete	cluster_arn, region		Delete an elastic cluster.
copy_cluster_snapshot	exec	snapshot_arn, region, targetSnapshotName		Copies a snapshot of an elastic cluster.
restore_cluster_from_snapshot	exec	snapshot_arn, region, clusterName		Restores an elastic cluster from a snapshot.
start_cluster	exec	cluster_arn, region		Restarts the stopped elastic cluster that is specified by clusterARN.
stop_cluster	exec	cluster_arn, region		Stops the running elastic cluster that is specified by clusterArn. The elastic cluster must be in the available state.

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
cluster_arn	string	The ARN identifier of the elastic cluster.
region	string	AWS region (default: us-east-1)
snapshot_arn	string	The ARN identifier of the elastic cluster snapshot.
maxResults	integer	The maximum number of elastic cluster snapshot results to receive in the response.
nextToken	string	A pagination token provided by a previous request. If this parameter is specified, the response includes only records beyond this token, up to the value specified by max-results. If there is no more data in the responce, the nextToken will not be returned.

SELECT examples

get_cluster

Returns information about a specific elastic cluster.

SELECT
admin_user_name,
auth_type,
backup_retention_period,
cluster_arn,
cluster_endpoint,
cluster_name,
create_time,
kms_key_id,
preferred_backup_window,
preferred_maintenance_window,
shard_capacity,
shard_count,
shard_instance_count,
shards,
status,
subnet_ids,
vpc_security_group_ids
FROM aws.docdb_elastic.clusters
WHERE cluster_arn = '{{ cluster_arn }}' -- required
AND region = '{{ region }}' -- required
;

list_clusters

Returns information about provisioned Amazon DocumentDB elastic clusters.

SELECT
cluster_arn,
cluster_name,
status
FROM aws.docdb_elastic.clusters
WHERE region = '{{ region }}' -- required
AND maxResults = '{{ maxResults }}'
AND nextToken = '{{ nextToken }}'
;

INSERT examples

create_cluster

Creates a new Amazon DocumentDB elastic cluster and returns its cluster structure.

INSERT INTO aws.docdb_elastic.clusters (
adminUserName,
adminUserPassword,
authType,
backupRetentionPeriod,
clientToken,
clusterName,
kmsKeyId,
preferredBackupWindow,
preferredMaintenanceWindow,
shardCapacity,
shardCount,
shardInstanceCount,
subnetIds,
tags,
vpcSecurityGroupIds,
region
)
SELECT 
'{{ adminUserName }}' /* required */,
'{{ adminUserPassword }}' /* required */,
'{{ authType }}' /* required */,
{{ backupRetentionPeriod }},
'{{ clientToken }}',
'{{ clusterName }}' /* required */,
'{{ kmsKeyId }}',
'{{ preferredBackupWindow }}',
'{{ preferredMaintenanceWindow }}',
{{ shardCapacity }} /* required */,
{{ shardCount }} /* required */,
{{ shardInstanceCount }},
'{{ subnetIds }}',
'{{ tags }}',
'{{ vpcSecurityGroupIds }}',
'{{ region }}'
RETURNING
cluster
;

Manifest

# Description fields are for documentation purposes
- name: clusters
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the clusters resource.
  - name: adminUserName
    value: "{{ adminUserName }}"
  - name: adminUserPassword
    value: "{{ adminUserPassword }}"
  - name: authType
    value: "{{ authType }}"
    valid_values: ['PLAIN_TEXT', 'SECRET_ARN']
  - name: backupRetentionPeriod
    value: {{ backupRetentionPeriod }}
  - name: clientToken
    value: "{{ clientToken }}"
  - name: clusterName
    value: "{{ clusterName }}"
  - name: kmsKeyId
    value: "{{ kmsKeyId }}"
  - name: preferredBackupWindow
    value: "{{ preferredBackupWindow }}"
  - name: preferredMaintenanceWindow
    value: "{{ preferredMaintenanceWindow }}"
  - name: shardCapacity
    value: {{ shardCapacity }}
  - name: shardCount
    value: {{ shardCount }}
  - name: shardInstanceCount
    value: {{ shardInstanceCount }}
  - name: subnetIds
    value:
      - "{{ subnetIds }}"
  - name: tags
    value: "{{ tags }}"
  - name: vpcSecurityGroupIds
    value:
      - "{{ vpcSecurityGroupIds }}"

UPDATE examples

update_cluster

Modifies an elastic cluster. This includes updating admin-username/password, upgrading the API version, and setting up a backup window and maintenance window

UPDATE aws.docdb_elastic.clusters
SET 
adminUserPassword = '{{ adminUserPassword }}',
authType = '{{ authType }}',
backupRetentionPeriod = {{ backupRetentionPeriod }},
clientToken = '{{ clientToken }}',
preferredBackupWindow = '{{ preferredBackupWindow }}',
preferredMaintenanceWindow = '{{ preferredMaintenanceWindow }}',
shardCapacity = {{ shardCapacity }},
shardCount = {{ shardCount }},
shardInstanceCount = {{ shardInstanceCount }},
subnetIds = '{{ subnetIds }}',
vpcSecurityGroupIds = '{{ vpcSecurityGroupIds }}'
WHERE 
cluster_arn = '{{ cluster_arn }}' --required
AND region = '{{ region }}' --required
RETURNING
cluster;

DELETE examples

delete_cluster

Delete an elastic cluster.

DELETE FROM aws.docdb_elastic.clusters
WHERE cluster_arn = '{{ cluster_arn }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

copy_cluster_snapshot

Copies a snapshot of an elastic cluster.

EXEC aws.docdb_elastic.clusters.copy_cluster_snapshot 
@snapshot_arn='{{ snapshot_arn }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"copyTags": {{ copyTags }}, 
"kmsKeyId": "{{ kmsKeyId }}", 
"tags": "{{ tags }}", 
"targetSnapshotName": "{{ targetSnapshotName }}"
}'
;

restore_cluster_from_snapshot

Restores an elastic cluster from a snapshot.

EXEC aws.docdb_elastic.clusters.restore_cluster_from_snapshot 
@snapshot_arn='{{ snapshot_arn }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"clusterName": "{{ clusterName }}", 
"kmsKeyId": "{{ kmsKeyId }}", 
"shardCapacity": {{ shardCapacity }}, 
"shardInstanceCount": {{ shardInstanceCount }}, 
"subnetIds": "{{ subnetIds }}", 
"tags": "{{ tags }}", 
"vpcSecurityGroupIds": "{{ vpcSecurityGroupIds }}"
}'
;

start_cluster

Restarts the stopped elastic cluster that is specified by clusterARN.

EXEC aws.docdb_elastic.clusters.start_cluster 
@cluster_arn='{{ cluster_arn }}' --required, 
@region='{{ region }}' --required
;

stop_cluster

Stops the running elastic cluster that is specified by clusterArn. The elastic cluster must be in the available state.

EXEC aws.docdb_elastic.clusters.stop_cluster 
@cluster_arn='{{ cluster_arn }}' --required, 
@region='{{ region }}' --required
;