doc: Updates guides & examples for removal of `mongodbatlas_advanced_cluster` deprecated params #3634

maastha · 2025-08-31T19:29:56Z

Description

Updates guides & examples for removal of mongodbatlas_advanced_cluster deprecated params

Link to any related issue(s): CLOUDP-333683

Type of change:

Bug fix (non-breaking change which fixes an issue). Please, add the "bug" label to the PR.
New feature (non-breaking change which adds functionality). Please, add the "enhancement" label to the PR. A migration guide must be created or updated if the new feature will go in a major version.
Breaking change (fix or feature that would cause existing functionality to not work as expected). Please, add the "breaking change" label to the PR. A migration guide must be created or updated.
This change requires a documentation update
Documentation fix/enhancement

Required Checklist:

I have signed the MongoDB CLA
I have read the contributing guides
I have checked that this change does not generate any credentials and that they are NOT accidentally logged anywhere.
I have added tests that prove my fix is effective or that my feature works per HashiCorp requirements
I have added any necessary documentation (if appropriate)
I have run make fmt and formatted my code
If changes include deprecations or removals I have added appropriate changelog entries.
If changes include removal or addition of 3rd party GitHub actions, I updated our internal document. Reach out to the APIx Integration slack channel to get access to the internal document.

Further comments

docs/guides/migrate-to-advanced-cluster-2.0.md

marcosuma

LGTM - might need another pass or two from other team members

antellezr-mdb

LGTM

AgustinBettati · 2025-09-02T08:14:53Z

docs/guides/advanced-cluster-new-sharding-schema.md

@@ -4,10 +4,11 @@ page_title: "Migration Guide: Advanced Cluster New Sharding Configurations"

 # Migration Guide: Advanced Cluster New Sharding Configurations

-**Objective**: Use this guide to migrate your existing `advanced_cluster` resources to support new sharding configurations introduced in version 1.18.0. The new sharding configurations allow you to scale shards independently. Additionally, as of version 1.23.0, compute auto-scaling supports scaling instance sizes independently for each shard when using the new sharding configuration. Existing sharding configurations continue to work, but you will receive deprecation messages if you continue to use them.
+**Objective**: Use this guide to migrate your existing `advanced_cluster` resources that may be using the legacy sharding schema (i.e. using `num_shards`) to support the new sharding configurations instead. The new sharding configurations allow you to scale shards independently. Additionally, compute auto-scaling supports scaling instance sizes independently for each shard when using the new sharding configuration.


Should we make explicit here that num_shards was deprecated in 1.18.0 and removed in 2.0.0? I see we do reiterate throughout the doc, but can be good to make clear here at the start.

AgustinBettati · 2025-09-02T08:23:20Z

docs/guides/advanced-cluster-new-sharding-schema.md

-1. Configuration was defined prior to version 1.23.0 when auto-scaling per shard feature was released.
-2. Cluster was imported from a legacy schema (For example, `mongodbatlas_cluster` or `mongodbatlas_advanced_cluster` using `num_shards` > 1).
-In these cases, you must update the cluster configuration to activate the auto-scaling per shard feature. This can be done by temporarily modifying a value like `compute_min_instance_size`.
+-> **NOTE:** In the following scenarios, a `mongodbatlas_advanced_cluster` using the new sharding configuration (single `replication_specs` per shard) might not have shard-level auto-scaling enabled: <br/>1. Configuration was defined prior to version 1.23.0 when auto-scaling per shard feature was released.<br/>2. Cluster was imported from a legacy schema (For example, `mongodbatlas_cluster` or `mongodbatlas_advanced_cluster` using `num_shards` > 1).<br/><br/>In these cases, you must update the cluster configuration to activate the auto-scaling per shard feature. This can be done by temporarily modifying a value like `compute_min_instance_size`.


Would add the 3rd case of users transitioning from 1.x directly to 2.x, the transition does not trigger any update operation so autoscaling will remain CLUSTER wide.

AgustinBettati · 2025-09-02T08:27:17Z

docs/guides/migrate-to-advanced-cluster-2.0.md

