Skip to content

Conversation

maastha
Copy link
Collaborator

@maastha maastha commented Oct 9, 2025

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 maastha marked this pull request as ready for review October 13, 2025 22:34
@maastha maastha requested review from a team as code owners October 13, 2025 22:34
@Copilot Copilot AI review requested due to automatic review settings October 13, 2025 22:34
@github-actions
Copy link
Contributor

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

Copy link
Contributor

@Copilot Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


... 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>"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

similarly about SA before

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

unrelated to this PR, but this makes me think: @lantoli we haven't thought about updating all examples to use SA, have we?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@marcosuma created this ticket: https://jira.mongodb.org/browse/CLOUDP-352831

@maastha feel free to skip these changes in this PR and we can do all SA to PAK changes in examples in that ticket

Copy link
Collaborator

@jwilliams-mongo jwilliams-mongo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

one minor comment but LGTM otherwise

Copy link
Collaborator

@marcosuma marcosuma left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

→ 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):
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@maastha yes, block vs attribute is clearer, especially if you link it to the Hashicorp Terraform documentation. Not sure if this text is still there though

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've now added a separate section for this
I tried finding an appropriate HC doc for this but didn't find anything relevant

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is the section and is referenced in various places through the doc

@marcosuma
Copy link
Collaborator

marcosuma commented Oct 15, 2025

Here's a proposed structure:

maastha and others added 2 commits October 15, 2025 11:59
Co-authored-by: John Williams <55147273+jwilliams-mongo@users.noreply.github.com>
@github-actions github-actions bot added the stale label Oct 21, 2025
@mongodb mongodb deleted a comment from github-actions bot Oct 21, 2025
- [Migrate advanced\_cluster type `SHARDED`](#migrate-advanced_cluster-type-sharded)
- [Migrate advanced\_cluster type `GEOSHARDED`](#migrate-advanced_cluster-type-geosharded)
- [Migrate advanced\_cluster type `REPLICASET`](#migrate-advanced_cluster-type-replicaset)
- [Upgrade type `REPLICASET` to `SHARDED`](#migrate-advanced_cluster-type-replicaset)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

curious: why the need to updating the link name here? The previous one was more consistent with the other two links

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

because if you look at the contents of this section it doesn't talk about "Migrating", this is what it starts with for example, To learn more, see the documentation on [transitioning from a replica set to a sharded cluster](https://www.mongodb.com/docs/atlas/scale-cluster/#scale-your-replica-set-to-a-sharded-cluster). so I think this is more appropriate as if you dont want to make the cluster sharded, you don't have to do anything in that case

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but why don't we have one migrate for REPLICASET by staying on REPLICASET? Is it because it's trivial? cc @AgustinBettati

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My understanding is it only involves removing num_shards , this example captures that but will wait for @AgustinBettati if I should add more context in the guides

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My understanding is it only involves removing num_shards

Correct, and most likely a replica set does not define num_shards = 1 so no action would be needed. I think the heading change makes sense 👍


In this section you can find the configuration changes between the legacy `mongodbatlas_advanced_cluster` and the new one released in v2.0.0.

## Identify your current setup
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

have you double checked how this table looks like on Terraform docs?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes, this is what it looks like:

image


... 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>"
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

unrelated to this PR, but this makes me think: @lantoli we haven't thought about updating all examples to use SA, have we?

Co-authored-by: Marco Suma <marco.suma@mongodb.com>
- [Migration Guide: Advanced Cluster New Sharding Configurations](#migration-guide-advanced-cluster-new-sharding-schema)
- [Changes Overview](#changes-overview)

If you are still using the deprecated `mongodbatlas_cluster` resource, use [Migration Guide: Cluster → Advanced Cluster instead](./cluster-to-advanced-cluster-migration-guide.md).
Copy link
Member

@lantoli lantoli Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If you are still using the deprecated `mongodbatlas_cluster` resource, use [Migration Guide: Cluster → Advanced Cluster instead](./cluster-to-advanced-cluster-migration-guide.md).
If you are still using the deprecated `mongodbatlas_cluster` resource, use [Migration Guide: Cluster → Advanced Cluster instead](./cluster-to-advanced-cluster-migration-guide).

let me know if you want me to generate a personal provider doc to check links and format

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes lets do that, ty!

After you upgrade to v2.0.0+ from v1.x.x, when you run `terraform plan`, you may run into syntax errors such as `Required attribute "replication_specs" not specified` or `Unexpected block: Blocks of type "advanced_configuration" are not expected here`. **This is expected** since the resource definition hasn't been updated yet using the latest schema.
At this point, you need to update the configuration by following all of below steps at once and finally running terraform apply:

- **Step #1:** Apply **all** configuration [changes mentioned here](#overview-of-configuration-changes-when-upgrading-from-1x) **until there are no errors and no planned changes**.
Copy link
Member

@lantoli lantoli Oct 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we can use normal numbered lists here, no need to say "step"

  1. blah blah
  2. blah blah
    ...

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find this more readable when looking at the preview:
image

maastha and others added 2 commits October 21, 2025 13:50
Co-authored-by: Leo Antoli <430982+lantoli@users.noreply.github.com>
Co-authored-by: Leo Antoli <430982+lantoli@users.noreply.github.com>
@maastha maastha removed the stale label Oct 21, 2025
@maastha maastha merged commit 0acfc1b into master Oct 22, 2025
46 checks passed
@maastha maastha deleted the adv-cluster-doc-ex branch October 22, 2025 02:48
lantoli added a commit that referenced this pull request Oct 22, 2025
* master:
  chore: Update SSDLC report for v2.1.0
  chore: Updates CHANGELOG.md header for v2.1.0 release
  chore: Update example links in registry docs for v2.1.0 release
  chore: Add support for typed nested objects in autogen (#3801)
  chore: Update examples and doc to use SA instead of PAK (#3804)
  chore: Updates CHANGELOG.md for #3793
  feat: Add workspace_name field in stream_processor resource and datasource (#3793)
  doc: Adds examples for advanced_cluster upgrade to v2.0 & improves documentation (#3767)

# Conflicts:
#	internal/serviceapi/streamprocessorapi/resource_schema.go
#	tools/codegen/config/config_model.go
#	tools/codegen/gofilegen/schema/schema_file_test.go
lantoli added a commit that referenced this pull request Oct 22, 2025
* master:
  chore: Update SSDLC report for v2.1.0
  chore: Updates CHANGELOG.md header for v2.1.0 release
  chore: Update example links in registry docs for v2.1.0 release
  chore: Add support for typed nested objects in autogen (#3801)
  chore: Update examples and doc to use SA instead of PAK (#3804)
  chore: Updates CHANGELOG.md for #3793
  feat: Add workspace_name field in stream_processor resource and datasource (#3793)
  doc: Adds examples for advanced_cluster upgrade to v2.0 & improves documentation (#3767)
  chore: Fix tests using GetIndependentShardScalingMode (#3799)
  chore: Don't send notifications in PRs or release (#3797)
  test: Adds delay to avoid flakiness in TestAccProjectAPIKey_recreateWhenDeletedExternally (#3798)
  move CloseTokenSource call out of defer (#3796)
  chore: Revoke SA tokens after Terraform command finishes (#3794)
  chore: Fix send_notification in Test Suite (#3792)
  chore: Document Troubleshooting SA (#3791)
  build(deps): bump go.mongodb.org/atlas-sdk (#3776)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants