db_instance submodule

The db_instance submodule is the core of the terraform-aws-rds module. It provisions the aws_db_instance resource along with the Enhanced Monitoring IAM role, CloudWatch log groups, and Secrets Manager password rotation. The root module wraps this submodule and coordinates it with the subnet group, parameter group, and option group submodules.

Source

./modules/db_instance

Usage

To use this submodule directly:

module "db_instance" {
  source  = "terraform-aws-modules/rds/aws//modules/db_instance"
  version = "~> 7.0"

  identifier        = "mydb"
  engine            = "postgres"
  engine_version    = "17"
  instance_class    = "db.t4g.large"
  allocated_storage = 20

  db_name  = "myapp"
  username = "dbadmin"
  password_wo = var.db_password
  password_wo_version = 1
  manage_master_user_password = false

  db_subnet_group_name   = module.db_subnet_group.db_subnet_group_id
  parameter_group_name   = module.db_parameter_group.db_parameter_group_id
  vpc_security_group_ids = [aws_security_group.rds.id]

  tags = {
    Environment = "production"
  }
}

In most cases, use the root module (terraform-aws-modules/rds/aws) rather than this submodule directly. The root module creates and wires together the subnet group, parameter group, and option group automatically.

Input variables

Resource control

create

bool

Whether to create the DB instance and all associated resources. Set to false to skip all resource creation.Default: true

region

string

Region where this resource will be managed. Defaults to the region set in the provider configuration.Default: null

Instance

identifier

string

required

The name of the RDS instance.

use_identifier_prefix

bool

Determines whether to use identifier as-is or create a unique identifier beginning with identifier as the specified prefix.Default: false

engine

string

The database engine to use. Not required when replicate_source_db is set.Default: null

engine_version

string

The engine version to use.Default: null

engine_lifecycle_support

string

The life cycle type for this DB instance. Applies only to RDS for MySQL and RDS for PostgreSQL. Valid values: open-source-rds-extended-support, open-source-rds-extended-support-disabled.Default: null

instance_class

string

The instance type of the RDS instance (e.g. db.t3.micro, db.r6g.large).Default: null

allocated_storage

number

The allocated storage in gigabytes.Default: null

storage_type

string

One of standard, gp2, gp3, or io1. Defaults to io1 if iops is specified, gp2 otherwise.Default: null

storage_encrypted

bool

Specifies whether the DB instance is encrypted.Default: true

kms_key_id

string

The ARN for the KMS encryption key.Default: null

max_allocated_storage

number

Enables Storage Autoscaling when set to a value greater than allocated_storage. Set to 0 to disable.Default: 0

storage_throughput

number

Storage throughput for gp3 storage type.Default: null

iops

number

The amount of provisioned IOPS. Requires storage_type of io1 or gp3.Default: null

dedicated_log_volume

bool

Use a dedicated log volume (DLV) for the DB instance. Requires Provisioned IOPS.Default: false

custom_iam_instance_profile

string

RDS custom IAM instance profile name.Default: null

Database credentials

db_name

string

The DB name to create. If omitted, no database is created initially.Default: null

username

string

Username for the master DB user. Ignored when replicate_source_db is set.Default: null

password_wo

string

Write-only, ephemeral password for the master DB user. Not used when manage_master_user_password is true or replicate_source_db is set.Default: null

password_wo_version

number

Version counter for password_wo. Increment to trigger a password update.Default: null

manage_master_user_password

bool

Set to true to let RDS manage the master user password via Secrets Manager.Default: true

master_user_secret_kms_key_id

string

KMS key ARN/ID/alias for encrypting the Secrets Manager secret.Default: null

port

string

The port on which the DB accepts connections.Default: null

Network

vpc_security_group_ids

list(string)

List of VPC security group IDs to associate.Default: []

db_subnet_group_name

string

Name of the DB subnet group for the instance.Default: null

parameter_group_name

string

Name of the DB parameter group to associate.Default: null

option_group_name

string

Name of the DB option group to associate.Default: null

publicly_accessible

bool

Bool to control if instance is publicly accessible.Default: false

multi_az

