doc: DOCSP-60307 -- [TF] Maintenance Performed on Non-Prod User Projects Before Prod by xargom · Pull Request #4508 · mongodb/terraform-provider-mongodbatlas

xargom · 2026-06-16T22:27:15Z

Description

Documents the Atlas maintenance waves feature for the Terraform provider. Maintenance waves allow Atlas to sequence cluster maintenance across projects in an organization — non-production projects are updated first, production projects last.

Related ticket: DOCSP-60307
Engineering implementation: CLOUDP-397100
Examples (in progress): CLOUDP-414003

Changes

docs/resources/maintenance_window.md — Added wave_assignment argument and effective_wave_assignment computed attribute. Includes a dedicated note on the two divergence scenarios where effective_wave_assignment can differ from wave_assignment: ENV_TAG_MAPPING mode active at the org level, and cross-organization billing (MAINTENANCE_SEQUENCE_CROSS_ORG).
docs/data-sources/maintenance_window.md — Added wave_assignment and effective_wave_assignment attributes with matching divergence note.
docs/resources/org_maintenance_settings.md — New resource doc for mongodbatlas_org_maintenance_settings. Manages org-level wave assignment mode (MANUAL or ENV_TAG_MAPPING). Singleton per organization.
docs/data-sources/org_maintenance_settings.md — New data source doc for mongodbatlas_org_maintenance_settings. Exposes wave_assignment_mode and effective_wave_assignment_mode.

Note: mongodbatlas_org_maintenance_settings is not yet registered in the provider. Engineering implementation is in progress. The Further Examples link in the resource doc will be updated once CLOUDP-414003 lands.

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 fix and verified 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

The Further Examples link in org_maintenance_settings.md points to master as a placeholder. Update to a versioned URL once Mar's example files from CLOUDP-414003 are merged.

github-actions · 2026-06-16T22:27:39Z

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

Copilot

Pull request overview

This PR updates the provider documentation to describe Atlas maintenance wave assignment behavior, including newly documented wave_assignment / effective_wave_assignment fields on maintenance windows, and adds new docs pages for an organization-level maintenance settings resource and data source.

Changes:

Add documentation pages for mongodbatlas_org_maintenance_settings (resource + data source).
Document maintenance window wave assignment fields (wave_assignment, effective_wave_assignment) in both the resource and data source docs.
Add additional explanatory text describing when the effective wave assignment may differ from the explicit assignment.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
docs/resources/org_maintenance_settings.md	Adds resource documentation for org-level maintenance wave assignment mode.
docs/data-sources/org_maintenance_settings.md	Adds data source documentation for reading org-level maintenance wave assignment mode.
docs/resources/maintenance_window.md	Documents new maintenance window wave assignment argument and effective wave attribute.
docs/data-sources/maintenance_window.md	Documents new maintenance window wave assignment and effective wave attributes.

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

xargom · 2026-06-16T22:40:21Z

+- `effective_wave_assignment` - The maintenance wave Atlas uses when scheduling maintenance for this project. This value can differ from `wave_assignment` in the following scenarios:
+  - **`ENV_TAG_MAPPING` mode is active at the organization level.** When the organization's `wave_assignment_mode` is set to `ENV_TAG_MAPPING` (see [`mongodbatlas_org_maintenance_settings`](org_maintenance_settings.md)), Atlas ignores any explicit `wave_assignment` and derives the effective wave from the project's environment tag. A project can have `wave_assignment = 1` in state while `effective_wave_assignment` returns a different value.
+  - **Cross-organization billing (`MAINTENANCE_SEQUENCE_CROSS_ORG`).** A linked non-paying organization inherits the paying organization's wave assignment mode. If the paying organization switches to `ENV_TAG_MAPPING`, all linked projects follow regardless of any explicit `wave_assignment` set on them.


To be added by engineering

See https://github.com/mongodb/terraform-provider-mongodbatlas/pull/4508/changes#r3429166526

corryroot

LGTM! I commented with some copy nits.

marcabreracast · 2026-06-17T15:02:52Z

Note as discussed with @xargom earlier: changes should be merged into branch dev/CLOUDP-397100_Add_Maintenance_Wave_Fields_to_Resource.

Once all the changes are ready, a final PR will be created to merge to master

xargom · 2026-06-17T18:34:46Z

Note as discussed with @xargom earlier: changes should be merged into branch dev/CLOUDP-397100_Add_Maintenance_Wave_Fields_to_Resource.

