chore: Update upgrade guide

bryantbiggs · bryantbiggs · commit f697c2d483cc · 2023-04-06T15:53:43.000-04:00
diff --git a/UPGRADE-8.0.md b/UPGRADE-8.0.md
@@ -5,37 +5,44 @@ If you find a bug, please open an issue with supporting configuration to reprodu
 
 ## List of backwards incompatible changes
 
+- With RDS now supporting the [integration with SecretsManager to manage the master user password](https://aws.amazon.com/about-aws/whats-new/2022/12/amazon-rds-integration-aws-secrets-manager/), the ability to generate a random password has been removed from this module. This is the preferred and strongly recommended route to mange the password since it keeps the password out of the Terraform state and allows for the password to be rotated automatically.
+- Support for generating a random snapshot identifier has been removed. The AWS provider has been updated to [enforce a conflict between `snapshot_identifier` and `global_cluster_identifier`](https://github.com/hashicorp/terraform-provider-aws/pull/30158)  which makes this feature challenging to support; which it has already been challenging to support in the past and often catching users off guard. Instead, the module now defaults to `null` for both of these values and puts the control back in user's hands if they wish to set a value for one of these arguments.
 - The default value for `create_db_subnet_group` has changed from `true` to `false` - typically, a common/shared DB subnet group is utilized since there are no real tangible benefits to creating a new one for each DB cluster
 - `allowed_security_groups`, `allowed_cidr_blocks`, and `security_group_egress_rules` have been removed and replaced with a more generic `security_group_rules` variable which supports both ingress and egress rules to/from all supported resources/destinations (e.g. security groups, CIDR blocks, prefix lists, etc.)
-- Minimum supported Terraform version is no 1.0
+- Minimum supported Terraform version is now 1.0
 
 ### Variable and output changes
 
 1. Removed variables:
 
-   - `allowed_security_groups` replaced by `security_group_rules`
-   - `allowed_cidr_blocks` replaced by `security_group_rules`
-   - `security_group_egress_rules` replaced by `security_group_rules`
+    - `create_random_password` -> support for random password generation has been removed
+    - `random_password_length` -> support for random password generation has been removed
+    - `final_snapshot_identifier_prefix` -> support for random snapshot identifier generation has been removed
+    - `allowed_security_groups` replaced by `security_group_rules`
+    - `allowed_cidr_blocks` replaced by `security_group_rules`
+    - `security_group_egress_rules` replaced by `security_group_rules`
 
 2. Renamed variables:
 
-   - None
+    - `create_cluster` -> `create`
 
 3. Added variables:
 
-   - `security_group_rules`
+    - `manage_master_user_password`
+    - `master_user_secret_kms_key_id`
+    - `security_group_rules`
 
 4. Removed outputs:
 
-   - None
+    - None
 
 5. Renamed outputs:
 
-   - None
+    - None
 
 6. Added outputs:
 
-   - None
+    - `cluster_master_user_secret`
 
 ## Upgrade Migrations
 
@@ -47,13 +54,26 @@ module "cluster_before" {
   version = "~> 7.0"
 
   # Only the affected attributes are shown
+  creat_cluster = true
+
+  master_username        = "admin"
+  create_random_password = true
+  random_password_length = 16
 
   create_db_subnet_group = false
   db_subnet_group_name   = module.vpc.database_subnet_group_name
 
   create_security_group   = true
   allowed_security_groups = ["sg-12345678"]
   allowed_cidr_blocks     = ["10.20.0.0/20"]
+  security_group_egress_rules = {
+    to_cidrs = {
+      cidr_blocks = ["10.33.0.0/28"]
+      description = "Egress to corporate printer closet"
+    }
+  }
+
+  final_snapshot_identifier_prefix = "my-cluster-"
 
   tags = {
     Environment = "dev"
@@ -70,6 +90,9 @@ module "cluster_after" {
   version = "~> 8.0"
 
   # Only the affected attributes are shown
+  create = true
+
+  manage_master_user_password = true
 
   db_subnet_group_name = module.vpc.database_subnet_group_name
 
@@ -80,8 +103,14 @@ module "cluster_after" {
     security_group_ingress_ex = {
       source_security_group_id = "sg-12345678"
     }
+    to_the_closet = {
+      cidr_blocks = ["10.33.0.0/28"]
+      description = "Egress to corporate printer closet"
+    }
   }
 
+  final_snapshot_identifier = "my-cluster-with-a-bit-of-something-unique"
+
   tags = {
     Environment = "dev"
     Terraform   = "true"
diff --git a/examples/global-cluster/README.md b/examples/global-cluster/README.md
@@ -21,13 +21,15 @@ Note that this example may create resources which cost money. Run `terraform des
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
 | <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 4.61 |
+| <a name="requirement_random"></a> [random](#requirement\_random) | >= 2.2 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
 | <a name="provider_aws"></a> [aws](#provider\_aws) | ~> 4.61 |
 | <a name="provider_aws.secondary"></a> [aws.secondary](#provider\_aws.secondary) | ~> 4.61 |
+| <a name="provider_random"></a> [random](#provider\_random) | >= 2.2 |
 
 ## Modules
 
@@ -45,6 +47,7 @@ Note that this example may create resources which cost money. Run `terraform des
 | [aws_kms_key.primary](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_key) | resource |
 | [aws_kms_key.secondary](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/kms_key) | resource |
 | [aws_rds_global_cluster.this](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/rds_global_cluster) | resource |
+| [random_password.master](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/password) | resource |
 | [aws_availability_zones.primary](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/availability_zones) | data source |
 | [aws_availability_zones.secondary](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/availability_zones) | data source |
 | [aws_caller_identity.current](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/caller_identity) | data source |
diff --git a/examples/global-cluster/main.tf b/examples/global-cluster/main.tf
@@ -1,10 +1,10 @@
 provider "aws" {
-  region = local.primary.region
+  region = local.primary_region
 }
 
 provider "aws" {
   alias  = "secondary"
-  region = local.secondary.region
+  region = local.secondary_region
 }
 
 data "aws_caller_identity" "current" {}
@@ -16,21 +16,14 @@ data "aws_availability_zones" "secondary" {
 locals {
   name = "ex-${basename(path.cwd)}"
 
+  primary_region   = "eu-west-1"
   primary_vpc_cidr = "10.0.0.0/16"
   primary_azs      = slice(data.aws_availability_zones.primary.names, 0, 3)
 
-  secondary_vpc_cidr = "10.0.1.0/16"
+  secondary_region   = "us-east-1"
+  secondary_vpc_cidr = "10.1.0.0/16"
   secondary_azs      = slice(data.aws_availability_zones.secondary.names, 0, 3)
 
-  primary = {
-    region      = "eu-west-1"
-    cidr_prefix = "10.99"
-  }
-  secondary = {
-    region      = "us-east-1"
-    cidr_prefix = "10.98"
-  }
-
   tags = {
     Example    = local.name
     GithubRepo = "terraform-aws-rds-aurora"
@@ -70,6 +63,9 @@ module "aurora_primary" {
     }
   }
 
+  # Global clusters do not support managed master user password
+  master_password = random_password.master.result
+
   skip_final_snapshot = true
 
   tags = local.tags
@@ -86,7 +82,7 @@ module "aurora_secondary" {
   engine                    = aws_rds_global_cluster.this.engine
   engine_version            = aws_rds_global_cluster.this.engine_version
   global_cluster_identifier = aws_rds_global_cluster.this.id
-  source_region             = local.primary.region
+  source_region             = local.primary_region
   instance_class            = "db.r6g.large"
   instances                 = { for i in range(2) : i => {} }
   kms_key_id                = aws_kms_key.secondary.arn
@@ -99,6 +95,9 @@ module "aurora_secondary" {
     }
   }
 
+  # Global clusters do not support managed master user password
+  master_password = random_password.master.result
+
   skip_final_snapshot = true
 
   depends_on = [
@@ -112,6 +111,11 @@ module "aurora_secondary" {
 # Supporting Resources
 ################################################################################
 
+resource "random_password" "master" {
+  length  = 20
+  special = false
+}
+
 module "primary_vpc" {
   source  = "terraform-aws-modules/vpc/aws"
   version = "~> 3.0"
diff --git a/examples/global-cluster/versions.tf b/examples/global-cluster/versions.tf
@@ -6,5 +6,10 @@ terraform {
       source  = "hashicorp/aws"
       version = "~> 4.61"
     }
+
+    random = {
+      source  = "hashicorp/random"
+      version = ">= 2.2"
+    }
   }
 }
diff --git a/examples/mysql/README.md b/examples/mysql/README.md
@@ -21,14 +21,12 @@ Note that this example may create resources which cost money. Run `terraform des
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
 | <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 4.61 |
-| <a name="requirement_random"></a> [random](#requirement\_random) | >= 2.2 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
 | <a name="provider_aws"></a> [aws](#provider\_aws) | ~> 4.61 |
-| <a name="provider_random"></a> [random](#provider\_random) | >= 2.2 |
 
 ## Modules
 
@@ -41,7 +39,6 @@ Note that this example may create resources which cost money. Run `terraform des
 
 | Name | Type |
 |------|------|
-| [random_password.master](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/password) | resource |
 | [aws_availability_zones.available](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/availability_zones) | data source |
 
 ## Inputs
diff --git a/examples/mysql/main.tf b/examples/mysql/main.tf
@@ -52,9 +52,6 @@ module "aurora" {
     }
   }
 
-  iam_database_authentication_enabled = true
-  master_password                     = random_password.master.result
-
   apply_immediately   = true
   skip_final_snapshot = true
 
@@ -151,11 +148,6 @@ module "aurora" {
 # Supporting Resources
 ################################################################################
 
-resource "random_password" "master" {
-  length  = 10
-  special = false
-}
-
 module "vpc" {
   source  = "terraform-aws-modules/vpc/aws"
   version = "~> 3.0"
diff --git a/examples/mysql/versions.tf b/examples/mysql/versions.tf
@@ -6,10 +6,5 @@ terraform {
       source  = "hashicorp/aws"
       version = "~> 4.61"
     }
-
-    random = {
-      source  = "hashicorp/random"
-      version = ">= 2.2"
-    }
   }
 }
diff --git a/examples/postgresql/README.md b/examples/postgresql/README.md
@@ -21,14 +21,12 @@ Note that this example may create resources which cost money. Run `terraform des
 |------|---------|
 | <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.0 |
 | <a name="requirement_aws"></a> [aws](#requirement\_aws) | ~> 4.61 |
-| <a name="requirement_random"></a> [random](#requirement\_random) | >= 2.2 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
 | <a name="provider_aws"></a> [aws](#provider\_aws) | ~> 4.61 |
-| <a name="provider_random"></a> [random](#provider\_random) | >= 2.2 |
 
 ## Modules
 
@@ -41,7 +39,6 @@ Note that this example may create resources which cost money. Run `terraform des
 
 | Name | Type |
 |------|------|
-| [random_password.master](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/password) | resource |
 | [aws_availability_zones.available](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/availability_zones) | data source |
 
 ## Inputs
diff --git a/examples/postgresql/main.tf b/examples/postgresql/main.tf
@@ -71,9 +71,6 @@ module "aurora" {
     }
   }
 
-  iam_database_authentication_enabled = true
-  master_password                     = random_password.master.result
-
   apply_immediately   = true
   skip_final_snapshot = true
 
@@ -115,11 +112,6 @@ module "aurora" {
 # Supporting Resources
 ################################################################################
 
-resource "random_password" "master" {
-  length  = 10
-  special = false
-}
-
 module "vpc" {
   source  = "terraform-aws-modules/vpc/aws"
   version = "~> 3.0"
diff --git a/examples/postgresql/versions.tf b/examples/postgresql/versions.tf
@@ -6,10 +6,5 @@ terraform {
       source  = "hashicorp/aws"
       version = "~> 4.61"
     }
-
-    random = {
-      source  = "hashicorp/random"
-      version = ">= 2.2"
-    }
   }
 }
diff --git a/main.tf b/main.tf
@@ -62,17 +62,18 @@ resource "aws_rds_cluster" "this" {
   final_snapshot_identifier           = var.final_snapshot_identifier
   global_cluster_identifier           = var.global_cluster_identifier
   iam_database_authentication_enabled = var.iam_database_authentication_enabled
-  iops                                = var.iops
-  kms_key_id                          = var.kms_key_id
-  manage_master_user_password         = var.is_primary_cluster ? var.manage_master_user_password : null
-  master_user_secret_kms_key_id       = var.is_primary_cluster ? var.master_user_secret_kms_key_id : null
-  master_password                     = var.is_primary_cluster ? var.master_password : null
-  master_username                     = var.is_primary_cluster ? var.master_username : null
-  network_type                        = var.network_type
-  port                                = local.port
-  preferred_backup_window             = local.is_serverless ? null : var.preferred_backup_window
-  preferred_maintenance_window        = local.is_serverless ? null : var.preferred_maintenance_window
-  replication_source_identifier       = var.replication_source_identifier
+  # iam_roles has been removed from this resource and instead will be used with aws_rds_cluster_role_association below to avoid conflicts per docs
+  iops                          = var.iops
+  kms_key_id                    = var.kms_key_id
+  manage_master_user_password   = var.global_cluster_identifier == null && var.manage_master_user_password ? var.manage_master_user_password : null
+  master_user_secret_kms_key_id = var.global_cluster_identifier == null && var.manage_master_user_password ? var.master_user_secret_kms_key_id : null
+  master_password               = var.is_primary_cluster && !var.manage_master_user_password ? var.master_password : null
+  master_username               = var.is_primary_cluster && !var.manage_master_user_password ? var.master_username : null
+  network_type                  = var.network_type
+  port                          = local.port
+  preferred_backup_window       = local.is_serverless ? null : var.preferred_backup_window
+  preferred_maintenance_window  = local.is_serverless ? null : var.preferred_maintenance_window
+  replication_source_identifier = var.replication_source_identifier
 
   dynamic "restore_to_point_in_time" {
     for_each = length(var.restore_to_point_in_time) > 0 ? [var.restore_to_point_in_time] : []

Original file line number	Diff line number	Diff line change
`@@ -6,5 +6,10 @@ terraform {`
`6`	`6`	`source = "hashicorp/aws"`
`7`	`7`	`version = "~> 4.61"`
`8`	`8`	`}`
	`9`	`+`
	`10`	`+ random = {`
	`11`	`+ source = "hashicorp/random"`
	`12`	`+ version = ">= 2.2"`
	`13`	`+ }`
`9`	`14`	`}`
`10`	`15`	`}`
Original file line number	Diff line number	Diff line change
`@@ -6,10 +6,5 @@ terraform {`
`6`	`6`	`source = "hashicorp/aws"`
`7`	`7`	`version = "~> 4.61"`
`8`	`8`	`}`
`9`		`-`
`10`		`- random = {`
`11`		`- source = "hashicorp/random"`
`12`		`- version = ">= 2.2"`
`13`		`- }`
`14`	`9`	`}`
`15`	`10`	`}`