doc: Adds examples for advanced_cluster upgrade to v2.0 & improves documentation #3767

maastha · 2025-10-09T00:07:27Z

Description

Adds examples for advanced_cluster upgrade to v2.0 & improves documentation.

This PR does not contain an example for modules which will be done as a follow-up.

Link to any related issue(s):

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

maastha · 2025-10-13T22:30:27Z

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


 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?


nit: this section may have some redundancy with the "Objective" in each guide, but will wait for the team for review first.

i'd probably follow the Objective style as in the other guides

could you clarify what you mean by "objective style"?

i mean we start many of the guides with an Objetive section, e.g.: https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/cluster-to-advanced-cluster-migration-guide

Right, there is some overlap between the two but still think we need a separate section because there are various guides that can be confusing for users, so this section is supposed to serve more as an index

Usually I would advise to combine these sections but I agree with @maastha that there is a lot of info here so I think it works

github-actions · 2025-10-13T22:34:45Z

APIx bot: a message has been sent to Docs Slack channel

Copilot

Pull Request Overview

This PR updates MongoDB Atlas provider documentation and examples to reflect the upgrade from v1.x to v2.0.0, removing references to preview functionality and updating documentation to reflect the stable release.

Updates documentation to reference provider v2.0.0 instead of v1.29.0 preview
Adds comprehensive examples for migrating from v1.x to v2.0.0 with side-by-side configurations
Improves build scripts to handle different provider versions during validation

Reviewed Changes

