doc: Adds initial structure for module examples cluster_to_advanced_cluster

examples/migrate_cluster_to_advanced_cluster/module_maintainer/README.md

@@ -0,0 +1,13 @@
+# Module Maintainer - `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster`
+
+The purpose of this example is to demonstrate how a Terraform module can help the migration from `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster`.
+The example contains three module versions:
+
+<!-- Update Variable count -->
+Version | Purpose | Variables | Resources
+--- | --- | --- | ---
+[v1](./v1) | Baseline | 5 | `mongodbatlas_cluster`
+[v2](./v2) | Migrate to advanced_cluster with no change in variables or plan | 5 | `mongodbatlas_advanced_cluster`
+[v3](./v3) | Use the latest features of advanced_cluster | 10 | `mongodbatlas_advanced_cluster`
+
+<!-- TODO: Add highlights of module implementations -->

examples/migrate_cluster_to_advanced_cluster/module_maintainer/v1/main.tf

@@ -0,0 +1,44 @@
+resource "mongodbatlas_cluster" "this" {
+  lifecycle {
+    precondition {
+      condition     = !(var.auto_scaling_disk_gb_enabled && var.disk_size > 0)
+      error_message = "Must use either auto_scaling_disk_gb_enabled or disk_size, not both."
+    }
+  }
+
+  project_id = var.project_id
+  name       = var.cluster_name
+
+  auto_scaling_disk_gb_enabled = var.auto_scaling_disk_gb_enabled
+  cluster_type                 = var.cluster_type
+  disk_size_gb                 = var.disk_size
+  mongo_db_major_version       = var.mongo_db_major_version
+  provider_instance_size_name  = var.instance_size
+  provider_name                = var.provider_name
+
+  dynamic "tags" {
+    for_each = var.tags
+    content {
+      key   = tags.key
+      value = tags.value
+    }
+  }
+
+  dynamic "replication_specs" {
+    for_each = var.replication_specs
+    content {
+      num_shards = replication_specs.value.num_shards
+      zone_name  = replication_specs.value.zone_name
+
+      dynamic "regions_config" {
+        for_each = replication_specs.value.regions_config
+        content {
+          electable_nodes = regions_config.value.electable_nodes
+          priority        = regions_config.value.priority
+          read_only_nodes = regions_config.value.read_only_nodes
+          region_name     = regions_config.value.region_name
+        }
+      }
+    }
+  }
+}

examples/migrate_cluster_to_advanced_cluster/module_maintainer/v1/outputs.tf

@@ -0,0 +1,24 @@
+output "mongodb_raw_connection_strings" {
+  value       = mongodbatlas_cluster.this.connection_strings
+  description = "This is the raw list of MongoDB Atlas connection strings. Note, these do not show the connection mechanism of the database details"
+}
+
+output "cluster_name" {
+  value       = mongodbatlas_cluster.this.name
+  description = "MongoDB Atlas cluster name"
+}
+
+output "project_id" {
+  value       = mongodbatlas_cluster.this.project_id
+  description = "MongoDB Atlas project id"
+}
+
+output "replication_specs" {
+  value       = mongodbatlas_cluster.this.replication_specs
+  description = "Replication Specs for cluster"
+}
+
+output "mongodbatlas_cluster" {
+  value       = mongodbatlas_cluster.this
+  description = "Full cluster configuration for mongodbatlas_cluster resource"
+}

examples/migrate_cluster_to_advanced_cluster/module_maintainer/v1/variables.tf

