mongodb · maastha · Oct 22, 2025 · Oct 8, 2025 · Oct 9, 2025 · Oct 13, 2025
@@ -8,6 +8,28 @@ page_title: "Migration Guide: Advanced Cluster New Sharding Configurations"
 
 Note: Once applied, the `mongodbatlas_advanced_cluster` resource making use of the new sharding configuration will not be able to transition back to the old sharding configuration.
 
+## Who should read this guide?
+
+This guide is intended for **customers using or migrating to the `mongodbatlas_advanced_cluster` resource** who want to understand the **new sharding model that allows you to scale shards independently**.
+
+Use this guide if any of the following applies to you:
+
+- **You currently use the legacy schema** (your configuration defines `num_shards` and a single `replication_specs` block):  
+  → Follow this guide to understand how multiple `replication_specs` blocks now represent shards individually, allowing you to scale or modify each shard independently.  
+  → As mentioned in the [Prerequisites](#prerequisites), once you understand the new model, proceed to the [Migrate to Advanced Cluster 2.0](migrate-to-advanced-cluster-2.0) guide to update your configuration to the latest schema first in order to upgrade to provider version 2.0.0 or later.
+
+- **You currently use v1.x.x of the provider with the preview schema** (using the `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER=true` environment variable and list-style attributes):    
 ### Attribute vs Block Syntax 
 ### Attribute vs Block Syntax 
+  → Use this guide to verify how your configuration aligns with the independent sharding model and ensure your syntax matches the latest attribute-based format described in the [Prerequisites](#prerequisites).
+
+If you currently use v1.x.x of our provider and want to upgrade to version 2.0.0 or later:<br/>
+→ See [Migrate to Advanced Cluster 2.0](migrate-to-advanced-cluster-2.0).
+
+If you are still using the deprecated `mongodbatlas_cluster` resource:<br/>
+→ See [Cluster → Advanced Cluster Migration Guide](cluster-to-advanced-cluster-migration-guide).
+
+---
+
+
 - [Prerequisites](#prerequisites)
 - [Migration Guide: Advanced Cluster New Sharding Configurations](#migration-guide-advanced-cluster-new-sharding-schema)
   - [Changes Overview](#changes-overview)

@@ -6,6 +6,24 @@ page_title: "Migration Guide: Cluster to Advanced Cluster"
 
 **Objective**: This guide explains how to replace the deprecated `mongodbatlas_cluster` resource with the `mongodbatlas_advanced_cluster` resource. For data source migrations, refer to the [output changes](#output-changes) section. If you're transitioning to independent sharding, additional guidance is available in the [Advanced Cluster New Sharding Configurations Migration Guide](advanced-cluster-new-sharding-schema#data-source-transition-for-asymmetric-clusters).
 
+
+## Who should read this guide?
+
+This guide is intended for **customers using the deprecated `mongodbatlas_cluster` resource** who want to migrate to the new `mongodbatlas_advanced_cluster` resource.
+
+If you are already using the `mongodbatlas_advanced_cluster` resource, determine which case applies to you:
+
+- **You currently use the legacy schema** (your configuration uses `num_shards`, `disk_size_gb` at the root, or block-based `tags`, `advanced_configuration`,`replication_specs` etc):  
+  → Follow [Migrate to Advanced Cluster 2.0](migrate-to-advanced-cluster-2.0) with the latest schema updates to upgrade to our 2.0.0 and later versions.
+
+- **You currently use v1.x.x of our provider and want to upgrade to version 2.0.0 or later**:  
+  → Follow [Migrate to Advanced Cluster 2.0](migrate-to-advanced-cluster-2.0) for the latest schema updates to upgrade to our 2.0.0 and later versions.
+
+- **You want to understand the new sharding model that allows you to scale shards independently** (how multiple `replication_specs` replace `num_shards`):  
+  → See [Advanced Cluster New Sharding Schema](advanced-cluster-new-sharding-schema).
+
+---
+
 ## Why do we have both `mongodbatlas_cluster` and `mongodbatlas_advanced_cluster` resources?
 
 Both `mongodbatlas_cluster` and `mongodbatlas_advanced_cluster` resources currently allow customers to manage MongoDB Atlas Clusters. Initially, only `mongodbatlas_cluster` existed. When MongoDB Atlas added support for important features such as multi-cloud deployments and the [MongoDB Atlas Admin API](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/) introduced versioning support, it became impossible to update this resource without causing many breaking changes for our customers. As a result, we decided to keep the resource as-is and created the `mongodbatlas_advanced_cluster` resource. Despite its name, `mongodbatlas_advanced_cluster` is intended for everyone and encompasses all functionalities, including the basic ones offered by `mongodbatlas_cluster`.

@@ -9,7 +9,26 @@ This guide helps you migrate from the legacy schema of `mongodbatlas_advanced_cl
 1. The recommended Terraform Plugin Framework, which, in addition to providing a better user experience and other features, adds support for the `moved` block between different resource types.
 2. New sharding configurations that supports scaling shards independently (see the [Migration Guide: Advanced Cluster New Sharding Configurations](advanced-cluster-new-sharding-schema#migration-sharded)).
 
-~> **IMPORTANT:** Preview of the new schema was already released in versions 1.29.0 and later which could be enabled by setting the environment variable `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER=true`. If you are already using the new schema preview with the new sharding configurations **and not using deprecated attributes**, you would not be required to make any additional changes except that the mentioned environment variable is no longer required.
+
+## Who should read this guide?
+
+This guide is intended for **customers on v1.x.x of our provider and using the `mongodbatlas_advanced_cluster` resource** who want to upgrade to our provider version **2.0.0 and later**.
+
+Use this guide if any of the following applies to you:
+
+- **You currently use the legacy schema** (your configuration uses `num_shards`, `disk_size_gb` at the root, or block-based `tags`, `advanced_configuration`, `replication_specs`, etc.):  
+  → Follow this guide to migrate your configuration to the latest v2.0.0 schema, which introduces list-based attributes, per-shard replication specs, and map-style tags.
+
+- **You currently use v1.x.x of the provider with the preview schema** (using the `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER=true` environment variable, and you already define list attributes such as `replication_specs` and `advanced_configuration`):  
+  → Follow this guide to complete the migration to the final v2.0.0 schema, which aligns with the new stable release format.
+
+If you are still using the deprecated `mongodbatlas_cluster` resource:  
+→ See [Cluster → Advanced Cluster Migration Guide](cluster-to-advanced-cluster-migration-guide).
+
+If you want to understand the new sharding configurations that enables independent shard scaling:  
+→ See [Advanced Cluster New Sharding Schema](advanced-cluster-new-sharding-schema).
+
+---
 
 ## Configuration changes when upgrading from v1.x
 
@@ -174,6 +193,13 @@ After you upgrade to v2.0.0+ from v1.x.x, when you run `terraform plan`, syntax
 
 - **Step #3:** Even though there are no plan changes shown at this point, run `terraform apply`. This will update the `mongodbatlas_advanced_cluster` state to support the new schema.
 
+### Examples
+- [Symmetric Sharded Cluster](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_advanced_cluster/symmetric-sharded-cluster/README.md#migrating-from-v1x-to-v200-or-later)
+- [Asymmetric Sharded Cluster](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_advanced_cluster/asymmetric-sharded-cluster/README.md#migrating-from-v1x-to-v200-or-later)
+- [Auto-Scaling Per Shard](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_advanced_cluster/auto-scaling-per-shard/README.md#migrating-from-v1x-to-v200-or-later)
+- [Basic Replicaset](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/mongodbatlas_advanced_cluster/replicaset/README.md#migrating-from-v1x-to-v200-or-later)
+
+
 ## Important notes
 
-Please refer to our [Considerations and Best Practices](#considerations-and-best-practices) section for additional guidance on this resource.
+Please refer to our [Considerations and Best Practices](../resources/advanced_cluster.md#considerations-and-best-practices) section for additional guidance on this resource.
@@ -1,19 +1,18 @@
-# MongoDB Atlas Provider -- Global Cluster (Preview for MongoDB Atlas Provider 2.0.0)
+# MongoDB Atlas Provider — Asymmetric Sharded Cluster
 
-This example creates a project and a Sharded Cluster with 4 independent shards with varying cluster tiers.
+This example creates a project and a Sharded Cluster with 4 independent shards with varying cluster tiers. 
 
-It uses the **Preview for MongoDB Atlas Provider 2.0.0** of `mongodbatlas_advanced_cluster`. In order to enable the Preview, you must set the enviroment variable `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER=true`, otherwise the current version will be used.
-
-You can find more information in the [resource documentation page](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/advanced_cluster%2520%2528preview%2520provider%25202.0.0%2529).
+### Migrating from v1.x to v2.0.0 or later
+If you are migrating from v1.x of our provider to v2.0.0 or later, the `v1.x.x/` sub-directory shows how your current configuration might look like (with added inline comments to demonstrate what has changed in v2.0.0+ for migration reference).
 
 ## Dependencies
 
-* Terraform MongoDB Atlas Provider v1.29.0
+* Terraform MongoDB Atlas Provider v2.0.0 or later
 * A MongoDB Atlas account 
 
 ```
 Terraform >= 0.13
-+ provider registry.terraform.io/terraform-providers/mongodbatlas v1.29.0
++ provider registry.terraform.io/terraform-providers/mongodbatlas v2.0.0
 ```
 
 
@@ -63,4 +62,3 @@ Once you are finished your testing, ensure you destroy the resources to avoid un
 ``` bash
 $ terraform destroy
 ```
-
@@ -17,6 +17,7 @@ resource "mongodbatlas_advanced_cluster" "cluster" {
             instance_size = "M30"
             disk_iops     = 3000
             node_count    = 3
+            disk_size_gb  = 10
           }
           provider_name = "AWS"
           priority      = 7
@@ -32,6 +33,7 @@ resource "mongodbatlas_advanced_cluster" "cluster" {
             instance_size = "M30"
             disk_iops     = 3000
             node_count    = 3
+            disk_size_gb  = 10
           }
           provider_name = "AWS"
           priority      = 7
@@ -47,6 +49,7 @@ resource "mongodbatlas_advanced_cluster" "cluster" {
             instance_size = "M40"
             disk_iops     = 3000
             node_count    = 3
+            disk_size_gb  = 10
           }
           provider_name = "AWS"
           priority      = 7
@@ -62,6 +65,7 @@ resource "mongodbatlas_advanced_cluster" "cluster" {
             instance_size = "M40"
             disk_iops     = 3000
             node_count    = 3
+            disk_size_gb  = 10
           }
           provider_name = "AWS"
           priority      = 7

@@ -0,0 +1,16 @@
+# Upgrade `mongodbatlas_advanced_cluster` v1.x → v2.0.0 (Asymmetric Sharded Cluster)
+
+This directory uses the deprecated v1.x schema version of the asymmetric sharded cluster example for migration reference.
+Refer the `main.tf` in the parent directory (`../`) that shows what the corresponding configuration should look like after upgrading to provider v2.0.0+.
+
+**For details & to learn how to migrate, review the complete [Migration Guide: Advanced Cluster (v1.x → v2.0.0)](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/migrate-to-advanced-cluster-2.0#how-to-migrate)**
+
+ ## Key changes in v2.0.0
+ - `replication_specs` becomes a list of objects (was blocks in v1.x).
+ - `region_configs` becomes a list of objects (was blocks in v1.x).
+ - `electable_specs` becomes an attribute (was a nested block in v1.x).
+ - `advanced_configuration` becomes an attribute (was a block in v1.x).
+ - `tags` becomes a map attribute (was blocks in v1.x).
+ - Per-shard configuration remains explicit and can vary (e.g., different `instance_size` per shard).
+ - **If previously using** `disk_size_gb` at resource root level, it has been removed in v2.0.0 and now can be specified into the inner specs (for example, `electable_specs.disk_size_gb`).
+ - Some references drop `[0]` or `.0` indexing because objects are no longer lists but singular attributes (e.g., `replication_specs[0].region_configs[0].electable_specs.disk_size_gb`).
@@ -0,0 +1,83 @@
+provider "mongodbatlas" {
+  public_key  = var.public_key
+  private_key = var.private_key
+}
+
+# Below is the old v1.x schema of mongodbatlas_advanced_cluster. 
+# To migrate to v2.0.0+, see the main.tf in the parent directory. Refer README.md for more details.
+resource "mongodbatlas_advanced_cluster" "cluster" {
+  project_id     = mongodbatlas_project.project.id
+  name           = var.cluster_name
+  cluster_type   = "SHARDED"
+  backup_enabled = true
+  disk_size_gb   = 10 # removed in v2.0.0+, this can now be set per shard for inner specs
+
+  # replication_specs are updated to a list of objects instead of blocks in v2.0.0+
+  replication_specs {   # shard 1 - M30 instance size
+    region_configs {    # region_configs are updated to a list of objects instead of blocks in v2.0.0+
+      electable_specs { # electable_specs are updated to an attribute instead of a block in v2.0.0+
+        instance_size = "M30"
+        disk_iops     = 3000
+        node_count    = 3
+      }
+      provider_name = "AWS"
+      priority      = 7
+      region_name   = "EU_WEST_1"
+    }
+  }
+
+  replication_specs { # shard 2 - M30 instance size
+    region_configs {
+      electable_specs {
+        instance_size = "M30"
+        disk_iops     = 3000
+        node_count    = 3
+      }
+      provider_name = "AWS"
+      priority      = 7
+      region_name   = "EU_WEST_1"
+    }
+  }
+
+  replication_specs { # shard 3 - M40 instance size
+    region_configs {
+      electable_specs {
+        instance_size = "M40"
+        disk_iops     = 3000
+        node_count    = 3
+      }
+      provider_name = "AWS"
+      priority      = 7
+      region_name   = "EU_WEST_1"
+    }
+  }
+
+  replication_specs { # shard 4 - M40 instance size
+    region_configs {
+      electable_specs {
+        instance_size = "M40"
+        disk_iops     = 3000
+        node_count    = 3
+      }
+      provider_name = "AWS"
+      priority      = 7
+      region_name   = "EU_WEST_1"
+    }
+  }
+
+  advanced_configuration { # advanced_configuration are updated to an attribute instead of a block in v2.0.0+
+    javascript_enabled                   = true
+    oplog_size_mb                        = 999
+    sample_refresh_interval_bi_connector = 300
+  }
+
+  tags { # tags and labels are updated to maps instead of blocks in v2.0.0+
+    key   = "environment"
+    value = "dev"
+  }
+}
+
+resource "mongodbatlas_project" "project" {
+  name   = "Asymmetric Sharded Cluster"
+  org_id = var.atlas_org_id
+}
@@ -0,0 +1,17 @@
+variable "atlas_org_id" {
+  description = "Atlas organization id"
+  type        = string
+}
+variable "public_key" {
+  description = "Public API key to authenticate to Atlas"
+  type        = string
+}
+variable "private_key" {
+  description = "Private API key to authenticate to Atlas"
+  type        = string
+}
+variable "cluster_name" {
+  description = "Atlas cluster name"
+  type        = string
+  default     = "AsymmetricShardedCluster"
+}
@@ -0,0 +1,9 @@
+terraform {
+  required_providers {
+    mongodbatlas = {
+      source  = "mongodb/mongodbatlas"
+      version = "<=1.41.0"
+    }
+  }
+  required_version = ">= 1.0"
+}
@@ -1,19 +1,18 @@
-# MongoDB Atlas Provider -- Sharded Cluster with Independent Shard Auto-scaling (Preview for MongoDB Atlas Provider 2.0.0)
+# MongoDB Atlas Provider — Sharded Cluster with Independent Shard Auto-scaling
 
 This example creates a Sharded Cluster with 2 shards defining electable and analytics nodes. Compute auto-scaling is enabled for both `electable_specs` and `analytics_specs`, while also leveraging the [New Sharding Configuration](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema) by defining each shard with its individual `replication_specs`. This enables scaling of each shard to be independent. Please reference the [Use Auto-Scaling Per Shard](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema#use-auto-scaling-per-shard) section for more details.
 
-It uses the **Preview for MongoDB Atlas Provider 2.0.0** of `mongodbatlas_advanced_cluster`. In order to enable the Preview, you must set the enviroment variable `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER=true`, otherwise the current version will be used.
-
-You can find more information in the [resource documentation page](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/advanced_cluster%2520%2528preview%2520provider%25202.0.0%2529).
+### Migrating from v1.x to v2.0.0 or later
+If you are migrating from v1.x of our provider to v2.0.0 or later, the `v1.x.x/` sub-directory shows how your current configuration might look like (with added inline comments to demonstrate what has changed in v2.0.0+ for migration reference).
 
 ## Dependencies
 
-* Terraform MongoDB Atlas Provider v1.29.0
+* Terraform MongoDB Atlas Provider v2.0.0 or later
 * A MongoDB Atlas account 
 
 ```
 Terraform >= 0.13
-+ provider registry.terraform.io/terraform-providers/mongodbatlas v1.29.0
++ provider registry.terraform.io/terraform-providers/mongodbatlas v2.0.0
 ```
 
 
@@ -63,4 +62,3 @@ Once you are finished your testing, ensure you destroy the resources to avoid un
 ``` bash
 $ terraform destroy
 ```
-
@@ -0,0 +1,14 @@
+# Upgrade `mongodbatlas_advanced_cluster` v1.x → v2.0.0 (Auto-scaling per Shard)
+
+This directory contains the deprecated v1.x schema version of the auto-scaling per shard example for migration reference.
+Refer the `main.tf` in the parent directory (`../`) that shows what the corresponding configuration should look like after upgrading to provider v2.0.0+.
+
+**For details & to learn how to migrate, review the complete [Migration Guide: Advanced Cluster (v1.x → v2.0.0)](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/migrate-to-advanced-cluster-2.0#how-to-migrate)**
+
+## Key changes in v2.0.0
+- `replication_specs` becomes a list of objects (was a block in v1.x).
+- `region_configs` becomes a list of objects (was a block in v1.x).
+- `auto_scaling` and `analytics_auto_scaling` become attributes (were nested blocks in v1.x).
+- `electable_specs` becomes an attribute (was a nested block in v1.x).
+- **If previously using** `disk_size_gb` at resource root level, it has been removed in v2.0.0 and now can be specified into the inner specs (for example, `electable_specs.disk_size_gb`).
+- Some references drop `[0]` or `.0` indexing because nested objects are no longer lists.