bool

Specifies if the RDS instance is multi-AZ.Default: false

availability_zone

string

The Availability Zone of the RDS instance.Default: null

network_type

string

The type of network stack to use. Valid values: IPV4, DUAL.Default: null

customer_owned_ip_enabled

bool

Indicates whether to enable a customer-owned IP address (CoIP) for an RDS on Outposts DB instance.Default: null

Backup & Recovery

backup_retention_period

number

The days to retain backups for.Default: null

backup_window

string

The daily time range (UTC) during which automated backups are created.Default: null

copy_tags_to_snapshot

bool

On delete, copy all Instance tags to the final snapshot.Default: true

skip_final_snapshot

bool

If true, no final snapshot is created on deletion.Default: false

final_snapshot_identifier_prefix

string

Prefix for the final snapshot identifier.Default: "final"

delete_automated_backups

bool

Specifies whether to remove automated backups immediately after the DB instance is deleted.Default: true

snapshot_identifier

string

Snapshot ID from which to create the DB instance.Default: null

restore_to_point_in_time

object

Restore to a point in time. MySQL is not supported. See inputs reference for the full object schema.Default: null

s3_import

object

Restore from a Percona Xtrabackup in S3. Only MySQL is supported. See inputs reference for the full object schema.Default: null

Maintenance

maintenance_window

string

The window to perform maintenance in.Default: null

apply_immediately

bool

Apply database modifications immediately rather than during the next maintenance window.Default: false

allow_major_version_upgrade

bool

Allow major engine version upgrades.Default: false

auto_minor_version_upgrade

bool

Automatically apply minor engine upgrades during the maintenance window.Default: true

blue_green_update

object

Enable low-downtime updates using RDS Blue/Green deployments.Default: null

upgrade_storage_config

bool

Upgrade the storage file system configuration on the read replica.Default: null

Monitoring

monitoring_interval

number

Enhanced Monitoring collection interval in seconds. Valid values: 0, 1, 5, 10, 15, 30, 60. Use 0 to disable.Default: 0

monitoring_role_arn

string

ARN of the IAM role for Enhanced Monitoring. Required when monitoring_interval > 0 and create_monitoring_role = false.Default: null

monitoring_role_name

string

Name of the IAM role to create for Enhanced Monitoring.Default: "rds-monitoring-role"

monitoring_role_use_name_prefix

bool

Use monitoring_role_name as a prefix instead of an exact name.Default: false

monitoring_role_description

string

Description of the monitoring IAM role.Default: null

create_monitoring_role

bool

Create an IAM role for Enhanced Monitoring.Default: false

monitoring_role_permissions_boundary

string

ARN of the permissions boundary policy for the monitoring IAM role.Default: null

performance_insights_enabled

bool

Enable Performance Insights.Default: false

performance_insights_retention_period

number

Days to retain Performance Insights data. Valid values: 7, 731, or a multiple of 31.Default: 7

performance_insights_kms_key_id

string

KMS key ARN for encrypting Performance Insights data.Default: null

database_insights_mode

string

Database Insights mode. Valid values: standard, advanced.Default: null

CloudWatch Logs

enabled_cloudwatch_logs_exports

list(string)

Log types to export to CloudWatch Logs.Default: []

create_cloudwatch_log_group

bool

Create CloudWatch log groups for each export type. Not created when use_identifier_prefix is true.Default: false

cloudwatch_log_group_retention_in_days

number

Days to retain CloudWatch logs.Default: 7

cloudwatch_log_group_kms_key_id

string

KMS key ARN for encrypting CloudWatch log data.Default: null

cloudwatch_log_group_skip_destroy

bool

Preserve log groups on destroy.Default: null

cloudwatch_log_group_class

string

Log group class. Valid values: STANDARD, INFREQUENT_ACCESS.Default: null

cloudwatch_log_group_tags

map(string)

Additional tags for the CloudWatch log group(s).Default: {}

Authentication — Password Rotation

manage_master_user_password_rotation

bool

Manage master user password rotation via Secrets Manager. Requires manage_master_user_password = true.Default: false

