doc: Adds initial structure for module examples cluster_to_advanced_cluster

examples/modules/cluster_to_advanced_cluster/README.md

@@ -0,0 +1,66 @@
+# Module - `cluster` to `advanced_cluster`
+
+The purpose of this example is to demonstrate the upgrade path from `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster` using a Terraform module.
+The example contains three module versions:
+
+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: Update the actual Variable counts  -->
+
+## 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"
+```
+
+* Configure `variables.tfvars`
+<!-- TODO: Example variables -->
+```tfvars
+# todo: add example variable declaration here
+```
+
+## Usage
+
+### `v1`
+
+```bash
+# uncomment the code in main.tf marked with v1, ensure v2 and v3 is commented
+export 
+terraform init
+terraform apply -var-file=variables.tfvars
+```
+
+### `v2`
+
+```bash
+# uncomment the code in main.tf marked with v2, ensure v1 and v3 is commented
+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
+```
+
+### `v3`
+
+```bash
+# uncomment the code in main.tf marked with v3, ensure v1 and v2 is commented
+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
+```
+
+### Cleanup with `terraform destroy`
+
+```bash
+terraform destroy
+```

examples/modules/cluster_to_advanced_cluster/main.tf

@@ -0,0 +1,20 @@
+provider "mongodbatlas" {
+  public_key  = var.public_key
+  private_key = var.private_key
+}
+
+# v1
+module "cluster" {
+  source = "./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/modules/cluster_to_advanced_cluster/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/modules/cluster_to_advanced_cluster/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/modules/cluster_to_advanced_cluster/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/modules/cluster_to_advanced_cluster/v1/versions.tf

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

examples/modules/cluster_to_advanced_cluster/v2/versions.tf

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

examples/modules/cluster_to_advanced_cluster/v3/versions.tf

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

examples/modules/cluster_to_advanced_cluster/variables.tf

@@ -0,0 +1,82 @@
+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
+    }]
+  }]
+}
+
+# v3 extra variables (TODO)

examples/modules/cluster_to_advanced_cluster/versions.tf

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