doc: Update effective field documentation #3891

lantoli · 2025-11-18T08:55:44Z

Description

Update effective field documentation

All the documentation changes are done in this PR to ensure consistency
Implementation is not done yet so it's ok that tf-validate PR check fails as use_effective_fields is not implemented yet

Doc changes:

Introduce use_effective_fields, explain why we need it and its opt-in nature in order to ensure full backward compatibility
Update guides and resource documentation to explain how this feature enhances the auto-scaling experience
Document alignment with the vision for mongodbatlas_advanced_cluster in Terraform provider 3.0.0, where the boolean attribute will be removed in Terraform and always enabled in Atlas operations

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

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

github-actions · 2025-11-19T13:52:01Z

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

Copilot

Pull Request Overview

This PR updates documentation to introduce the use_effective_fields attribute for the mongodbatlas_advanced_cluster resource. This new opt-in feature simplifies auto-scaling workflows by eliminating the need for lifecycle.ignore_changes blocks and providing visibility into Atlas-managed changes through effective field attributes.

Key Changes:

Introduction of use_effective_fields attribute documentation explaining its purpose and benefits for auto-scaling scenarios
Updates to examples demonstrating the recommended approach for managing auto-scaled clusters
Addition of new module examples showing how to build reusable Terraform modules that support both auto-scaling and non-auto-scaling configurations