@@ -60,8 +73,9 @@ replication_specs = [
  }
 ]
 ```
+Additionally, `mongodbatlas_advanced_cluster` now supports only the new sharding configuration that allows scaling shards independently. If not using the new configuration already, please also see the [Migration Guide: Advanced Cluster New Sharding Configurations](advanced-cluster-new-sharding-schema#migration-sharded).


nit: Can we add this as a separate point to highlight more its importance?
Would also be explicit on when users have to take action on this case, potentially rephrasing If not using the new configuration already, ... If the configuration defines the now removed num_shards attribute, ...

updated and this is now a separate point

3.mongodbatlas_advanced_clusternow supports only the new sharding configuration that allows scaling shards independently. If your configuration defines the num_shards attribute (removed in 2.0.0), please also see the [Migration Guide: Advanced Cluster New Sharding Configurations](advanced-cluster-new-sharding-schema#migration-sharded).

AgustinBettati · 2025-09-02T08:30:08Z

docs/guides/migrate-to-advanced-cluster-2.0.md

+- **Step #1:** Apply definition changes [explained on this page](#configuration-changes-when-upgrading-from-v1x) until there are no errors and no planned changes. 
+  - You can also use the [Atlas CLI plugin](https://github.com/mongodb-labs/atlas-cli-plugin-terraform?tab=readme-ov-file#2-advancedclustertov2-adv2v2) to generate the `mongodbatlas_advanced_cluster` resource definition. This is the recommended method as it will generate a clean configuration while keeping the original Terraform expressions. Please be aware of the [plugin limitations](https://github.com/mongodb-labs/atlas-cli-plugin-terraform/blob/main/docs/command_adv2v2.md#limitations).
+
+~> NOTE: If not using the new **sharding** configuration already, you would also need to adjust `replication_specs` as per the [Migration Guide: Advanced Cluster New Sharding Configurations](advanced-cluster-new-sharding-schema#migration-sharded).


nit: This seems slightly redundant given it has to be a clear step of Configuration changes when upgrading from v1.x

removed it now that it's an explicit point in Configuration changes...

…schema-attrs

Co-authored-by: Marco Suma <[email protected]>

Copilot

Pull Request Overview - OUTDATED - Please IGNORE

This PR removes deprecated parameters from the mongodbatlas_advanced_cluster resource and related configurations to complete the cleanup initiated in version 2.0.0. The changes focus on eliminating references to deprecated sharding configurations and updating documentation and examples to reflect the current supported schema.

Key changes include:

Removal of deprecated parameter references in deprecation messages
Cleanup of deprecated num_shards and use_replication_spec_per_shard attributes from test files and examples
Documentation updates to reflect the removal of deprecated attributes
Import statement cleanup where deprecated constants are no longer needed

Reviewed Changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
internal/service/team/resource_team.go	Updates deprecation message placeholder for team usernames parameter
internal/service/team/data_source_team.go	Updates deprecation message placeholder for team usernames data source
internal/service/projectinvitation/resource_project_invitation.go	Removes deprecation message and unused import for project invitation resource
internal/service/projectinvitation/data_source_project_invitation.go	Removes deprecation message and unused import for project invitation data source
internal/service/project/resource_project_schema.go	Removes deprecation message for teams parameter
internal/service/project/model_project.go	Removes deprecation message and unused imports for project model
internal/service/orginvitation/resource_org_invitation.go	Removes deprecation message and unused import for org invitation resource
internal/service/orginvitation/data_source_org_invitation.go	Removes deprecation message and unused import for org invitation data source
internal/service/atlasuser/data_source_atlas_users.go	Removes deprecation messages and unused import for atlas users data source
internal/service/atlasuser/data_source_atlas_user.go	Removes deprecation messages and unused import for atlas user data source
internal/service/advancedcluster/testdata/*.yaml	Removes deprecated `use_replication_spec_per_shard` parameters from test configurations
examples/*/main.tf	Removes deprecated `num_shards` parameters from advanced cluster examples
examples/mongodbatlas_encryption_at_rest/aws/multi-region-cluster/modules/multi-region-cluster/main.tf	Converts from deprecated `num_shards` to new sharding configuration with separate replication specs
docs/resources/advanced_cluster.md	Updates documentation to remove references to deprecated parameters and configurations
docs/guides/*.md	Updates migration guides and documentation to reflect removal of deprecated attributes
docs/data-sources/advanced_cluster*.md	Updates data source documentation to remove deprecated parameter references
.github/workflows/code-health.yml	Modifies CI workflow dependencies and test configuration

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

internal/service/team/resource_team.go

internal/service/team/data_source_team.go

...ongodbatlas_encryption_at_rest/aws/multi-region-cluster/modules/multi-region-cluster/main.tf

docs/data-sources/advanced_cluster.md

…-docs-examples

Co-authored-by: Copilot <[email protected]>

lantoli · 2025-09-04T05:04:14Z

docs/guides/2.0.0-upgrade-guide.md

@@ -40,6 +40,18 @@ New user and team management resources that replace deprecated invitation-based

 ## Breaking Changes

+### `mongodbatlas_advanced_cluster`
+Resource:
+  - Following attributes have been removed: `id`, `disk_size_gb`, `replication_specs.#.num_shards`, `replication_specs.#.id`, `advanced_configuration.default_read_concern`, `advanced_configuration.fail_index_key_too_long`. 