master_user_password_rotate_immediately

bool

Rotate the secret immediately on next apply.Default: null

master_user_password_rotation_automatically_after_days

number

Days between automatic rotations.Default: null

master_user_password_rotation_duration

string

Length of the rotation window in hours (e.g. 3h).Default: null

master_user_password_rotation_schedule_expression

string

cron() or rate() expression for the rotation schedule.Default: null

Active Directory

domain

string

ID of the Directory Service Active Directory domain.Default: null

domain_auth_secret_arn

string

ARN of the Secrets Manager secret with Active Directory credentials.Default: null

domain_dns_ips

list(string)

IPv4 DNS IPs of Active Directory domain controllers.Default: null

domain_fqdn

string

FQDN of the self-managed Active Directory domain.Default: null

domain_iam_role_name

string

Name of the IAM role for Directory Service API calls.Default: null

domain_ou

string

Active Directory organizational unit for the DB instance.Default: null

Replicas

replicate_source_db

string

Identifier of the source DB instance to replicate.Default: null

replica_mode

string

Oracle replica mode. Valid values: mounted, open-read-only.Default: null

Database settings

character_set_name

string

Character set name for Oracle instances. Cannot be changed after creation.Default: null

nchar_character_set_name

string

National character set for Oracle NCHAR/NVARCHAR2/NCLOB columns. Cannot be changed after creation.Default: null

timezone

string

DB instance timezone. Only supported by Microsoft SQL Server.Default: null

license_model

string

License model for the DB instance. Required for some engines.Default: null

iam_database_authentication_enabled

bool

Enable IAM database authentication.Default: false

deletion_protection

bool

Prevent the instance from being deleted.Default: false

ca_cert_identifier

string

Identifier of the CA certificate for the DB instance.Default: null

Tags & Timeouts

Outputs

db_instance_address

string

The hostname of the RDS instance.

db_instance_arn

string

The ARN of the RDS instance.

db_instance_availability_zone

string

The Availability Zone of the RDS instance.

db_instance_endpoint

string

The connection endpoint in address:port format.

db_listener_endpoint

object

The listener connection endpoint for SQL Server Always On.

db_instance_engine

string

The database engine.

db_instance_engine_version_actual

string

The running version of the database engine.

db_instance_hosted_zone_id

string

The canonical hosted zone ID of the DB instance.

db_instance_identifier

string

The RDS instance identifier.

db_instance_resource_id

string

The RDS Resource ID of this instance.

db_instance_status

string

The RDS instance status.

db_instance_name

string

The database name.

db_instance_username

string

The master username for the database. Sensitive.

db_instance_port

number

The database port.

db_instance_ca_cert_identifier

string

The CA certificate identifier.

db_instance_domain

string

The ID of the Active Directory domain the instance is joined to.

db_instance_domain_auth_secret_arn

string

The ARN of the Active Directory credentials secret.

db_instance_domain_dns_ips

list(string)

The DNS IP addresses of the Active Directory domain controllers.

db_instance_domain_fqdn

string

The FQDN of the Active Directory domain.

db_instance_domain_iam_role_name

string

The IAM role name used for Directory Service API calls.

db_instance_domain_ou

string

The Active Directory organizational unit the instance joined.

db_instance_master_user_secret_arn

string

The ARN of the Secrets Manager secret for the master user password.

db_instance_upgrade_rollout_order

string

The upgrade rollout order for the instance.

db_instance_cloudwatch_log_groups

map(object)

Map of CloudWatch log groups created for the DB instance.

db_instance_secretsmanager_secret_rotation_enabled

bool

Whether automatic Secrets Manager rotation is enabled.

enhanced_monitoring_iam_role_name

string

The name of the Enhanced Monitoring IAM role.

enhanced_monitoring_iam_role_arn

string

The ARN of the Enhanced Monitoring IAM role.

Root Module

Submodules

Source

Usage

Input variables

Outputs

Build docs developers (and LLMs) love

Root Module

Submodules

​Source

​Usage

​Input variables

​Outputs

Build docs developers (and LLMs) love

Source

Usage

Input variables

Outputs