Skip to content

Relational Database Service (RDS)

A managed relational database. BYM runs PostgreSQL on RDS, and AWS runs the servers and applies minor version upgrades. You provision the database outside the Byks module. The Byks module then finds it in the account and gives your application network access to it.

Byks guides

Terraform configuration

terraform-byks-module doesn't create RDS databases. Provision the database directly with the terraform-aws-rds-postgresql module, outside the module "application" block. Each instance of the module creates one PostgreSQL instance named <environment>-<application_name>, with its admin password stored and rotated in AWS Secrets Manager.

terraform-byks-module then finds the database through its access security group, rds_access-<environment>-<application_name>. Use the same application_name in both modules, or set override_rds_name in module "application" if the names differ. Set has_rds = false in module "application" if the account has no database.

For the full steps to set up a new database, see Provision a PostgreSQL RDS database.

rds.tf
data "aws_ssm_parameter" "vpc_information" {
  name = "/bym/vpc"
}

module "rds" {
  source = "git@github.com:BYM-IKT/terraform-aws-rds-postgresql.git?ref=v4"
  application_name     = "example"
  environment          = var.environment
  vpc                  = jsondecode(data.aws_ssm_parameter.vpc_information.insecure_value)
  major_engine_version = "17"
  instance_class       = "db.t4g.micro"
  disk_size            = 20
  disk_type            = "gp3"
  # options go here
}

Options

Option Type Default Description
application_name string required Name of the application using the database. Part of the instance name and security group names.
environment string required Environment the database belongs to, for example test or prod. The defaults for disk_autoscaling_size, multi_az_replica, skip_final_snapshot, and backup_settings differ in prod.
vpc any required The account's VPC information. Read it from the /bym/vpc SSM parameter with jsondecode, as in the example. The module uses its vpc_id and database_subnet_group_name.
major_engine_version string required PostgreSQL major version, for example "17". Also sets the parameter group family.
instance_class string required Instance size, which sets CPU and memory, for example db.t4g.micro.
disk_size number required Allocated storage in GB. The minimum for gp3 is 20 GB.
disk_type string required Storage type, for example gp3 or gp2.
deletion_protection bool true Block deletion of the database. Set to false before you delete it on purpose.
allow_major_version_upgrade bool false Allow changing major_engine_version on an existing database.
minor_engine_version string "" Minor version appended to major_engine_version, including the leading dot, for example ".4". Empty selects the latest minor version.
enable_auto_minor_version_upgrade bool true Let AWS apply minor version upgrades during the maintenance window.
maintenance_window string "Sun:00:15-Sun:02:15" Weekly window for maintenance, in UTC, formatted as Day:hh:mm-Day:hh:mm.
apply_changes_immediately bool true Apply configuration changes right away instead of waiting for the maintenance window.
disk_autoscaling_size number 0 Maximum storage in GB that auto-scaling can grow the disk to. With 0, prod gets a limit of disk_size × 1.5, and other environments get no auto-scaling.
disk_io number null Provisioned IOPS. Only applies to gp3, io1, and io2. With null, AWS uses its default IOPS for the disk type.
db_username string "dbadmin" Username of the database admin user.
manage_master_user_password_rotation bool true Rotate the admin password in Secrets Manager on a schedule. Setting this back to false turns off rotation.
master_user_password_rotation_duration string null Length of the rotation window, for example 3h.
master_user_password_rotate_immediately bool false Rotate the admin password right away, instead of at the next scheduled rotation.
master_user_password_rotation_automatically_after_days number 30 Days between scheduled admin password rotations.
db_parameters list(map(string)) [] Extra PostgreSQL parameters for the parameter group. Each map takes name, value, and optionally apply_method, set to immediate or pending-reboot.
multi_az_replica bool null Run a standby replica in a second availability zone. With null, it's on in prod and off in other environments.
iam_database_authentication_enabled bool false Allow logging in to the database with IAM credentials instead of a password.
transit_gateway_cidr string null CIDR range of the VPN client network, for example "172.20.0.0/20". When set, the database accepts connections from the VPN and from GitHub runners in shared_private_network_cidr. With null, neither can connect.
shared_private_network_cidr string "10.100.0.0/23" CIDR range of the shared private network where GitHub runners in AWS run. Only used when transit_gateway_cidr is set.
alarm_topic_arn string null ARN of an SNS topic that receives the default CloudWatch alarms and RDS events, such as high CPU, latency, or low free storage. With null, the module creates no alarms.
ca_cert_identifier string "rds-ca-rsa2048-g1" Certificate authority used for the database's TLS certificate.
create_from_snapshot_id string null Full ID of an existing RDS snapshot to create the database from.
skip_final_snapshot bool null Skip taking a final snapshot when the database is deleted. With null, prod takes a final snapshot and other environments skip it.
enable_pg_auditing bool false Turn on the pgaudit extension for audit logging. Takes effect after a reboot.
pg_audit_log_level string "" Statement classes that pgaudit logs, as a comma-separated list. Allowed values are ddl, function, misc, read, role, write, none, all, and the same values with a - prefix to exclude them. Only used when enable_pg_auditing is true.
pg_log_retention_period number 30 Days to keep the database's PostgreSQL logs in CloudWatch.
pg_log_parameter string "0" Set to "1" to include statement parameters in pgaudit logs. Only used when enable_pg_auditing is true.
overrides object {} Override generated names and encryption keys. See Overrides object.
backup_settings map(string) null AWS Backup schedule and retention settings for the database. With null, prod gets daily backups kept for 35 days and monthly backups kept for 370 days, and other environments get no backups. See Backup settings object.

