doc: DOCSP-60307 -- [TF] Maintenance Performed on Non-Prod User Projects Before Prod

docs/data-sources/maintenance_window.md

@@ -50,10 +50,13 @@ In addition to all arguments above, the following attributes are exported:
 * `auto_defer_once_enabled` - When `true`, enables automatic deferral of all scheduled maintenance for the given project by one week.
 * `protected_hours` - (Optional) Defines the time period during which there will be no standard updates to the clusters. See [Protected Hours](#protected-hours).
 * `time_zone_id` - Identifier for the current time zone of the maintenance window. This can only be updated via the Project Settings UI.
+* `wave_assignment` - Maintenance wave explicitly assigned to this project. Always returned when a value has been set, regardless of the organization's [`wave_assignment_mode`](../data-sources/org_maintenance_settings.md#attributes-reference). When the mode is `ENV_TAG_MAPPING`, the system preserves the stored value but does not uses it for scheduling. Switching back to `MANUAL` restores this value as the effective wave. Returns `null` when no explicit wave has been assigned.
+* `effective_wave_assignment` - Read-only 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`](../resources/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`).** When 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.
 
 ### Protected Hours
 * `start_hour_of_day` - Zero-based integer that represents the beginning hour of the day for the protected hours window.
 * `end_hour_of_day` - Zero-based integer that represents the end hour of the day for the protected hours window.
 
-
-For more information see: [MongoDB Atlas API Reference.](https://www.mongodb.com/docs/atlas/reference/api/maintenance-windows/)
+For more information see: [MongoDB Atlas API Reference.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-maintenance-windows)

docs/data-sources/org_maintenance_settings.md

@@ -0,0 +1,35 @@
+---
+subcategory: "Organizations"
+---
+
+# Data Source: mongodbatlas_org_maintenance_settings
+
+`mongodbatlas_org_maintenance_settings` provides a data source to read the organization-level [maintenance wave settings](https://www.mongodb.com/docs/atlas/tutorial/cluster-maintenance-window/) for a MongoDB Atlas organization.
+
+## Example Usage
+
+```terraform
+data "mongodbatlas_org_maintenance_settings" "example" {
+  org_id = var.org_id
+}
+
+output "maintenance_settings" {
+  value = {
+    wave_assignment_mode           = data.mongodbatlas_org_maintenance_settings.example.wave_assignment_mode
+    effective_wave_assignment_mode = data.mongodbatlas_org_maintenance_settings.example.effective_wave_assignment_mode
+  }
+}
+```
+
+## Argument Reference
+
+* `org_id` - (Required) Unique 24-hexadecimal digit string that identifies the Atlas organization.
+
+## Attributes Reference
+
+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 information see: [MongoDB Atlas API Reference.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-maintenance-windows)

docs/resources/maintenance_window.md

@@ -71,6 +71,7 @@ Use `defer` to defer the next scheduled maintenance event by one week. This only
 * `auto_defer_once_enabled` - (Optional) **Recommended** field to enable or disable automatic deferral of all scheduled maintenance for the given project by one week. Achieves the same outcome as `auto_defer`, but by directly setting the value to `true` or `false`, which is idempotent and keeps Terraform state aligned with Atlas. If `auto_defer` is used to toggle the underlying flag, it will also affect the value of this attribute.
 * `auto_defer` - (Optional) Boolean flag to **toggle** automatic deferral on/off. Each change flips the current state (ON → OFF or OFF → ON). Achieves the same outcome as `auto_defer_once_enabled` but through a toggle operation, which can make the current state opaque to Terraform and introduce state drift. **For most use cases, prefer `auto_defer_once_enabled` instead.** <!-- see CLOUDP-375465 for details -->
 * `protected_hours` - (Optional) Defines the time period during which there will be no standard updates to the clusters. See [Protected Hours](#protected-hours).
+* `wave_assignment` - (Optional) Integer that identifies the maintenance wave explicitly assigned to this project. Not editable when the organization's wave assignment mode is `ENV_TAG_MAPPING`. In this case, the system preserves the stored value but does not uses it for scheduling; environment tags determine the effective wave instead. Switching back to `MANUAL` restores the `wave_assignment` value as the effective wave. Remove this attribute from your configuration and run `terraform apply` to clear the explicit assignment. See [`mongodbatlas_org_maintenance_settings`](org_maintenance_settings.md#argument-reference) to configure the organization-level wave assignment mode.
 
 ### Protected Hours
 * `start_hour_of_day` - Zero-based integer that represents the beginning hour of the day for the protected hours window.
@@ -94,4 +95,4 @@ Maintenance Window entries can be imported using project project_id, in the form
 $ terraform import mongodbatlas_maintenance_window.test 5d0f1f73cf09a29120e173cf
 ```
 
-For more information see: [MongoDB Atlas API Reference.](https://www.mongodb.com/docs/atlas/reference/api/maintenance-windows/)
+For more information see: [MongoDB Atlas API Reference.](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/group/endpoint-maintenance-windows)

docs/resources/org_maintenance_settings.md

@@ -0,0 +1,55 @@
+---
+subcategory: "Organizations"
+---
+
+# Resource: mongodbatlas_org_maintenance_settings
+
+`mongodbatlas_org_maintenance_settings` provides a resource to manage organization-level maintenance wave settings for a MongoDB Atlas organization. Use this resource to control how [Atlas assigns projects to maintenance waves](https://www.mongodb.com/docs/atlas/tutorial/cluster-maintenance-window/), either explicitly by project (`MANUAL` mode) or automatically based on each project's environment tag (`ENV_TAG_MAPPING` mode).
+
+-> **NOTE:** Only one `mongodbatlas_org_maintenance_settings` resource can be defined per organization.
+
+## Example Usage
+
+### Manual wave assignment
+
+Set the organization to `MANUAL` mode so you can assign each project to a specific maintenance wave using the `wave_assignment` attribute on [`mongodbatlas_maintenance_window`](maintenance_window.md).
+
+```terraform
+resource "mongodbatlas_org_maintenance_settings" "example" {
+  org_id               = var.org_id
+  wave_assignment_mode = "MANUAL"
+}
+```
+
+### Automatic wave assignment based on environment tags
+
+Set the organization to `ENV_TAG_MAPPING` mode to have Atlas derive the maintenance wave from each project's environment tag.
+
+```terraform
+resource "mongodbatlas_org_maintenance_settings" "example" {
+  org_id               = var.org_id
+  wave_assignment_mode = "ENV_TAG_MAPPING"
+}
+```
+
+### Further Examples
+
+<!-- TODO(CLOUDP-414003): Add link to examples once Mar's examples land -->
+Configure Organization Maintenance Settings
+
+## Argument Reference
+
+`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`.
+
+## Import
+
+Organization maintenance settings can be imported using the organization ID, in the format `ORG_ID`, e.g.
+
+```
+$ terraform import mongodbatlas_org_maintenance_settings.example 5d09d6a59ccf6445652a444a
+```
+
+For more information see: [MongoDB Atlas API Reference.](https://www.mongodb.com/docs/atlas/reference/api/maintenance-windows/)