AWS Amazon RDS Cluster

This page shows how to write Terraform and CloudFormation for Amazon RDS Cluster and write them securely.

aws_rds_cluster (Terraform)

The Cluster in Amazon RDS can be configured in Terraform with the resource name aws_rds_cluster. The following sections describe 5 examples of how to use the resource and its parameters.

Example Usage from GitHub

storage_encryption.tf#L10
resource "aws_rds_cluster" "storage_encrypted_set_to_true" {
  engine            = "aurora-mysql"
  master_username   = "foo"
  master_password   = "bar"
  storage_encrypted = true
  kms_key_id        = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
rds_cluster_test.tf#L12
resource "aws_rds_cluster" "postgres_serverless" {
  cluster_identifier = "aurora-serverless"
  engine             = "aurora-postgresql"
  engine_mode        = "serverless"
  master_username    = "foo"
  master_password    = "barbut8chars"
storage_encryption.tf#L10
resource "aws_rds_cluster" "storage_encrypted_set_to_true" {
  engine            = "aurora-mysql"
  master_username   = "foo"
  master_password   = "bar"
  storage_encrypted = true
  kms_key_id        = "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
rdscluster.tf#L1
resource "aws_rds_cluster" "noStorageEncryption" {
  master_password = "barbarbarbar"
  master_username = "foo"
}

resource "aws_rds_cluster" "storageEncryptedNoKms" {
rds_cluster_test.tf#L12
resource "aws_rds_cluster" "postgres_serverless" {
  cluster_identifier = "aurora-serverless"
  engine             = "aurora-postgresql"
  engine_mode        = "serverless"
  master_username    = "foo"
  master_password    = "barbut8chars"

Review your Terraform file for AWS best practices

Shisho Cloud, our free checker to make sure your Terraform configuration follows best practices, is available (beta).

Security Best Practices for aws_rds_cluster

There are 2 settings in aws_rds_cluster that should be taken care of for security reasons. The following section explain an overview and example code.

risk-label

Ensure backup retension of your RDS cluster is specified

It's better to set it explicitly to reduce the risk of availability issues.

risk-label

Ensure to enable storage encryption of your RDS cluster

It is better to enable storage encryption of your RDS cluster. Encryption reduces the risk of data leakage.

Review your AWS Amazon RDS settings

You can check if the aws_rds_cluster setting in your .tf file is correct in 3 min with Shisho Cloud.

Parameters

Explanation in Terraform Registry

Manages a [RDS Aurora Cluster][2]. To manage cluster instances that inherit configuration from the cluster (when not running the cluster in serverless engine mode), see the aws_rds_cluster_instance resource. To manage non-Aurora databases (e.g., MySQL, PostgreSQL, SQL Server, etc.), see the aws_db_instance resource. For information on the difference between the available Aurora MySQL engines see Comparison between Aurora MySQL 1 and Aurora MySQL 2 in the Amazon RDS User Guide. Changes to an RDS Cluster can occur when you manually change a parameter, such as port, and are reflected in the next maintenance window. Because of this, Terraform may report a difference in its planning phase because a modification has not yet taken place. You can use the apply_immediately flag to instruct the service to apply the change immediately (see documentation below).

Note: using apply_immediately can result in a brief downtime as the server reboots. See the AWS Docs on [RDS Maintenance][4] for more information. Note: All arguments including the username and password will be stored in the raw state as plain-text. Read more about sensitive data in state. NOTE on RDS Clusters and RDS Cluster Role Associations: Terraform provides both a standalone RDS Cluster Role Association - (an association between an RDS Cluster and a single IAM Role) and an RDS Cluster resource with iam_roles attributes. Use one resource or the other to associate IAM Roles and RDS Clusters. Not doing so will cause a conflict of associations and will result in the association being overwritten.

Tips: Best Practices for The Other AWS Amazon RDS Resources

In addition to the aws_db_instance, AWS Amazon RDS has the other resources that should be configured for security reasons. Please check some examples of those resources and precautions.

risk-label

aws_db_instance

Ensure backup retension of your RDS instance is specified

It's better to set it explicitly to reduce the risk of availability issues.

risk-label

aws_rds_cluster_instance

Ensure your RDS cluster instance blocks unwanted access

It's better to limit accessibily to the minimum that is required for the application to work.

Review your AWS Amazon RDS settings

In addition to the above, there are other security points you should be aware of making sure that your .tf files are protected in Shisho Cloud.

AWS::RDS::DBCluster (CloudFormation)

The DBCluster in RDS can be configured in CloudFormation with the resource name AWS::RDS::DBCluster. The following sections describe 10 examples of how to use the resource and its parameters.

Example Usage from GitHub

deploy.yml#L4
    Type: 'AWS::RDS::DBCluster'
    Properties:
      MasterUsername: !Ref DBUsername
      MasterUserPassword: !Ref DBPassword
      DBClusterIdentifier: aurora-postgresql-cluster
      Engine: aurora-postgresql
rds.yml#L30
    Type: AWS::RDS::DBClusterParameterGroup
    Properties:
      Family: aurora-mysql5.7
      Description: DB Cluster Parameter Group
      Parameters:
        character_set_client: utf8mb4
RDS.yml#L3
    Type: 'AWS::RDS::DBClusterParameterGroup'
    Properties:
      Description: 'Aurora PostgreSQL 10 Parameter Group'
      Family: aurora-postgresql10
      Parameters:
        rds.force_ssl: 1
rds.cluster.yml#L26
    Type: AWS::RDS::DBCluster
    Properties:
      AvailabilityZones:
        - !Join ['', [!Ref 'AWS::Region', a]]
        - !Join ['', [!Ref 'AWS::Region', b]]
      DBClusterParameterGroupName: !Ref ParameterGroup
aurora-serverless.yml#L24
      TargetType: AWS::RDS::DBCluster

  # aurora-postgresql serverless DB
  DBCluster:
    Type: AWS::RDS::DBCluster
    Properties:
config.ListDiscoveredResources_1.json#L6
                "resourceType": "AWS::RDS::DBClusterSnapshot",
                "resourceId": "rds:database-1-2020-05-19-05-58",
                "resourceName": "rds:database-1-2020-05-19-05-58"
            },
            {
                "resourceType": "AWS::RDS::DBClusterSnapshot",
config.ListDiscoveredResources_1.json#L6
                "resourceType": "AWS::RDS::DBClusterSnapshot",
                "resourceId": "rds:database-1-2020-05-19-05-58",
                "resourceName": "rds:database-1-2020-05-19-05-58"
            },
            {
                "resourceType": "AWS::RDS::DBClusterSnapshot",
config.ListDiscoveredResources_1.json#L6
                "resourceType": "AWS::RDS::DBClusterSnapshot",
                "resourceId": "rds:database-1-2020-05-19-05-58",
                "resourceName": "rds:database-1-2020-05-19-05-58"
            },
            {
                "resourceType": "AWS::RDS::DBClusterSnapshot",
cloudformation-list-stack-resources.aurora.json#L5
            "ResourceType": "AWS::RDS::DBCluster",
            "ResourceStatus": "CREATE_COMPLETE"
        },
        {
            "PhysicalResourceId": "auroraClusterParameterGroup",
            "ResourceType": "AWS::RDS::DBClusterParameterGroup",
aurora-postgresql.json#L18
      "Type": "AWS::RDS::DBCluster",
      "Properties": {
        "Engine": "aurora-postgresql",
        "EngineMode": "provisioned",
        "EngineVersion": {
          "Ref": "EngineVersion"

Parameters

Explanation in CloudFormation Registry

The AWS::RDS::DBCluster resource creates an Amazon Aurora DB cluster. For more information, see Managing an Amazon Aurora DB Cluster in the Amazon Aurora User Guide.

Note You can only create this resource in AWS Regions where Amazon Aurora is supported.

Updating DB clustersWhen properties labeled "Update requires: Replacement" are updated, AWS CloudFormation first creates a replacement DB cluster, then changes references from other dependent resources to point to the replacement DB cluster, and finally deletes the old DB cluster.

Important We highly recommend that you take a snapshot of the database before updating the stack. If you don't, you lose the data when AWS CloudFormation replaces your DB cluster. To preserve your data, perform the following procedure: Deactivate any applications that are using the DB cluster so that there's no activity on the DB instance.

Create a snapshot of the DB cluster. For more information about creating DB snapshots, see Creating a DB Cluster Snapshot.

If you want to restore your DB cluster using a DB cluster snapshot, modify the updated template with your DB cluster changes and add the SnapshotIdentifier property with the ID of the DB cluster snapshot that you want to use. After you restore a DB cluster with a SnapshotIdentifier property, you must specify the same SnapshotIdentifier property for any future updates to the DB cluster. When you specify this property for an update, the DB cluster is not restored from the DB cluster snapshot again, and the data in the database is not changed. However, if you don't specify the SnapshotIdentifier property, an empty DB cluster is created, and the original DB cluster is deleted. If you specify a property that is different from the previous snapshot restore property, a new DB cluster is restored from the specified SnapshotIdentifier property, and the original DB cluster is deleted.

Update the stack.

Currently, when you are updating the stack for an Aurora Serverless DB cluster, you can't include changes to any other properties when you specify one of the following properties: PreferredBackupWindow, PreferredMaintenanceWindow, and Port. This limitation doesn't apply to provisioned DB clusters.

For more information about updating other properties of this resource, see [ModifyDBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBCluster.html). For more information about updating stacks, see AWS CloudFormation Stacks Updates.

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

Frequently asked questions

What is AWS Amazon RDS Cluster?

AWS Amazon RDS Cluster is a resource for Amazon RDS of Amazon Web Service. Settings can be wrote in Terraform and CloudFormation.

Where can I find the example code for the AWS Amazon RDS Cluster?

For Terraform, the stelligent/config-lint, infracost/infracost and ffsclyh/config-lint source code examples are useful. See the Terraform Example section for further details.

For CloudFormation, the accurics/KaiMonkey, tanimon/todo-list-api and KennethWussmann/aurora-serverless-kotlin-api-example source code examples are useful. See the CloudFormation Example section for further details.