doc: Clarify use_effective_fields doc - #4741
Conversation
|
APIx bot: a message has been sent to Docs Slack channel |
🤖 Augment PR SummarySummary: Clarifies 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
There was a problem hiding this comment.
🟢 Approval recommended
The changes are documentation-only and the only issue found is a minor Markdown list-formatting inconsistency with a straightforward fix.
Pull request overview
Clarifies the use_effective_fields documentation for mongodbatlas_advanced_cluster, specifically how spec fields behave under auto-scaling and when updates to instance_size/disk_size_gb/disk_iops actually take effect.
Changes:
- Refines the
use_effective_fieldsattribute description to clarify that the spec-preserving behavior only applies while auto-scaling remains enabled, and explains the behavior when auto-scaling is toggled. - Updates the auto-scaling guidance (“Option 1”) to consistently describe behavior while auto-scaling remains enabled.
- Adds an explicit “When are spec updates applied?” explanation and tightens the manual update workflow wording.
File summaries
| File | Description |
|---|---|
| docs/resources/advanced_cluster.md | Updates use_effective_fields guidance to clarify behavior with auto-scaling and spec updates. |
Review details
- Files reviewed: 1/1 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
JuliaMongo
left a comment
JuliaMongo
left a comment
There was a problem hiding this comment.
Thank you for all this work! Left a few comments, all optional, if they help, then see if you can apply them. If you don't believe they help, then they are optional.
| * `config_server_management_mode` - (Optional) Config Server Management Mode for creating or updating a sharded cluster. Valid values are `ATLAS_MANAGED` (default) and `FIXED_TO_DEDICATED`. When configured as `ATLAS_MANAGED`, Atlas may automatically switch the cluster's config server type for optimal performance and savings. When configured as `FIXED_TO_DEDICATED`, the cluster will always use a dedicated config server. To learn more, see the [Sharded Cluster Config Servers documentation](https://www.mongodb.com/docs/manual/core/sharded-cluster-config-servers/). | ||
| - `delete_on_create_timeout`- (Optional) Indicates whether to delete the resource being created if a timeout is reached when waiting for completion. When set to `true` and timeout occurs, it triggers the deletion and returns immediately without waiting for deletion to complete. When set to `false`, the timeout will not trigger resource deletion. If you suspect a transient error when the value is `true`, wait before retrying to allow resource deletion to finish. Default is `true`. | ||
| * `use_effective_fields` - (Optional) Controls how hardware specification fields are returned in the response. When set to true, the non-effective specs (`electable_specs`, `read_only_specs`, `analytics_specs`) fields return the hardware specifications that the client provided. When set to false (default), the non-effective specs fields show the **current** hardware specifications. Cluster auto-scaling is the primary cause for differences between initial and current hardware specifications. This opt-in feature enhances auto-scaling workflows by eliminating the need for `lifecycle.ignore_changes` blocks and preventing plan drift from Atlas-managed changes. This attribute applies to dedicated clusters, not to tenant or flex clusters. This attribute will be deprecated in provider version 2.x and removed in 3.x when the new behavior becomes default. See [Auto-Scaling with Effective Fields](#auto-scaling-with-effective-fields) for more details. | ||
| * `delete_on_create_timeout` - (Optional) Indicates whether to delete the resource being created if a timeout is reached when waiting for completion. When set to `true` and timeout occurs, it triggers the deletion and returns immediately without waiting for deletion to complete. When set to `false`, the timeout will not trigger resource deletion. If you suspect a transient error when the value is `true`, wait before retrying to allow resource deletion to finish. Default is `true`. |
There was a problem hiding this comment.
Indicates whether to delete the resource that Atlas creates, if a timeout is reached when waiting for completion.
Q: completion of what? Add that maybe?
When this flag is set to true and the timeout occurs, (what triggers the deletion? -- name it, instead of uisng it)
Start a new paragraph for When set to false Consider using bullets for each of these, under the main intro.
Replace "it" by naming the entity that triggers the deletion.
Name the entity that must complete in the sentence "waiting for completion". did you mean completes deleting of the resource? Then simplify that part.
There was a problem hiding this comment.
Restructured into bullets and named entities throughout, done in fa21cc4.
| - `delete_on_create_timeout`- (Optional) Indicates whether to delete the resource being created if a timeout is reached when waiting for completion. When set to `true` and timeout occurs, it triggers the deletion and returns immediately without waiting for deletion to complete. When set to `false`, the timeout will not trigger resource deletion. If you suspect a transient error when the value is `true`, wait before retrying to allow resource deletion to finish. Default is `true`. | ||
| * `use_effective_fields` - (Optional) Controls how hardware specification fields are returned in the response. When set to true, the non-effective specs (`electable_specs`, `read_only_specs`, `analytics_specs`) fields return the hardware specifications that the client provided. When set to false (default), the non-effective specs fields show the **current** hardware specifications. Cluster auto-scaling is the primary cause for differences between initial and current hardware specifications. This opt-in feature enhances auto-scaling workflows by eliminating the need for `lifecycle.ignore_changes` blocks and preventing plan drift from Atlas-managed changes. This attribute applies to dedicated clusters, not to tenant or flex clusters. This attribute will be deprecated in provider version 2.x and removed in 3.x when the new behavior becomes default. See [Auto-Scaling with Effective Fields](#auto-scaling-with-effective-fields) for more details. | ||
| * `delete_on_create_timeout` - (Optional) Indicates whether to delete the resource being created if a timeout is reached when waiting for completion. When set to `true` and timeout occurs, it triggers the deletion and returns immediately without waiting for deletion to complete. When set to `false`, the timeout will not trigger resource deletion. If you suspect a transient error when the value is `true`, wait before retrying to allow resource deletion to finish. Default is `true`. | ||
| * `use_effective_fields` - (Optional) Controls how hardware specification fields are returned in the response. When set to true, the non-effective specs (`electable_specs`, `read_only_specs`, `analytics_specs`) fields return the hardware specifications that the client provided. When set to false (default), the non-effective specs fields show the **current** hardware specifications. Cluster auto-scaling is the primary cause for differences between initial and current hardware specifications. This opt-in feature enhances auto-scaling workflows by eliminating the need for `lifecycle.ignore_changes` blocks and preventing plan drift from Atlas-managed changes. The spec-preserving behavior applies only while auto-scaling remains enabled; if an update toggles auto-scaling on or off, the requested spec values are applied normally. This attribute applies to dedicated clusters, not to tenant or flex clusters. See [Auto-Scaling with Effective Fields](#auto-scaling-with-effective-fields) for more details. |
There was a problem hiding this comment.
New para for when set to true, new para for when set to false, formatting for true and false with singe back ticks.
break the sentence that now uses semicolon into two sentences. Explain what you mean when you say "applied normally". Is it TF that applies them, or Atlas? In this context, try to use active voice and name the entity that applies the spec values.
There was a problem hiding this comment.
Split into separate paragraphs for true and false, broke the semicolon into two sentences, and replaced "applied normally" with "Atlas applies the requested spec values in that update" for clarity, done in fa21cc4.
| When auto-scaling is enabled, there are two approaches to manage your cluster configuration with Terraform: | ||
|
|
||
| **Option 1 (Recommended):** Use `use_effective_fields = true` to enable the new effective fields behavior. With this option, Atlas-managed auto-scaling changes won't cause plan drift, eliminating the need for `lifecycle` ignore customizations. When either compute or disk auto-scaling is enabled (or both), all three fields (`instance_size`, `disk_size_gb`, and `disk_iops`) are ignored in the Terraform configuration, as Atlas may adjust any of these resources to maintain optimal cluster performance. You can read the actual scaled values using the `effective_electable_specs` and `effective_read_only_specs` attributes in the `mongodbatlas_advanced_cluster` data source. See [Auto-Scaling with Effective Fields](#auto-scaling-with-effective-fields) for details. | ||
| **Option 1 (Recommended):** Use `use_effective_fields = true` to enable the new effective fields behavior. With this option, Atlas-managed auto-scaling changes won't cause plan drift, eliminating the need for `lifecycle` ignore customizations. While auto-scaling remains enabled (compute or disk, or both), all three fields (`instance_size`, `disk_size_gb`, and `disk_iops`) are ignored in the Terraform configuration, as Atlas may adjust any of these resources to maintain optimal cluster performance. You can read the actual scaled values using the `effective_electable_specs` and `effective_read_only_specs` attributes in the `mongodbatlas_advanced_cluster` data source. See [Auto-Scaling with Effective Fields](#auto-scaling-with-effective-fields) for details. |
There was a problem hiding this comment.
instead of "won't" use present tense and say " do not cause plan drift"
Lifecycle ignore -- Should we format it properly? it might be as single formatted field, now you format only lifecycle but not ignore. I don't recall, check the syntax and apply formatting.
General comment: all content here is true, but it is provided out of order (paragraphs). See if starting with the auto-scaling behavior's description and following up with the rest might be more logical.
There was a problem hiding this comment.
Changed to present tense ("do not cause") and fixed the formatting to lifecycle.ignore_changes. On the paragraph reordering, the current order follows a what/how/where-to-read-more structure that matches the surrounding sections. Happy to revisit if you feel strongly about it, done in fa21cc4.
| **Option 1 (Recommended):** Use `use_effective_fields = true` to enable the new effective fields behavior. With this option, Atlas-managed auto-scaling changes won't cause plan drift, eliminating the need for `lifecycle` ignore customizations. When either compute or disk auto-scaling is enabled (or both), all three fields (`instance_size`, `disk_size_gb`, and `disk_iops`) are ignored in the Terraform configuration, as Atlas may adjust any of these resources to maintain optimal cluster performance. You can read the actual scaled values using the `effective_electable_specs` and `effective_read_only_specs` attributes in the `mongodbatlas_advanced_cluster` data source. See [Auto-Scaling with Effective Fields](#auto-scaling-with-effective-fields) for details. | ||
| **Option 1 (Recommended):** Use `use_effective_fields = true` to enable the new effective fields behavior. With this option, Atlas-managed auto-scaling changes won't cause plan drift, eliminating the need for `lifecycle` ignore customizations. While auto-scaling remains enabled (compute or disk, or both), all three fields (`instance_size`, `disk_size_gb`, and `disk_iops`) are ignored in the Terraform configuration, as Atlas may adjust any of these resources to maintain optimal cluster performance. You can read the actual scaled values using the `effective_electable_specs` and `effective_read_only_specs` attributes in the `mongodbatlas_advanced_cluster` data source. See [Auto-Scaling with Effective Fields](#auto-scaling-with-effective-fields) for details. | ||
|
|
||
| **Important:** If you're enabling this flag on an existing cluster that has `lifecycle.ignore_changes` blocks for spec fields, enable the flag and remove the blocks in the same apply. The blocks are no longer needed and may interfere with the new behavior. If you previously removed `read_only_specs` or `analytics_specs` attributes, you may encounter a validation error. This is a safety check to prevent accidental node loss. To resolve: add the blocks back (to keep nodes) or with `node_count = 0` (to delete nodes), apply without toggling the flag, then toggle in a separate apply. |
There was a problem hiding this comment.
can't comment here but the first sentence in important is a bit repetitive. Also, for the future: recommend documenting this entire thing in a separate section: troubleshoot effective fields and referencing it here.
There was a problem hiding this comment.
The first sentence is intentionally a standalone directive since it's the most common mistake. Agree a separate troubleshooting section would be valuable, noted for a follow-up docs improvement.
|
|
||
| **Key difference:** With `use_effective_fields = true`, your configuration stays clean and represents your intent, while effective specs show the reality of what Atlas has provisioned. | ||
|
|
||
| **When are spec updates applied?** The spec-preserving behavior described above applies only when auto-scaling is enabled both before and after an update. If an update toggles auto-scaling (enabling or disabling compute or disk auto-scaling), the requested `instance_size`, `disk_size_gb`, and `disk_iops` values are applied normally in that update, as if `use_effective_fields` were not set. This is why the manual update workflow below works: disabling auto-scaling in the same apply allows the requested spec values to take effect. |
There was a problem hiding this comment.
Would it make sense to move this section up and place it before everything else that follows? If so, then you'd need to change the text to say: The following behavior ..... Instead of "above".
Normally: explain and say something like: Atlas auto-scales the cluster based on the values you specify for bounds... -- check what docs say for this and use that.
There was a problem hiding this comment.
Moved to the top of the section and rephrased to active voice ("When does Atlas apply requested spec values?"). Added a brief explanation of the auto-scaling bounds in the intro. No more "above" reference since it now precedes the behavior descriptions, done in fa21cc4.
| ### Manually Updating Specs with use_effective_fields | ||
|
|
||
| When `use_effective_fields = true` and auto-scaling is enabled, you can update `instance_size`, `disk_size_gb`, or `disk_iops` in your configuration at any time without validation errors. However, Atlas echoes these values back in state while continuing to use auto-scaled values for actual cluster operations. To have your configured values take effect, temporarily disable auto-scaling: | ||
| When `use_effective_fields = true` and auto-scaling remains enabled, you can update `instance_size`, `disk_size_gb`, or `disk_iops` in your configuration at any time without validation errors. However, Atlas preserves the auto-scaled values and the configured values do not take effect. An update that disables auto-scaling is not subject to this preservation, so to have your configured values take effect, temporarily disable auto-scaling: |
There was a problem hiding this comment.
This is good. But we might need an article on this specifically and separately.
There was a problem hiding this comment.
agreed, a dedicated article on this workflow would be helpful
Description
Clarify use_effective_fields doc, auto-scaling must remain enabled before and after the update.
Also:
delete_on_create_timeoutline (-instead of*, missing space before dash) found by Copilot review. Low risk, included in this PR.use_effective_fieldsattribute description. The attribute has noDeprecationMessagein the schema yet; the text will be added when the deprecation actually lands.Link to any related issue(s): CLOUDP-447163
Type of change:
Required Checklist:
Further comments