AWS::RDS::DBCluster

The AWS::RDS::DBCluster resource creates a cluster, such as an Aurora for Amazon RDS (Amazon Aurora) DB cluster. Amazon Aurora is a fully managed, MySQL-compatible, relational database engine. For more information, see Aurora on Amazon RDS in the Amazon RDS User Guide.

Note

Currently, you can create this resource only in regions in which Amazon Aurora is supported.

The default DeletionPolicy for AWS::RDS::DBCluster resources is Snapshot. For more information about how AWS CloudFormation deletes resources, see DeletionPolicy Attribute.

Syntax

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

JSON


{
  "Type" : "AWS::RDS::DBCluster",
  "Properties" :
  {
    "AvailabilityZones" : [ String, ... ],
    "BacktrackWindow" : Integer,
    "BackupRetentionPeriod" : Integer,
    "DatabaseName" : String,   
    "DBClusterIdentifier" : String,
    "DBClusterParameterGroupName" : String,
    "DBSubnetGroupName" : String,
    "DeletionProtection" : Boolean,
    "EnableCloudwatchLogsExports" : [ String, ... ],
    "EnableIAMDatabaseAuthentication" : Boolean,
    "Engine" : String,
    "EngineMode" : String,
    "EngineVersion" : String,
    "KmsKeyId" : String,
    "MasterUsername" : String,
    "MasterUserPassword" : String,
    "Port" : Integer,
    "PreferredBackupWindow" : String,
    "PreferredMaintenanceWindow" : String,
    "ReplicationSourceIdentifier" : String,
    "ScalingConfiguration" : ScalingConfiguration,
    "SnapshotIdentifier" : String,
    "StorageEncrypted" : Boolean,
    "Tags" : [ Resource Tag, ... ],
    "VpcSecurityGroupIds" : [ String, ... ]
  }
}

YAML


Type: "AWS::RDS::DBCluster"
Properties:
  AvailabilityZones:
    - String
  BacktrackWindow: Integer
  BackupRetentionPeriod: Integer
  DatabaseName: String
  DBClusterIdentifier: String
  DBClusterParameterGroupName: String
  DBSubnetGroupName: String
  DeletionProtection: Boolean
  EnableCloudwatchLogsExports:
    - String
  EnableIAMDatabaseAuthentication: Boolean
  Engine: String
  EngineMode: String
  EngineVersion: String
  KmsKeyId: String
  MasterUsername: String
  MasterUserPassword: String
  Port: Integer
  PreferredBackupWindow: String
  PreferredMaintenanceWindow: String
  ReplicationSourceIdentifier: String
  ScalingConfiguration: 
    ScalingConfiguration
  SnapshotIdentifier: String
  StorageEncrypted: Boolean
  Tags:
    - Resource 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

BacktrackWindow

The target backtrack window, in seconds. To disable backtracking, specify 0. If specified, this property must be set to a number from 0 to 259,200 (72 hours).

Required: No

Type: Long

Update requires: No interruption

BackupRetentionPeriod

The number of days for which automatic backups are retained. For more information, see CreateDBCluster in the Amazon RDS API Reference.

Required: No

Type: Integer

Update requires: No interruption

DatabaseName

The name of your database. If you don't provide a name, Amazon Relational Database Service (Amazon RDS) won't create a database in this DB cluster. For naming constraints, see Naming Constraints in Amazon RDS in the Amazon RDS User Guide.

Required: No

Type: String

Update requires: Replacement

DBClusterIdentifier

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

Constraints:

Must contain from 1 to 63 letters, numbers, or hyphens.
First character must be a letter.
Cannot end with a hyphen or contain two consecutive hyphens.

For additional information, see the DBClusterIdentifier parameter of the CreateDBCluster action in the Amazon RDS API Reference.

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.aurora5.6 is used. If default.aurora5.6 is used, specifying aurora-mysql or aurora-postgresql for the Engine property might result in an error.

