Skip to content

doc: Implements v2 and v3 MongoDB Atlas cluster migration examples #3050

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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 26 commits into from
Feb 13, 2025
Merged

doc: Implements v2 and v3 MongoDB Atlas cluster migration examples #3050

merged 26 commits into from
Feb 13, 2025

Conversation

EspenAlbert
Copy link
Collaborator

@EspenAlbert EspenAlbert commented Feb 11, 2025 •
edited
Loading

Description

  • Implements v2 and v3 MongoDB Atlas cluster migration examples
  • PR remaining work
    • Choose approach for documenting implementation changes (see comments below)
  • Remaining work (out of scope for this PR)
    • Add descriptions to all variables
    • Handle TODOs
    • Docs review

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

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

EspenAlbert
EspenAlbert commented Feb 11, 2025
View reviewed changes
scripts/tf-validate.sh
@@ -14,6 +14,19 @@
# See the License for the specific language governing permissions and
# limitations under the License.

# TODO: remove this after releasing TPF
Copy link
Collaborator Author

@EspenAlbert EspenAlbert Feb 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Changes in this file are necessary to use v2 schema in examples

marcosuma
marcosuma reviewed Feb 11, 2025
View reviewed changes
examples/migrate_cluster_to_advanced_cluster/module_maintainer/README.md Outdated
@@ -10,4 +10,45 @@ Version | Purpose | Variables | Resources
[v2](./v2) | Migrate to advanced_cluster with no change in variables or plan | 5 | `mongodbatlas_advanced_cluster`
Copy link
Collaborator

Choose a reason for hiding this comment

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

@EspenAlbert @lantoli unrelated to this PR, but as we are using vX in so many places, could we call these sections with a different name? Perhaps just "Step 1, Step 2, ..."?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Updated partially in 12265f3
However, I prefer talking about module versions as v1, v2, etc. rather than Step 1, Step 2.

Copy link
Collaborator Author

@EspenAlbert EspenAlbert Feb 12, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Another update in d5a9be7
WDYT?

@marcosuma
Copy link
Collaborator

looking pretty solid! left some preliminary comments as you've asked

@EspenAlbert EspenAlbert marked this pull request as ready for review February 12, 2025 12:45
@EspenAlbert EspenAlbert requested a review from a team as a code owner February 12, 2025 12:45
lantoli
lantoli reviewed Feb 12, 2025
View reviewed changes
lantoli
lantoli reviewed Feb 12, 2025
View reviewed changes
examples/migrate_cluster_to_advanced_cluster/module_maintainer/v2/versions.tf
required_providers {
mongodbatlas = {
source = "mongodb/mongodbatlas"
version = "~> 1.26" # todo: PLACEHOLDER_TPF_RELEASE
Copy link
Member

Choose a reason for hiding this comment

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

what about using 1.27 as in the other examples I did, so we can search/replace easily if needed?

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, but I think it is better to change it later, otherwise CI will fail:

│ Error: Failed to query available provider packages
│ 
│ Could not retrieve the list of available versions for provider mongodb/mongodbatlas: no available releases match the given constraints ~> 1.26, ~> 1.27
│ 
│ To see which modules are currently depending on mongodb/mongodbatlas and what versions are specified, run the following command:
│     terraform providers

Copy link
Member

Choose a reason for hiding this comment

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

sounds good

Copy link
Member

Choose a reason for hiding this comment

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

created a ticket so we don't forget: CLOUDP-300537

lantoli
lantoli reviewed Feb 12, 2025
View reviewed changes
examples/migrate_cluster_to_advanced_cluster/module_user/README.md
- [Run Commands](#run-commands)
- [Step 2: Upgrade to `mongodbatlas_advanced_cluster` by using `v2` of the module](#step-2-upgrade-to-mongodbatlas_advanced_cluster-by-using-v2-of-the-module)
- [Step 3: Use the latest `mongodbatlas_advanced_cluster` features by using `v3` of the module](#step-3-use-the-latest-mongodbatlas_advanced_cluster-features-by-using-v3-of-the-module)
- [Update `v3.tfvars`](#update-v3tfvars)
Copy link
Member

Choose a reason for hiding this comment

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

should we recommend to do 3 in two steps, first having a new repl_spec without plan changes, then do some change?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

IMO: Not worth it, but open to change

Copy link
Member

Choose a reason for hiding this comment

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

I think it's important to educate users to have empty plans before doing any further change

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Ok. I'll add a variable file

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Added in c12fbdd

lantoli
lantoli approved these changes Feb 12, 2025
View reviewed changes
Copy link
Member

@lantoli lantoli left a comment

Choose a reason for hiding this comment

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

LGTM, great work, good for me to merge once comments are addressed

@lantoli
Copy link
Member

lantoli commented Feb 13, 2025

note that tf-validate is failing

@EspenAlbert
Copy link
Collaborator Author

EspenAlbert commented Feb 13, 2025 •
edited
Loading

note that tf-validate is failing

It was after updating the var name... Fixed in 58de2de
But now, merge conflict 🤦 merging with docs dev now

@EspenAlbert
Copy link
Collaborator Author

Merging. Need changes in #3058.
I will do another PR handling the remaining steps, so feel free to add more comments

  • Add descriptions to all variables
  • Handle TODOs
  • Docs review

@EspenAlbert EspenAlbert merged commit d2f0b0f into CLOUDP-274025-dev-docs-examples Feb 13, 2025
40 checks passed
@EspenAlbert EspenAlbert deleted the CLOUDP-299312_demos_cluster_mig_modules_v2 branch February 13, 2025 09:12
marcosuma
marcosuma reviewed Feb 13, 2025
View reviewed changes
examples/migrate_cluster_to_advanced_cluster/module_user/README.md
[v1](./v1) | <= PLACEHOLDER_TPF_RELEASE | Baseline configuration | -
[v2](./v2) | >= PLACEHOLDER_TPF_RELEASE | Only change to `v2` module version | No changes. Only moved.
[v3](./v3) | >= PLACEHOLDER_TPF_RELEASE | Usage of new variables to support multi-cloud and independent shard scaling | Yes (new features)
[Step 1](./v1) | `<= 1.27.0` | Baseline configuration | -
Copy link
Collaborator

Choose a reason for hiding this comment

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

Are we confident it's 1.27? it probably won't because we will have 1.27 next week for other features (unless we can also bundle this next week)

Copy link
Member

Choose a reason for hiding this comment

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

no, we have a ticket to update it if needed: CLOUDP-300537

lantoli added a commit that referenced this pull request Mar 11, 2025
@lantoli @EspenAlbert
@carriecwk @marcosuma @maastha @oarbusi @jwilliams-mongo @themantissa
doc: Merges CLOUDP-274025 docs & examples branch - DONT MERGE YET (#3079
015ba58 
)

* duplicate files (#3046)

* doc: Adds initial structure for module examples cluster_to_advanced_cluster (#3043)

* doc: Adds initial structure for module example cluster_to_advanced_cluster

* chore: fix lint errors

* refactor: directory move

* doc: Initial module_user

* doc: Remove hcl simplification purpose (most likely done only in module_maintainer)

* Update examples/migrate_cluster_to_advanced_cluster/module_maintainer/README.md

Co-authored-by: Leo Antoli <[email protected]>

* address PR comments

---------

Co-authored-by: Leo Antoli <[email protected]>

* duplicate files (#3052)

* doc: Examples for advanced_cluster preview v2 (#3054)

* root readme

* fix example as used region doesn't exist in GCP

* change examples

* undo comment

* doc for backing_provider_name

* doc: Create doc pages for `mongodb_advanced_cluster` schema v2 resource and data sources (#3048)

* add doc references at the beginning of the doc

* examples

* replace replication_specs.#

* leftover

* connection_strings

* Move and other changes

* rename schema to preview

* ds

* fix defaultMaxTimeMS links

* fix typo region_config

* Update docs/data-sources/advanced_clusters (preview v2).md

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

* Update docs/resources/advanced_cluster.md

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

* apply feedback

---------

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

* chore: Follow-up for PR 3054 (#3059)

* null default value

* org id

* doc: Rename env. var. to `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER` (#3064)

* rename env. var. to MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER

* change example doc

* update links and menu items

* fix links

* change style

* doc: Implements v2 and v3 MongoDB Atlas cluster migration examples (#3050)

* initial v2 & v3 implementations

* Adds `v2` Implementation Changes and Highlights

* doc: Update README with v3 implementation changes and highlights

* doc: Update README and add v1_v2 and v3 variable files for cluster migration examples

* style: fmt

* doc: Fix v3 usage of cluster data source

* feat: Add output for MongoDB connection strings in v1, v2, and v3 examples

* style: fmt

* chore: Enable Advanced Cluster V2 Schema validation in tf-validate script

* fix lint errors

* feat: Add function to check for V2 schema directories in tf-validate script

* refactor: Use approach 1 (file headings) rather than a table

* address PR comments

* docs: Update README files to enhance migration guidance for mongodbatlas_cluster to mongodbatlas_advanced_cluster

* address PR comments

* chore: Update ToC

* Review suggestions

* update var name

* docs: Enhance README to clarify standalone usage and upgrade support for module_maintainer

* fix: Update required_version comment for clarity in versions.tf files

* docs: Add v3_no_plan_changes and step for ensuring no changes when using new `replication_specs_new` variable

* update var name to make tf-validate pass

* fix: Update environment variable for Terraform validation in v2 schema

* docs: Update ToC

* fix: update restore command in tf-validate script to use preview_provider_v2.go

* doc: Adds migration example from `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster` (#3058)

* doc: Adds migration example from `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster`

* rename directory and example

* chore: use a Note to warn about creating a `mongodbatlas_cluster` and more details

* add review suggestions

* support using v2 schema in basic

* doc: Updates guide cluster to advanced_cluster and creates guide advanced_cluster preview provider v2 (#3071)

* new guide

* update docs

* some adjustements

* typos

* feedback

* best practices feedback

* fix identation

* doc: Adds remaining work to migrate_cluster_to_advanced_cluster examples (#3065)

* handle todos

* doc: Fix link in README for replication_specs in advanced cluster migration example

* doc: Enhance variable descriptions in migration examples

* doc: Update descriptions for outputs

* doc: Change regions_config type from set to list in replication_specs variable (otherwise priority order failure)

* doc: Change regions_config type from set to list in replication_specs variable (otherwise priority order failure)

* doc: Applies some feedback for migration guides doc (#3075)

* remove part about state

* add doc about using the env var locally

* doc: Updates table formatting and migration guides (#3076)

* doc: Updates table formatting

* clarify how to migrate

* change order

* move block section down

* apply feedback

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

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

---------

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

* fix mongodb_atlas typo

* address PR comments

* doc: Clarify purpose of migration example for Terraform module

* clarify when to use alternative

* own section for env.var.

* change option to use Import

* adjust step

* refactor: Improve formatting and consistency in preview provider v2 examples

* typo dot in deprecated

* Update docs/guides/advanced-cluster-preview-provider-v2.md

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

* style: add linebreaks to examples

* chore: Adds Flex GA documentation changes (#3087)

* Update examples/migrate_cluster_to_advanced_cluster/basic/README.md

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

* remove M0 info as it can be seen in Atlas doc

* plural ds description

* change migration guide title

* Update docs/guides/advanced-cluster-preview-provider-v2.md

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

* move output example

* doc: Adds examples for flex clusters in mongodbatlas_advanced_cluster in v2 examples (#3097)

* doc: Missing backported docs & followup (#3098)

* missing docs & followup

* v2 change

* missing changein v2

* Update examples/migrate_cluster_to_advanced_cluster/module_user/README.md

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

* rename Tags to tags

* remove "l" leftover

* typo add blank after dot

* typo

* unify [#]

* uppercase Flex

* adv cluster doc sync with v2

* align data sources

* Add docs suggestions

* apply feedback

* fix incorrect database reference in project_id

* add dot

* more dots added

* Update docs/guides/advanced-cluster-preview-provider-v2.md

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

* bi_connector

* Update docs/guides/advanced-cluster-preview-provider-v2.md

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

* Update docs/guides/advanced-cluster-preview-provider-v2.md

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

* Update docs/guides/advanced-cluster-preview-provider-v2.md

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

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

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

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

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

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

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

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

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

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

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

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

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

* remove "of a specs"

* order list

* change doc and info

* typo

* plural ds link

* update README in examples

* plugin limitations

* set old guides for 1.14.0 and 1.15.0 as they were published more than 1 year ago

* update examples provider version to 1.29

* v2 to 2.0.0

* move "main changes" section to resource doc page

* remove adv_cluster guide and move content to upgrade guide and resource page

* wip

* updates documentation.

* Update README.md file for the basic example.

* Update README.md file for the module example.

* syntax changes.

* fix tflint

* rename filenames from v2 to 2.0.0

* change links v2 to 2.0.0

* fix tflint for migration examples

* typo

* fix order in import process

* add reference update step

* update examples with todo and findings from demo branch `CLOUDP-299313_DO_NOT_DELETE_demo_tpf_adv_cluster_big`

* update tf-validate

* id to cluster_id

* Apply suggestions from code review

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

* address initial comments.

* add a main README.md file for the examples folder.

* move Terraform Actions doc

* small typo

* use explicit numbering

* change version requirement for v1 of the examples

* Update examples/migrate_cluster_to_advanced_cluster/README.md

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

* Update examples/migrate_cluster_to_advanced_cluster/basic/README.md

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

* add coming soon for plugin

* get plugin alternatives back

* update plugin doc

* change section

* indent coming soon

* same line for coming soon

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

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

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

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

* remove refs to cli plugin and fix text for the 'import+remove' approach.

* make some titles shorter.

---------

Co-authored-by: Espen Albert <[email protected]>
Co-authored-by: carriecwk <[email protected]>
Co-authored-by: Marco Suma <[email protected]>
Co-authored-by: Espen Albert <[email protected]>
Co-authored-by: maastha <[email protected]>
Co-authored-by: Oriol <[email protected]>
Co-authored-by: John Williams <[email protected]>
Co-authored-by: Melissa Plunkett <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@lantoli lantoli lantoli approved these changes

@marcosuma marcosuma marcosuma left review comments

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@EspenAlbert @marcosuma @lantoli