Suggested change

- Following attributes have been removed: `id`, `disk_size_gb`, `replication_specs.#.num_shards`, `replication_specs.#.id`, `advanced_configuration.default_read_concern`, `advanced_configuration.fail_index_key_too_long`.

- The following attributes have been removed: `id`, `disk_size_gb`, `replication_specs.#.num_shards`, `replication_specs.#.id`, `advanced_configuration.default_read_concern`, `advanced_configuration.fail_index_key_too_long`.

nit

lantoli · 2025-09-04T05:04:51Z

docs/guides/2.0.0-upgrade-guide.md

+  - For details, see [Migration Guide: Advanced Cluster (v1.x → v2.0.0)](migrate-to-advanced-cluster-2.0.md).
+
+Data source:
+  - Following attributes have been removed: `id`, `disk_size_gb`, `replication_specs.#.num_shards`, `replication_specs.#.id`, `advanced_configuration.default_read_concern`, `advanced_configuration.fail_index_key_too_long`, `use_replication_spec_per_shard`.


Suggested change

- Following attributes have been removed: `id`, `disk_size_gb`, `replication_specs.#.num_shards`, `replication_specs.#.id`, `advanced_configuration.default_read_concern`, `advanced_configuration.fail_index_key_too_long`, `use_replication_spec_per_shard`.

- The following attributes have been removed: `id`, `disk_size_gb`, `replication_specs.#.num_shards`, `replication_specs.#.id`, `advanced_configuration.default_read_concern`, `advanced_configuration.fail_index_key_too_long`, `use_replication_spec_per_shard`.

lantoli · 2025-09-04T05:09:49Z

docs/guides/2.0.0-upgrade-guide.md

+
+Data source:
+  - Following attributes have been removed: `id`, `disk_size_gb`, `replication_specs.#.num_shards`, `replication_specs.#.id`, `advanced_configuration.default_read_concern`, `advanced_configuration.fail_index_key_too_long`, `use_replication_spec_per_shard`.
+  - The data sources will now return only the new sharding configuration (one `replication_spec` for each shard) of the clusters that allows scaling shards independently.


q: not about doc, have we checked what happens when singular/plural ds refer to pre-ISS clusters, do we raise an error or ignore the cluster?

lantoli · 2025-09-04T05:11:10Z

docs/guides/advanced-cluster-new-sharding-schema.md

@@ -4,10 +4,11 @@ page_title: "Migration Guide: Advanced Cluster New Sharding Configurations"

 # Migration Guide: Advanced Cluster New Sharding Configurations

-**Objective**: Use this guide to migrate your existing `advanced_cluster` resources to support new sharding configurations introduced in version 1.18.0. The new sharding configurations allow you to scale shards independently. Additionally, as of version 1.23.0, compute auto-scaling supports scaling instance sizes independently for each shard when using the new sharding configuration. Existing sharding configurations continue to work, but you will receive deprecation messages if you continue to use them.
+**Objective**: Use this guide to migrate your existing `advanced_cluster` resources that may be using the legacy sharding schema _(i.e. using `num_shards` which was deprecated in v1.18.0 and removed in 2.0.0)_ to support the new sharding configurations instead. The new sharding configurations allow you to scale shards independently. Additionally, compute auto-scaling supports scaling instance sizes independently for each shard when using the new sharding configuration.


nit: refer by the full resource name, mongodbatlas_advanced_cluster, same for all occurences

maastha added 30 commits August 14, 2025 21:26

remove num shards logic

6827075

fmt

48fd9d6

tmp

a4a9cea

remove root disk_size_gb

a53266f

restructure

79d2212

Merge branch 'CLOUDP-320243-dev-2.0.0' into numShards-disk-gb-remove-poc

162d83c