Required: No

Type: String

Update requires: Some interruptions

DBSubnetGroupName

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

Required: No

Type: String

Update requires: Replacement

DeletionProtection

Indicates whether the DB cluster should have deletion protection enabled. The database can't be deleted when this value is set to true. If you want to delete a stack with a protected cluster, update this value to false before you delete the stack.

For more information, see Deleting a DB Instance.

Required: No

Type: Boolean

Update requires: No interruption

EnableCloudwatchLogsExports

The list of log types that need to be enabled for exporting to CloudWatch Logs. The values in the list depend on the DB engine being used. Log types that are excluded or removed from this list during updates are disabled. For more information, see Publishing Database Logs to Amazon CloudWatch Logs in the Amazon Aurora User Guide.

Required: No

Type: List of String values

Update requires: No interruption

EnableIAMDatabaseAuthentication

If set to true, enables mapping of AWS Identity and Access Management (IAM) accounts to database accounts.

Required: No

Type: Boolean

Update requires: No interruption

Engine

The name of the database engine that you want to use for this DB cluster.

For valid values, see the Engine parameter of the CreateDBCluster action in the Amazon RDS API Reference.

Note

If you don't specify a value for the DBClusterParameterGroupName property and default.aurora5.6 is used, specifying aurora.mysql or aurora-postgresql for this property might result in an error.

Required: Yes

Type: String

Update requires: Replacement

EngineMode

The DB engine mode of the DB cluster. Valid values include provisioned or serverless.

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 database 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.

If you specify the SnapshotIdentifier, do not specify this property. The value is inherited from the snapshot DB cluster.

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.

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, 3306 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 you want to create automated backups.

For valid values, see the PreferredBackupWindow parameter of the CreateDBInstance action in the Amazon RDS API Reference.

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 CreateDBInstance action in the Amazon RDS API Reference.

Required: No

Type: String

Update requires: No interruption or some interruptions. For more information, see ModifyDBInstance in the Amazon RDS API Reference.

ReplicationSourceIdentifier

The Amazon Resource Name (ARN) of the source Amazon RDS DB instance or DB cluster, if this DB cluster is created as a Read Replica.

Required: No

Type: String

Update requires: No interruption

ScalingConfiguration

For DB clusters in serverless DB engine mode, the scaling properties of the DB cluster.

Required: No

Type: ScalingConfiguration

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.

If you specify the SnapshotIdentifier property, do not specify this property. The value is inherited from the snapshot DB cluster.

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

Type: Boolean

Update requires: Replacement.

Tags

The tags that you want to attach to this DB cluster.

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 the logical ID of this resource is provided to the Ref intrinsic function, Ref returns the resource name.

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.

Endpoint.Address: The connection endpoint for the DB cluster. For example: mystack-mydbcluster-1apw1j4phylrk.cg034hpkmmjt.us-east-2.rds.amazonaws.com.
Endpoint.Port: The port number that will accept connections on this DB cluster. For example: 3306.
ReadEndpoint.Address: The reader endpoint for the DB cluster. For example: mystack-mydbcluster-ro-1apw1j4phylrk.cg034hpkmmjt.us-east-2.rds.amazonaws.com.

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

Example

The following snippet creates an Amazon Aurora DB cluster and adds two DB instances to it. Because Amazon RDS automatically assigns a writer and reader DB instances in the cluster, use the cluster endpoint to read and write data, not the individual DB instance endpoints.

JSON


