Skip to content

doc: Updates table formatting and migration guides #3076

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

Merged
merged 6 commits into from
Feb 17, 2025
Merged

doc: Updates table formatting and migration guides #3076

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2f4d661
doc: Updates table formatting
EspenAlbert Feb 17, 2025
e088eda
clarify how to migrate
lantoli Feb 17, 2025
073206b
change order
lantoli Feb 17, 2025
fb89053
move block section down
lantoli Feb 17, 2025
0a1574d
apply feedback
lantoli Feb 17, 2025
7ff6afb
Update docs/guides/cluster-to-advanced-cluster-migration-guide.md
lantoli Feb 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/guides/advanced-cluster-preview-provider-v2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,8 @@ tags = {
## Best Practices Before Migrating
Before doing any migration create a backup of your [Terraform state file](https://developer.hashicorp.com/terraform/cli/commands/state).

## How to migrate
## How to migrate `mongodbatlas_advanced_cluster` to Preview for MongoDB Atlas Provider v2

The process to migrate from current `mongodbatlas_advanced_cluster` to the one in Preview for MongoDB Atlas Provider v2 is as follows:
- Before starting, run `terraform plan` to make sure that there are no planned changes.
- Set environment variable `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER=true` in order to use the Preview for MongoDB Atlas Provider v2. You can also define the environment variable in your local development environment so your tools can use the new format and help you with linting and auto-completion.
Expand Down
58 changes: 29 additions & 29 deletions docs/guides/cluster-to-advanced-cluster-migration-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,39 @@ page_title: "Migration Guide: Cluster to Advanced Cluster"

**Objective**: This guide explains how to replace the `mongodbatlas_cluster` resource with the `mongodbatlas_advanced_cluster` resource. The data source(s) migration only requires [output changes](#output-changes) as data sources only read clusters.

**Note**: Please look at the section [Moved block](#moved-block) below for an improved migration path. We are also exploring additional migration paths. If interested to learn more or to test out directly please contact [email protected].

## Best Practices Before Migrating

Before doing any migration create a backup of your [Terraform state file](https://developer.hashicorp.com/terraform/cli/commands/state).

## Main Changes Between `mongodbatlas_cluster` and `mongodbatlas_advanced_cluster`
## Migration using Moved block (preferred)
Copy link
Collaborator

Choose a reason for hiding this comment

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

@lantoli I think this section is now "too high" :) It should go right before

## Migration using `terraform plan -generate-config-out=adv_cluster.tf`

otherwise it's hard to follow

Copy link
Collaborator

Choose a reason for hiding this comment

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

Also in the section

## Migration using `terraform plan -generate-config-out=adv_cluster.tf`
``` (line 119)

we should re-emphasise that `moved` is recommended. In addition we should also say that if they are moving they with that guide our recommendation is to do it following the latest schema (hence use the ENV VAR)

Copy link
Member

Choose a reason for hiding this comment

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

position updated here: fb89053

Copy link
Member

Choose a reason for hiding this comment

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

added more emphasis here: 0a1574d


The [moved block](https://developer.hashicorp.com/terraform/language/moved) is a Terraform feature that allows to move between resource types. It's conceptually similar to do `removed` and `import` but it's more convenient as it's done in one step, and can be used in `modules`. The main requirements are:
- Terraform version 1.8 or later is required, more info in the [State Move doc](https://developer.hashicorp.com/terraform/plugin/framework/resources/state-move).
- Preview for MongoDB Atlas Provider v2 of `mongodbatlas_advanced_cluster` is required, you can find more info in the [resource doc](../resources/advanced_cluster%2520%2528preview%2520provider%2520v2%2529) and the [Migration Guide: Advanced Cluster Preview Provider v2](advanced-cluster-preview-provider-v2).

The process to migrate from `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster` using the `moved` block is as follows:
- Before starting, run `terraform plan` to make sure that there are no planned changes.
- Add the `mongodbatlas_advanced_cluster` resource definition.
- Make sure environment variable `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER=true` is set in order to use the Preview for MongoDB Atlas Provider v2. You can also define the environment variable in your local development environment so your tools can use the new format and help you with linting and auto-completion.
- The [Atlas CLI plugin](https://github.com/mongodb-labs/atlas-cli-plugin-terraform) can be used to generate the `mongodbatlas_advanced_cluster` resource definition. This is the recommended method as it will generate a clean configuration keeping the original Terraform expressions.
- Alternatively, you can use the `terraform plan -generate-config-out=adv_cluster.tf` method to create the `mongodbatlas_advanced_cluster` resource definition, or create it manually.
- Comment out or delete the `mongodbatlas_cluster` resource definition.
- Add the `moved` block to your configuration file, e.g.:
```terraform
moved {
from = mongodbatlas_cluster.this
to = mongodbatlas_advanced_cluster.this
}
```
- Run `terraform plan` and make sure that there are no planned changes, only the moved should be shown. **Important**: Don't apply until planning shows only the moved changes. If it shows other changes, you will need to keep updating the `mongodb_atlas_advanced_cluster` configuration until it matches the original `mongodbatlas_cluster` configuration.
- Run `terraform apply` to apply the changes. The `mongodbatlas_cluster` resource will be removed from the Terraform state and the `mongodbatlas_advanced_cluster` resource will be added.
- At this moment you can delete the `moved` block from your configuration file, although it's recommended to keep it to help track the migrations.

You can find full-detailed examples in [migrate_cluster_to_advanced_cluster](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_cluster_to_advanced_cluster).

## Manual migration
Copy link
Member

Choose a reason for hiding this comment

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

nit: This section feels a little disconnected as I am not clear what part of the migration is manual. Does this refer to manual config changes? Maybe you can state this would be an alternative to using the CLI, and moved or remove/import can still be used for state manipulation.

Copy link
Member

Choose a reason for hiding this comment

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

i've changed to the original format, can you review the latest changes again and see if it's fine?


The main Changes Between `mongodbatlas_cluster` and `mongodbatlas_advanced_cluster` are:
1. Replication Spec Configuration: Supports different node types (electable, analytics, read_only) where hardware configuration can differ between node types. `regions_config` is renamed to `region_configs`.
2. Provider Settings: Moved from the top level to the replication spec allowing you to create multi-cloud clusters.
3. Auto Scaling: Moved from the top level to the replication spec allowing you to scale replication specs individually.
Expand Down Expand Up @@ -187,29 +213,3 @@ This method uses only [Terraform native tools](https://developer.hashicorp.com/t

### Terraform Actions
Using the `project_id` and `cluster.name`, Terraform imports your cluster and uses the new `mongodbatlas_advanced_cluster` schema to generate a configuration file. This file includes all configurable values in the schema, but none of the previous configuration defined for your `mongodbatlas_cluster`. Therefore, the new configuration will likely be a lot more verbose and contain none of your original [Terraform expressions.](https://developer.hashicorp.com/terraform/language/expressions)

## Moved block

The [moved block](https://developer.hashicorp.com/terraform/language/moved) is a Terraform feature that allows to move between resource types. It's conceptually similar to do `removed` and `import` but it's more convenient as it's done in one step, and can be used in `modules`. The main requirements are:
- Terraform version 1.8 or later is required, more info in the [State Move doc](https://developer.hashicorp.com/terraform/plugin/framework/resources/state-move).
- Preview for MongoDB Atlas Provider v2 of `mongodbatlas_advanced_cluster` is required, you can find more info in the [resource doc](../resources/advanced_cluster%2520%2528preview%2520provider%2520v2%2529) and the [Migration Guide: Advanced Cluster Preview Provider v2](advanced-cluster-preview-provider-v2).

The process to migrate from `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster` using the `moved` block is as follows:
- Before starting, run `terraform plan` to make sure that there are no planned changes.
- Add the `mongodbatlas_advanced_cluster` resource definition.
- Make sure environment variable `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER=true` is set in order to use the Preview for MongoDB Atlas Provider v2. You can also define the environment variable in your local development environment so your tools can use the new format and help you with linting and auto-completion.
- The [Atlas CLI plugin](https://github.com/mongodb-labs/atlas-cli-plugin-terraform) can be used to generate the `mongodbatlas_advanced_cluster` resource definition. This is the recommended method as it will generate a clean configuration keeping the original Terraform expressions.
- Alternatively, you can use the `terraform plan -generate-config-out=adv_cluster.tf` method to create the `mongodbatlas_advanced_cluster` resource definition, or create it manually.
- Comment out or delete the `mongodbatlas_cluster` resource definition.
- Add the `moved` block to your configuration file, e.g.:
```terraform
moved {
from = mongodbatlas_cluster.this
to = mongodbatlas_advanced_cluster.this
}
```
- Run `terraform plan` and make sure that there are no planned changes, only the moved should be shown. **Important**: Don't apply until planning shows only the moved changes. If it shows other changes, you will need to keep updating the `mongodb_atlas_advanced_cluster` configuration until it matches the original `mongodbatlas_cluster` configuration.
- Run `terraform apply` to apply the changes. The `mongodbatlas_cluster` resource will be removed from the Terraform state and the `mongodbatlas_advanced_cluster` resource will be added.
- At this moment you can delete the `moved` block from your configuration file, although it's recommended to keep it to help track the migrations.

You can find full-detailed examples in [migrate_cluster_to_advanced_cluster](https://github.com/mongodb/terraform-provider-mongodbatlas/tree/master/examples/migrate_cluster_to_advanced_cluster).
2 changes: 1 addition & 1 deletion examples/migrate_cluster_to_advanced_cluster/module_maintainer/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The purpose of this example is to demonstrate how a Terraform module can help in
The example contains three module versions which represent the three steps of the migration:

Step | Purpose | Resources
--- | --- | --- | ---
--- | --- | ---
[Step 1](./v1) | Baseline | `mongodbatlas_cluster`
[Step 2](./v2) | Migrate to advanced_cluster with no change in variables or plan | `mongodbatlas_advanced_cluster`
[Step 3](./v3) | Use the latest features of advanced_cluster | `mongodbatlas_advanced_cluster`
Expand Down