Skip to content

Commit 9cb43b4

Browse files
lantoliCopilotAgustinBettatilmkerbey-mdb
authored
doc: Update doc for adv2v2 command (#68)
Co-authored-by: Copilot <[email protected]> Co-authored-by: Agustin Bettati <[email protected]> Co-authored-by: lmkerbey-mdb <[email protected]>
1 parent 59e6f89 commit 9cb43b4

File tree

4 files changed

+434
-184
lines changed

4 files changed

+434
-184
lines changed

‎README.md

Lines changed: 15 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,6 @@
44

55
This repository contains the Atlas CLI plugin for [Terraform's MongoDB Atlas Provider](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs).
66

7-
It has the following commands to help with your Terraform configurations:
8-
- **clusterToAdvancedCluster**: Convert a `mongodbatlas_cluster` Terraform configuration to `mongodbatlas_advanced_cluster` (preview provider 2.0.0).
9-
107
## Installation
118

129
Install the [Atlas CLI](https://github.com/mongodb/mongodb-atlas-cli) if you haven't done it yet.
@@ -26,101 +23,33 @@ If you want to see the list of installed plugins or check if this plugin is inst
2623
atlas plugin list
2724
```
2825

29-
## Convert mongodbatlas_cluster to mongodbatlas_advanced_cluster (preview provider 2.0.0)
30-
31-
### Usage
26+
## Available Commands
3227

33-
You can find more information in the [Migration Guide: Cluster to Advanced Cluster](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/cluster-to-advanced-cluster-migration-guide).
28+
The plugin provides the following commands to help with your Terraform configurations:
3429

35-
**Note**: In order to use the **Preview for MongoDB Atlas Provider 2.0.0** of `mongodbatlas_advanced_cluster`, you need to set the environment variable `MONGODB_ATLAS_PREVIEW_PROVIDER_V2_ADVANCED_CLUSTER` to `true`.
30+
### 1. clusterToAdvancedCluster (clu2adv)
31+
Convert `mongodbatlas_cluster` resources to `mongodbatlas_advanced_cluster` Provider 2.0.0 schema.
3632

37-
If you want to convert a Terraform configuration from `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster`, use the following command:
33+
**Quick Start:**
3834
```bash
3935
atlas terraform clusterToAdvancedCluster --file in.tf --output out.tf
40-
```
41-
42-
you can also use shorter aliases, e.g.:
43-
```bash
36+
# or using alias
4437
atlas tf clu2adv -f in.tf -o out.tf
4538
```
4639

47-
If you want to include the `moved blocks` in the output file, use the `--includeMoved` or the `-m` flag.
48-
49-
If you want to overwrite the output file if it exists, or even use the same output file as the input file, use the `--replaceOutput` or the `-r` flag.
50-
51-
You can use the `--watch` or the `-w` flag to keep the plugin running and watching for changes in the input file. You can have input and output files open in an editor and see easily how changes to the input file affect the output file.
52-
53-
You can find [here](https://github.com/mongodb-labs/atlas-cli-plugin-terraform/tree/main/internal/convert/testdata/clu2adv) some examples of input files (suffix .in.tf) and the corresponding output files (suffix .out.tf).
40+
[📖 Full Documentation](./docs/command_clu2adv.md) | [🔄 Migration Guide: Cluster to Advanced Cluster](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/cluster-to-advanced-cluster-migration-guide)
5441

55-
### Dynamic blocks
42+
### 2. advancedClusterToV2 (adv2v2)
43+
Convert previous `mongodbatlas_advanced_cluster` configurations to the new Provider 2.0.0 schema with simplified structure.
5644

57-
`dynamic` blocks are used to generate multiple nested blocks based on a set of values.
58-
Given the different ways of using dynamic blocks, we recommend reviewing the output and making sure it fits your needs.
59-
60-
#### Dynamic blocks in tags and labels
61-
62-
You can use `dynamic` blocks for `tags` and `labels`. The plugin assumes that `for_each` has an expression which is evaluated to a `map` of strings.
63-
You can also combine the use of dynamic blocks in `tags` and `labels` with individual blocks in the same cluster definition, e.g.:
64-
```hcl
65-
tags {
66-
key = "environment"
67-
value = var.environment
68-
}
69-
dynamic "tags" {
70-
for_each = var.tags
71-
content {
72-
key = tags.key
73-
value = replace(tags.value, "/", "_")
74-
}
75-
}
76-
```
77-
78-
#### Dynamic blocks in regions_config
79-
80-
You can use `dynamic` blocks for `regions_config`. The plugin assumes that `for_each` has an expression which is evaluated to a `list` or `set` of objects. See this [guide](./docs/guide_clu2adv_dynamic_block.md) to learn more about some limitations.
81-
This is an example of how to use dynamic blocks in `regions_config`:
82-
```hcl
83-
replication_specs {
84-
num_shards = var.replication_specs.num_shards
85-
zone_name = var.replication_specs.zone_name # only needed if you're using zones
86-
dynamic "regions_config" {
87-
for_each = var.replication_specs.regions_config
88-
content {
89-
priority = regions_config.value.priority
90-
region_name = regions_config.value.region_name
91-
electable_nodes = regions_config.value.electable_nodes
92-
read_only_nodes = regions_config.value.read_only_nodes
93-
}
94-
}
95-
}
96-
```
97-
98-
#### Dynamic blocks in replication_specs
99-
100-
You can use `dynamic` blocks for `replication_specs`. The plugin assumes that `for_each` has an expression which is evaluated to a `list` of objects. See this [guide](./docs/guide_clu2adv_dynamic_block.md) to learn more about some limitations.
101-
This is an example of how to use dynamic blocks in `replication_specs`:
102-
```hcl
103-
dynamic "replication_specs" {
104-
for_each = var.replication_specs
105-
content {
106-
num_shards = replication_specs.value.num_shards
107-
zone_name = replication_specs.value.zone_name # only needed if you're using zones
108-
dynamic "regions_config" {
109-
for_each = replication_specs.value.regions_config
110-
content {
111-
electable_nodes = regions_config.value.electable_nodes
112-
priority = regions_config.value.priority
113-
read_only_nodes = regions_config.value.read_only_nodes
114-
region_name = regions_config.value.region_name
115-
}
116-
}
117-
}
118-
}
45+
**Quick Start:**
46+
```bash
47+
atlas terraform advancedClusterToV2 --file in.tf --output out.tf
48+
# or using alias
49+
atlas tf adv2v2 -f in.tf -o out.tf
11950
```
12051

121-
### Limitations
122-
123-
- `dynamic` blocks are supported with some [limitations](./docs/guide_clu2adv_dynamic_block.md).
52+
[📖 Full Documentation](./docs/command_adv2v2.md)
12453

12554
## Feedback
12655

‎docs/command_adv2v2.md

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
# Convert mongodbatlas_advanced_cluster to Provider 2.0.0 schema
2+
3+
The advancedClusterToV2 (adv2v2) command helps you migrate previous `mongodbatlas_advanced_cluster` configurations to the new Provider 2.0.0 schema.
4+
5+
This revised file migrates the Terraform configurations and state to the latest version and doesn't modify the resources deployed in MongoDB Atlas.
6+
7+
MongoDB Atlas Provider 2.0.0 introduces a new, cleaner structure for `mongodbatlas_advanced_cluster` resources. The main changes include the use of nested attributes instead of blocks and deletion of deprecated attributes like `disk_size_gb` at root level or `num_shards`.
8+
9+
## Usage
10+
11+
To convert a Terraform configuration from the previous `mongodbatlas_advanced_cluster` schema to the Provider 2.0.0 schema, use the following command:
12+
13+
```bash
14+
atlas terraform advancedClusterToV2 --file in.tf --output out.tf
15+
```
16+
17+
You can also use shorter aliases:
18+
```bash
19+
atlas tf adv2v2 -f in.tf -o out.tf
20+
```
21+
22+
### Command Options
23+
24+
- `--file` or `-f`: Input file path containing the `mongodbatlas_advanced_cluster` configuration
25+
- `--output` or `-o`: Output file path for the converted Provider 2.0.0 configuration
26+
- `--replaceOutput` or `-r`: Overwrite the file at the output path if it already exists. You can also modify the input file in-place.
27+
- `--watch` or `-w`: Keep the plugin running and watching for changes in the input file
28+
29+
## Examples
30+
31+
You can find [here](https://github.com/mongodb-labs/atlas-cli-plugin-terraform/tree/main/internal/convert/testdata/adv2v2) examples of input files (suffix .in.tf) and the corresponding output files (suffix .out.tf).
32+
33+
## Dynamic Blocks
34+
35+
`dynamic` blocks are used to generate multiple nested blocks based on a set of values.
36+
We recommend reviewing the output and making sure it fits your needs.
37+
38+
### Dynamic blocks in tags and labels
39+
40+
You can use `dynamic` blocks for `tags` and `labels`. The plugin assumes that the value of `for_each` is an expression which evaluates to a `map` of strings.
41+
You can also combine the use of dynamic blocks in `tags` and `labels` with individual blocks in the same cluster definition, for example:
42+
```hcl
43+
tags {
44+
key = "environment"
45+
value = var.environment
46+
}
47+
dynamic "tags" {
48+
for_each = var.tags
49+
content {
50+
key = tags.key
51+
value = replace(tags.value, "/", "_")
52+
}
53+
}
54+
```
55+
56+
### Dynamic blocks in region_configs
57+
58+
You can use `dynamic` blocks for `region_configs`. The plugin assumes that the value of `for_each` is an expression which evaluates to a `list` of objects.
59+
60+
This is an example of how to use dynamic blocks in `region_configs`:
61+
```hcl
62+
replication_specs {
63+
num_shards = var.replication_specs.num_shards
64+
zone_name = var.replication_specs.zone_name # only needed if you're using zones
65+
dynamic "region_configs" {
66+
for_each = var.replication_specs.region_configs
67+
content {
68+
priority = region_configs.value.priority
69+
provider_name = region_configs.value.provider_name
70+
region_name = region_configs.value.region_name
71+
electable_specs {
72+
instance_size = region_configs.value.instance_size
73+
node_count = region_configs.value.electable_node_count
74+
}
75+
# read_only_specs, analytics_specs, auto_scaling and analytics_auto_scaling can also be defined
76+
}
77+
}
78+
}
79+
```
80+
81+
### Dynamic blocks in replication_specs
82+
83+
You can use `dynamic` blocks for `replication_specs`. The plugin assumes that the value of `for_each` is an expression which evaluates to a `list` of objects.
84+
85+
This is an example of how to use dynamic blocks in `replication_specs`:
86+
```hcl
87+
dynamic "replication_specs" {
88+
for_each = var.replication_specs
89+
content {
90+
num_shards = replication_specs.value.num_shards
91+
zone_name = replication_specs.value.zone_name # only needed if you're using zones
92+
dynamic "region_configs" {
93+
for_each = replication_specs.value.region_configs
94+
priority = region_configs.value.priority
95+
provider_name = region_configs.value.provider_name
96+
region_name = region_configs.value.region_name
97+
electable_specs {
98+
instance_size = region_configs.value.instance_size
99+
node_count = region_configs.value.electable_node_count
100+
}
101+
# read_only_specs, analytics_specs, auto_scaling and analytics_auto_scaling can also be defined
102+
}
103+
}
104+
}
105+
```
106+
107+
### Limitations
108+
109+
If you need to use the plugin for `dynamic` block use cases not yet supported, please send us [feedback](https://github.com/mongodb-labs/atlas-cli-plugin-terraform/issues).
110+
111+
#### Combination of blocks with dynamic and inline expressions
112+
113+
Dynamic blocks and individual blocks for `region_configs` or `replication_specs` are not supported at the same time. To continue using this plugin, remove `region_configs` or `replication_specs` blocks and use a local `list` variable with [concat](https://developer.hashicorp.com/terraform/language/functions/concat) to add the individual block information to the variable you're using in the `for_each` expression.
114+
115+
#### Example
116+
117+
Let's see an example with `region_configs`, the same idea applies for `replication_specs`. In the original configuration file, the `mongodb_cluster` resource is used inside a module that receives the `region_configs` elements in a `list` variable and we want to add an additional `region_configs` with a read-only node.
118+
```hcl
119+
variable "replication_specs" {
120+
type = object({
121+
num_shards = number
122+
region_configs = list(object({
123+
priority = number
124+
provider_name = string
125+
region_name = string
126+
instance_size = string
127+
electable_node_count = number
128+
read_only_node_count = number
129+
}))
130+
})
131+
}
132+
133+
resource "mongodbatlas_advanced_cluster" "this" {
134+
project_id = var.project_id
135+
name = var.cluster_name
136+
cluster_type = var.cluster_type
137+
replication_specs {
138+
num_shards = var.replication_specs.num_shards
139+
dynamic "region_configs" {
140+
for_each = var.replication_specs.region_configs
141+
priority = region_configs.value.priority
142+
provider_name = region_configs.value.provider_name
143+
region_name = region_configs.value.region_name
144+
electable_specs {
145+
instance_size = region_configs.value.instance_size
146+
node_count = region_configs.value.electable_node_count
147+
}
148+
read_only_specs {
149+
instance_size = region_configs.value.instance_size
150+
node_count = region_configs.value.read_only_node_count
151+
}
152+
}
153+
region_configs { # individual region
154+
priority = 0
155+
provider_name = "AWS"
156+
region_name = "US_EAST_1"
157+
read_only_specs {
158+
instance_size = var.instance_size
159+
node_count = 1
160+
}
161+
}
162+
}
163+
}
164+
```
165+
166+
We modify the configuration file to create an intermediate `local` variable to merge the `region_configs` variable elements and the additional `region_configs`:
167+
```hcl
168+
variable "replication_specs" {
169+
type = object({
170+
num_shards = number
171+
region_configs = list(object({
172+
priority = number
173+
provider_name = string
174+
region_name = string
175+
instance_size = string
176+
electable_node_count = number
177+
read_only_node_count = number
178+
}))
179+
})
180+
}
181+
182+
locals {
183+
region_configs_all = concat(
184+
var.replication_specs.region_configs,
185+
[
186+
{
187+
priority = 0
188+
provider_name = "AWS"
189+
region_name = "US_EAST_1"
190+
instance_size = var.instance_size
191+
electable_node_count = 0
192+
read_only_node_count = 1
193+
},
194+
]
195+
)
196+
}
197+
198+
resource "mongodbatlas_advanced_cluster" "this" {
199+
project_id = var.project_id
200+
name = var.cluster_name
201+
cluster_type = var.cluster_type
202+
replication_specs {
203+
num_shards = var.replication_specs.num_shards
204+
dynamic "region_configs" {
205+
for_each = local.region_configs_all # changed to use the local variable
206+
priority = region_configs.value.priority
207+
provider_name = region_configs.value.provider_name
208+
region_name = region_configs.value.region_name
209+
electable_specs {
210+
instance_size = region_configs.value.instance_size
211+
node_count = region_configs.value.electable_node_count
212+
}
213+
read_only_specs {
214+
instance_size = region_configs.value.instance_size
215+
node_count = region_configs.value.read_only_node_count
216+
}
217+
}
218+
}
219+
}
220+
```
221+
This modified configuration file has the same behavior as the original one, but it doesn't have individual blocks anymore, only the `dynamic` block, so it's supported by the plugin.

0 commit comments

Comments
 (0)