AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS::DocDB::DBCluster

The AWS::DocDB::DBCluster Amazon DocumentDB (with MongoDB compatibility) resource describes a DBCluster. Amazon DocumentDB is a fully managed, MongoDB-compatible document database engine. For more information, see DBCluster in the Amazon DocumentDB Developer Guide.

You can only use this resource in regions supported by Amazon DocumentDB. For more information, see Choosing Regions and Availability Zones.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{ "Type" : "AWS::DocDB::DBCluster", "Properties" : { "AvailabilityZones" : [ String, ... ], "BackupRetentionPeriod" : Integer, "DBClusterIdentifier" : String, "DBClusterParameterGroupName" : String, "DBSubnetGroupName" : String, "EngineVersion : String, "KmsKeyId" : String, "MasterUsername" : String, "MasterUserPassword" : String, "Port" : Integer, "PreferredBackupWindow" : String, "PreferredMaintenanceWindow" : String, "SnapshotIdentifier" : String, "StorageEncrypted" : Boolean, "Tags" : [ Tag, ... ], "VpcSecurityGroupIds" : [ String, ... ] } }

YAML

Type: "AWS::DocDB::DBCluster" Properties: AvailabilityZones: - String BackupRetentionPeriod: Integer DBClusterIdentifier: String DBClusterParameterGroupName: String DBSubnetGroupName: String EngineVersion: String KmsKeyId: String MasterUsername: String MasterUserPassword: String Port: Integer PreferredBackupWindow: String PreferredMaintenanceWindow: String SnapshotIdentifier: String StorageEncrypted: Boolean Tags: - Tag VpcSecurityGroupIds: - String

Properties

AvailabilityZones

A list of Availability Zones (AZs) in which DB instances in the cluster can be created.

Required: No

Type: List of String values

Update requires: Replacement

BackupRetentionPeriod

The number of days for which automatic backups are retained. For more information, see Comparing Automatic and Manual Snapshots in the Amazon DocumentDB Developer Guide.

Required: No

Type: Integer

Update requires: No interruption

DBClusterIdentifier

The DB cluster identifier. This parameter is stored as a lowercase string.

Constraints:

  • Length is between [1-63] letters, numbers, or hyphens

  • First character must be a letter

  • Cannot end with a hyphen or contain two consecutive hyphens

  • Must be unique for all clusters (across Amazon RDS, Neptune and Amazon DocumentDB) per AWS account, per region.

Required: No

Type: String

Update requires: Replacement

DBClusterParameterGroupName

The name of the DB cluster parameter group to associate with this DB cluster.

Note

If this argument is omitted, default.docdb3.6 is used.

Required: No

Type: String

Update requires: No interruption

DBSubnetGroupName

A DB subnet group that you want to associate with this DB cluster.

Required: No

Type: String

Update requires: Replacement

EngineVersion

The version number of the database engine that you want to use.

Required: No

Type: String

Update requires: Replacement

KmsKeyId

The Amazon Resource Name (ARN) of the AWS Key Management Service master key that is used to encrypt the DB instances in the DB cluster, such as arn:aws:kms:us-east-1:012345678910:key/abcd1234-a123-456a-a12b-a123b4cd56ef. If you enable the StorageEncrypted property but don't specify this property, the default master key is used. If you specify this property, you must set the StorageEncrypted property to true.

Required: No

Type: String

Update requires: Replacement

MasterUsername

The master user name for the DB instance.

Required: Conditional. You must specify this property unless you specify the SnapshotIdentifier property. In that case, do not specify this property.

Type: String

Update requires: Replacement

MasterUserPassword

The password for the master database user.

Required: Conditional. You must specify this property unless you specify the SnapshotIdentifier property. In that case, do not specify this property.

Required: No

Type: String

Update requires: No interruption

Port

The port number on which the DB instances in the cluster can accept connections. If this argument is omitted, 27017 is used.

Required: No

Type: Integer

Update requires: No interruption

PreferredBackupWindow

If automated backups are enabled (see the BackupRetentionPeriod property), the daily time range in UTC during which automated backups are created.

Required: No

Type: String

Update requires: No interruption

PreferredMaintenanceWindow

The weekly time range (in UTC) during which system maintenance can occur.

For valid values, see the PreferredMaintenanceWindow parameter of the CreateDBCluster action in the Amazon DocumentDB Developer Guide.

Required: No

Type: String

Update requires: No interruption

SnapshotIdentifier

The identifier for the DB cluster snapshot from which you want to restore.

Required: No

Type: String

Update requires: Replacement

StorageEncrypted

Indicates whether the DB instances in the cluster are encrypted.

Required: Conditional. If you specify the KmsKeyId property, you must enable encryption.

Type: Boolean

Update requires: Replacement

Tags

A list of up to 50 tags. A tag is metadata assigned to an Amazon DocumentDB resource consisting of a key-value pair.

Required: No

Type: List of Resource Tag property types

Update requires: No interruption

VpcSecurityGroupIds

A list of VPC security groups to associate with this DB cluster.

Required: No

Type: List of String values

Update requires: No interruption

Return Values

Ref

When you pass the logical ID of an AWS::DocDB::DBCluster resource to the intrinsic Ref function, the function returns the DB cluster identifier, such as MyCluster.

For more information about using the Ref function, see Ref.

Fn::GetAtt

Fn::GetAtt returns a value for a specified attribute of this type. The following are the available attributes and sample return values.

ClusterResourceId

The resource id for the DB cluster; for example: cluster-ABCD1234EFGH5678IJKL90MNOP. The cluster ID uniquely identifies the cluster and is used in things like IAM authentication policies.

Endpoint

The connection endpoint for the DB cluster, such as "sample-cluster.cluster-cozrlsfrcjoc.us-east-1.docdb.amazonaws.com.

Port

The port number on which the DB cluster accepts connections. For example: 27017.

ReadEndpoint

The reader endpoint for the DB cluster. For example: sample-cluster.cluster-ro-cozrlsfrcjoc.us-east-1.docdb.amazonaws.com.

For more information about using Fn::GetAtt, see Fn::GetAtt.

Examples

JSON

{ "AWSTemplateFormatVersion" : "2010-09-09", "Resources" : { "myDBInstance" : { "Type" : "AWS::DocDB::DBCluster", "Properties" : { "BackupRetentionPeriod" : 8, "DBClusterIdentufier" : "sample-cluster", "DBClusterParameterGroupName" : "default.docdb3.6", "DBSubnetGroupName" : "default", "KMSKeyId" : "your-kms-key-id", "MasterUsername" : "your-master-username", "MasterUserPassword" : "your-master-user-password", "Port" : "27017", "PreferredBackupWindow" : "07:34-08:04", "PreferredMaintenanceWindow" : "sat:04:51-sat:05:21", "SnapshotIdentifier" : "sample-cluster-snapshot-id", "StorageEncrypted" : true, "Tags" : [ {"Key" : "String", "Value" : "String"} ] } } } }

YAML

AWSTemplateFormatVersion: "2010-09-09" Resources: myDBInstance: Type: "AWS::DocDB::DBCluster" Properties: BackupRetentionPeriod : 8 DBClusterIdentufier : "sample-cluster" DBClusterParameterGroupName : "default.docdb3.6" DBSubnetGroupName : "default" KMSKeyId : "your-kms-key-id" MasterUsername : "your-master-username" MasterUserPassword : "your-master-user-password" Port : "27017" PreferredBackupWindow : "07:34-08:04" PreferredMaintenanceWindow : "sat:04:51-sat:05:21" SnapshotIdentifier : "sample-cluster-snapshot-id" StorageEncrypted : true Tags: - Key: "String" Value: "String"

See Also

For more information, see the following topics in the Amazon DocumentDB Developer Guide.