Overrides object

Used in overrides.

Option Type Default Description
instance_name string null Override the instance name, which is <environment>-<application_name> by default. If you change it, set override_rds_name in module "application" to match.
rds_sg_access_name string null Override the name of the access security group, which is rds_access-<instance name> followed by a random suffix by default.
rds_sg_name string null Override the name of the database's own security group, which is rds-<instance name> followed by a random suffix by default.
kms_key_arn string null ARN of an existing KMS key to encrypt the database with, instead of a key the module creates.
performance_insights_kms_key_arn string null ARN of an existing KMS key to encrypt performance monitoring data with, instead of a key the module creates.

Backup settings object

Used in backup_settings.

Option Type Default Description
hourly bool false Take hourly backups.
hourly_retention_days number 7 Days to keep hourly backups. Must be 2 or 7.
twelve_hours bool false Take backups every twelve hours.
twelve_hours_retention_days number 14 Days to keep twelve-hour backups. Must be 14.
daily bool false Take daily backups.
daily_retention_days number 14 Days to keep daily backups. Must be 5, 10, 14, or 35.
biweekly bool false Take backups every two weeks.
biweekly_retention_days number 185 Days to keep biweekly backups. Must be 185.
monthly bool false Take monthly backups.
monthly_retention_days number 370 Days to keep monthly backups. Must be 95, 185, 370, or 1850.
monthly_annually bool false Take an extra yearly backup alongside the monthly one.
monthly_retention_years number 5 Years to keep the yearly backup. Must be 5.
biannual bool false Take backups every six months.
biannual_retention_days number 370 Days to keep biannual backups. Must be 370.
daily_no_copy bool false Take daily backups on the no-copy plan, instead of daily.
daily_no_copy_retention_days number 14 Days to keep no-copy daily backups. Must be 1, 14, or 35.
biweekly_no_copy bool false Take biweekly backups on the no-copy plan, instead of biweekly.
biweekly_no_copy_retention_days number 35 Days to keep no-copy biweekly backups. Must be 35.
monthly_no_copy bool false Take monthly backups on the no-copy plan, instead of monthly.
monthly_no_copy_retention_days number 370 Days to keep no-copy monthly backups. Must be 370.
biannual_no_copy bool false Take biannual backups on the no-copy plan, instead of biannual.
biannual_no_copy_retention_days number 740 Days to keep no-copy biannual backups. Must be 740.

Outputs

Read these from the module, for example module.rds.rds_endpoint.

Output Description
rds_endpoint The hostname to connect to the database on.
rds_port Port the database listens on, always 5432.
rds_instance_name Name of the RDS instance.
rds_access_sg ID of the access security group. Resources in this group can connect to the database.
rds_instance_sg ID of the database's own security group.
rds_master_user_secret_arn ARN of the Secrets Manager secret holding the admin username and password.

Resources