doc: Adds basic module for mongodbatlas_advanced_cluster (Preview for MongoDB Atlas Provider 2.0.0) (#3270)

* doc: Adds example of v4 module of new advanced_cluster

* refactor: move v4 to basic_module

* chore: update external issue links

* feat: add call to basic module for mongodbatlas_advanced_cluster

* doc: update README.md with description and add example.tfvars

* refactor: move files back to v4

* doc: Add description for the module_maintainer and remove old variables.

* chore: remove unused link

* apply suggestions

Author: EspenAlbert

docs/guides/cluster-to-advanced-cluster-migration-guide.md

@@ -56,7 +56,7 @@ The basic experience when using the `moved` block is as follows:
 3. Comment out or delete the `mongodbatlas_cluster` resource definition.
 4. Update the references from your previous cluster resource: `mongodbatlas_cluster.this.XXXX` to the new `mongodbatlas_advanced_cluster.this.XXX`.
    - Double check [output-changes](#output-changes) to ensure the underlying configuration stays unchanged.
-   - If you are using output variables that use the new resource `mongodbatlas_advanced_cluster.this`, the plan output can be more verbose than expected (extra `Note: Objects have changed outside of Terraform` section). Consider adding/updating output variables only **after** performing the move (see more in the [Github Issue](https://github.com/hashicorp/terraform-plugin-framework/issues/1109)).
+   - If you are using output variables that use the new resource `mongodbatlas_advanced_cluster.this`, the plan output can be more verbose than expected (extra `Note: Objects have changed outside of Terraform` section). Consider adding/updating output variables only **after** performing the move (see more in the [Github Issue](https://github.com/hashicorp/terraform/issues/36796).
 5. Add the `moved` block to your configuration file, e.g.:
 ```terraform
 moved {

examples/migrate_cluster_to_advanced_cluster/basic/README.md

@@ -49,7 +49,7 @@ The [CLI Plugin](https://github.com/mongodb-labs/atlas-cli-plugin-terraform) hel
 ## Manual updates to the Terraform configuration
 
 1. Ensure all references are updated (see example of updates in [outputs.tf](outputs.tf))
-   1. Ensure you are not adding any output variables that use the new `mongodbatlas_advanced_cluster` resource. Referencing the new resource before moving can lead to a more verbose plan output (extra `Note: Objects have changed outside of Terraform` section) when performing the move (see more in the [Github Issue](https://github.com/hashicorp/terraform-plugin-framework/issues/1109)).
+   1. Ensure you are not adding any output variables that use the new `mongodbatlas_advanced_cluster` resource. Referencing the new resource before moving can lead to a more verbose plan output (extra `Note: Objects have changed outside of Terraform` section) when performing the move (see more in the [Github Issue](https://github.com/hashicorp/terraform/issues/36796).
 2. Comment out the `mongodbatlas_cluster` in `{CLUSTER_IN}.tf`
 3. Add the moved block for each resource migrated in `{CLUSTER_OUT}.tf`
 ```terraform

examples/migrate_cluster_to_advanced_cluster/module_maintainer/README.md

@@ -9,6 +9,7 @@ Step | Purpose | Resources
 [Step 1](./v1) | Baseline | `mongodbatlas_cluster`
 [Step 2](./v2) | Migrate to advanced_cluster with no change in variables or plan | `mongodbatlas_advanced_cluster`
 [Step 3](./v3) | Use the latest features of advanced_cluster | `mongodbatlas_advanced_cluster`
+[Step 4](./v4) | Future proofs the module by removing all `mongodbatlas_cluster` references | `mongodbatlas_advanced_cluster`
 
 The rest of this document summarizes the different implementations:
 
@@ -83,15 +84,15 @@ moved {
 - Adds `data "mongodbatlas_cluster" "this"` to avoid breaking changes in `outputs.tf` (see below).
 
 ### [`outputs.tf`](v2/outputs.tf)
-- Ensure you are not adding any output variables that use the new `mongodbatlas_advanced_cluster` resource. Referencing the new resource before moving can lead to a more verbose plan output (extra `Note: Objects have changed outside of Terraform` section) when performing the move (see more in the [Github Issue](https://github.com/hashicorp/terraform-plugin-framework/issues/1109)).
+- Ensure you are not adding any output variables that use the new `mongodbatlas_advanced_cluster` resource. Referencing the new resource before moving can lead to a more verbose plan output (extra `Note: Objects have changed outside of Terraform` section) when performing the move (see more in the [Github Issue](https://github.com/hashicorp/terraform/issues/36796).
 - Ensure compatibility with `v1` outputs by modifying:
   - `replication_specs`, uses `data.mongodbatlas_cluster.this.replication_specs` to keep the same format.
   - `mongodbatlas_cluster`, uses the `data.mongodbatlas_cluster.this` to keep the same format.
 
 
 ## Step 3: Module `v3` Implementation Changes and Highlights
 This module adds variables to support the latest `mongodbatlas_advanced_cluster` features while staying compatible with the old input variables.
-The module supports standalone usage when there is no existing `mongodbatlas_cluster` and also upgrading from `v1` using a `moved` block. However, upgrading directly from `v1` can lead to a more verbose plan output (extra `Note: Objects have changed outside of Terraform` section) when performing the move (see more in the [Github Issue](https://github.com/hashicorp/terraform-plugin-framework/issues/1109)).
+The module supports standalone usage when there is no existing `mongodbatlas_cluster` and also upgrading from `v1` using a `moved` block. However, upgrading directly from `v1` can lead to a more verbose plan output (extra `Note: Objects have changed outside of Terraform` section) when performing the move (see more in the [Github Issue](https://github.com/hashicorp/terraform/issues/36796).
 The module also supports changing an existing `mongodbatlas_advanced_cluster` created in `v2`.
 
 ### [`variables.tf`](v3/variables.tf)
@@ -144,3 +145,25 @@ output "mongodbatlas_cluster" {
   description = "Full cluster configuration for mongodbatlas_cluster resource, will be null if var.replication_specs_new is set"
 }
 ```
+
+## Step 4: Module `v4` Implementation Changes and Highlights
+This module marks the end of the migration to `mongodbatlas_advanced_cluster`.
+We future-proof the module by removing references to the `mongodbatlas_cluster` data source and only allowing the latest schema for the `replication_specs` variable.
+A major version bump would typically accompany this module version since we remove and rename input and output variables.
+The reduced compatibility simplifies the module but forces the module user to rename their input variable `replication_specs_new` to `replication_specs`.
+You can keep the `replication_specs_new` variable name, but it might confuse new module users and complicate future updates.
+
+### [`variables.tf`](v4/variables.tf)
+- Remove the `replication_specs`, `auto_scaling_disk_gb_enabled`, `disk_size`, `provider_name`, and `instance_size`.
+- Rename the `replication_specs_new` to `replication_specs`.
+- Remove the default (`[]`) of `replication_specs`.
+
+### [`main.tf`](v4/main.tf)
+- Remove `locals` block (no longer needed to modify the old replication_spec variable to fit the new `mongodbatlas_advanced_cluster` schema).
+- Remove the `moved` block.
+- Remove the `mongodbatlas_cluster` data source.
+
+### [`outputs.tf`](v4/outputs.tf)
+- Remove conditional logic from `replication_specs`.
+- Flatten `mongodb_connection_strings` to use `mongodbatlas_advanced_cluster.this.connection_strings` directly instead of wrapping inside a list.
+- Remove the `mongodbatlas_cluster`.

examples/migrate_cluster_to_advanced_cluster/module_maintainer/v4/main.tf

@@ -0,0 +1,8 @@
+resource "mongodbatlas_advanced_cluster" "this" {
+  project_id             = var.project_id
+  name                   = var.cluster_name
+  cluster_type           = var.cluster_type
+  mongo_db_major_version = var.mongo_db_major_version
+  replication_specs      = var.replication_specs
+  tags                   = var.tags
+}

examples/migrate_cluster_to_advanced_cluster/module_maintainer/v4/outputs.tf

@@ -0,0 +1,24 @@
+output "mongodb_connection_strings" {
+  value       = mongodbatlas_advanced_cluster.this.connection_strings
+  description = "Map of Uniform Resource Locators that point to the MongoDB database."
+}
+
+output "cluster_name" {
+  value       = mongodbatlas_advanced_cluster.this.name
+  description = "MongoDB Atlas cluster name"
+}
+
+output "project_id" {
+  value       = mongodbatlas_advanced_cluster.this.project_id
+  description = "MongoDB Atlas project id"
+}
+
+output "replication_specs" {
+  value       = mongodbatlas_advanced_cluster.this.replication_specs
+  description = "Replication Specs for the cluster"
+}
+
+output "mongodbatlas_advanced_cluster" {
+  value       = resource.mongodbatlas_advanced_cluster.this
+  description = "Full cluster configuration for mongodbatlas_advanced_cluster resource"
+}

examples/migrate_cluster_to_advanced_cluster/module_maintainer/v4/variables.tf

@@ -0,0 +1,65 @@
+variable "project_id" {
+  description = "Unique 24-hexadecimal digit string that identifies your project. Use the `/groups` at https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Projects/operation/listProjects endpoint to retrieve all projects to which the authenticated user has access.  **NOTE**: Groups and projects are synonymous terms. Your group id is the same as your project id. For existing groups, your group/project id remains the same. The resource and corresponding endpoints use the term groups"
+  type        = string
+}
+
+variable "cluster_name" {
+  description = "Human-readable label that identifies this cluster."
+  type        = string
+}
+
+variable "cluster_type" {
+  description = "Configuration of nodes that comprise the cluster."
+  type        = string
+}
+
+
+variable "mongo_db_major_version" {
+  description = "MongoDB major version of the cluster.  On creation: Choose from the available versions of MongoDB, or leave unspecified for the current recommended default in the MongoDB Cloud platform. The recommended version is a recent Long Term Support version. The default is not guaranteed to be the most recently released version throughout the entire release cycle. For versions available in a specific project, see the linked documentation or use the API endpoint for https://www.mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Projects/operation/getProjectLtsVersions.   On update: Increase version only by 1 major version at a time. If the cluster is pinned to a MongoDB feature compatibility version exactly one major version below the current MongoDB version, the MongoDB version can be downgraded to the previous major version."
+  type        = string
+}
+
+variable "tags" {
+  description = "Map that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the cluster."
+  type        = map(string)
+  default     = {}
+}
+
+variable "replication_specs" {
+  description = "List of replication specifications using new mongodbatlas_advanced_cluster format"
+  type = list(object({
+    zone_name = optional(string, "Zone 1")
+
+    region_configs = list(object({
+      region_name   = string
+      provider_name = string
+      priority      = optional(number, 7)
+
+      auto_scaling = optional(object({
+        disk_gb_enabled = optional(bool, false)
+      }), null)
+
+      read_only_specs = optional(object({
+        node_count      = number
+        instance_size   = string
+        disk_size_gb    = optional(number, null)
+        ebs_volume_type = optional(string, null)
+        disk_iops       = optional(number, null)
+      }), null)
+      analytics_specs = optional(object({
+        node_count      = number
+        instance_size   = string
+        disk_size_gb    = optional(number, null)
+        ebs_volume_type = optional(string, null)
+        disk_iops       = optional(number, null)
+      }), null)
+      electable_specs = object({
+        node_count      = number
+        instance_size   = string
+        disk_size_gb    = optional(number, null)
+        ebs_volume_type = optional(string, null)
+        disk_iops       = optional(number, null)
+      })
+    }))
+  }))
+}

examples/migrate_cluster_to_advanced_cluster/module_maintainer/v4/versions.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_providers {
+    mongodbatlas = {
+      source  = "mongodb/mongodbatlas"
+      version = "~> 1.29"
+    }
+  }
+  required_version = ">= 1.0"
+}

examples/migrate_cluster_to_advanced_cluster/module_user/README.md

@@ -9,6 +9,7 @@ Migration Step Code | `mongodbatlas` version | Config Changes | Plan Changes
 [Step 1](./v1) | `<= 1.29.0` | Baseline configuration | -
 [Step 2](./v2) | `>= 1.29.0` | Only change to `v2` module version | No changes. Only moved.
 [Step 3](./v3) | `>= 1.29.0` | Usage of new variables to support multi-cloud and independent shard scaling | Yes (new features)
+[Step 4](./v4) | `>= 1.29.0` | Rename `replication_specs_new` to `replication_specs` | No
 
 
 The rest of this example is a step by step guide on how to migrate from `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster`:
@@ -26,8 +27,8 @@ The rest of this example is a step by step guide on how to migrate from `mongodb
 - [Cleanup with `terraform destroy`](#cleanup-with-terraform-destroy)
 
 ## Dependencies
-- Terraform CLI >= 1.8-
-- Terraform MongoDB Atlas Provider `>=v1.29.0`-
+- Terraform CLI >= 1.8
+- Terraform MongoDB Atlas Provider `>=v1.29.0`
 - A MongoDB Atlas account.
 - Configure the provider (can also be done by configuring `public_key` and `private_key` in a `provider.tfvars`).
 
@@ -102,6 +103,22 @@ terraform init -upgrade # in case your Atlas Provider version needs to be upgrad
 terraform apply -var-file=../v3.tfvars # updated variables to enable latest mongodb_advanced_cluster features
 ```
 
+## Step 4: Adapt to the future proof `v4` module without any `mongodbatlas_cluster` references
+
+### Update `v4.tfvars`
+
+See the example in [v4.tfvars](v4.tfvars).
+This example renames the variable `replication_specs_new` to `replication_specs`.
+
+### Run `terraform plan` to ensure no plan changes
+```bash
+cd v4
+cp ../v3/terraform.tfstate . # if you are not using a remote state
+export MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER=true # necessary to use the latest schema
+terraform init -upgrade # in case your Atlas Provider version needs to be upgraded
+terraform plan -var-file=../v4.tfvars
+```
+
 ## Cleanup with `terraform destroy`
 
 ```bash

examples/migrate_cluster_to_advanced_cluster/module_user/v4.tfvars

@@ -0,0 +1,49 @@
+project_id             = "664619d870c247237f4b86a6"
+cluster_name           = "module-cluster"
+cluster_type           = "SHARDED"
+mongo_db_major_version = "8.0"
+
+tags = {
+  env    = "examples"
+  module = "basic_module"
+}
+
+replication_specs = [
+  { # shard 1
+    region_configs = [{
+      electable_specs = {
+        disk_size_gb  = 50 # must be the same for all replication specs
+        instance_size = "M30"
+        node_count    = 3
+      }
+      priority      = 7
+      provider_name = "AWS"
+      read_only_specs = {
+        disk_size_gb  = 50
+        instance_size = "M30"
+        node_count    = 1
+      }
+      region_name = "US_EAST_1"
+    }]
+    zone_name = "Zone 1"
+  },
+  { # shard 2
+    region_configs = [{
+      electable_specs = {
+        disk_size_gb  = 50
+        instance_size = "M50"
+        node_count    = 3
+      }
+      priority      = 7
+      provider_name = "AWS"
+      read_only_specs = {
+        disk_size_gb  = 50
+        instance_size = "M50"
+        node_count    = 1
+      }
+      region_name = "US_EAST_1"
+    }]
+    zone_name = "Zone 1"
+  },
+]
+

examples/migrate_cluster_to_advanced_cluster/module_user/v4/main.tf

@@ -0,0 +1,20 @@
+provider "mongodbatlas" {
+  public_key  = var.public_key
+  private_key = var.private_key
+}
+
+module "cluster" {
+  source = "../../module_maintainer/v4"
+
+  cluster_name           = var.cluster_name
+  cluster_type           = var.cluster_type
+  mongo_db_major_version = var.mongo_db_major_version
+  project_id             = var.project_id
+  replication_specs      = var.replication_specs
+  tags                   = var.tags
+}
+
+output "mongodb_connection_strings" {
+  description = "Collection of Uniform Resource Locators that point to the MongoDB database."
+  value       = module.cluster.mongodb_connection_strings
+}