Reviewed Changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
examples/mongodbatlas_network_peering/gcp/cluster.tf	Demonstrates use_effective_fields in a VPC peering scenario, removes lifecycle blocks
examples/mongodbatlas_advanced_cluster/effective-fields-module/*/versions.tf	Defines Terraform and provider version requirements for new module examples
examples/mongodbatlas_advanced_cluster/effective-fields-module/*/variables.tf	Defines input variables for module examples
examples/mongodbatlas_advanced_cluster/effective-fields-module/*/main.tf	Implements module examples with and without auto-scaling using use_effective_fields
examples/mongodbatlas_advanced_cluster/effective-fields-module/module/*.tf	Provides reusable module implementation demonstrating effective fields usage
examples/mongodbatlas_advanced_cluster/effective-fields-module/README.md	Comprehensive documentation for the effective fields module examples
examples/mongodbatlas_advanced_cluster/auto-scaling-per-shard/.	Updates auto-scaling per shard example to use recommended use_effective_fields approach
docs/resources/advanced_cluster.md	Extensive documentation updates explaining use_effective_fields, effective specs, and migration path
docs/guides/*.md	Updates migration and sharding guides to reference new effective fields functionality
docs/data-sources/advanced_cluster*.md	Documents use_effective_fields and effective spec attributes in data sources

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

examples/mongodbatlas_network_peering/gcp/cluster.tf

examples/mongodbatlas_advanced_cluster/effective-fields-module/README.md

docs/resources/advanced_cluster.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

marcosuma · 2025-11-19T14:55:39Z

docs/data-sources/advanced_cluster.md


 * `project_id` - (Required) The unique ID for the project to create the cluster.
 * `name` - (Required) Name of the cluster as it appears in Atlas. Once the cluster is created, its name cannot be changed.
+* `use_effective_fields` - (Optional) Controls how hardware specification fields are returned in the response. When set to true, returns the original client-specified values and provides separate effective fields showing current operational values. When false (default), hardware specification fields show current operational values directly. Primarily used for autoscaling compatibility. **Note:** Effective specs (`effective_electable_specs`, `effective_analytics_specs`, `effective_read_only_specs`) are always returned independently of the flag value. See the resource documentation for [Auto-Scaling with Effective Fields](../resources/advanced_cluster.md#auto-scaling-with-effective-fields) for more details.


Suggested change

* `use_effective_fields` - (Optional) Controls how hardware specification fields are returned in the response. When set to true, returns the original client-specified values and provides separate effective fields showing current operational values. When false (default), hardware specification fields show current operational values directly. Primarily used for autoscaling compatibility. **Note:** Effective specs (`effective_electable_specs`, `effective_analytics_specs`, `effective_read_only_specs`) are always returned independently of the flag value. See the resource documentation for [Auto-Scaling with Effective Fields](../resources/advanced_cluster.md#auto-scaling-with-effective-fields) for more details.

* `use_effective_fields` - (Optional) Controls how hardware specification fields (e.g. `instance_size`) are returned in the response. When set to true, returns the original client-specified values and provides separate effective fields showing current operational values. When false (default), hardware specification fields show current operational values directly. Primarily used for autoscaling compatibility. **Note:** Effective specs (`effective_electable_specs`, `effective_analytics_specs`, `effective_read_only_specs`) are always returned independently of the flag value. See the resource documentation for [Auto-Scaling with Effective Fields](../resources/advanced_cluster.md#auto-scaling-with-effective-fields) for more details.

I think Primarily used for autoscaling compatibility. is confusing, what are you referring to?

the first part is directly got from API doc: "Controls how hardware specification fields are returned in the response. When set to true, returns the original client-specified values and provides separate effective fields showing current operational values. When false (default), hardware specification fields show current operational values directly. Primarily used for autoscaling compatibility."

Agreed it's a bit confusing, I interpreted it's to help with autoscaling

looking with @jwilliams-mongo to change it

changed here: 8a1a4e6 and here: fa08b39

marcosuma · 2025-11-19T14:56:39Z

docs/data-sources/advanced_cluster.md


 * `project_id` - (Required) The unique ID for the project to create the cluster.
 * `name` - (Required) Name of the cluster as it appears in Atlas. Once the cluster is created, its name cannot be changed.
+* `use_effective_fields` - (Optional) Controls how hardware specification fields are returned in the response. When set to true, returns the original client-specified values and provides separate effective fields showing current operational values. When false (default), hardware specification fields show current operational values directly. Primarily used for autoscaling compatibility. **Note:** Effective specs (`effective_electable_specs`, `effective_analytics_specs`, `effective_read_only_specs`) are always returned independently of the flag value. See the resource documentation for [Auto-Scaling with Effective Fields](../resources/advanced_cluster.md#auto-scaling-with-effective-fields) for more details.


could we perhaps link this section to the previous "ignore_changes" recommendation we have in our docs, meaning that setting it to true resolves the need of using ignore_changes

data source doc doesn't mention ignore_changes, it's only in the resource doc, that's why I think it's fine as it is, with the last link to the resource effective-field specific section with all the info including ignore_changes: ../resources/advanced_cluster.md#auto-scaling-with-effective-fields

or maybe i didn't understand you

marcabreracast · 2025-11-19T15:12:24Z

docs/data-sources/advanced_cluster.md


 ```terraform
-resource "mongodbatlas_advanced_cluster" "example" {
+resource "mongodbatlas_advanced_cluster" "this" {


Nice! Ensuring consistency 😄

yes, I remembered @EspenAlbert suggestion 😄

AgustinBettati

LGTM

docs/resources/advanced_cluster.md

AgustinBettati · 2025-11-19T15:21:15Z

examples/mongodbatlas_advanced_cluster/auto-scaling-per-shard/main.tf

+  name                 = "AutoScalingCluster"
+  cluster_type         = "SHARDED"
+  use_effective_fields = true
+


nit: Maybe we can add a comment on the electable_specs.instance_size attribute to clarify the value will be preserved but will not reflect actual scaling.

good idea, added this comment when applicable:

instance_size = "M10" # Initial size value that won't change in Terraform state, actual size in Atlas may differ due to auto-scaling

AgustinBettati · 2025-11-19T15:22:08Z

examples/mongodbatlas_advanced_cluster/effective-fields-module/README.md

@@ -0,0 +1,297 @@
+# MongoDB Atlas Advanced Cluster Module with Effective Fields
+
+This example demonstrates a reusable Terraform module for MongoDB Atlas clusters that supports both auto-scaling and non-auto-scaling configurations without requiring `lifecycle.ignore_changes` blocks.


+1 very nicely written

examples/mongodbatlas_advanced_cluster/effective-fields-module/README.md

marcabreracast · 2025-11-19T16:02:04Z

docs/data-sources/advanced_clusters.md

+```terraform
+resource "mongodbatlas_advanced_cluster" "this" {
+  project_id            = "<YOUR-PROJECT-ID>"
+  name                  = "auto-scale-cluster-1"


Nit: Do we have specific criteria for naming clusters? I've noticed it usually follows a CamelCase format (i.e SymmetricShardedCluster), but in others like this one, the spinal-case is used.

I think we don't but agreed we could

marcabreracast

LGTM

jwilliams-mongo

a few minor comments (mainly suggested revision of use_effective_fields definition). Looks great

jwilliams-mongo · 2025-11-19T16:57:58Z

docs/data-sources/advanced_cluster.md


 * `project_id` - (Required) The unique ID for the project to create the cluster.
 * `name` - (Required) Name of the cluster as it appears in Atlas. Once the cluster is created, its name cannot be changed.
+* `use_effective_fields` - (Optional) Controls how hardware specification fields are returned in the response. When set to true, returns the original client-specified values and provides separate effective fields showing current operational values. When false (default), hardware specification fields show current operational values directly. Primarily used for autoscaling compatibility. **Note:** Effective specs (`effective_electable_specs`, `effective_analytics_specs`, `effective_read_only_specs`) are always returned independently of the flag value. See the resource documentation for [Auto-Scaling with Effective Fields](../resources/advanced_cluster.md#auto-scaling-with-effective-fields) for more details.


Suggested change

* `use_effective_fields` - (Optional) Controls how hardware specification fields are returned in the response. When set to true, returns the original client-specified values and provides separate effective fields showing current operational values. When false (default), hardware specification fields show current operational values directly. Primarily used for autoscaling compatibility. **Note:** Effective specs (`effective_electable_specs`, `effective_analytics_specs`, `effective_read_only_specs`) are always returned independently of the flag value. See the resource documentation for [Auto-Scaling with Effective Fields](../resources/advanced_cluster.md#auto-scaling-with-effective-fields) for more details.

* `use_effective_fields` - (Optional) Controls how hardware specification fields are returned in the response. When set to true, the `analytics_specs`, electable_specs`, and `read_only_specs` fields return the hardware specifications that the client provided. When set to false (default), the `analytics_specs`, electable_specs`, and `read_only_specs` fields show the **current** hardware specifications. Cluster auto-scaling is the primary cause for differences between initial and current hardware specifications. **Note:** Effective specs (`effective_electable_specs`, `effective_analytics_specs`, `effective_read_only_specs`) are always returned regardless of the flag value and always report the **current** hardware specifications. See the resource documentation for [Auto-Scaling with Effective Fields](../resources/advanced_cluster.md#auto-scaling-with-effective-fields) for more details.

left a few suggestions for clarity. One question: if a user manually scales a cluster and this field is set to true would the original hardware configuration or the new one be returned for the non-effective fields? The answer might cause me to slightly alter suggestion

the first part is exactly like that in API doc: "Controls how hardware specification fields are returned in the response. When set to true, returns the original client-specified values and provides separate effective fields showing current operational values. When false (default), hardware specification fields show current operational values directly. Primarily used for autoscaling compatibility."

@jwilliams-mongo I'm ok to change it here, then do you mind to create a ticket to MMS to align with your suggestion? Or we can keep Atlas doc text if that's preferred.

return the hardware specifications that the client provided when the resource was created

not totally accurate, the user can update the cluster specs in TF config and these new values will be returned, so we can delete "when the resource was created" from that sentence.

if a user manually scales a cluster and this field is set to true would the original hardware configuration or the new one be returned for the non-effective fields

for non-effective specs: the original one (configured in Terraform) when true so there is no state drift

for effective specs: always the new values, are unaffected by flag value.

I can file a ticket because we should adjust this upstream as well. I had to read it a few times to understand as-written.

revised suggestion to remove "when resource was created".

thanks @jwilliams-mongo for taking care of the MMS ticket.

I've updated the doc with your suggestion, only difference i've reduced writing the 3 specs to only once, WDYT? commit with changes: 8a1a4e6

was not correct, fixed here: fa08b39

jwilliams-mongo · 2025-11-19T16:58:34Z

docs/data-sources/advanced_clusters.md

 ## Argument Reference

 * `project_id` - (Required) The unique ID for the project to get the clusters.
+* `use_effective_fields` - (Optional) Controls how hardware specification fields are returned in the response. When set to true, returns the original client-specified values and provides separate effective fields showing current operational values. When false (default), hardware specification fields show current operational values directly. Primarily used for autoscaling compatibility. **Note:** Effective specs (`effective_electable_specs`, `effective_analytics_specs`, `effective_read_only_specs`) are always returned independently of the flag value. See the resource documentation for [Auto-Scaling with Effective Fields](../resources/advanced_cluster.md#auto-scaling-with-effective-fields) for more details.


see comment above

docs/guides/advanced-cluster-new-sharding-schema.md

examples/mongodbatlas_advanced_cluster/auto-scaling-per-shard/README.md

jwilliams-mongo · 2025-11-19T17:01:59Z

examples/mongodbatlas_advanced_cluster/effective-fields-module/README.md

@@ -0,0 +1,297 @@
+# MongoDB Atlas Advanced Cluster Module with Effective Fields
+
+This example demonstrates a reusable Terraform module for MongoDB Atlas clusters that supports both auto-scaling and non-auto-scaling configurations without requiring `lifecycle.ignore_changes` blocks.


+1 very nicely written

Co-authored-by: John Williams <55147273+jwilliams-mongo@users.noreply.github.com>

…README.md Co-authored-by: John Williams <55147273+jwilliams-mongo@users.noreply.github.com>

docs/guides/advanced-cluster-new-sharding-schema.md

* CLOUDP-313272-dev-effective-fields: test: Fixes `TestAccEventTriggerDSPlural_realmClientWorks` failing test (#3899) chore: Bump actions/checkout from 5.0.0 to 5.0.1 (#3896) chore: Bump github.com/hashicorp/terraform-plugin-log (#3897) chore: Avoids accidental context.Background usage to support all analytics (#3888) doc: Fix assume_role.role_arn doc (#3894) build(deps): bump go.mongodb.org/atlas-sdk (#3890) Add older version of autogen cluster_api (#3892) chore: Generate and consume flattened multi-version API Spec in autogeneration (#3884)

bodegus · 2025-11-20T12:59:20Z

I propose we make effective fields the only recommendation and remove the life cycle improvement reference and note

Option 2: If not using use_effective_fields, use a lifecycle ignore customization to prevent unintended changes. To explicitly change disk_size_gb or instance_size values, comment out the lifecycle block and run terraform apply. Please be sure to uncomment the lifecycle block once done to prevent any accidental changes.

Example: ignore disk_size_gb and instance_size changes in a replica set
lifecycle {
ignore_changes = [
replication_specs[0].region_configs[0].electable_specs.disk_size_gb,
replication_specs[0].region_configs[0].electable_specs.instance_size,
replication_specs[0].region_configs[0].electable_specs.disk_iops # instance_size change can affect disk_iops in case that you are using it
]
}
Copy
IMPORTANT:
With Option 2, when disk_gb_enabled or compute_enabled is true, Atlas automatically scales the cluster up or down. This will cause the value of replication_specs[#].region_config[#].(electable_specs|read_only_specs).disk_size_gb or replication_specs[#].region_config[#].(electable_specs|read_only_specs).instance_size returned to potentially be different than what is specified in the Terraform config. If you then apply a plan without the lifecycle ignore customization, Terraform will scale the cluster back to the original values in the config.

lantoli · 2025-11-20T14:42:59Z

as discussed offline I'm going to go ahead and merge

lantoli added 13 commits November 18, 2025 09:54

initial doc

73e080b

module example

fd4f4a3

network peering with effective fields

06e3a28

minor changes

e871e39

improve resource doc

9406537

update flag description

29d7b8a

versions.tf file

329469f

this

9202ae1

reorder examples

259c05e

classify examples

421c159

add effective specs in region_configs in resource

db28bfd

improve auto_scaling notes

27b9abd

improve effective fields section

f3aea33

lantoli changed the title ~~chore: Doc WIP~~ chore: Update effective field documentation Nov 19, 2025

lantoli added 5 commits November 19, 2025 12:40

fix cluster formatting in new sharding guide

5434a88

improve example

ab2aa05

reorder section

a7d76b4

improve example

0a02431

simplify Terraform Modules section

a0c34ed

lantoli marked this pull request as ready for review November 19, 2025 13:51

lantoli requested review from a team as code owners November 19, 2025 13:51

Copilot AI review requested due to automatic review settings November 19, 2025 13:51

Copilot AI reviewed Nov 19, 2025

View reviewed changes

examples/mongodbatlas_network_peering/gcp/cluster.tf Outdated Show resolved Hide resolved

examples/mongodbatlas_advanced_cluster/effective-fields-module/README.md Show resolved Hide resolved

docs/resources/advanced_cluster.md Outdated Show resolved Hide resolved

lantoli and others added 2 commits November 19, 2025 14:53

Update examples/mongodbatlas_network_peering/gcp/cluster.tf

755aef0

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

auto_scale notes at the end of the section

7aa65a5

lantoli changed the title ~~chore: Update effective field documentation~~ doc: Update effective field documentation Nov 19, 2025

marcosuma approved these changes Nov 19, 2025

View reviewed changes

marcabreracast reviewed Nov 19, 2025

View reviewed changes

AgustinBettati approved these changes Nov 19, 2025

View reviewed changes

marcabreracast reviewed Nov 19, 2025

View reviewed changes

marcabreracast approved these changes Nov 19, 2025

View reviewed changes

jwilliams-mongo reviewed Nov 19, 2025

View reviewed changes

lantoli and others added 4 commits November 19, 2025 18:26

Update docs/guides/advanced-cluster-new-sharding-schema.md

dd6f73d

Co-authored-by: John Williams <55147273+jwilliams-mongo@users.noreply.github.com>

Update examples/mongodbatlas_advanced_cluster/auto-scaling-per-shard/…

07368e2

…README.md Co-authored-by: John Williams <55147273+jwilliams-mongo@users.noreply.github.com>

flag in data source examples

70ec127

feedback use_effective_fields attribute doc

8a1a4e6

jwilliams-mongo approved these changes Nov 19, 2025

View reviewed changes

fix use_effective_fields doc

fa08b39

EspenAlbert reviewed Nov 20, 2025

View reviewed changes

docs/guides/advanced-cluster-new-sharding-schema.md Outdated Show resolved Hide resolved

EspenAlbert approved these changes Nov 20, 2025

View reviewed changes

oarbusi approved these changes Nov 20, 2025

View reviewed changes

lantoli added 3 commits November 20, 2025 12:31

document instance_size behavior

bd644d6

document instance_size behavior in analytics_specs

4dc42fa

revert comment when flag is not used

368b363

lantoli merged commit 3938b53 into CLOUDP-313272-dev-effective-fields Nov 20, 2025
47 of 48 checks passed

lantoli deleted the CLOUDP-360060_doc branch November 20, 2025 14:44

		@@ -0,0 +1,297 @@
		# MongoDB Atlas Advanced Cluster Module with Effective Fields

		This example demonstrates a reusable Terraform module for MongoDB Atlas clusters that supports both auto-scaling and non-auto-scaling configurations without requiring `lifecycle.ignore_changes` blocks.

doc: Update effective field documentation #3891

doc: Update effective field documentation #3891

Uh oh!

Conversation

lantoli commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change:

Required Checklist:

Further comments

Uh oh!

github-actions bot commented Nov 19, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lantoli Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AgustinBettati left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marcabreracast left a comment

Choose a reason for hiding this comment

Uh oh!

jwilliams-mongo left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jwilliams-mongo Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lantoli Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lantoli commented Nov 18, 2025 •

edited

Loading

lantoli Nov 19, 2025 •

edited

Loading

jwilliams-mongo left a comment •

edited

Loading

jwilliams-mongo Nov 19, 2025 •

edited

Loading

lantoli Nov 19, 2025 •

edited

Loading

bodegus commented Nov 20, 2025 •

edited

Loading