-
Notifications
You must be signed in to change notification settings - Fork 207
doc: Adds examples for advanced_cluster upgrade to v2.0 & improves documentation #3767
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
APIx bot: a message has been sent to Docs Slack channel |
There was a problem hiding this 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.
examples/mongodbatlas_advanced_cluster/asymmetric-sharded-cluster/v1.x.x/main.tf
Show resolved
Hide resolved
|
||
... 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>" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
similarly about SA before
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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
There was a problem hiding this 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
examples/mongodbatlas_advanced_cluster/symmetric-sharded-cluster/main.tf
Show resolved
Hide resolved
examples/mongodbatlas_advanced_cluster/symmetric-sharded-cluster/main.tf
Show resolved
Hide resolved
There was a problem hiding this 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:
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): |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
### Attribute vs Block Syntax |
Here's a proposed structure:
|
Co-authored-by: John Williams <55147273+jwilliams-mongo@users.noreply.github.com>
- [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) |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
|
||
... 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>" |
There was a problem hiding this comment.
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). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
There was a problem hiding this comment.
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**. |
There was a problem hiding this comment.
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"
- blah blah
- blah blah
...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
examples/mongodbatlas_advanced_cluster/asymmetric-sharded-cluster/v1.x.x/main.tf
Show resolved
Hide resolved
examples/mongodbatlas_advanced_cluster/asymmetric-sharded-cluster/v1.x.x/variables.tf
Show resolved
Hide resolved
Co-authored-by: Leo Antoli <430982+lantoli@users.noreply.github.com>
Co-authored-by: Leo Antoli <430982+lantoli@users.noreply.github.com>
* 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
* 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)
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:
Required Checklist:
Further comments