Skip to main content
A DB subnet group is a collection of subnets that RDS can use when creating a DB instance inside a VPC. AWS requires that a subnet group spans at least two Availability Zones (AZs). Without a subnet group, RDS places the instance in the default VPC.
The module defaults to create_db_subnet_group = false. In most cases you will either create a subnet group through a VPC module (like terraform-aws-modules/vpc/aws) and pass its name via db_subnet_group_name, or set create_db_subnet_group = true and provide subnet_ids.

​
Variables

VariableDefaultDescription
create_db_subnet_groupfalseWhether to create a DB subnet group.
db_subnet_group_namenullName of the subnet group to create or reference. When creating, defaults to the instance identifier.
db_subnet_group_use_name_prefixtrueWhen true, appends a unique suffix to the name. Set to false to use the exact name.
subnet_ids[]List of VPC subnet IDs to include. Required when create_db_subnet_group = true.
db_subnet_group_descriptionnullDescription for the subnet group.
db_subnet_group_tags{}Additional tags to apply to the subnet group resource.

​
Setup

1

Identify private subnets across multiple AZs

RDS instances should always be placed in private subnets — not public subnets. Ensure your VPC has at least two private subnets in different AZs. Most production deployments use three AZs for resilience.If you are using the terraform-aws-modules/vpc/aws module, it creates a database_subnet_group output that you can reference directly:
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 6.0"

  name = "my-vpc"
  cidr = "10.0.0.0/16"

  azs              = ["eu-west-1a", "eu-west-1b", "eu-west-1c"]
  database_subnets = ["10.0.6.0/24", "10.0.7.0/24", "10.0.8.0/24"]

  create_database_subnet_group = true
}
2

Pass the subnet group to the RDS module

Reference the VPC-created subnet group by name:
module "db" {
  source = "terraform-aws-modules/rds/aws"

  identifier = "my-db"

  # Reference the subnet group from the VPC module
  # create_db_subnet_group is false (default) — not creating one here
  db_subnet_group_name = module.vpc.database_subnet_group

  engine         = "mysql"
  engine_version = "8.0"
  instance_class = "db.t4g.large"
  # ... other required variables
}
3

Or create a subnet group within the module

If you have subnet IDs but no pre-created subnet group, let the module create it:
module "db" {
  source = "terraform-aws-modules/rds/aws"

  identifier = "my-db"

  # Create a subnet group
  create_db_subnet_group = true
  subnet_ids             = ["subnet-12345678", "subnet-87654321", "subnet-abcdef01"]

  engine         = "mysql"
  engine_version = "8.0"
  instance_class = "db.t4g.large"
  # ... other required variables
}
The subnet group name defaults to the identifier value with a generated suffix (because db_subnet_group_use_name_prefix = true by default).To use a specific name:
create_db_subnet_group          = true
db_subnet_group_name            = "production-rds-subnets"
db_subnet_group_use_name_prefix = false
subnet_ids                      = ["subnet-12345678", "subnet-87654321"]

​
Use existing subnet group

If a subnet group already exists in AWS and is not managed by this module: 
module "db" {
  source = "terraform-aws-modules/rds/aws"

  identifier = "my-db"

  # create_db_subnet_group = false (default)
  db_subnet_group_name = "existing-subnet-group-name"

  # ... other required variables
}

​
Best practices

Use private subnets

Never place RDS instances in public subnets. Use dedicated database subnets that have no route to an internet gateway.

Span multiple AZs

Include subnets from at least two Availability Zones. For Multi-AZ deployments, AWS needs to place the standby replica in a different AZ.

Separate database subnets

Use dedicated database subnets rather than reusing your application’s private subnets. This allows independent routing and network ACL control.

Tag consistently

Use db_subnet_group_tags to add environment or team tags separate from the global tags variable.

Build docs developers (and LLMs) love

Get started for freeTalk to us