@@ -0,0 +1,68 @@
+variable "project_id" {
+  type = string
+}
+
+variable "cluster_name" {
+  type = string
+}
+
+variable "cluster_type" {
+  type = string
+
+  validation {
+    condition     = contains(["REPLICASET", "SHARDED", "GEOSHARDED"], var.cluster_type)
+    error_message = "Valid supported cluster types are \"REPLICASET\", \"SHARDED\" or \"GEOSHARDED\"."
+  }
+}
+
+variable "instance_size" {
+  type = string
+}
+
+variable "mongo_db_major_version" {
+  type = string
+}
+
+variable "provider_name" {
+  type = string
+}
+
+# OPTIONAL VARIABLES
+
+variable "disk_size" {
+  type    = number
+  default = 0
+}
+
+variable "auto_scaling_disk_gb_enabled" {
+  type    = bool
+  default = false
+}
+
+variable "tags" {
+  type    = map(string)
+  default = {}
+}
+
+variable "replication_specs" {
+  type = list(object({
+    num_shards = number
+    zone_name  = string
+    regions_config = set(object({
+      region_name     = string
+      electable_nodes = number
+      priority        = number
+      read_only_nodes = number
+    }))
+  }))
+  default = [{
+    num_shards = 1
+    zone_name  = "Zone 1"
+    regions_config = [{
+      region_name     = "US_EAST_1"
+      electable_nodes = 3
+      priority        = 7
+      read_only_nodes = 0
+    }]
+  }]
+}

examples/migrate_cluster_to_advanced_cluster/module_maintainer/v1/versions.tf

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

examples/migrate_cluster_to_advanced_cluster/module_maintainer/v2/versions.tf

@@ -0,0 +1,3 @@
+terraform {
+  required_version = ">= 1.0"
+}

examples/migrate_cluster_to_advanced_cluster/module_maintainer/v3/versions.tf

@@ -0,0 +1,3 @@
+terraform {
+  required_version = ">= 1.0"
+}

examples/migrate_cluster_to_advanced_cluster/module_user/README.md

@@ -0,0 +1,94 @@
+# Module User - `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster`
+
+The purpose of this example is to demonstrate the User experience when upgrading `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster`.
+
+Module Version | `mongodbatlas` version | Config Changes | Plan Changes
+--- | --- | --- | ---
+[v1](./v1) | <= PLACEHOLDER_TPF_RELEASE | Baseline configuration | -
+[v2](./v2) | >= PLACEHOLDER_TPF_RELEASE | Only change to `v2` module version | No changes. Only moved.
+[v3](./v3) | >= PLACEHOLDER_TPF_RELEASE | Usage of new variables to support multi-cloud and independent shard scaling | Yes (new features)
+
+
+## Dependencies
+<!-- TODO: Update XX versions -->
+<!-- TODO: Update the `versions.tf` inside each vX -->
+* Terraform CLI >= 1.X
+* Terraform MongoDB Atlas Provider v1.XX.0
+* A MongoDB Atlas account
+* Configure the provider (can also be done with `variables.tfvars`)
+
+```bash
+export MONGODB_ATLAS_PUBLIC_KEY="xxxx"
+export MONGODB_ATLAS_PRIVATE_KEY="xxxx"
+```
+
+## Usage
+
+**Configure `variables.tfvars`:**
+
+```tfvars
+project_id             = "664619d870c247237f4b86a6"
+cluster_name           = "module-cluster"
+cluster_type           = "SHARDED"
+instance_size          = "M10"
+mongo_db_major_version = "8.0"
+provider_name          = "AWS"
+disk_size              = 40
+tags = {
+  env    = "examples"
+  module = "cluster_to_advanced_cluster"
+}
+replication_specs = [
+  {
+    num_shards = 2
+    zone_name  = "Zone 1"
+    regions_config = [
+      {
+        region_name     = "US_EAST_1"
+        electable_nodes = 3
+        priority        = 7
+        read_only_nodes = 0
+      }
+    ]
+  }
+]
+```
+
+
+### `v1`
+
+```bash
+cd v1
+terraform init
+terraform apply -var-file=variables.tfvars
+```
+
+### `v2`
+
+```bash
+cd v2
+export MONGODB_ATLAS_ADVANCED_CLUSTER_V2_SCHEMA=true # necessary for the `moved` block to work
+terraform init -upgrade # in case your Atlas Provider version needs to be upgraded
+terraform apply -var-file=variables.tfvars # notice the same variables used as in `v1`
+```
+
+### `v3`
+
+**Configure `variables-updated.tfvars`:**
+
+```tfvars
+# TODO: Use the new variables for latest features
+```
+
+```bash
+cd v3
+export MONGODB_ATLAS_ADVANCED_CLUSTER_V2_SCHEMA=true # necessary for the `moved` block to work
+terraform init -upgrade # in case your Atlas Provider version needs to be upgraded
+terraform apply -var-file=variables-updated.tfvars # updated variables to enable latest mongodb_advanced_cluster features
+```
+
+### Cleanup with `terraform destroy`
+
+```bash
+terraform destroy
+```

