doc: Adds migration guides to transition out of Serverless and Shared…

…-tier clusters (#2746) * wip: migration guides * add details on 1.22 guide * remove guide, will be in resource docs * wip: correct details on 1.22 guide * added migration guide for serverless to flex and serverless to dedicated * added migration guide for shared-tier to flex * added migration guide for serverless to free * implementing review feedback * implementing feedback to guide * changes to migration guide * Adjustments to migration guides * put URL instead of placeholder * move post before pre autoconversion guides, clarify serverless to dedicated * pr comment * pr comments * Update docs/guides/1.22.0-upgrade-guide.md Co-authored-by: lmkerbey-mdb <[email protected]> * Update docs/guides/serverless-shared-migration-guide.md Co-authored-by: lmkerbey-mdb <[email protected]> * Update docs/guides/1.22.0-upgrade-guide.md Co-authored-by: lmkerbey-mdb <[email protected]> * Update docs/guides/serverless-shared-migration-guide.md Co-authored-by: lmkerbey-mdb <[email protected]> * Update docs/guides/serverless-shared-migration-guide.md Co-authored-by: lmkerbey-mdb <[email protected]> * Update docs/guides/serverless-shared-migration-guide.md Co-authored-by: lmkerbey-mdb <[email protected]> * Update docs/guides/serverless-shared-migration-guide.md Co-authored-by: cveticm <[email protected]> * Update docs/guides/serverless-shared-migration-guide.md Co-authored-by: cveticm <[email protected]> --------- Co-authored-by: Melanija Cvetic <[email protected]> Co-authored-by: lmkerbey-mdb <[email protected]> Co-authored-by: cveticm <[email protected]>
mongodb · Nov 21, 2024 · f828c3e · f828c3e
1 parent 4529b81
commit f828c3e
Show file tree

Hide file tree

Showing 2 changed files with 297 additions and 0 deletions.
diff --git a/docs/guides/1.22.0-upgrade-guide.md b/docs/guides/1.22.0-upgrade-guide.md
@@ -0,0 +1,30 @@
+---
+page_title: "Upgrade Guide 1.22.0"
+---
+
+# MongoDB Atlas Provider 1.22.0: Upgrade and Information Guide
+
+The Terraform MongoDB Atlas Provider version 1.22.0 has a number of new and exciting features.
+
+## New Resources, Data Sources, and Features
+
+- You can now manage Flex Clusters with the new `mongodbatlas_flex_cluster` resource and corresponding data sources. The feature is available as a preview feature. To learn more, please review `mongodbatlas_flex_cluster` [resource documentation](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/flex_cluster).
+
+## Deprecations and removals
+
+- `continuous_backup_enabled` attribute is deprecated in `mongodbatlas_serverless_instance` resource and data sources. If your workload requires this feature, we recommend switching to Atlas Dedicated clusters. To learn more, see the [Migration Guide: Transition out of Serverless Instances and Shared-tier clusters](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/serverless-shared-migration-guide).
+- `auto_indexing` attribute is deprecated in `mongodbatlas_serverless_instance` resource and data sources. If your workload requires this feature, we recommend switching to Atlas Dedicated clusters. To learn more, please see the [Migration Guide: Transition out of Serverless Instances and Shared-tier clusters](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/serverless-shared-migration-guide).
+- `mongodbatlas_privatelink_endpoint_serverless` resource is deprecated. If your workload requires this feature, we recommend switching to Atlas Dedicated clusters. To learn more, please see the [Migration Guide: Transition out of Serverless Instances and Shared-tier clusters](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/serverless-shared-migration-guide).
+- `mongodbatlas_privatelink_endpoint_service_serverless` resource, `mongodbatlas_privatelink_endpoint_service_serverless` and `mongodbatlas_privatelink_endpoints_service_serverless` data sources are deprecated. If your workload requires this feature, we recommend switching to Atlas Dedicated clusters. To learn more, please see the [Migration Guide: Transition out of Serverless Instances and Shared-tier clusters](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/serverless-shared-migration-guide).
+
+## Terraform MongoDB Atlas modules
+
+You can now leverage our [Terraform Modules](https://registry.terraform.io/namespaces/terraform-mongodbatlas-modules) to easily get started with MongoDB Atlas and critical features like [Push-based log export](https://registry.terraform.io/modules/terraform-mongodbatlas-modules/push-based-log-export/mongodbatlas/latest), [Private Endpoints](https://registry.terraform.io/modules/terraform-mongodbatlas-modules/private-endpoint/mongodbatlas/latest), etc.
+
+## Helpful Links
+
+* [Report bugs](https://github.com/mongodb/terraform-provider-mongodbatlas/issues)
+
+* [Request Features](https://feedback.mongodb.com/forums/924145-atlas?category_id=370723)
+
+* [Contact Support](https://docs.atlas.mongodb.com/support/) covered by MongoDB Atlas support plans, Developer and above.
diff --git a/docs/guides/serverless-shared-migration-guide.md b/docs/guides/serverless-shared-migration-guide.md
@@ -0,0 +1,267 @@
+---
+page_title: "Migration Guide: Transition out of Serverless Instances and Shared-tier clusters"
+---
+
+# Migration Guide: Transition out of Serverless Instances and Shared-tier clusters
+
+The goal of this guide is to help users transition from Serverless Instances and Shared-tier clusters (M2/M5) to Free, Flex or Dedicated Clusters. 
+
+Starting in January 2025, all Shared-tier clusters (in both `mongodbatlas_cluster` and `mongodbatlas_advanced_cluster`) will automatically convert to Flex clusters. Similarly, in March 2025 all Serverless instances (`mongodb_serverless_instance`) will be converted into Free/Flex/Dedicated clusters, [depending on your existing configuration](https://www.mongodb.com/docs/atlas/flex-migration/).
+If a Serverless instance has $0 MRR, it automatically converts into a Free cluster. Else, if it does not fit the constraints of a Flex cluster, it will convert into a Dedicated cluster, resulting in downtime and workload disruption. Otherwise, it will convert to a Flex cluster.
+Some of these conversions will result in configuration drift in Terraform. 
+
+
+You can migrate from Serverless instances and Shared-tier clusters manually before autoconversion. 
+
+**--> NOTE:** We recommend waiting until March 2025 or later for Serverless instances and Shared-tier clusters to autoconvert.
+
+For Shared-tier clusters, we are working on enhancing the User Experience such that Terraform Atlas Providers users can make even fewer required changes to their scripts from what is shown below. More updates to come over the next few months. For more details reach out to: [email protected]
+
+### Jump to:
+- [Shared-tier to Flex](#from-shared-tier-clusters-to-flex)
+- [Serverless to Free](#from-serverless-to-free)
+- [Serverless to Flex](#from-serverless-to-flex)
+- [Serverless to Dedicated](#from-serverless-to-dedicated)
+
+## From Shared-tier clusters to Flex 
+
+### Post-Autoconversion Migration Procedure
+
+Shared-tier clusters will automatically convert in January 2025 to Flex clusters in Atlas, retaining all data. We recommend to migrate to `mongodbatlas_flex_cluster` resource once the autoconversion is done.
+
+The following steps explain how to move your exising Shared-tier cluster resource to the new `mongodbatlas_flex_cluster` resource and does not affect the underlying cluster infrastructure:
+
+1. Find the import IDs of the Flex clusters: `{PROJECT_ID}-{CLUSTER_NAME}`, such as `664619d870c247237f4b86a6-flexClusterName`
+2. Add an import block per cluster to one of your `.tf` files:
+    ```terraform
+    import {
+    to = mongodbatlas_flex_cluster.this
+    id = "664619d870c247237f4b86a6-flexClusterName" # from step 1
+    }
+    ```
+3. Run `terraform plan -generate-config-out=flex_cluster.tf`. This should generate a `flex_cluster.tf` file with your Flex cluster in it.
+4. Run `terraform apply`. You should see the resource(s) imported: `Apply complete! Resources: 1 imported, 0 added, 0 changed, 0 destroyed.`
+5. Remove the "default" fields. Many fields of this resource are optional. Look for fields with a `null` or `0` value.
+6. Re-use existing [Terraform expressions](https://developer.hashicorp.com/terraform/language/expressions). All fields in the generated configuration have static values. Look in your previous configuration for:
+   - variables, for example: `var.project_id`
+   - Terraform keywords, for example: `for_each`, `count`, and `depends_on`
+7. Update the references from your previous cluster resource: `mongodbatlas_advanced_cluster.this.X` or `mongodbatlas_cluster.this.X` to the new `mongodbatlas_flex_cluster.this.X`.
+8. Update any shared-tier data source blocks to refer to `mongodbatlas_flex_cluster`.
+9. Replace your existing clusters with the ones from `flex_cluster.tf` and run 
+
+    `terraform state rm mongodbatlas_advanced_cluster.this`
+
+    or `terraform state rm mongodbatlas_cluster.this`. 
+
+    Without this step, Terraform creates a plan to delete your existing cluster.
+
+10.  Remove the import block created in step 2.
+11.  Re-run `terraform plan` to ensure you have no planned changes: `No changes. Your infrastructure matches the configuration.` 
+
+### Pre-Autoconversion Migration Procedure
+
+**NOTE:** We recommend waiting until January 2025 or later for Shared-tier clusters to autoconvert. Manually doing the migration can cause downtime and workload disruption.
+
+1. Create a new Flex Cluster directly from your `.tf` file, e.g.:
+
+    ```terraform
+    resource "mongodbatlas_flex_cluster" "this" {
+        project_id = var.project_id
+        name       = "flexClusterName"
+        provider_settings = {
+            backing_provider_name = "AWS"
+            region_name           = "US_EAST_1"
+        }
+        termination_protection_enabled = true
+    }
+    ```
+2. Run `terraform apply` to create the new resource.
+3. Migrate data from your Shared-tier cluster to the Flex cluster using `mongodump` and `mongostore`.
+
+    Please see the following guide on how to retrieve data from one cluster and store it in another cluster: [Convert a Serverless Instance to a Dedicated Cluster](https://www.mongodb.com/docs/atlas/tutorial/convert-serverless-to-dedicated/)
+
+    Verify that your data is present within the Flex cluster before proceeding.
+4. Delete the Shared-tier cluster by running a destroy command against it.
+    
+    For *mongodbatlas_advanced_cluster*:
+
+    `terraform destroy -target=mongodbatlas_advanced_cluster.this`
+
+    For *mongodbatlas_cluster*:
+
+    `terraform destroy -target=mongodbatlas_cluster.this`
+
+ 5. Remove the resource block for the Shared-tier cluster from your `.tf` file.
+
+## From Serverless to Free 
+
+**Please ensure your Serverless instance meets the following requirements to migrate to Free:**
+- $0 MRR
+
+### Post-Autoconversion Migration Procedure
+
+Given your Serverless Instance has $0 MRR, it will automatically convert in March 2025 into a Free cluster in Atlas, retaining all data.
+
+The following steps resolve the configuration drift in Terraform without affecting the underlying cluster infrastructure:
+
+1. Find the import IDs of the Free clusters: `{PROJECT_ID}-{CLUSTER_NAME}`, such as `664619d870c247237f4b86a6-freeClusterName`
+2. Add an import block per cluster to one of your `.tf` files:
+    ```terraform
+    import {
+    to = mongodbatlas_advanced_cluster.this
+    id = "664619d870c247237f4b86a6-freeClusterName" # from step 1
+    }
+    ```
+3. Run `terraform plan -generate-config-out=free_cluster.tf`. This should generate a `free_cluster.tf` file with your Free cluster in it.
+4. Run `terraform apply`. You should see the resource(s) imported: `Apply complete! Resources: 1 imported, 0 added, 0 changed, 0 destroyed.`
+5. Remove the "default" fields. Many fields of this resource are optional. Look for fields with a `null` or `0` value.
+6. Re-use existing [Terraform expressions](https://developer.hashicorp.com/terraform/language/expressions). All fields in the generated configuration have static values. Look in your previous configuration for:
+   - variables, for example: `var.project_id`
+   - Terraform keywords, for example: `for_each`, `count`, and `depends_on`
+7. Update the references from your previous cluster resource: `mongodbatlas_serverless_instance.this.X` to the new `mongodbatlas_advanced_cluster.this.X`.
+8. Update any shared-tier data source blocks to refer to `mongodbatlas_advanced_cluster`.
+9. Replace your existing clusters with the ones from `free_cluster.tf` and run `terraform state rm mongodbatlas_serverless_instance.this`. Without this step, Terraform creates a plan to delete your existing cluster.
+10.  Remove the import block created in step 2.
+11.  Re-run `terraform plan` to ensure you have no planned changes: `No changes. Your infrastructure matches the configuration.` 
+
+### Pre-Autoconversion Migration Procedure
+
+**NOTE:** We recommend waiting until March 2025 or later for Serverless instances to autoconvert. Manually doing the migration can cause downtime and workload disruption.
+
+1. Create a new Free Cluster directly from your `.tf` file, e.g.:
+
+    ```terraform
+    resource "mongodbatlas_advanced_cluster" "this" {
+        project_id   = var.atlas_project_id
+        name         = "freeClusterName"
+        cluster_type = "REPLICASET"
+
+        replication_specs {
+            region_configs {
+            electable_specs {
+                instance_size = "M0"
+            }
+            provider_name         = "TENANT"
+            backing_provider_name = "AWS"
+            region_name           = "US_EAST_1"
+            priority              = 7
+            }
+        }
+    }
+    ```
+2.  Run `terraform apply` to create the new resource.
+3. Migrate data from your Serverless Instance to the Free cluster using `mongodump` and `mongostore`.
+
+    Please see the following guide on how to retrieve data from one cluster and store it in another cluster: [Convert a Serverless Instance to a Dedicated Cluster](https://www.mongodb.com/docs/atlas/tutorial/convert-serverless-to-dedicated/)
+
+    Verify that your data is present within the Free cluster before proceeding.
+4. Delete the Serverless Instance by running a destroy command against the Serverless Instance:
+
+    `terraform destroy -target=mongodbatlas_serverless_instance.this`
+
+ 5. Remove the resource block for the Serverless Instance from your `.tf` file.
+
+## From Serverless to Flex
+
+**Please ensure your Serverless instance meets the following requirements to migrate to Flex:**
+- <= 5GB of data
+- no privatelink or continuous backup
+- < 500 ops/sec consistently.
+
+### Post-Autoconversion Migration Procedure
+
+Given your Serverless Instance fits the constraints of a Flex cluster, it will automatically convert in March 2025 into a Flex cluster in Atlas, retaining all data. We recommend to migrate to `mongodbatlas_flex_cluster` resource once the autoconversion is done.
+
+The following steps explain how to move your exising Serverless instance resource to the new `mongodbatlas_flex_cluster` resource and does not affect the underlying cluster infrastructure:
+
+1. Find the import IDs of the Flex clusters: `{PROJECT_ID}-{CLUSTER_NAME}`, such as `664619d870c247237f4b86a6-flexClusterName`
+2. Add an import block per cluster to one of your `.tf` files:
+    ```terraform
+    import {
+    to = mongodbatlas_flex_cluster.this
+    id = "664619d870c247237f4b86a6-flexClusterName" # from step 1
+    }
+    ```
+3. Run `terraform plan -generate-config-out=flex_cluster.tf`. This should generate a `flex_cluster.tf` file with your Flex cluster in it.
+4. Run `terraform apply`. You should see the resource(s) imported: `Apply complete! Resources: 1 imported, 0 added, 0 changed, 0 destroyed.`
+5. Remove the "default" fields. Many fields of this resource are optional. Look for fields with a `null` or `0` value.
+6. Re-use existing [Terraform expressions](https://developer.hashicorp.com/terraform/language/expressions). All fields in the generated configuration have static values. Look in your previous configuration for:
+   - variables, for example: `var.project_id`
+   - Terraform keywords, for example: `for_each`, `count`, and `depends_on`
+7. Update the references from your previous cluster resource: `mongodbatlas_serverless_instance.this.X` to the new `mongodbatlas_flex_cluster.this.X`.
+8. Update any shared-tier data source blocks to refer to `mongodbatlas_flex_cluster`.
+9. Replace your existing clusters with the ones from `flex_cluster.tf` and run `terraform state rm mongodbatlas_serverless_instance.this`. Without this step, Terraform creates a plan to delete your existing cluster.
+10.  Remove the import block created in step 2.
+11.  Re-run `terraform plan` to ensure you have no planned changes: `No changes. Your infrastructure matches the configuration.` 
+
+### Pre-Autoconversion Migration Procedure
+
+**NOTE:** We recommend waiting until March 2025 or later for Serverless instances to autoconvert. Manual migration can cause downtime and workload disruption.
+
+1. Create a new Flex Cluster directly from your `.tf` file, e.g.:
+
+    ```terraform
+    resource "mongodbatlas_flex_cluster" "this" {
+        project_id = var.project_id
+        name       = "flexClusterName"
+        provider_settings = {
+            backing_provider_name = "AWS"
+            region_name           = "US_EAST_1"
+        }
+        termination_protection_enabled = true
+    }
+    ```
+2.  Run `terraform apply` to create the new resource.
+3. Migrate data from your Serverless Instance to the Flex cluster using `mongodump` and `mongostore`.
+
+    Please see the following guide on how to retrieve data from one cluster and store it in another cluster: [Convert a Serverless Instance to a Dedicated Cluster](https://www.mongodb.com/docs/atlas/tutorial/convert-serverless-to-dedicated/)
+
+    Verify that your data is present within the Flex cluster before proceeding.
+4. Delete the Serverless Instance by running a destroy command against it:
+
+    `terraform destroy -target=mongodbatlas_serverless_instance.this`
+
+ 5. You may now safely remove the resource block for the Serverless Instance from your `.tf` file.
+
+## From Serverless to Dedicated 
+
+**Please note your Serverless instance will need to migrate to Decidated if it meets the following requirements:**
+- \>= 5GB of data
+- needs privatelink or continuous backup
+- \> 500 ops/sec consistently.
+
+You cannot migrate from Serverless to Dedicated using the Terraform provider.
+
+### Pre-Autoconversion Migration Procedure
+
+**NOTE:** In early 2025, we will release a UI-based tool for migrating your workloads from Serverless instances to Dedicated clusters. This tool will ensure correct migration with little downtime. You won't need to change connection strings.
+
+To migrate from Serverless to Dedicated prior to early 2025, please see the following guide: [Convert a Serverless Instance to a Dedicated Cluster](https://www.mongodb.com/docs/atlas/tutorial/convert-serverless-to-dedicated/). **NOTE:** Manual migration can cause downtime and workload disruption.
+
+### Post-Autoconversion Migration Procedure
+
+**NOTE:** Auto-conversion from Serverless to Dedicated will cause downtime and workload disruption. This guide is only valid after the auto-conversion is done.
+
+Given your Serverless Instance doesn't fit the constraints of a Flex cluster, it will automatically convert in March 2025 into a Dedicated cluster in Atlas, retaining all data.
+
+The following steps resolve the configuration drift in Terraform and does not affect the underlying cluster infrastructure:
+
+1. Find the import IDs of the Dedicated clusters: `{PROJECT_ID}-{CLUSTER_NAME}`, such as `664619d870c247237f4b86a6-advancedClusterName`
+2. Add an import block per cluster to one of your `.tf` files:
+    ```terraform
+    import {
+    to = mongodbatlas_advanced_cluster.this
+    id = "664619d870c247237f4b86a6-advancedClusterName" # from step 1
+    }
+    ```
+3. Run `terraform plan -generate-config-out=dedicated_cluster.tf`. This should generate a `dedicated_cluster.tf` file with your Dedicated cluster in it.
+4. Run `terraform apply`. You should see the resource(s) imported: `Apply complete! Resources: 1 imported, 0 added, 0 changed, 0 destroyed.`
+5. Remove the "default" fields. Many fields of this resource are optional. Look for fields with a `null` or `0` value.
+6. Re-use existing [Terraform expressions](https://developer.hashicorp.com/terraform/language/expressions). All fields in the generated configuration have static values. Look in your previous configuration for:
+   - variables, for example: `var.project_id`
+   - Terraform keywords, for example: `for_each`, `count`, and `depends_on`
+7. Update the references from your previous cluster resource: `mongodbatlas_serverless_instance.this.X` to the new `mongodbatlas_advanced_cluster.this.X`.
+8. Update any shared-tier data source blocks to refer to `mongodbatlas_advanced_cluster`.
+9. Replace your existing clusters with the ones from `dedicated_cluster.tf` and run `terraform state rm mongodbatlas_serverless_instance.this`. Without this step, Terraform creates a plan to delete your existing cluster.
+10.  Remove the import block created in step 2.
+11.  Re-run `terraform plan` to ensure you have no planned changes: `No changes. Your infrastructure matches the configuration.`