"RDSCluster" : {
  "Type" : "AWS::RDS::DBCluster",
  "Properties" : {
    "MasterUsername" : { "Ref" : "username" },
    "MasterUserPassword" : { "Ref" : "password" },
    "Engine" : "aurora",
    "DBSubnetGroupName" : { "Ref" : "DBSubnetGroup" },
    "DBClusterParameterGroupName" : { "Ref" : "RDSDBClusterParameterGroup" }
  }
},
"RDSDBInstance1" : {
  "Type" : "AWS::RDS::DBInstance",
  "Properties" : {
    "DBSubnetGroupName" : {
      "Ref" : "DBSubnetGroup"
    },
    "DBParameterGroupName" :{"Ref": "RDSDBParameterGroup"},
    "Engine" : "aurora",
    "DBClusterIdentifier" : {
      "Ref" : "RDSCluster"
    },
    "PubliclyAccessible" : "true",
    "AvailabilityZone" : { "Fn::GetAtt" : [ "Subnet1", "AvailabilityZone" ] },
    "DBInstanceClass" : "db.r3.xlarge"
  }
},
"RDSDBInstance2" : {
  "Type" : "AWS::RDS::DBInstance",
  "Properties" : {
    "DBSubnetGroupName" : {
      "Ref" : "DBSubnetGroup"
    },
    "DBParameterGroupName" :{"Ref": "RDSDBParameterGroup"},
    "Engine" : "aurora",
    "DBClusterIdentifier" : {
      "Ref" : "RDSCluster"
    },
    "PubliclyAccessible" : "true",
    "AvailabilityZone" : { "Fn::GetAtt" : [ "Subnet2", "AvailabilityZone" ] },
    "DBInstanceClass" : "db.r3.xlarge"
  }
},
"RDSDBClusterParameterGroup" : {
  "Type": "AWS::RDS::DBClusterParameterGroup",
  "Properties" : {
    "Description" : "CloudFormation Sample Aurora Cluster Parameter Group",
    "Family" : "aurora5.6",
    "Parameters" : {
      "time_zone" : "US/Eastern"
    }
  }
},
"RDSDBParameterGroup": {
  "Type": "AWS::RDS::DBParameterGroup",
  "Properties" : {
    "Description" : "CloudFormation Sample Aurora Parameter Group",
    "Family" : "aurora5.6",
    "Parameters" : {
      "sql_mode": "IGNORE_SPACE"
    }
  }
}

YAML


RDSCluster:
  Type: AWS::RDS::DBCluster
  Properties:
    MasterUsername:
      Ref: username
    MasterUserPassword:
      Ref: password
    Engine: aurora
    DBSubnetGroupName:
      Ref: DBSubnetGroup
    DBClusterParameterGroupName:
      Ref: RDSDBClusterParameterGroup
RDSDBInstance1:
  Type: AWS::RDS::DBInstance
  Properties:
    DBSubnetGroupName:
      Ref: DBSubnetGroup
    DBParameterGroupName:
      Ref: RDSDBParameterGroup
    Engine: aurora
    DBClusterIdentifier:
      Ref: RDSCluster
    PubliclyAccessible: 'true'
    AvailabilityZone:
      Fn::GetAtt:
      - Subnet1
      - AvailabilityZone
    DBInstanceClass: db.r3.xlarge
RDSDBInstance2:
  Type: AWS::RDS::DBInstance
  Properties:
    DBSubnetGroupName:
      Ref: DBSubnetGroup
    DBParameterGroupName:
      Ref: RDSDBParameterGroup
    Engine: aurora
    DBClusterIdentifier:
      Ref: RDSCluster
    PubliclyAccessible: 'true'
    AvailabilityZone:
      Fn::GetAtt:
      - Subnet2
      - AvailabilityZone
    DBInstanceClass: db.r3.xlarge
RDSDBClusterParameterGroup:
  Type: AWS::RDS::DBClusterParameterGroup
  Properties:
    Description: CloudFormation Sample Aurora Cluster Parameter Group
    Family: aurora5.6
    Parameters:
      time_zone: US/Eastern
RDSDBParameterGroup:
  Type: AWS::RDS::DBParameterGroup
  Properties:
    Description: CloudFormation Sample Aurora Parameter Group
    Family: aurora5.6
    Parameters:
      sql_mode: IGNORE_SPACE

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

« Previous Next »