diff --git a/README.md b/README.md
index 37eeae0d..8805ceb9 100644
--- a/README.md
+++ b/README.md
@@ -286,7 +286,7 @@ No resources.
| [maintenance\_window](#input\_maintenance\_window) | The window to perform maintenance in. Syntax: 'ddd:hh24:mi-ddd:hh24:mi'. Eg: 'Mon:00:00-Mon:03:00' | `string` | `null` | no |
| [major\_engine\_version](#input\_major\_engine\_version) | Specifies the major version of the engine that this option group should be associated with | `string` | `null` | no |
| [manage\_master\_user\_password](#input\_manage\_master\_user\_password) | Set to true to allow RDS to manage the master user password in Secrets Manager | `bool` | `true` | no |
-| [manage\_master\_user\_password\_rotation](#input\_manage\_master\_user\_password\_rotation) | Whether to manage the master user password rotation. Setting this value to false after previously having been set to true will disable automatic rotation. | `bool` | `false` | no |
+| [manage\_master\_user\_password\_rotation](#input\_manage\_master\_user\_password\_rotation) | Whether to manage the master user password rotation. By default, false on creation, rotation is managed by RDS. Setting this value to false after previously having been set to true will disable automatic rotation. | `bool` | `false` | no |
| [master\_user\_password\_rotate\_immediately](#input\_master\_user\_password\_rotate\_immediately) | Specifies whether to rotate the secret immediately or wait until the next scheduled rotation window. | `bool` | `null` | no |
| [master\_user\_password\_rotation\_automatically\_after\_days](#input\_master\_user\_password\_rotation\_automatically\_after\_days) | Specifies the number of days between automatic scheduled rotations of the secret. Either automatically\_after\_days or schedule\_expression must be specified. | `number` | `null` | no |
| [master\_user\_password\_rotation\_duration](#input\_master\_user\_password\_rotation\_duration) | The length of the rotation window in hours. For example, 3h for a three hour window. | `string` | `null` | no |
diff --git a/UPGRADE-6.0.md b/UPGRADE-6.0.md
new file mode 100644
index 00000000..fefc89e7
--- /dev/null
+++ b/UPGRADE-6.0.md
@@ -0,0 +1,115 @@
+# Upgrade from v5.x to v6.x
+
+If you have any questions regarding this upgrade process, please consult the [`examples/`](https://github.com/terraform-aws-modules/terraform-aws-rds/tree/master/examples) projects:
+
+If you find a bug, please open an issue with supporting configuration to reproduce.
+
+## List of backwards incompatible changes
+
+With RDS now supporting the integration with SecretsManager to manage the master user password, 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.
+
+## Variable and output changes
+
+1. Removed variables:
+
+ - `create_random_password` -> support for random password generation has been removed
+ - `random_password_length` -> support for random password generation has been removed
+
+2. Renamed variables:
+
+ - None
+
+3. Added variables:
+
+ - `manage_master_user_password`
+ - `master_user_secret_kms_key_id`
+
+4. Removed outputs:
+
+ - `db_instance_password` -> support for random password generation has been removed
+
+
+5. Renamed outputs:
+
+ - `db_instance_id` -> `db_instance_identifier`
+
+6. Added outputs:
+
+ - None
+
+
+## Upgrade Migrations
+
+### Before 5.x Example
+
+```hcl
+module "rds" {
+ source = "terraform-aws-modules/rds/aws"
+ version = "~> 5.0"
+
+ # Only the affected attributes are shown
+ create_db_instance = true
+
+ create_random_password = true
+ random_password_length = 16
+
+ tags = {
+ Environment = "dev"
+ Terraform = "true"
+ }
+}
+```
+
+### After 6.x Example
+
+```hcl
+module "rds" {
+ source = "terraform-aws-modules/rds/aws"
+ version = "~> 6.0"
+
+ create_db_instance = true
+
+ manage_master_user_password = true
+
+ tags = {
+ Environment = "dev"
+ Terraform = "true"
+ }
+}
+```
+
+### Retaining use of random password
+
+The following example demonstrates the changes that users can elect to make to avoid any potential disruptions when upgrading if electing not to use RDS password management with SecretsManager `manage_master_user_password` when previously using `create_random_password`.
+
+In this example, the `random_password` resource is added alongside the existing module to preserve the existing password.
+
+```hcl
+resource "random_password" "master_password" {
+ length = 16
+ special = false
+}
+
+module "rds" {
+ source = "terraform-aws-modules/rds/aws"
+ version = "~> 5.0"
+
+ # Only the affected attributes are shown
+ create_db_instance = true
+
+ manage_master_user_password = false
+
+ password = random_password.master_password.result
+
+ tags = {
+ Environment = "dev"
+ Terraform = "true"
+ }
+}
+```
+
+A state move must be done to preserve the previously used random password. Example:
+
+```
+terraform state mv 'module.rds.random_password.master_password[0]' random_password.master_password
+```
diff --git a/examples/complete-postgres/main.tf b/examples/complete-postgres/main.tf
index 0b8ba8e2..37137dd7 100644
--- a/examples/complete-postgres/main.tf
+++ b/examples/complete-postgres/main.tf
@@ -46,8 +46,13 @@ module "db" {
username = "complete_postgresql"
port = 5432
- # setting manage_master_user_password_rotation to false after it
- # has been set to true previously disables automatic rotation
+ # Setting manage_master_user_password_rotation to false after it
+ # has previously been set to true disables automatic rotation
+ # however using an initial value of false (default) does not disable
+ # automatic rotation and rotation will be handled by RDS.
+ # manage_master_user_password_rotation allows users to configure
+ # a non-default schedule and is not meant to disable rotation
+ # when initially creating / enabling the password management feature
manage_master_user_password_rotation = true
master_user_password_rotate_immediately = false
master_user_password_rotation_schedule_expression = "rate(15 days)"
diff --git a/modules/db_instance/README.md b/modules/db_instance/README.md
index df849af2..d02e6dfa 100644
--- a/modules/db_instance/README.md
+++ b/modules/db_instance/README.md
@@ -77,7 +77,7 @@ No modules.
| [license\_model](#input\_license\_model) | License model information for this DB instance. Optional, but required for some DB engines, i.e. Oracle SE1 | `string` | `null` | no |
| [maintenance\_window](#input\_maintenance\_window) | The window to perform maintenance in. Syntax: 'ddd:hh24:mi-ddd:hh24:mi'. Eg: 'Mon:00:00-Mon:03:00' | `string` | `null` | no |
| [manage\_master\_user\_password](#input\_manage\_master\_user\_password) | Set to true to allow RDS to manage the master user password in Secrets Manager. Cannot be set if password is provided | `bool` | `true` | no |
-| [manage\_master\_user\_password\_rotation](#input\_manage\_master\_user\_password\_rotation) | Whether to manage the master user password rotation. Setting this value to false after previously having been set to true will disable automatic rotation. | `bool` | `false` | no |
+| [manage\_master\_user\_password\_rotation](#input\_manage\_master\_user\_password\_rotation) | Whether to manage the master user password rotation. By default, false on creation, rotation is managed by RDS. Setting this value to false after previously having been set to true will disable automatic rotation. | `bool` | `false` | no |
| [master\_user\_password\_rotate\_immediately](#input\_master\_user\_password\_rotate\_immediately) | Specifies whether to rotate the secret immediately or wait until the next scheduled rotation window. | `bool` | `null` | no |
| [master\_user\_password\_rotation\_automatically\_after\_days](#input\_master\_user\_password\_rotation\_automatically\_after\_days) | Specifies the number of days between automatic scheduled rotations of the secret. Either automatically\_after\_days or schedule\_expression must be specified. | `number` | `null` | no |
| [master\_user\_password\_rotation\_duration](#input\_master\_user\_password\_rotation\_duration) | The length of the rotation window in hours. For example, 3h for a three hour window. | `string` | `null` | no |
diff --git a/modules/db_instance/variables.tf b/modules/db_instance/variables.tf
index e7fb4c33..6013f0ea 100644
--- a/modules/db_instance/variables.tf
+++ b/modules/db_instance/variables.tf
@@ -453,7 +453,7 @@ variable "cloudwatch_log_group_kms_key_id" {
################################################################################
variable "manage_master_user_password_rotation" {
- description = "Whether to manage the master user password rotation. Setting this value to false after previously having been set to true will disable automatic rotation."
+ description = "Whether to manage the master user password rotation. By default, false on creation, rotation is managed by RDS. Setting this value to false after previously having been set to true will disable automatic rotation."
type = bool
default = false
}
diff --git a/variables.tf b/variables.tf
index ce42b38f..123ec430 100644
--- a/variables.tf
+++ b/variables.tf
@@ -584,7 +584,7 @@ variable "db_instance_role_associations" {
################################################################################
variable "manage_master_user_password_rotation" {
- description = "Whether to manage the master user password rotation. Setting this value to false after previously having been set to true will disable automatic rotation."
+ description = "Whether to manage the master user password rotation. By default, false on creation, rotation is managed by RDS. Setting this value to false after previously having been set to true will disable automatic rotation."
type = bool
default = false
}