Once all the changes are ready, a final PR will be created to merge to master

Base branch changed

…ce_window and add org_maintenance_settings resource and data source docs

Co-authored-by: corryroot <72401712+corryroot@users.noreply.github.com>

…ment from resource doc, deletes explicit values for wave:assignment, and fix null-assignment language

…_maintenance_settings.md

… changes in CLOUDP-414939

…ds, drops $ and specifies shell language

marcabreracast · 2026-06-22T16:14:37Z

+terraform import mongodbatlas_org_maintenance_settings.example 5d09d6a59ccf6445652a444a
+```
+
+For more information see: [MongoDB Atlas API Reference.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-maintenance-windows)


Missing new line

marcabreracast · 2026-06-22T16:20:23Z

+`mongodbatlas_org_maintenance_settings` supports the following arguments:
+
+* `org_id` - (Required) Unique 24-hexadecimal digit string that identifies the Atlas organization. This attribute cannot be changed after the resource is created.
+* `wave_assignment_mode` - (Optional) Controls how Atlas assigns projects to maintenance waves. Accepted values are `MANUAL` and `ENV_TAG_MAPPING`. Remove this attribute from your configuration and run `terraform apply` to reset the mode to `MANUAL`.


Remove this attribute from your configuration and run terraform apply to reset the mode to MANUAL

Regarding resetting the field again to MANUAL there is currently https://jira.mongodb.org/browse/CLOUDP-415703 to address this behaviour.

Updated to consider new behaviour

…g to CLOUDP-415703

marcabreracast · 2026-06-24T15:38:18Z

+
+In addition to all arguments above, the following attributes are exported:
+
+* `wave_assignment_mode` - Configured wave assignment mode for the organization. Accepted values are `MANUAL` and `ENV_TAG_MAPPING`. Defaults to `MANUAL` when unset.


Defaults to MANUAL when unset.

This was the initial behaviour, however CLOUDP-415703 intends to drop the default value since it's a client field. I'd drop that phrase if you agree.

marcabreracast · 2026-06-24T15:44:47Z

+
+### Further Examples
+
+<!-- TODO(CLOUDP-414003): Add link to examples once Mar's examples land -->


FYI, examples will be merged in this PR: #4531

Waiting for PR to merge to incorporate here.

marcabreracast · 2026-06-24T15:50:25Z

+In addition to all arguments above, the following attributes are exported:
+
+* `wave_assignment_mode` - Configured wave assignment mode for the organization. Accepted values are `MANUAL` and `ENV_TAG_MAPPING`. Defaults to `MANUAL` when unset.
+* `effective_wave_assignment_mode` - Wave assignment mode Atlas actually uses for scheduling. Its value can differ from `wave_assignment_mode` in some cases. For more details, see the [`mongodbatlas_maintenance_window` data source](../data-sources/maintenance_window.md).


For more details, see the mongodbatlas_maintenance_window data source.

I believe we should specify the scenarios where this divergence can happen. Upstream team updated the docs as it follows for the API behaviour, can we adapt those for the Terraform field?

"In a cross-organization billing hierarchy, a linked non-paying organization cannot update its effectiveWaveAssignmentMode field, which inherits from the paying organization's waveAssignmentMode. In this case, a linked non-paying organization's effectiveWaveAssignmentMode and waveAssignmentMode might differ."

Proposed change, but feel free to adapt it to better wording:

effective_wave_assignment_mode - Wave assignment mode Atlas uses for scheduling. Matches wave_assignment_mode except in a cross-organization billing hierarchy where this is a linked non-paying organization. In that case, effective_wave_assignment_mode inherits from the paying organization's wave_assignment_mode and the two values might differ.

Changed to the proposed copy

marcabreracast

LGTM after latest comments have been addressed. We can merge this PR after the examples one is available in the dev branch if you agree.

Good work!

…. Adds details on when effective wave assignment mode differs from wave assignment mode

* feat: Add wave_assignment field to mongodbatlas_maintenance_window resource (#4510) * Add new fields to resource * Add new resource field to CREATE * Add new fields to resource READ * WIP: null value * Remove nil guard * Add acceptance tests * Remove effective_wave_maintenance field from resource * Add additional step to ensure other values are not modified after PATCH * Add changelog * Add method to distinguish between 0 and unset value edge case * Reword comment * Add distinction between 0 and unset * Rephrase comment for better clarification * feat: Add wave_assignment and effective_wave_assignment fields to mongodbatlas_maintenance_window data source (#4512) * Add fields to schema * Remove nil guard since it's not needed * Add acceptance tests * Address format consistency * Add changelog * Fix changelog entry to use attribute instead of field * Address PR comments to align test structure in resource to best practices * chore: Pin SDK v20250312020 for maintenance_window wave assignment fields (#4529) * Pin SDK v20250312020 for maintenance_window wave assignment fields * Add comment explaining SkipTestForCI for wave assignment test * Refine comment * Add TODO to SkipTestForCI comment * feat: Add mongodbatlas_org_maintenance_settings resource (#4513) * Add configuration for autogen resource * Drop _api wording to match prod naming resources * Add autogenerated resource * Update version header to use preview version * Register resource in the provider * Add Computed to field to avoid inconsistency issues due to DELETE * Add acceptance tests for org_maintenance_settings resource * Fix import step to ignore wave_assignment_mode verification * Add changelog entry for org_maintenance_settings resource * Add notes to config.yaml for follow-up * Refine acceptance tests * Remove ignore import test * Add clarifying comment * Edit changelog to match format * Override org_id description * feat: Add mongodbatlas_org_maintenance_settings data source (#4527) * Add configuration for autogen resource * Drop _api wording to match prod naming resources * Add autogenerated resource * Update version header to use preview version * Register resource in the provider * Add Computed to field to avoid inconsistency issues due to DELETE * Add acceptance tests for org_maintenance_settings resource * Fix import step to ignore wave_assignment_mode verification * Add changelog entry for org_maintenance_settings resource * Add notes to config.yaml for follow-up * Refine acceptance tests * Remove ignore import test * Configure and generate data source * Register Data Source in provider * Add aceptance tests * Add changelog entry for org_maintenance_settings data source * Edit changelog * Fix previous changelog from conflict * Override org_id schema description * Re-enable wave assignment acceptance test (#4535) * doc: DOCSP-60307 -- [TF] Maintenance Performed on Non-Prod User Projects Before Prod (#4508) * doc: DOCSP-60307 -- Document wave_assignment attributes for maintenance_window and add org_maintenance_settings resource and data source docs * doc: DOCSP-60307 -- updates link * Apply suggestions from code review Co-authored-by: corryroot <72401712+corryroot@users.noreply.github.com> * doc: DOCSP-60307 -- Address PR feedback: remove effective_wave_assignment from resource doc, deletes explicit values for wave:assignment, and fix null-assignment language * doc: DOCSP-60307 -- Replaces link for plaintext in docs/resources/org_maintenance_settings.md * doc: DOCSP-60307 -- Updates field descriptions to align with upstream changes in CLOUDP-414939 * doc: DOCSP-60307 -- Copy changes. Updates broken links * doc: DOCSP-60307 -- Copy changes * doc: DOCSP-60307 -- Fixes broken link * doc: DOCSP-60307 -- Fixes broken link. Raplaces null for 0. In commands, drops $ and specifies shell language * doc: DOCSP-60307 -- Fixes typos and improves copy * doc: DOCSP-60307 -- Addresses wave_assignment_mode behaviour according to CLOUDP-415703 * doc: DOCSP-60307 -- Small copy change * doc: DOCSP-60307 -- Adds newline * DOCSP-60307 -- Drops default to manual for wave assignment mode field. Adds details on when effective wave assignment mode differs from wave assignment mode * doc: DOCSP-60307 -- Adds tag key information for ENV_TAG_MAPPING mode * doc: DOCSP--60307 -- Adds examples in org maintenance settings resource --------- Co-authored-by: corryroot <72401712+corryroot@users.noreply.github.com> * doc: Add examples for maintenance window wave assignment and org maintenance settings (#4531) * Add example for maintenance_window * Add example for org_maintenance_settings * Refine example for consistency * Refine example * Refine ENV_TAG_MAPPING example * Restructure examples to leave maintenance_window example basic * Remove wave_assignment example * Add tag mapping values to example * Apply nit suggestion Co-authored-by: Javier Armendáriz <136641722+xargom@users.noreply.github.com> --------- Co-authored-by: Javier Armendáriz <136641722+xargom@users.noreply.github.com> * chore: Improvements on mongodbatlas_org_maintenance_settings resource after API improvements (#4536) * update destroy operation to use custom reset method * Remove override for wave_assignment_mode being Computed * Capture attribute description from autogen * Add flattened spec for internal OpenAPI * Fix tests * test: Add comment to PlanOnly step and remove redundant ENV_TAG_MAPPING plan check * Fix typo * Fix typo * Update comment * test: Enable org_maintenance_settings acceptance tests in CI (#4562) * Remove TODO as CLOUDP has been merged * Add acceptance tests to CI * Replace pinned SDK version with private preview (#4569) * fix: Resolve merge conflict leaving aimodelapikey and projectserviceaccount schemas out of sync with docs * refactor: Replace clearMaintenanceWave workaround with SDK NullFields (#4691) * Remove workaround * Address PR comment * feat: Support maintenance wave assignment without a maintenance window (#4687) * Update attributes to Optional to match API spec * Update CRUD for fields * Add acceptance tests to cover new use case * Update docs * Remove validation functions in favor of API validation * Pin preview version to get latest changes * chore: Add changelog entry * Add plan validator for required attributes * Add assertion to test * Add test coverage for plan only validator of dayOfWeek and hourOfDay attributes * Add comment suggestion * chore: Clear maintenance schedule on wave-only transition (#4716) * Add functionality to allow fields to be null * Fix issue where Update did not perform a follow-up read * chore: Add changelog entry for #4716 * chore: Remove unnecessary changelog entry for unreleased feature work * Address PR comments * Remove comments * Update resource and data source with stable API version * Update link version * chore: Update API spec for org_maintenance_settings stable version Pins the atlasapispec to the spec where maintenanceSettings exposes the 2025-03-12 media type, matching the generated code and config.yml version_header so the autogen consistency check passes. Also points the Further Examples links for org_maintenance_settings at tree/master. * chore: Restore ai_model_api_key and stream_connection_failover models from master These model YAMLs carried stale-merge divergence (a changed description in ai_model_api_key and 246 extra lines in stream_connection_failover), making the autogen code-gen check regenerate different schemas than committed. Restoring master's versions aligns the models so the check stays stable. * chore: Restore go.mod and go.sum dependency pins from master --------- Co-authored-by: Javier Armendáriz <136641722+xargom@users.noreply.github.com> Co-authored-by: corryroot <72401712+corryroot@users.noreply.github.com> Co-authored-by: svc-apix-bot <svc-api-experience-integrations-escalation@mongodb.com> Co-authored-by: Aastha Mahendru <aastha.mahendru@mongodb.com> Co-authored-by: Agustin Bettati <bettatiagustin@gmail.com> Co-authored-by: Oriol Arbusi Abadal <oriol.abadal@mongodb.com>

xargom requested a review from a team as a code owner June 16, 2026 22:27

Copilot AI review requested due to automatic review settings June 16, 2026 22:27

Copilot started reviewing on behalf of xargom June 16, 2026 22:27 View session

Copilot AI reviewed Jun 16, 2026

View reviewed changes

xargom changed the title ~~doc: DOCSP-60307 -- Document wave_assignment attributes for maintenan…~~ doc: DOCSP-60307 -- [TF] Maintenance Performed on Non-Prod User Projects Before Prod Jun 16, 2026

corryroot approved these changes Jun 17, 2026

View reviewed changes

Comment thread docs/data-sources/maintenance_window.md Outdated

Comment thread docs/data-sources/org_maintenance_settings.md Outdated

Comment thread docs/resources/maintenance_window.md Outdated

marcabreracast reviewed Jun 17, 2026

View reviewed changes

Comment thread docs/resources/maintenance_window.md Outdated

marcabreracast reviewed Jun 17, 2026

View reviewed changes

Comment thread docs/resources/maintenance_window.md Outdated

marcabreracast reviewed Jun 17, 2026

View reviewed changes

Comment thread docs/resources/maintenance_window.md Outdated

marcabreracast mentioned this pull request Jun 17, 2026

feat: Add wave_assignment and effective_wave_assignment fields to mongodbatlas_maintenance_window data source #4512

Merged

12 tasks

xargom changed the base branch from master to CLOUDP-397100_Add_Maintenance_Wave_Fields_to_Resource June 17, 2026 18:33

xargom changed the base branch from CLOUDP-397100_Add_Maintenance_Wave_Fields_to_Resource to dev/CLOUDP-306618_Maintenance_Waves_Non_Prod June 18, 2026 18:20

xargom requested a review from a team as a code owner June 18, 2026 18:20

xargom and others added 5 commits June 18, 2026 12:30

doc: DOCSP-60307 -- Document wave_assignment attributes for maintenan…

69f9fbc

…ce_window and add org_maintenance_settings resource and data source docs

doc: DOCSP-60307 -- updates link

5d3ec4e

Apply suggestions from code review

20c1ce5

Co-authored-by: corryroot <72401712+corryroot@users.noreply.github.com>

doc: DOCSP-60307 -- Address PR feedback: remove effective_wave_assign…

013cde1

…ment from resource doc, deletes explicit values for wave:assignment, and fix null-assignment language

doc: DOCSP-60307 -- Replaces link for plaintext in docs/resources/org…

778e802

…_maintenance_settings.md

xargom force-pushed the DOCSP-60307 branch from cd6b1cd to 778e802 Compare June 18, 2026 18:30

xargom added 4 commits June 18, 2026 13:28

doc: DOCSP-60307 -- Updates field descriptions to align with upstream…

2c99808

… changes in CLOUDP-414939

doc: DOCSP-60307 -- Copy changes. Updates broken links

188ff38

doc: DOCSP-60307 -- Copy changes

4c5c405

doc: DOCSP-60307 -- Fixes broken link

c43e22a

marcabreracast reviewed Jun 19, 2026

View reviewed changes

Comment thread docs/data-sources/maintenance_window.md Outdated

doc: DOCSP-60307 -- Fixes broken link. Raplaces null for 0. In comman…

94f92d8

…ds, drops $ and specifies shell language

marcabreracast mentioned this pull request Jun 22, 2026

feat: Add mongodbatlas_org_maintenance_settings resource #4513

Merged

8 tasks

marcabreracast reviewed Jun 22, 2026

View reviewed changes

Comment thread docs/data-sources/maintenance_window.md Outdated

marcabreracast reviewed Jun 22, 2026

View reviewed changes

Comment thread docs/resources/maintenance_window.md Outdated

marcabreracast reviewed Jun 22, 2026

View reviewed changes

marcabreracast mentioned this pull request Jun 23, 2026

feat: Add mongodbatlas_org_maintenance_settings data source #4527

Merged

9 tasks

xargom added 4 commits June 23, 2026 12:12

doc: DOCSP-60307 -- Fixes typos and improves copy

7a64187

doc: DOCSP-60307 -- Addresses wave_assignment_mode behaviour accordin…

9f93ba9

…g to CLOUDP-415703

doc: DOCSP-60307 -- Small copy change

41b6ef0

doc: DOCSP-60307 -- Adds newline

6dedf22

marcabreracast reviewed Jun 24, 2026

View reviewed changes

Comment thread docs/resources/org_maintenance_settings.md Outdated

marcabreracast reviewed Jun 24, 2026

View reviewed changes

marcabreracast approved these changes Jun 24, 2026

View reviewed changes

DOCSP-60307 -- Drops default to manual for wave assignment mode field…

932eabc

…. Adds details on when effective wave assignment mode differs from wave assignment mode

marcabreracast mentioned this pull request Jun 25, 2026

doc: Add examples for maintenance window wave assignment and org maintenance settings #4531

Merged

13 tasks

xargom added 2 commits June 25, 2026 12:33

doc: DOCSP-60307 -- Adds tag key information for ENV_TAG_MAPPING mode

14e3a23

doc: DOCSP--60307 -- Adds examples in org maintenance settings resource

ee210f9

xargom merged commit 865eb69 into dev/CLOUDP-306618_Maintenance_Waves_Non_Prod Jun 25, 2026
48 of 49 checks passed

xargom deleted the DOCSP-60307 branch June 25, 2026 18:49


		In addition to all arguments above, the following attributes are exported:

		* `wave_assignment_mode` - Configured wave assignment mode for the organization. Accepted values are `MANUAL` and `ENV_TAG_MAPPING`. Defaults to `MANUAL` when unset.


		### Further Examples

		<!-- TODO(CLOUDP-414003): Add link to examples once Mar's examples land -->

Conversation

xargom commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Type of change:

Required Checklist:

Further comments

Uh oh!

github-actions Bot commented Jun 16, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

corryroot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

marcabreracast commented Jun 17, 2026

Uh oh!

xargom commented Jun 17, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

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!

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!

marcabreracast left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

xargom commented Jun 16, 2026 •

edited

Loading