Skip to content

Commit 770c0b8

Browse files
oarbusioarbusi
authored
doc: Restores migration guide to transition out of Serverless (#3724)
1 parent 04423c1 commit 770c0b8

File tree

1 file changed

+245
-0
lines changed

1 file changed

+245
-0
lines changed

‎docs/guides/serverless-shared-migration-guide.md‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
---
2+
page_title: "Migration Guide: Transition out of Serverless Instances and Shared-tier clusters"
3+
---
4+
5+
# Migration Guide: Transition out of Serverless Instances and Shared-tier clusters
6+
7+
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.
8+
9+
Starting in January 2025 or later, 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 (`mongodbatlas_serverless_instance`) will be converted into Free/Flex/Dedicated clusters, [depending on your existing configuration](https://www.mongodb.com/docs/atlas/flex-migration/).
10+
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.
11+
Some of these conversions will result in configuration drift in Terraform.
12+
13+
14+
You can migrate from Serverless instances and Shared-tier clusters manually before autoconversion.
15+
16+
**--> NOTE:** We recommend waiting until March 2025 or later for Serverless instances and Shared-tier clusters to autoconvert.
17+
18+
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.
19+
20+
### Jump to:
21+
- [Shared-tier to Flex](#from-shared-tier-clusters-to-flex)
22+
- [Serverless to Free](#from-serverless-to-free)
23+
- [Serverless to Flex](#from-serverless-to-flex)
24+
- [Serverless to Dedicated](#from-serverless-to-dedicated)
25+
26+
## From Shared-tier clusters to Flex
27+
28+
### Post-Autoconversion Migration Procedure
29+
30+
Shared-tier clusters will automatically convert in January 2025 or later to Flex clusters in Atlas, retaining all data. We recommend that you migrate to a Flex cluster managed by `mongodbatlas_advanced_cluster` resource once the autoconversion is done.
31+
32+
The following steps explain how to move your exising Shared-tier cluster resource to a Flex cluster using `mongodbatlas_advanced_cluster` resource and does not affect the underlying cluster infrastructure:
33+
34+
1. Change the configuration of your Shared-tier cluster to a Flex cluster. For more details on the exact changes, see the [Example Tenant Cluster Upgrade to Flex](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/advanced_cluster#example-tenant-cluster-upgrade-to-flex)
35+
3. Run `terraform plan` to see the planned changes.
36+
4. Run `terraform apply`. This will upgrade your Shared-tier cluster to a Flex tier cluster.
37+
10. Re-run `terraform plan` to ensure you have no planned changes: `No changes. Your infrastructure matches the configuration.`
38+
11. Change your usages of `mongodbatlas_shared_tier_restore_job`, `mongodbatlas_shared_tier_restore_jobs`, `mongodbatlas_shared_tier_snapshot` and `mongodbatlas_shared_tier_snapshots` data sources to the new `mongodbatlas_flex_restore_job`, `mongodbatlas_flex_restore_jobs`, `mongodbatlas_flex_snapshot` and `mongodbatlas_flex_snapshot` respectively.
39+
40+
### Pre-Autoconversion Migration Procedure
41+
42+
**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.
43+
44+
1. Create a new Flex Cluster directly from your `.tf` file, e.g.:
45+
46+
```terraform
47+
resource "mongodbatlas_flex_cluster" "this" {
48+
project_id = var.project_id
49+
name = "flexClusterName"
50+
provider_settings = {
51+
backing_provider_name = "AWS"
52+
region_name = "US_EAST_1"
53+
}
54+
termination_protection_enabled = true
55+
}
56+
```
57+
2. Run `terraform apply` to create the new resource.
58+
3. Migrate data from your Shared-tier cluster to the Flex cluster using `mongodump` and `mongostore`.
59+
60+
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/)
61+
62+
Verify that your data is present within the Flex cluster before proceeding.
63+
4. Delete the Shared-tier cluster by running a destroy command against it.
64+
65+
For *mongodbatlas_advanced_cluster*:
66+
67+
`terraform destroy -target=mongodbatlas_advanced_cluster.this`
68+
69+
For *mongodbatlas_cluster*:
70+
71+
`terraform destroy -target=mongodbatlas_cluster.this`
72+
73+
5. Remove the resource block for the Shared-tier cluster from your `.tf` file.
74+
75+
## From Serverless to Free
76+
77+
**Please ensure your Serverless instance meets the following requirements to migrate to Free:**
78+
- $0 MRR
79+
80+
### Post-Autoconversion Migration Procedure
81+
82+
Given your Serverless Instance has $0 MRR, it will automatically convert in March 2025 into a Free cluster in Atlas, retaining all data.
83+
84+
The following steps resolve the configuration drift in Terraform without affecting the underlying cluster infrastructure:
85+
86+
1. Find the import IDs of the Free clusters: `{PROJECT_ID}-{CLUSTER_NAME}`, such as `664619d870c247237f4b86a6-freeClusterName`
87+
2. Add an import block per cluster to one of your `.tf` files:
88+
```terraform
89+
import {
90+
to = mongodbatlas_advanced_cluster.this
91+
id = "664619d870c247237f4b86a6-freeClusterName" # from step 1
92+
}
93+
```
94+
3. Run `terraform plan -generate-config-out=free_cluster.tf`. This should generate a `free_cluster.tf` file with your Free cluster in it.
95+
4. Run `terraform apply`. You should see the resource(s) imported: `Apply complete! Resources: 1 imported, 0 added, 0 changed, 0 destroyed.`
96+
5. Remove the "default" fields. Many fields of this resource are optional. Look for fields with a `null` or `0` value.
97+
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:
98+
- variables, for example: `var.project_id`
99+
- Terraform keywords, for example: `for_each`, `count`, and `depends_on`
100+
7. Update the references from your previous cluster resource: `mongodbatlas_serverless_instance.this.X` to the new `mongodbatlas_advanced_cluster.this.X`.
101+
8. Update any shared-tier data source blocks to refer to `mongodbatlas_advanced_cluster`.
102+
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.
103+
10. Remove the import block created in step 2.
104+
11. Re-run `terraform plan` to ensure you have no planned changes: `No changes. Your infrastructure matches the configuration.`
105+
106+
### Pre-Autoconversion Migration Procedure
107+
108+
**NOTE:** We recommend waiting until March 2025 or later for Serverless instances to autoconvert. Manually doing the migration can cause downtime and workload disruption.
109+
110+
1. Create a new Free Cluster directly from your `.tf` file, e.g.:
111+
112+
```terraform
113+
resource "mongodbatlas_advanced_cluster" "this" {
114+
project_id = var.atlas_project_id
115+
name = "freeClusterName"
116+
cluster_type = "REPLICASET"
117+
118+
replication_specs {
119+
region_configs {
120+
electable_specs {
121+
instance_size = "M0"
122+
}
123+
provider_name = "TENANT"
124+
backing_provider_name = "AWS"
125+
region_name = "US_EAST_1"
126+
priority = 7
127+
}
128+
}
129+
}
130+
```
131+
2. Run `terraform apply` to create the new resource.
132+
3. Migrate data from your Serverless Instance to the Free cluster using `mongodump` and `mongostore`.
133+
134+
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/)
135+
136+
Verify that your data is present within the Free cluster before proceeding.
137+
4. Delete the Serverless Instance by running a destroy command against the Serverless Instance:
138+
139+
`terraform destroy -target=mongodbatlas_serverless_instance.this`
140+
141+
5. Remove the resource block for the Serverless Instance from your `.tf` file.
142+
143+
## From Serverless to Flex
144+
145+
**Please ensure your Serverless instance meets the following requirements to migrate to Flex:**
146+
- <= 5GB of data
147+
- no privatelink or continuous backup
148+
- < 500 ops/sec consistently.
149+
150+
### Post-Autoconversion Migration Procedure
151+
152+
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.
153+
154+
The following steps explain how to move your exising Serverless instance resource to a Flex cluster using `mongodbatlas_advanced_cluster` resource and does not affect the underlying cluster infrastructure:
155+
156+
1. Find the import IDs of the Flex clusters: `{PROJECT_ID}-{CLUSTER_NAME}`, such as `664619d870c247237f4b86a6-flexClusterName`
157+
2. Add an import block per cluster to one of your `.tf` files:
158+
```terraform
159+
import {
160+
to = mongodbatlas_advanced_cluster.flex
161+
id = "664619d870c247237f4b86a6-flexClusterName" # from step 1
162+
}
163+
```
164+
3. Run `terraform plan -generate-config-out=flex_cluster.tf`. This should generate a `flex_cluster.tf` file with your Flex cluster in it.
165+
4. Run `terraform apply`. You should see the resource(s) imported: `Apply complete! Resources: 1 imported, 0 added, 0 changed, 0 destroyed.`
166+
5. Remove the "default" fields. Many fields of this resource are optional. Look for fields with a `null` or `0` value.
167+
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:
168+
- variables, for example: `var.project_id`
169+
- Terraform keywords, for example: `for_each`, `count`, and `depends_on`
170+
7. Update the references from your previous cluster resource: `mongodbatlas_serverless_instance.this.X` to the new `mongodbatlas_advanced_cluster.flex.X`.
171+
8. Replace your existing clusters with the ones from `flex_cluster.tf` and run `terraform state rm mongodbatlas_serverless_instance.this`. **IMPORTANT**: Without this step, Terraform creates a plan to delete your existing cluster.
172+
9. Remove the import block created in step 2.
173+
10. Re-run `terraform plan` to ensure you have no planned changes: `No changes. Your infrastructure matches the configuration.`
174+
175+
### Pre-Autoconversion Migration Procedure
176+
177+
**NOTE:** We recommend waiting until March 2025 or later for Serverless instances to autoconvert. Manual migration can cause downtime and workload disruption.
178+
179+
1. Create a new Flex Cluster directly from your `.tf` file, e.g.:
180+
181+
```terraform
182+
resource "mongodbatlas_flex_cluster" "this" {
183+
project_id = var.project_id
184+
name = "flexClusterName"
185+
provider_settings = {
186+
backing_provider_name = "AWS"
187+
region_name = "US_EAST_1"
188+
}
189+
termination_protection_enabled = true
190+
}
191+
```
192+
2. Run `terraform apply` to create the new resource.
193+
3. Migrate data from your Serverless Instance to the Flex cluster using `mongodump` and `mongostore`.
194+
195+
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/)
196+
197+
Verify that your data is present within the Flex cluster before proceeding.
198+
4. Delete the Serverless Instance by running a destroy command against it:
199+
200+
`terraform destroy -target=mongodbatlas_serverless_instance.this`
201+
202+
5. You may now safely remove the resource block for the Serverless Instance from your `.tf` file.
203+
204+
## From Serverless to Dedicated
205+
206+
**Please note your Serverless instance will need to migrate to Decidated if it meets the following requirements:**
207+
- \>= 5GB of data
208+
- needs privatelink or continuous backup
209+
- \> 500 ops/sec consistently.
210+
211+
You cannot migrate from Serverless to Dedicated using the Terraform provider.
212+
213+
### Pre-Autoconversion Migration Procedure
214+
215+
**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.
216+
217+
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.
218+
219+
### Post-Autoconversion Migration Procedure
220+
221+
**NOTE:** Auto-conversion from Serverless to Dedicated will cause downtime and workload disruption. This guide is only valid after the auto-conversion is done.
222+
223+
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.
224+
225+
The following steps resolve the configuration drift in Terraform and does not affect the underlying cluster infrastructure:
226+
227+
1. Find the import IDs of the Dedicated clusters: `{PROJECT_ID}-{CLUSTER_NAME}`, such as `664619d870c247237f4b86a6-advancedClusterName`
228+
2. Add an import block per cluster to one of your `.tf` files:
229+
```terraform
230+
import {
231+
to = mongodbatlas_advanced_cluster.this
232+
id = "664619d870c247237f4b86a6-advancedClusterName" # from step 1
233+
}
234+
```
235+
3. Run `terraform plan -generate-config-out=dedicated_cluster.tf`. This should generate a `dedicated_cluster.tf` file with your Dedicated cluster in it.
236+
4. Run `terraform apply`. You should see the resource(s) imported: `Apply complete! Resources: 1 imported, 0 added, 0 changed, 0 destroyed.`
237+
5. Remove the "default" fields. Many fields of this resource are optional. Look for fields with a `null` or `0` value.
238+
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:
239+
- variables, for example: `var.project_id`
240+
- Terraform keywords, for example: `for_each`, `count`, and `depends_on`
241+
7. Update the references from your previous cluster resource: `mongodbatlas_serverless_instance.this.X` to the new `mongodbatlas_advanced_cluster.this.X`.
242+
8. Update any shared-tier data source blocks to refer to `mongodbatlas_advanced_cluster`.
243+
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.
244+
10. Remove the import block created in step 2.
245+
11. Re-run `terraform plan` to ensure you have no planned changes: `No changes. Your infrastructure matches the configuration.`

0 commit comments

Comments
 (0)