examples/migrate_cluster_to_advanced_cluster/module_user/v1/main.tf

@@ -0,0 +1,19 @@
+provider "mongodbatlas" {
+  public_key  = var.public_key
+  private_key = var.private_key
+}
+
+module "cluster" {
+  source = "../../module_maintainer/v1"
+
+  auto_scaling_disk_gb_enabled = var.auto_scaling_disk_gb_enabled
+  cluster_name                 = var.cluster_name
+  cluster_type                 = var.cluster_type
+  disk_size                    = var.disk_size
+  instance_size                = var.instance_size
+  mongo_db_major_version       = var.mongo_db_major_version
+  project_id                   = var.project_id
+  provider_name                = var.provider_name
+  replication_specs            = var.replication_specs
+  tags                         = var.tags
+}

examples/migrate_cluster_to_advanced_cluster/module_user/v1/variables.tf

@@ -0,0 +1,80 @@
+variable "public_key" {
+  description = "Public API key to authenticate to Atlas"
+  type        = string
+  default     = ""
+}
+variable "private_key" {
+  description = "Private API key to authenticate to Atlas"
+  type        = string
+  default     = ""
+}
+
+# v1 & v2 variables
+variable "project_id" {
+  type = string
+}
+
+variable "cluster_name" {
+  type = string
+}
+
+variable "cluster_type" {
+  type = string
+
+  validation {
+    condition     = contains(["REPLICASET", "SHARDED", "GEOSHARDED"], var.cluster_type)
+    error_message = "Valid supported cluster types are \"REPLICASET\", \"SHARDED\" or \"GEOSHARDED\"."
+  }
+}
+
+variable "instance_size" {
+  type = string
+}
+
+variable "mongo_db_major_version" {
+  type = string
+}
+
+variable "provider_name" {
+  type = string
+}
+
+# OPTIONAL VARIABLES
+
+variable "disk_size" {
+  type    = number
+  default = 0
+}
+
+variable "auto_scaling_disk_gb_enabled" {
+  type    = bool
+  default = false
+}
+
+variable "tags" {
+  type    = map(string)
+  default = {}
+}
+
+variable "replication_specs" {
+  type = list(object({
+    num_shards = number
+    zone_name  = string
+    regions_config = set(object({
+      region_name     = string
+      electable_nodes = number
+      priority        = number
+      read_only_nodes = number
+    }))
+  }))
+  default = [{
+    num_shards = 1
+    zone_name  = "Zone 1"
+    regions_config = [{
+      region_name     = "US_EAST_1"
+      electable_nodes = 3
+      priority        = 7
+      read_only_nodes = 0
+    }]
+  }]
+}

examples/migrate_cluster_to_advanced_cluster/module_user/v1/versions.tf

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

examples/migrate_cluster_to_advanced_cluster/module_user/v2/versions.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_providers {
+    mongodbatlas = {
+      source  = "mongodb/mongodbatlas"
+      version = "~> 1.26" # todo: PLACEHOLDER_TPF_RELEASE
+    }
+  }
+  required_version = ">= 1.0" # todo: minimum moved block supported version
+}

examples/migrate_cluster_to_advanced_cluster/module_user/v3/versions.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_providers {
+    mongodbatlas = {
+      source  = "mongodb/mongodbatlas"
+      version = "~> 1.26" # todo: PLACEHOLDER_TPF_RELEASE
+    }
+  }
+  required_version = ">= 1.0" # todo: minimum moved block supported version
+}