awscc_rds_db_instance (Resource)

The AWS::RDS::DBInstance resource creates an Amazon DB instance. The new DB instance can be an RDS DB instance, or it can be a DB instance in an Aurora DB cluster. For more information about creating an RDS DB instance, see Creating an Amazon RDS DB instance in the Amazon RDS User Guide. For more information about creating a DB instance in an Aurora DB cluster, see Creating an Amazon Aurora DB cluster in the Amazon Aurora User Guide. If you import an existing DB instance, and the template configuration doesn't match the actual configuration of the DB instance, AWS CloudFormation applies the changes in the template during the import operation. If a DB instance is deleted or replaced during an update, AWS CloudFormation deletes all automated snapshots. However, it retains manual DB snapshots. During an update that requires replacement, you can apply a stack policy to prevent DB instances from being replaced. For more information, see Prevent Updates to Stack Resources. Updating DB instances When properties labeled "Update requires: Replacement" are updated, AWS CloudFormation first creates a replacement DB instance, then changes references from other dependent resources to point to the replacement DB instance, and finally deletes the old DB instance. 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 instance. To preserve your data, perform the following procedure:

  1. Deactivate any applications that are using the DB instance so that there's no activity on the DB instance.
  2. Create a snapshot of the DB instance. For more information, see Creating a DB Snapshot.
  3. If you want to restore your instance using a DB snapshot, modify the updated template with your DB instance changes and add the DBSnapshotIdentifier property with the ID of the DB snapshot that you want to use. After you restore a DB instance with a DBSnapshotIdentifier property, you can delete the DBSnapshotIdentifier property. When you specify this property for an update, the DB instance is not restored from the DB snapshot again, and the data in the database is not changed. However, if you don't specify the DBSnapshotIdentifier property, an empty DB instance is created, and the original DB instance is deleted. If you specify a property that is different from the previous snapshot restore property, a new DB instance is restored from the specified DBSnapshotIdentifier property, and the original DB instance is deleted.
  4. Update the stack.

For more information about updating other properties of this resource, see ModifyDBInstance. For more information about updating stacks, see CloudFormation Stacks Updates. Deleting DB instances For DB instances that are part of an Aurora DB cluster, you can set a deletion policy for your DB instance to control how AWS CloudFormation handles the DB instance when the stack is deleted. For Amazon RDS DB instances, you can choose to retain the DB instance, to delete the DB instance, or to create a snapshot of the DB instance. The default AWS CloudFormation behavior depends on the DBClusterIdentifier property:

  1. For AWS::RDS::DBInstance resources that don't specify the DBClusterIdentifier property, AWS CloudFormation saves a snapshot of the DB instance.
  2. For AWS::RDS::DBInstance resources that do specify the DBClusterIdentifier property, AWS CloudFormation deletes the DB instance.

For more information, see DeletionPolicy Attribute.

Example Usage

Basic example

To create a AWS RDS DB instance with basic details

resource "awscc_rds_db_instance" "this" {
  allocated_storage       = 10
  db_name                 = "mydb"
  engine                  = "mysql"
  engine_version          = "5.7"
  db_instance_class       = "db.t3.micro"
  master_username         = "foo"
  master_user_password    = "foobarbaz"
  db_parameter_group_name = "default.mysql5.7"
}

Storage Autoscaling example

To enable Storage Autoscaling with instances that support the feature, define the max_allocated_storage argument higher than the allocated_storage argument. Terraform will automatically hide differences with the allocated_storage argument value if autoscaling occurs.

resource "awscc_rds_db_instance" "this" {
  # ... other configuration ...
  db_name                 = "mydb"
  engine                  = "mysql"
  engine_version          = "5.7"
  db_instance_class       = "db.t3.micro"
  master_username         = "foo"
  master_user_password    = "foobarbaz"
  db_parameter_group_name = "default.mysql5.7"
  allocated_storage       = 50
  max_allocated_storage   = 100
}

Managed Master Passwords via Secrets Manager, default KMS Key example

You can specify the manage_master_user_password attribute to enable managing the master password with Secrets Manager. You can also update an existing cluster to use Secrets Manager by specify the manage_master_user_password attribute and removing the password attribute (removal is required).

resource "awscc_rds_db_instance" "this" {
  allocated_storage           = 10
  db_name                     = "mydb"
  engine                      = "mysql"
  engine_version              = "5.7"
  db_instance_class           = "db.t3.micro"
  manage_master_user_password = true
  master_username             = "foo"
  db_parameter_group_name     = "default.mysql5.7"
}

Managed Master Passwords via Secrets Manager, specific KMS Key example

You can specify the kms_key_id attribute under nested block master_user_secret to specify a specific KMS Key.

resource "aws_kms_key" "this" {
  description = "Example KMS Key"
}

resource "awscc_rds_db_instance" "this" {
  allocated_storage           = 10
  db_name                     = "mydb"
  engine                      = "mysql"
  engine_version              = "5.7"
  db_instance_class           = "db.t3.micro"
  manage_master_user_password = true
  master_username             = "foo"
  master_user_secret = {
    kms_key_id = aws_kms_key.this.key_id
  }
  db_parameter_group_name = "default.mysql5.7"
}

DB Instance creation with custom subnet group example

You can create RDS DB instance by using custom db subnet group

resource "awscc_rds_db_subnet_group" "this" {
  db_subnet_group_name        = "example"
  db_subnet_group_description = "example subnet group"
  subnet_ids                  = ["subnet-006182af0254ccbc4", "subnet-0c40688dd8ca51435"]
}

resource "awscc_rds_db_instance" "this" {
  allocated_storage       = 10
  db_name                 = "mydb"
  engine                  = "mysql"
  engine_version          = "5.7"
  db_instance_class       = "db.t3.micro"
  master_username         = "foo"
  master_user_password    = "foobarbaz"
  db_parameter_group_name = "default.mysql5.7"
  db_subnet_group_name    = awscc_rds_db_subnet_group.this.id
  tags = [{
    key   = "Name"
    value = "this"
  }]
}

Schema

Optional

Read-Only

Nested Schema for associated_roles

Required:

Nested Schema for certificate_details

Read-Only:

Nested Schema for endpoint

Read-Only:

Nested Schema for master_user_secret

Optional:

Read-Only:

Nested Schema for processor_features

Optional:

Nested Schema for tags

Required:

Optional:

Import

Import is supported using the following syntax:

$ terraform import awscc_rds_db_instance.example <resource ID>