doc: Adds example for mongodbatlas_backup_compliance_policy (#3391)

* doc: Initial example for mongodbatlas_backup_compliance_policy

* doc: Add links to mongodbatlas_backup_compliance_policy example

* chore: fix lint error and example

* fix: improve v2 directory detection logic in tf-validate script

* fix shell errors

* address PR comments

* doc: Adds module example

* fix tf errors

* chore: fix tf-validate script

* address PR comments

* chore: fix use v2 in the internal cluster_with_schedule module

* docs feedback

* doc: Simplify module example

* doc: Apply docs feedback

* pr suggestions

* main.tf fixes

* doc: Add important notes regarding Backup Compliance Policy deletion considerations

* doc: Update support links

* doc: Clarify note on using Terraform Module for deletion methods

* add links from cluster docs to example

* apply PR comments

* doc: Add reference to Terraform issue for moved and removed blocks in backup compliance policy example

Author: EspenAlbert

docs/resources/advanced_cluster (preview provider 2.0.0).md

@@ -604,7 +604,7 @@ Refer to the following for full privatelink endpoint connection string examples:
   [Flex Cluster Backups](https://www.mongodb.com/docs/atlas/backup/cloud-backup/flex-cluster-backup/) for flex clusters.
   If "`backup_enabled`"  is `false` (default), the cluster doesn't use Atlas backups.
 
-* `retain_backups_enabled` - (Optional) Set to true to retain backup snapshots for the deleted cluster. M10 and above only. This only applies to the `Delete` operation. If you see the `CANNOT_DELETE_SNAPSHOT_WITH_BACKUP_COMPLIANCE_POLICY` error code, set it to explicit `true`.
+- `retain_backups_enabled` - (Optional) Set to true to retain backup snapshots for the deleted cluster. M10 and above only. This only applies to the `Delete` operation. If you see the `CANNOT_DELETE_SNAPSHOT_WITH_BACKUP_COMPLIANCE_POLICY` error code, set it to explicit `true`. To learn more, see [this](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_backup_compliance_policy/resource) example.
 
 **NOTE** Prior version of provider had parameter as `bi_connector` state will migrate it to new value you only need to update parameter in your terraform file
 

docs/resources/advanced_cluster.md

@@ -431,7 +431,7 @@ Refer to the following for full privatelink endpoint connection string examples:
   [Flex Cluster Backups](https://www.mongodb.com/docs/atlas/backup/cloud-backup/flex-cluster-backup/) for flex clusters.
   If "`backup_enabled`"  is `false` (default), the cluster doesn't use Atlas backups.
 
-* `retain_backups_enabled` - (Optional) Set to true to retain backup snapshots for the deleted cluster. M10 and above only. This only applies to the `Delete` operation. If you see the `CANNOT_DELETE_SNAPSHOT_WITH_BACKUP_COMPLIANCE_POLICY` error code, set it to explicit `true`.
+* `retain_backups_enabled` - (Optional) Set to true to retain backup snapshots for the deleted cluster. M10 and above only. This only applies to the `Delete` operation. If you see the `CANNOT_DELETE_SNAPSHOT_WITH_BACKUP_COMPLIANCE_POLICY` error code, set it to explicit `true`. To learn more, see [this](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_backup_compliance_policy/resource) example.
 
 **NOTE** Prior version of provider had parameter as `bi_connector` state will migrate it to new value you only need to update parameter in your terraform file
 

docs/resources/backup_compliance_policy.md

@@ -10,30 +10,9 @@ When enabled, the Backup Compliance Policy will be applied as the minimum backup
 
 -> **NOTE:** With Backup Compliance Policy enabled, cluster backups are retained after a cluster is deleted and backups can be used normally until retention expiration. When the Backup Compliance Policy is not enabled, Atlas deletes the cluster's associated backup snapshots when a cluster is terminated. By default, a Backup Compliance Policy is not enabled. For more details see [Back Up, Restore, and Archive Data](https://www.mongodb.com/docs/atlas/backup-restore-cluster/). 
 
--> **NOTE:** If you encounter errors when deleting an Atlas Cluster which has an associated `mongodbatlas_cloud_backup_schedule` resource, we suggest the following: 
-* `mongodbatlas_cloud_backup_schedule` fails when you delete an Atlas cluster because an existing backup compliancy policy is enabled, which is expected.
-We first suggest disabling `mongodbatlas_backup_compliance_policy` resource, which requires contacting MongoDB Support and completing an extensive verification process.
-* Second, if the first suggestion is not possible, we suggest changing the order in which terraform deletes the resource. This might not always be possible since the `mongodbatlas_cloud_backup_schedule` resource is referencing attributes from the `mongodbatlas_advanced_cluster`, or `mongodbatlas_cluster resource`, and therefore has to delete the backup schedule before deleting the cluster resource. This dependency must be defined as stated in the `mongodbatlas_cloud_backup_schedule` per the [documentation](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/cloud_backup_schedule).
-* Third, another alternative is to modify the `mongodbatlas_cloud_backup_schedule` resource by replacing all the references to the `mongodbatlas_advanced_cluster`, or `mongodbatlas_cluster`, resource with the underlying values. This enables you to delete the cluster resource first, but you must obtain values from the state to do the appropriate replacements. Since there is no more reference to previous cluster resource, terraform will allow you to delete the cluster resource without having to delete the backup schedule previously.
-  * For example, replace:
-	  ```
-	  resource "mongodbatlas_cloud_backup_schedule" "test" {
-		  project_id   = mongodbatlas_advanced_cluster.my_cluster.project_id
-		  cluster_name = mongodbatlas_advanced_cluster.my_cluster.name
-          ...
-      }
-	  ```
-    with
-	  ```
-	resource "mongodbatlas_cloud_backup_schedule" "test" {
-		project_id   = "65251446ae5f3f6ec7968b13"
-		cluster_name = "Cluster0"
-	   ...
-	}
-* Lastly, as a final resort taking into account the limitations, we recommend you to do the following:
-   * Remove the `mongodbatlas_cloud_backup_schedule` resource from the state using `terraform state rm mongodbatlas_cloud_backup_schedule.backup_retention_policy`.
-   * Remove the `mongodbatlas_cloud_backup_schedule` and `mongodbatlas_advanced_cluster`, or `mongodbatlas_cluster`, resource for the terraform configuration script and apply changes. Now only the cluster delete operation is called and runs successfully.
-     
+-> **NOTE:** If you encounter errors when deleting an Atlas Cluster that has an associated `mongodbatlas_cloud_backup_schedule` resource, follow the cleanup steps in the [`mongodbatlas_backup_compliance_policy`](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/examples/mongodbatlas_backup_compliance_policy/README.md#4-cleanup-extra-steps-when-a-backup-compliance-policy-is-enabled) example.
+
+
 ## Example Usage
 
 ```terraform

docs/resources/cloud_backup_schedule.md

@@ -4,7 +4,9 @@
 
 -> **NOTE** Groups and projects are synonymous terms. You may find `groupId` in the official documentation.
 
--> **NOTE:** If Backup Compliance Policy is enabled for the project for which this backup schedule is defined, you cannot modify the backup schedule for an individual cluster below the minimum requirements set in the Backup Compliance Policy.  See [Backup Compliance Policy Prohibited Actions and Considerations](https://www.mongodb.com/docs/atlas/backup/cloud-backup/backup-compliance-policy/#configure-a-backup-compliance-policy).
+-> **NOTE:** If Backup Compliance Policy is enabled for the project for which this backup schedule is defined, you cannot modify the backup schedule for an individual cluster below the minimum requirements set in the Backup Compliance Policy.  See [Backup Compliance Policy Prohibited Actions and Considerations](https://www.mongodb.com/docs/atlas/backup/cloud-backup/backup-compliance-policy/#configure-a-backup-compliance-policy). 
+
+If you need to remove the `mongodbatlas_cloud_backup_schedule`, follow the cleanup steps in the [`mongodbatlas_backup_compliance_policy`](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/examples/mongodbatlas_backup_compliance_policy/README.md#4-cleanup-extra-steps-when-a-backup-compliance-policy-is-enabled) example.
 
 -> **NOTE:** When creating a backup schedule you **must either** use the `depends_on` clause to indicate the cluster to which it refers **or** specify the values of `project_id` and `cluster_name` as reference of the cluster resource (e.g. `cluster_name = mongodbatlas_advanced_cluster.my_cluster.name` - see the example below). Failure in doing so will result in an error when executing the plan.
 

docs/resources/cluster.md

@@ -305,7 +305,7 @@ But in order to explicitly change `provider_instance_size_name` comment the `lif
     ```
   * The default value is false. M10 and above only.
 
-* `retain_backups_enabled` - (Optional) Set to true to retain backup snapshots for the deleted cluster. M10 and above only. This only applies to the `Delete` operation. If you see the `CANNOT_DELETE_SNAPSHOT_WITH_BACKUP_COMPLIANCE_POLICY` error code, set it to explicit `true`.
+* `retain_backups_enabled` - (Optional) Set to true to retain backup snapshots for the deleted cluster. M10 and above only. This only applies to the `Delete` operation. If you see the `CANNOT_DELETE_SNAPSHOT_WITH_BACKUP_COMPLIANCE_POLICY` error code, set it to explicit `true`. To learn more, see [this](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_backup_compliance_policy/resource) example.
 * `bi_connector_config` - (Optional) Specifies BI Connector for Atlas configuration on this cluster. BI Connector for Atlas is only available for M10+ clusters. See [BI Connector](#bi-connector) below for more details.
 * `cluster_type` - (Required) Specifies the type of the cluster that you want to modify. You cannot convert a sharded cluster deployment to a replica set deployment.
 

examples/mongodbatlas_backup_compliance_policy/module/README.md

@@ -0,0 +1,74 @@
+# Example - MongoDB Atlas Backup Compliance Policy with a module
+We recommend first to read the [resource example](../resource/README.md) as it contains all the relevant information. This example module is identical to it except that it is designed to serve as a reference for platform teams who have created their own module and make it available to internal teams for leveraging the MongoDB Atlas Terraform provider. Typically, these users do not have the ability to execute `terraform state` commands or modify the Terraform state manually.
+
+As in the resource example, the attention is focused on how to avoid the [BACKUP_POLICIES_NOT_MEETING_BACKUP_COMPLIANCE_POLICY_REQUIREMENTS](../resource/README.md#4-cleanup-extra-steps-when-a-backup-compliance-policy-is-enabled) when running `terraform destroy` on a `mongodbatlas_advanced_cluster` with `mongodbatlas_cloud_backup_schedule` and enabled backup compliance policy.
+
+To do that, we'll use:
+- an `add_schedule` variable provided by the module maintainer that controls the presence of the `mongodbatlas_cloud_backup_schedule` in the configuration
+- the `moved` and `removed` blocks used by the module user and added at the root level. For more info on why the two blocks are needed, please read this [Terraform issue](https://github.com/hashicorp/terraform/issues/34439).
+
+-> **IMPORTANT NOTE:** Read the [Backup Compliance Policy Deletion Consideration](../resource/README.md#backup-compliance-policy-deletion-consideration) before running this example.
+
+## How to delete the cluster and retain their backup snapshots
+
+Let's begin by assuming you've created a module instance with the following configuration:
+
+```terraform
+module "cluster_with_schedule" {
+  source = "./modules/cluster_with_schedule"
+
+  project_id    = var.project_id
+  instance_size = var.instance_size
+  cluster_name  = var.cluster_name
+  add_schedule  = true
+}
+```
+Note: The `add_schedule` field is set to true, indicating that a `mongodbatlas_cloud_backup_schedule` resource has been defined, as reflected in the module's source code.
+
+To proceed with the deletion, we'll update the configuration as follows:
+
+```terraform
+module "cluster_with_schedule" {
+  source = "./modules/cluster_with_schedule"
+
+  project_id    = var.project_id
+  instance_size = var.instance_size
+  cluster_name  = var.cluster_name
+  add_schedule  = false # changed
+}
+
+moved {
+  from = module.cluster_with_schedule.mongodbatlas_cloud_backup_schedule.this[0] # must be deleted with the `add_schedule` variable set to false
+  to   = mongodbatlas_cloud_backup_schedule.to_be_deleted                              # any resource name that doesn't exist works!
+}
+
+removed {
+  from = mongodbatlas_cloud_backup_schedule.to_be_deleted # any resource name that doesn't exist works!
+
+  lifecycle {
+    destroy = false
+  }
+}
+```
+
+Then when you run `terraform apply`, you should see:
+
+```bash
+[...]
+mongodbatlas_cloud_backup_schedule.to_be_deleted will no longer be managed by Terraform, but will not be destroyed
+ (destroy = false is set in the configuration)
+  (moved from module.cluster_with_schedule.mongodbatlas_cloud_backup_schedule.this[0])
+[...]
+Plan: 0 to add, 0 to change, 0 to destroy.
+```
+
+Reply `yes` to confirm the state removal of `mongodbatlas_cloud_backup_schedule`.
+
+Then run `terraform destroy` to destroy the cluster defined in `module.cluster_with_schedule.mongodbatlas_advanced_cluster.this`.
+See [Backup Compliance Policy Deletion Consideration](../resource/README.md#backup-compliance-policy-deletion-consideration) for details on the `mongodbatlas_backup_compliance_policy` deletion.
+
+## FAQ
+I get a `Removed Resource still exists error` when running `terraform apply`, how do I fix it?
+
+This error happens because the configuration still has the `mongodbatlas_cloud_backup_schedule` active.
+When using a module, together with the `removed` block, remember to add the `moved` block and set `add_schedule=false` on the `cluster_with_schedule` module.

examples/mongodbatlas_backup_compliance_policy/module/main.tf

@@ -0,0 +1,50 @@
+data "mongodbatlas_atlas_user" "this" {
+  user_id = var.user_id
+}
+
+# Be aware that deleting the `mongodbatlas_backup_compliance_policy` resource requires contacting MongoDB Support.
+resource "mongodbatlas_backup_compliance_policy" "this" {
+  project_id                 = var.project_id
+  authorized_email           = data.mongodbatlas_atlas_user.this.email_address
+  authorized_user_first_name = data.mongodbatlas_atlas_user.this.first_name
+  authorized_user_last_name  = data.mongodbatlas_atlas_user.this.last_name
+  copy_protection_enabled    = false
+  pit_enabled                = false
+  encryption_at_rest_enabled = false
+
+  restore_window_days = 7
+  on_demand_policy_item {
+    frequency_interval = 0
+    retention_unit     = "days"
+    retention_value    = 1
+  }
+  policy_item_daily {
+    frequency_interval = 0
+    retention_unit     = "days"
+    retention_value    = 1
+  }
+}
+
+module "cluster_with_schedule" {
+  source = "./modules/cluster_with_schedule"
+
+  project_id    = var.project_id
+  instance_size = var.instance_size
+  cluster_name  = var.cluster_name
+  add_schedule  = true # change to false in Step 2
+}
+
+# Step 2: For removing the `mongodbatlas_cloud_backup_schedule` resource
+# Rename the resource to avoid the `Removed Resource still exists error`
+# moved {
+#   from = module.cluster_with_schedule.mongodbatlas_cloud_backup_schedule.this[0] # must be deleted with the `add_schedule` variable set to false
+#   to   = mongodbatlas_cloud_backup_schedule.to_be_deleted                              # any resource name that doesn't exist works!
+# }
+
+# removed {
+#   from = mongodbatlas_cloud_backup_schedule.to_be_deleted # any resource name that doesn't exist works!
+
+#   lifecycle {
+#     destroy = false
+#   }
+# }

examples/mongodbatlas_backup_compliance_policy/module/modules/cluster_with_schedule/main.tf

@@ -0,0 +1,59 @@
+terraform {
+  required_providers {
+    mongodbatlas = {
+      source  = "mongodb/mongodbatlas"
+      version = "~> 1.34"
+    }
+  }
+  required_version = ">= 1.0"
+}
+
+resource "mongodbatlas_advanced_cluster" "this" {
+  project_id             = var.project_id
+  name                   = var.cluster_name
+  cluster_type           = "REPLICASET"
+  backup_enabled         = true
+  retain_backups_enabled = true
+
+  replication_specs = [
+    {
+      region_configs = [
+        {
+          provider_name = "AWS"
+          region_name   = "US_EAST_1"
+          priority      = 7
+          electable_specs = {
+            node_count    = 3
+            instance_size = var.instance_size
+            disk_size_gb  = 10
+          }
+        },
+      ]
+    }
+  ]
+}
+resource "mongodbatlas_cloud_backup_schedule" "this" {
+  count                    = var.add_schedule ? 1 : 0
+  project_id               = var.project_id
+  cluster_name             = mongodbatlas_advanced_cluster.this.name
+  reference_hour_of_day    = 19
+  reference_minute_of_hour = 15
+  restore_window_days      = 7
+  policy_item_daily {
+    frequency_interval = 1
+    retention_unit     = "days"
+    retention_value    = 1
+  }
+  copy_settings {
+    cloud_provider = "AWS"
+    frequencies = ["HOURLY",
+      "DAILY",
+      "WEEKLY",
+      "MONTHLY",
+      "YEARLY",
+    "ON_DEMAND"]
+    region_name        = "US_EAST_2"
+    zone_id            = mongodbatlas_advanced_cluster.this.replication_specs[0].zone_id
+    should_copy_oplogs = false
+  }
+}

examples/mongodbatlas_backup_compliance_policy/module/modules/cluster_with_schedule/variables.tf

@@ -0,0 +1,15 @@
+variable "project_id" {
+  type = string
+}
+
+variable "cluster_name" {
+  type = string
+}
+
+variable "instance_size" {
+  type = string
+}
+
+variable "add_schedule" {
+  type = bool
+}

examples/mongodbatlas_backup_compliance_policy/module/provider.tf

@@ -0,0 +1,4 @@
+provider "mongodbatlas" {
+  public_key  = var.public_key
+  private_key = var.private_key
+}