Copilot reviewed 37 out of 38 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
scripts/tf-validate.sh	Adds conditional handling for v1.x.x directories to use remote provider instead of local override
examples/mongodbatlas_advanced_cluster/*/README.md	Updates documentation to remove preview references and update version requirements
examples/mongodbatlas_advanced_cluster//v1.x.x/	Adds migration reference examples showing deprecated v1.x schema
examples/mongodbatlas_advanced_cluster/*/versions.tf	Adds version constraints for new examples
docs/guides/*.md	Updates migration guides with clearer targeting and improved cross-references

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

examples/mongodbatlas_advanced_cluster/flex-upgrade/main.tf

lantoli · 2025-10-14T10:04:01Z

docs/guides/cluster-to-advanced-cluster-migration-guide.md

 **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?


same, shouldn't we use the same Objective style?

lantoli · 2025-10-14T10:04:57Z

examples/mongodbatlas_advanced_cluster/asymmetric-sharded-cluster/v1.x.x/main.tf

@@ -0,0 +1,83 @@
+provider "mongodbatlas" {
+  public_key  = var.public_key


nit: we're releasing SA soon, and it'll be the recommended authentication method

good callout! I think that can be done as a follow-up. Since it would only require updating examples in the repo (& not TF docs) it should be okay to do post-SA release, WDYT?

yes, follow-up is fine

lantoli · 2025-10-14T10:05:36Z

examples/mongodbatlas_advanced_cluster/symmetric-sharded-cluster/README.md

+
+... or follow as in the `variables.tf` file and create **terraform.tfvars** file with all the variable values, ex:
+```
+public_key           = "<MONGODB_ATLAS_PUBLIC_KEY>"


similarly about SA before

jwilliams-mongo

one minor comment but LGTM otherwise

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

jwilliams-mongo · 2025-10-14T13:54:45Z

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


 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?


Usually I would advise to combine these sections but I agree with @maastha that there is a lot of info here so I think it works

EspenAlbert · 2025-10-15T07:19:40Z

examples/mongodbatlas_advanced_cluster/symmetric-sharded-cluster/main.tf

+  private_key = var.private_key
+}
+
+resource "mongodbatlas_advanced_cluster" "cluster" {


[nit] use this instead of cluster/project/etc. See naming conventions

EspenAlbert · 2025-10-15T07:20:50Z

scripts/tf-validate.sh

 for DIR in $(find ./examples -type f -name '*.tf' -exec dirname {} \; | sort -u); do
  [ ! -d "$DIR" ] && continue
  pushd "$DIR"
+  # For directories named like v1.x.x, do NOT use local override


EspenAlbert · 2025-10-15T07:22:17Z

examples/mongodbatlas_advanced_cluster/symmetric-sharded-cluster/main.tf

+  }]
+
+  advanced_configuration = {
+    javascript_enabled                   = true


Any reasoning behind these values?

marcosuma

Regarding the docs/guides: I think we should consider streamlining them and think of them by connecting the target configuration and what are the starting points.

For example:

the target is mongodbatlas_advanced_cluster 2.0.0 (which includes ISS, no deprecated fields and TPF)
the starting points are:
- #1 mongodbatlas_cluster
- #2 mongodbatlas_advanced_cluster SDKv2 (pre-ISS and post-ISS)
- #3 mongodbatlas_advanced_cluster preview (post-ISS only)

We should basically re-organise our guides with the following tenets:

each starting point and target to have an how-to and an example
each guide to have the exact same identical structure

I find, in fact, that "## Who should read this guide?" could help but it looks like a patch to what we have now instead of reorganising it to make it more intuitive.

marcosuma · 2025-10-14T16:22:44Z

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

+  → 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):    


I am not sure I would understand what are list-style attributes as a customer

I understand, do you think "block" vs "attribute" may be better wording for users? Essentially, don't think we can directly say "TPF" as that's more of an implementation detail that users may not understand.
Or may be make it more descriptive with "attributes (containing of an = sign)..." or something? Tried to keep it as short as possible

marcosuma · 2025-10-15T07:41:57Z

Here's a proposed structure:

Migration Guide: Cluster to Advanced Cluster
Migration Guide: Advanced Cluster v1.x to v2
- Scenario 1: SDKv2 pre-ISS (this is where you can reuse most of the https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema)
- Scenario 2: SDKv2 post-ISS
- Scenario 3: preview

Co-authored-by: John Williams <[email protected]>

maastha added 10 commits October 8, 2025 23:58

cleanup

44f53c8

init examples

7de8b29

nit

da12de7

move to sub directory

ddb255f

move to sub directory

f2b83c5

readme

5a52443

readme

4a3f929

who should read this

f4cce6d

nit

ae2c6ab

nit

3020d5e

maastha commented Oct 13, 2025

View reviewed changes

maastha added 2 commits October 14, 2025 00:33

nit

97805a6

nit

98bc7ad

maastha marked this pull request as ready for review October 13, 2025 22:34

maastha requested review from a team as code owners October 13, 2025 22:34

Copilot AI review requested due to automatic review settings October 13, 2025 22:34

Copilot AI reviewed Oct 13, 2025

View reviewed changes

examples/mongodbatlas_advanced_cluster/flex-upgrade/main.tf Show resolved Hide resolved

lantoli reviewed Oct 14, 2025

View reviewed changes

jwilliams-mongo approved these changes Oct 14, 2025

View reviewed changes

EspenAlbert reviewed Oct 15, 2025

View reviewed changes

marcosuma reviewed Oct 15, 2025

View reviewed changes

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

733c619

Co-authored-by: John Williams <[email protected]>


		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?

		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?

		@@ -0,0 +1,83 @@
		provider "mongodbatlas" {
		public_key = var.public_key

doc: Adds examples for advanced_cluster upgrade to v2.0 & improves documentation #3767

Are you sure you want to change the base?

doc: Adds examples for advanced_cluster upgrade to v2.0 & improves documentation #3767

Uh oh!

Conversation

maastha commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change:

Required Checklist:

Further comments

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!

github-actions bot commented Oct 13, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

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!

lantoli Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jwilliams-mongo left a comment

Choose a reason for hiding this comment

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!

EspenAlbert Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

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!

marcosuma commented Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

maastha commented Oct 9, 2025 •

edited

Loading

lantoli Oct 14, 2025 •

edited

Loading

EspenAlbert Oct 15, 2025 •

edited

Loading

marcosuma left a comment •

edited

Loading

marcosuma commented Oct 15, 2025 •

edited

Loading