remove advanced_config attrs

d70849f

add plan modifier

e56d7af

Merge branch 'CLOUDP-320243-dev-2.0.0' into numShards-disk-gb-remove-poc

b1ec818

changelog

16b7815

fmt

0ab2030

tmp revert

6c49c37

docs update

b70d292

ut disable

8739fd0

fmt

30d0085

remove use_replication_spec_per_shard

6cef0bb

fmt

393b011

fmt

0959a78

aws

1a229ef

fmt

84a0039

adv_config

049b858

nit

69cdbc2

Merge branch 'CLOUDP-320243-dev-2.0.0' into numShards-disk-gb-remove-poc

01fc6f9

extraInfo

4392e71

checkGeoShardedOldSchema

ea19cbd

fmt

19dfe3e

update test

28a5a26

disable mockable reduced tmp

ec18aae

fmt

c891d69

nit

71ce6d3

marcosuma reviewed Sep 1, 2025

View reviewed changes

docs/guides/migrate-to-advanced-cluster-2.0.md Outdated Show resolved Hide resolved

marcosuma approved these changes Sep 1, 2025

View reviewed changes

antellezr-mdb approved these changes Sep 1, 2025

View reviewed changes

nit

700bb62

AgustinBettati approved these changes Sep 2, 2025

View reviewed changes

maastha and others added 11 commits September 2, 2025 18:17

address PR comments

d23991a

Merge branch 'CLOUDP-320243-dev-2.0.0' into CLOUDP-333683-remove-old-…

c010456

…schema-attrs

address PR comments

ab85310

address PR comments

e6f6f49

add plan modifier test for node_count

542a198

Apply suggestions from code review

08ca903

Co-authored-by: Marco Suma <[email protected]>

address PR comments

a9bad40

remove root id from docs

f5bdaaf

remove root id from docs

280f48f

2.0 upgrade guide

d02c314

2.0 upgrade guide

8247c92

Base automatically changed from CLOUDP-333683-remove-old-schema-attrs to CLOUDP-320243-dev-2.0.0 September 3, 2025 23:44

Copilot AI review requested due to automatic review settings September 3, 2025 23:50

Copilot AI reviewed Sep 3, 2025

View reviewed changes

maastha force-pushed the CLOUDP-333683-docs-examples branch from 1903756 to 8247c92 Compare September 3, 2025 23:59

maastha and others added 4 commits September 4, 2025 02:00

Merge branch 'CLOUDP-333683-remove-old-schema-attrs' into CLOUDP-333683…

61506c9

…-docs-examples

Merge branch 'CLOUDP-320243-dev-2.0.0' into CLOUDP-333683-docs-examples

af8de3c

Update docs/data-sources/advanced_cluster.md

9d2b749

Co-authored-by: Copilot <[email protected]>

revert reduced_tests to false

65d3311

maastha mentioned this pull request Sep 4, 2025

remove: Removes mongodbatlas_advanced_cluster deprecated params #3592

Closed

13 tasks

lantoli reviewed Sep 4, 2025

View reviewed changes

lantoli approved these changes Sep 4, 2025

View reviewed changes

	- Following attributes have been removed: `id`, `disk_size_gb`, `replication_specs.#.num_shards`, `replication_specs.#.id`, `advanced_configuration.default_read_concern`, `advanced_configuration.fail_index_key_too_long`.
	- The following attributes have been removed: `id`, `disk_size_gb`, `replication_specs.#.num_shards`, `replication_specs.#.id`, `advanced_configuration.default_read_concern`, `advanced_configuration.fail_index_key_too_long`.

doc: Updates guides & examples for removal of mongodbatlas_advanced_cluster deprecated params #3634

Are you sure you want to change the base?

doc: Updates guides & examples for removal of mongodbatlas_advanced_cluster deprecated params #3634

Uh oh!

Conversation

maastha commented Aug 31, 2025

Description

Type of change:

Required Checklist:

Further comments

Uh oh!

Uh oh!

marcosuma left a comment

Choose a reason for hiding this comment

Uh oh!

antellezr-mdb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment • edited by maastha Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Pull Request Overview - OUTDATED - Please IGNORE

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

doc: Updates guides & examples for removal of `mongodbatlas_advanced_cluster` deprecated params #3634

doc: Updates guides & examples for removal of `mongodbatlas_advanced_cluster` deprecated params #3634

Copilot AI left a comment •

edited by maastha

Loading