From 685b01b64754953db29a89f79488f560e56e5731 Mon Sep 17 00:00:00 2001
From: Melissa Greenbaum <69476188+magreenbaum@users.noreply.github.com>
Date: Fri, 20 Dec 2024 09:16:09 -0500
Subject: [PATCH] docs: Clarify the `manage_master_user_password_rotation`
 functionality  (#478)

---
 README.md    | 2 +-
 main.tf      | 6 ++++++
 variables.tf | 2 +-
 3 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index af333a1..d03d05a 100644
--- a/README.md
+++ b/README.md
@@ -351,7 +351,7 @@ No modules.
 | <a name="input_is_primary_cluster"></a> [is\_primary\_cluster](#input\_is\_primary\_cluster) | Determines whether cluster is primary cluster with writer instance (set to `false` for global cluster and replica clusters) | `bool` | `true` | no |
 | <a name="input_kms_key_id"></a> [kms\_key\_id](#input\_kms\_key\_id) | The ARN for the KMS encryption key. When specifying `kms_key_id`, `storage_encrypted` needs to be set to `true` | `string` | `null` | no |
 | <a name="input_manage_master_user_password"></a> [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 `master_password` is provided | `bool` | `true` | no |
-| <a name="input_manage_master_user_password_rotation"></a> [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 |
+| <a name="input_manage_master_user_password_rotation"></a> [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. There is not currently a way to disable this on initial creation even when set to false. Setting this value to false after previously having been set to true will disable automatic rotation. | `bool` | `false` | no |
 | <a name="input_master_password"></a> [master\_password](#input\_master\_password) | Password for the master DB user. Note that this may show up in logs, and it will be stored in the state file. Required unless `manage_master_user_password` is set to `true` or unless `snapshot_identifier` or `replication_source_identifier` is provided or unless a `global_cluster_identifier` is provided when the cluster is the secondary cluster of a global database | `string` | `null` | no |
 | <a name="input_master_user_password_rotate_immediately"></a> [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 |
 | <a name="input_master_user_password_rotation_automatically_after_days"></a> [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 `master_user_password_rotation_automatically_after_days` or `master_user_password_rotation_schedule_expression` must be specified | `number` | `null` | no |
diff --git a/main.tf b/main.tf
index 1cb7442..d18ab9e 100644
--- a/main.tf
+++ b/main.tf
@@ -453,6 +453,12 @@ resource "aws_rds_cluster_activity_stream" "this" {
 # Managed Secret Rotation
 ################################################################################
 
+# There is not currently a way to disable secret rotation on an initial apply.
+# In order to use master password secrets management without a rotation, the following workaround can be used:
+# `manage_master_user_password_rotation` must be set to true first and applied followed by setting it to false and another apply.
+# Note: when setting `manage_master_user_password_rotation` to true, a schedule must also be set using `master_user_password_rotation_schedule_expression` or `master_user_password_rotation_automatically_after_days`.
+# To prevent password from being immediately rotated when implementing this workaround, set `master_user_password_rotate_immediately` to false.
+# See: https://github.com/hashicorp/terraform-provider-aws/issues/37779
 resource "aws_secretsmanager_secret_rotation" "this" {
   count = local.create && var.manage_master_user_password && var.manage_master_user_password_rotation ? 1 : 0
 
diff --git a/variables.tf b/variables.tf
index 8b49969..8e46247 100644
--- a/variables.tf
+++ b/variables.tf
@@ -789,7 +789,7 @@ variable "engine_native_audit_fields_included" {
 ################################################################################
 
 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. There is not currently a way to disable this on initial creation even when set to false. Setting this value to false after previously having been set to true will disable automatic rotation."
   type        = bool
   default     = false
 }