Skip to content

Upgrade RDS Terraform provider from major version 7 to 8

Before you begin

A thorough understanding of your database usage: if you use the root user for any operation it is recommended to implement separate application users.

Read and understand the upgrade instruction from the provider.

Affected versions

  • Everyone using terraform-aws-modules/rds-aurora/aws prior to version 8
  • Password change only apply to the root user

Rationale

The latest major version of terraform-aws-modules/rds-aurora/aws now support the RDS integration with AWS Secrets Manager to manage the master user password, this includes auto-rotation of the password.

The template was updated in #869.

Manual upgrades

This is a manual upgrade, follow the steps described below in your database stack.

Assumption: RDS is configured in postgres_aurora_serverless.tf

Step 1: Upgrade AWS provider

Upgrade hashicorp/aws to the latest version in common.tf

required_providers {
  aws = {
    source  = "hashicorp/aws"
    version = "5.12.0"
  }
}

Upgrade the provider

terraform init -upgrade

Step 2: Upgrade RDS module

Upgrade terraform-aws-modules/rds-aurora/aws to version 8.3.1 in postgres_aurora_serverless.tf

source  = "terraform-aws-modules/rds-aurora/aws"
version = "8.3.1"

Step 3: Remove random_password_length

Remove the configuration option random_password_length from postgres_aurora_serverless.tf.

diff --git a/stacks/prod/database/postgres_aurora_serverless.tf b/stacks/prod/database/postgres_aurora_serverless.tf
  deletion_protection    = local.args_rds.deletion_protection
- random_password_length = local.args_rds.random_password_length
 }

This configuration is for the now deprecated db_password below.

Step 4: Remove db_password

Remove the resource aws_ssm_parameter.db_password from postgres_aurora_serverless.tf. A new password for the master username will be generated and stored in AWS Secrets Manager.

Master username still available

In the AWS console under your-cluster-name -> Configuration -> Authentication the Master username will still be available, but the Master password will no longer be configured here.

Step 5: Security group migration

The upgrade deprecates several variables related to RDS and security groups setup.

The Golden Path template does not utilize any of these variables.

However: review any custom setup for your database stack according to documentation in the 8.0 upgrade migration before continuing. Running terraform plan will give you a indication if your setup is affected by this change.

Step 6: Plan your changes

Install the RDS module and plan the changes:

terraform init
terraform plan

This should result in the following changes based on the Golden Path template:

  • Destroy aws_ssm_parameter.db_password
  • Destroy random_password.master_password
  • Removal of master_password from aws_rds_cluster
  • Addition of manage_master_user_password to aws_rds_cluster

Review any additional changes before continuing: the module updated can have affected more parts of your infrastructure.

Step 7: Apply and commit changes

Apply the changes:

terraform apply

Review changes in the AWS console under Cluster -> Configuration -> Authentication

  • master password is no longer configured
  • Master Credentials ARN is added, with a direct link to AWS Secrets Manager

Commit all changes and push them to your IAC repository.

Test the connectivity to your cluster with ok forward and make sure both the updated root password in addition to any application users can connect to your cluster.