Guide: Managing RDS and ElastiCache

Relevant source files

The following files were used as context for generating this wiki page:

• internal/service/rds/instance.go
• internal/service/rds/cluster.go
• internal/service/elasticache/cluster.go
• examples/rds/main.tf
• internal/service/rds/README.md
• internal/service/elasticache/README.md
• ROADMAP.md

# Guide: Managing RDS and ElastiCache

This guide provides a technical overview of how the Terraform AWS Provider manages AWS Relational Database Service (RDS) and AWS ElastiCache resources. It covers the primary resources, their configuration schemas, and how they are defined and provisioned using Terraform. The information herein is intended for contributors and maintainers working on the provider's RDS and ElastiCache packages.

The provider facilitates the full lifecycle management of these services, allowing for declarative infrastructure-as-code definitions of database clusters, instances, and caching clusters. This includes creation, updates, and deletion, all handled through the Terraform plugin which interacts with the AWS SDK for Go.

AWS Relational Database Service (RDS)

The provider offers comprehensive support for managing RDS resources, primarily through the aws_rds_cluster and aws_db_instance resources. These work together to provision and configure database clusters and the instances within them.

Sources: internal/service/rds/README.md

RDS Cluster (aws_rds_cluster)

The aws_rds_cluster resource is responsible for managing an RDS Cluster. A cluster can contain one or more DB instances. The schema for this resource defines the configurable attributes for an RDS cluster.

The following diagram illustrates the basic dependency flow when creating an RDS cluster with associated instances, as seen in the example configuration.

Key configuration attributes for an aws_rds_cluster are defined in its schema.

Attribute	Description	Type
cluster_identifier	The cluster identifier. If omitted, Terraform will assign a random, unique identifier.	TypeString
engine	The name of the database engine to be used for this cluster.	TypeString
engine_version	The version number of the database engine to use.	TypeString
master_username	The username for the master DB user.	TypeString
master_password	The password for the master DB user.	TypeString
db_subnet_group_name	A DB subnet group to associate with this DB cluster.	TypeString
vpc_security_group_ids	A list of EC2 VPC security groups to associate with this DB cluster.	TypeSet
skip_final_snapshot	Determines whether a final DB snapshot is created before the DB cluster is deleted.	TypeBool

Sources: internal/service/rds/cluster.go:61-238

RDS Instance (aws_db_instance)

The aws_db_instance resource manages a standalone RDS DB instance. While it can be used independently, it's often used to create instances within an aws_rds_cluster. The resource schema defines a wide range of configurable parameters for an instance.

Attribute	Description	Type
identifier	The DB instance identifier. If omitted, Terraform will assign a random, unique identifier.	TypeString
instance_class	The compute and memory capacity of the DB instance.	TypeString
allocated_storage	The allocated storage in gigabytes.	TypeInt
engine	The database engine to use.	TypeString
username	The master username for the database.	TypeString
password	The master password for the database.	TypeString
db_subnet_group_name	Name of the DB subnet group to associate with this DB instance.	TypeString
multi_az	Specifies if the DB instance is a Multi-AZ deployment.	TypeBool

Sources: internal/service/rds/instance.go:128-660

Example RDS Configuration

The following code demonstrates how to provision a complete RDS Aurora cluster and an associated instance within a dedicated VPC.

# main.tf
resource "aws_vpc" "default" {
  cidr_block = "10.0.0.0/16"
}

resource "aws_subnet" "default" {
  count             = 2
  vpc_id            = aws_vpc.default.id
  cidr_block        = "10.0.${count.index}.0/24"
  availability_zone = "us-west-2${element(list("a", "b", "c"), count.index)}"
}

resource "aws_db_subnet_group" "default" {
  name       = "main"
  subnet_ids = aws_subnet.default.*.id
}

resource "aws_rds_cluster" "default" {
  cluster_identifier      = "aurora-cluster-demo"
  engine                  = "aurora-mysql"
  availability_zones      = ["us-west-2a", "us-west-2b", "us-west-2c"]
  database_name           = "mydb"
  master_username         = "foo"
  master_password         = "bar"
  db_subnet_group_name    = aws_db_subnet_group.default.name
  skip_final_snapshot     = true
}

resource "aws_rds_cluster_instance" "default" {
  count              = 2
  identifier         = "aurora-cluster-demo-${count.index}"
  cluster_identifier = aws_rds_cluster.default.id
  instance_class     = "db.r4.large"
  engine             = aws_rds_cluster.default.engine
  engine_version     = aws_rds_cluster.default.engine_version
}

Sources: examples/rds/main.tf:1-44

AWS ElastiCache

The provider supports AWS ElastiCache through resources like aws_elasticache_cluster. This allows for the management of in-memory caching environments using Redis or Memcached.

Sources: internal/service/elasticache/README.md

ElastiCache Cluster (aws_elasticache_cluster)

The aws_elasticache_cluster resource manages an ElastiCache cluster. The resource schema defines its configuration, including the engine, node type, and number of nodes.

The lifecycle of an ElastiCache cluster resource within Terraform follows a standard pattern of create, read, update, and delete operations, mapped to corresponding AWS SDK calls.

This diagram shows the simplified logic for managing an ElastiCache cluster resource.
Sources: internal/service/elasticache/cluster.go:50-54

Key configuration attributes for an aws_elasticache_cluster are defined in its schema.

Attribute	Description	Type
cluster_id	The cluster identifier. This parameter is stored as a lowercase string.	TypeString
engine	The name of the cache engine to be used for this cluster. Valid values are memcached or redis.	TypeString
node_type	The compute and memory capacity of the nodes in the cache cluster.	TypeString
num_cache_nodes	The number of cache nodes that the cache cluster should have.	TypeInt
parameter_group_name	The name of the parameter group to associate with this cache cluster.	TypeString
subnet_group_name	The name of the subnet group to be used for the cache cluster.	TypeString
security_group_ids	A list of VPC Security Groups to associate with this cache cluster.	TypeSet

Sources: internal/service/elasticache/cluster.go:56-200

Future Enhancements and Roadmap

The provider is continuously evolving. Based on the project roadmap, several key enhancements are planned for both RDS and ElastiCache.

• RDS:
  • Address an issue where changing the identifier of an aws_db_instance forces a destroy-and-create operation.
  • Implement support for enabling cross-region automated backups for aws_db_instance.
• ElastiCache:
  • Add a user_group argument to the aws_elasticache_replication_group resource.

Sources: ROADMAP.md