feat: Support pinned_fcv attribute in advanced_cluster resource and data sources

.changelog/2789.txt

@@ -0,0 +1,23 @@
+```release-note:enhancement
+resource/mongodbatlas_advanced_cluster: Adds `pinned_fcv` attribute
+```
+
+```release-note:enhancement
+data-source/mongodbatlas_advanced_cluster: Adds `pinned_fcv` attribute
+```
+
+```release-note:enhancement
+data-source/mongodbatlas_advanced_clusters: Adds `pinned_fcv` attribute
+```
+
+```release-note:bug
+resource/mongodbatlas_advanced_cluster: `mongo_db_major_version` attribute is populated with binary version when FCV pin is active
+```
+
+```release-note:bug
+data-source/mongodbatlas_advanced_cluster: `mongo_db_major_version` attribute is populated with binary version when FCV pin is active
+```
+
+```release-note:bug
+data-source/mongodbatlas_advanced_clusters: `mongo_db_major_version` attribute is populated with binary version when FCV pin is active
+```

docs/data-sources/advanced_cluster.md

@@ -98,6 +98,7 @@ In addition to all arguments above, the following attributes are exported:
 * `tags` - Set that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the cluster. See [below](#tags).
 * `labels` - Set that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the cluster. See [below](#labels). **(DEPRECATED.)** Use `tags` instead.
 * `mongo_db_major_version` - Version of the cluster to deploy.
+* `pinned_fcv` - The pinned Feature Compatibility Version (FCV) with its associated expiration date. See [below](#pinned_fcv).
 * `pit_enabled` - Flag that indicates if the cluster uses Continuous Cloud Backup.
 * `replication_specs` - List of settings that configure your cluster regions. If `use_replication_spec_per_shard = true`, this array has one object per shard representing node configurations in each shard. For replica sets there is only one object representing node configurations. See [below](#replication_specs).
 * `root_cert_type` - Certificate Authority that MongoDB Atlas clusters use. 
@@ -204,6 +205,11 @@ Key-value pairs that categorize the cluster. Each key and value has a maximum le
 * `transaction_lifetime_limit_seconds` - Lifetime, in seconds, of multi-document transactions. Defaults to 60 seconds.
 * `change_stream_options_pre_and_post_images_expire_after_seconds` - (Optional) The minimum pre- and post-image retention time in seconds This parameter is only supported for MongoDB version 6.0 and above. Defaults to `-1`(off).
 
+### pinned_fcv
+
+* `expiration_date` - Expiration date of the fixed FCV. This value is in the ISO 8601 timestamp format (e.g. "2024-12-04T16:25:00Z").
+* `version` - Feature compatibility version of the cluster.
+
 ## Attributes Reference
 
 In addition to all arguments above, the following attributes are exported:

docs/data-sources/advanced_clusters.md

@@ -100,6 +100,7 @@ In addition to all arguments above, the following attributes are exported:
 * `tags` - Set that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the cluster. See [below](#tags).
 * `labels` - Set that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the cluster. See [below](#labels).
 * `mongo_db_major_version` - Version of the cluster to deploy.
+* `pinned_fcv` - The pinned Feature Compatibility Version (FCV) with its associated expiration date. See [below](#pinned_fcv).
 * `pit_enabled` - Flag that indicates if the cluster uses Continuous Cloud Backup.
 * `replication_specs` - List of settings that configure your cluster regions. If `use_replication_spec_per_shard = true`, this array has one object per shard representing node configurations in each shard. For replica sets there is only one object representing node configurations. See [below](#replication_specs)
 * `root_cert_type` - Certificate Authority that MongoDB Atlas clusters use.
@@ -207,6 +208,11 @@ Key-value pairs that categorize the cluster. Each key and value has a maximum le
 * `transaction_lifetime_limit_seconds` - (Optional) Lifetime, in seconds, of multi-document transactions. Defaults to 60 seconds.
 * `change_stream_options_pre_and_post_images_expire_after_seconds` - (Optional) The minimum pre- and post-image retention time in seconds. This parameter is only supported for MongoDB version 6.0 and above. Defaults to `-1`(off).
 
+### pinned_fcv
+
+* `expiration_date` - Expiration date of the fixed FCV. This value is in the ISO 8601 timestamp format (e.g. "2024-12-04T16:25:00Z").
+* `version` - Feature compatibility version of the cluster.
+
 
 ## Attributes Reference
 

docs/resources/advanced_cluster.md

@@ -385,7 +385,8 @@ This parameter defaults to false.
 * `tags` - (Optional) Set that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the cluster. See [below](#tags).
 * `labels` - (Optional) Set that contains key-value pairs between 1 to 255 characters in length for tagging and categorizing the cluster. See [below](#labels). **DEPRECATED** Use `tags` instead.
 * `mongo_db_major_version` - (Optional) Version of the cluster to deploy. Atlas supports all the MongoDB versions that have **not** reached [End of Live](https://www.mongodb.com/legal/support-policy/lifecycles) for M10+ clusters. If omitted, Atlas deploys the cluster with the default version. For more details, see [documentation](https://www.mongodb.com/docs/atlas/reference/faq/database/#which-versions-of-mongodb-do-service-clusters-use-). Atlas always deploys the cluster with the latest stable release of the specified version.  If you set a value to this parameter and set `version_release_system` `CONTINUOUS`, the resource returns an error. Either clear this parameter or set `version_release_system`: `LTS`.
-* `pit_enabled` - (Optional) - Flag that indicates if the cluster uses Continuous Cloud Backup.
+* `pinned_fcv` - (Optional) Pins the Feature Compatibility Version (FCV) to the current MongoDB version with a provided expiration date. To unpin the FCV the `pinned_fcv` attribute must be removed. This operation can take several minutes as the request processes through the MongoDB data plane. Once FCV is unpinned it will not be possible to downgrade the `mongo_db_major_version`. It is advised that updates to `pinned_fcv` are done isolated from other cluster changes. If a plan contains multiple changes, the FCV change will be applied first. If FCV is unpinned past the expiration date the `pinned_fcv` attribute must be removed. The following [knowledge hub article](https://kb.corp.mongodb.com/article/000021785/) and [FCV documentation](https://www.mongodb.com/docs/atlas/tutorial/major-version-change/#manage-feature-compatibility--fcv--during-upgrades) can be referenced for more details. See [below](#pinned_fcv).
+* `pit_enabled` - (Optional) Flag that indicates if the cluster uses Continuous Cloud Backup.
 * `replication_specs` - List of settings that configure your cluster regions. This attribute has one object per shard representing node configurations in each shard. For replica sets there is only one object representing node configurations. If for each replication_spec `num_shards` is configured with a value greater than 1 (using deprecated sharding configurations), then each object represents a zone with one or more shards. See [below](#replication_specs)
 * `root_cert_type` - (Optional) - Certificate Authority that MongoDB Atlas clusters use. You can specify ISRGROOTX1 (for ISRG Root X1).
 * `termination_protection_enabled` - Flag that indicates whether termination protection is enabled on the cluster. If set to true, MongoDB Cloud won't delete the cluster. If set to false, MongoDB Cloud will delete the cluster.
@@ -652,6 +653,11 @@ After adding the `lifecycle` block to explicitly change `instance_size` comment
 * `compute_min_instance_size` - (Optional) Minimum instance size to which your cluster can automatically scale (such as M10). Atlas requires this parameter if `replication_specs.#.region_configs.#.analytics_auto_scaling.0.compute_scale_down_enabled` is true.
 * `compute_max_instance_size` - (Optional) Maximum instance size to which your cluster can automatically scale (such as M40). Atlas requires this parameter if `replication_specs.#.region_configs.#.analytics_auto_scaling.0.compute_enabled` is true.
 
+### pinned_fcv
+
+* `expiration_date` - (Required) Expiration date of the fixed FCV. This value is in the ISO 8601 timestamp format (e.g. "2024-12-04T16:25:00Z"). Note that this field cannot exceed 4 weeks from the pinned date.
+* `version` - Feature compatibility version of the cluster.
+
 ## Attributes Reference
 
 In addition to all arguments above, the following attributes are exported:

examples/mongodbatlas_advanced_cluster/version-upgrade-with-pinned-fcv/README.md

@@ -0,0 +1,57 @@
+# MongoDB Atlas Provider -- Cluster with pinned FCV
+
+Example shows how to pin the FCV of a cluster making use of `pinned_fcv` block. This enables direct control to pin cluster’s FCV before performing an upgrade on the `mongo_db_major_version`. Users can then downgrade to the previous MongoDB version with minimal risk if desired, as the FCV is maintained.
+
+The unpin operation can be performed by removing the `pinned_fcv` block. **Note**: Once FCV is unpinned it will not be possible to downgrade the `mongo_db_major_version`. If FCV is unpinned past the expiration date the `pinned_fcv` attribute must be removed.
+
+The following [knowledge hub article](https://kb.corp.mongodb.com/article/000021785/) and [FCV documentation](https://www.mongodb.com/docs/atlas/tutorial/major-version-change/#manage-feature-compatibility--fcv--during-upgrades) can be referenced for more details.
+
+## Dependencies
+
+* Terraform MongoDB Atlas Provider v1.23.0
+* A MongoDB Atlas account 
+
+```
+Terraform >= 0.13
++ provider registry.terraform.io/terraform-providers/mongodbatlas v1.23.0
+```
+
+
+## Usage
+**1\. Ensure your MongoDB Atlas credentials are set up.**
+
+Following `variables.tf` file create **terraform.tfvars** file with all the variable values, as demonstrated below:
+```
+public_key           = "<MONGODB_ATLAS_PUBLIC_KEY>"
+private_key          = "<MONGODB_ATLAS_PRIVATE_KEY>"
+atlas_project_id     = "<MONGODB_ATLAS_PROJECT_ID>"
+fcv_expiration_date  = "<FCV pin expiration date, e.g. 2024-11-22T10:50:00Z>"
+```
+
+**2\. Review the Terraform plan.**
+
+Execute the following command.
+
+``` bash
+$ terraform plan
+```
+This project currently supports the following deployments:
+
+- A Cluster with pinned FCV configured.
+
+**3\. Execute the Terraform apply.**
+
+Execute the following plan to provision the Atlas Project and Cluster resources.
+
+``` bash
+$ terraform apply
+```
+
+**4\. Destroy the resources.**
+
+Once you finished your testing, ensure you destroy the resources to avoid unnecessary Atlas charges.
+
+``` bash
+$ terraform destroy
+```
+

examples/mongodbatlas_advanced_cluster/version-upgrade-with-pinned-fcv/main.tf

@@ -0,0 +1,33 @@
+provider "mongodbatlas" {
+  public_key  = var.public_key
+  private_key = var.private_key
+}
+
+resource "mongodbatlas_advanced_cluster" "cluster" {
+  project_id   = var.project_id
+  name         = "cluster"
+  cluster_type = "REPLICASET"
+
+  mongo_db_major_version = "7.0"
+
+  pinned_fcv {
+    expiration_date = var.fcv_expiration_date # e.g. format: "2024-11-22T10:50:00Z". Hashicorp time provider https://registry.terraform.io/providers/hashicorp/time/latest/docs/resources/offset can be used to compute this string value.
+  }
+
+  replication_specs {
+    region_configs {
+      electable_specs {
+        instance_size = "M10"
+        node_count    = 3
+      }
+      provider_name = "AWS"
+      priority      = 7
+      region_name   = "EU_WEST_1"
+    }
+  }
+}
+
+output "feature_compatibility_version" {
+  value = mongodbatlas_advanced_cluster.cluster.pinned_fcv[0].version
+}
+

examples/mongodbatlas_advanced_cluster/version-upgrade-with-pinned-fcv/variables.tf

@@ -0,0 +1,17 @@
+variable "project_id" {
+  description = "Atlas project id"
+  type        = string
+}
+variable "public_key" {
+  description = "Public API key to authenticate to Atlas"
+  type        = string
+}
+variable "private_key" {
+  description = "Private API key to authenticate to Atlas"
+  type        = string
+}
+
+variable "fcv_expiration_date" {
+  description = "Expiration date of the pinned FCV"
+  type        = string
+}

examples/mongodbatlas_advanced_cluster/version-upgrade-with-pinned-fcv/versions.tf

@@ -0,0 +1,9 @@
+terraform {
+  required_providers {
+    mongodbatlas = {
+      source  = "mongodb/mongodbatlas"
+      version = "~> 1.22"
+    }
+  }
+  required_version = ">= 1.0"
+}

internal/service/advancedcluster/data_source_advanced_cluster.go

@@ -260,6 +260,22 @@ func DataSource() *schema.Resource {
 				Type:     schema.TypeString,
 				Computed: true,
 			},
+			"pinned_fcv": {
+				Type:     schema.TypeList,
+				Computed: true,
+				Elem: &schema.Resource{
+					Schema: map[string]*schema.Schema{
+						"version": {
+							Type:     schema.TypeString,
+							Computed: true,
+						},
+						"expiration_date": {
+							Type:     schema.TypeString,
+							Computed: true,
+						},
+					},
+				},
+			},
 		},
 	}
 }
@@ -301,12 +317,6 @@ func dataSourceRead(ctx context.Context, d *schema.ResourceData, meta any) diag.
 		if err != nil {
 			return diag.FromErr(fmt.Errorf(errorRead, clusterName, err))
 		}
-		if err := d.Set("replica_set_scaling_strategy", clusterDescNew.GetReplicaSetScalingStrategy()); err != nil {
-			return diag.FromErr(fmt.Errorf(ErrorClusterAdvancedSetting, "replica_set_scaling_strategy", clusterName, err))
-		}
-		if err := d.Set("redact_client_log_data", clusterDescNew.GetRedactClientLogData()); err != nil {
-			return diag.FromErr(fmt.Errorf(ErrorClusterAdvancedSetting, "redact_client_log_data", clusterName, err))
-		}
 
 		zoneNameToZoneIDs, err := getZoneIDsFromNewAPI(clusterDescNew)
 		if err != nil {
@@ -318,10 +328,7 @@ func dataSourceRead(ctx context.Context, d *schema.ResourceData, meta any) diag.
 			return diag.FromErr(fmt.Errorf(ErrorClusterAdvancedSetting, "replication_specs", clusterName, err))
 		}
 
-		clusterDesc := convertClusterDescToLatestExcludeRepSpecs(clusterDescOld)
-		clusterDesc.ConfigServerManagementMode = clusterDescNew.ConfigServerManagementMode
-		clusterDesc.ConfigServerType = clusterDescNew.ConfigServerType
-		diags := setRootFields(d, clusterDesc, false)
+		diags := setRootFields(d, clusterDescNew, false)
 		if diags.HasError() {
 			return diags
 		}
@@ -340,12 +347,6 @@ func dataSourceRead(ctx context.Context, d *schema.ResourceData, meta any) diag.
 		if err := d.Set("disk_size_gb", GetDiskSizeGBFromReplicationSpec(clusterDescLatest)); err != nil {
 			return diag.FromErr(fmt.Errorf(ErrorClusterAdvancedSetting, "disk_size_gb", clusterName, err))
 		}
-		if err := d.Set("replica_set_scaling_strategy", clusterDescLatest.GetReplicaSetScalingStrategy()); err != nil {
-			return diag.FromErr(fmt.Errorf(ErrorClusterAdvancedSetting, "replica_set_scaling_strategy", clusterName, err))
-		}
-		if err := d.Set("redact_client_log_data", clusterDescLatest.GetRedactClientLogData()); err != nil {
-			return diag.FromErr(fmt.Errorf(ErrorClusterAdvancedSetting, "redact_client_log_data", clusterName, err))
-		}
 
 		zoneNameToOldReplicationSpecIDs, err := getReplicationSpecIDsFromOldAPI(ctx, projectID, clusterName, connV220240530)
 		if err != nil {

internal/service/advancedcluster/data_source_advanced_clusters.go

@@ -273,6 +273,22 @@ func PluralDataSource() *schema.Resource {
 							Type:     schema.TypeString,
 							Computed: true,
 						},
+						"pinned_fcv": {
+							Type:     schema.TypeList,
+							Computed: true,
+							Elem: &schema.Resource{
+								Schema: map[string]*schema.Schema{
+									"version": {
+										Type:     schema.TypeString,
+										Computed: true,
+									},
+									"expiration_date": {
+										Type:     schema.TypeString,
+										Computed: true,
+									},
+								},
+							},
+						},
 					},
 				},
 			},
@@ -375,6 +391,7 @@ func flattenAdvancedClusters(ctx context.Context, connV220240530 *admin20240530.
 			"redact_client_log_data":               cluster.GetRedactClientLogData(),
 			"config_server_management_mode":        cluster.GetConfigServerManagementMode(),
 			"config_server_type":                   cluster.GetConfigServerType(),
+			"pinned_fcv":                           flattenPinnedFCV(cluster),
 		}
 		results = append(results, result)
 	}
@@ -419,7 +436,6 @@ func flattenAdvancedClustersOldSDK(ctx context.Context, connV20240530 *admin2024
 			"encryption_at_rest_provider":          cluster.GetEncryptionAtRestProvider(),
 			"labels":                               flattenLabels(*convertLabelsToLatest(cluster.Labels)),
 			"tags":                                 conversion.FlattenTags(convertTagsToLatest(cluster.GetTags())),
-			"mongo_db_major_version":               cluster.GetMongoDBMajorVersion(),
 			"mongo_db_version":                     cluster.GetMongoDBVersion(),
 			"name":                                 cluster.GetName(),
 			"paused":                               cluster.GetPaused(),
@@ -430,10 +446,12 @@ func flattenAdvancedClustersOldSDK(ctx context.Context, connV20240530 *admin2024
 			"termination_protection_enabled":       cluster.GetTerminationProtectionEnabled(),
 			"version_release_system":               cluster.GetVersionReleaseSystem(),
 			"global_cluster_self_managed_sharding": cluster.GetGlobalClusterSelfManagedSharding(),
+			"mongo_db_major_version":               clusterDescNew.GetMongoDBMajorVersion(), // uses 2024-08-05 as it has fix for correct value when FCV is active
 			"replica_set_scaling_strategy":         clusterDescNew.GetReplicaSetScalingStrategy(),
 			"redact_client_log_data":               clusterDescNew.GetRedactClientLogData(),
 			"config_server_management_mode":        clusterDescNew.GetConfigServerManagementMode(),
 			"config_server_type":                   clusterDescNew.GetConfigServerType(),
+			"pinned_fcv":                           flattenPinnedFCV(clusterDescNew),
 		}
 		results = append(results, result)
 	}

internal/service/advancedcluster/model_advanced_cluster.go

@@ -426,6 +426,16 @@ func CheckRegionConfigsPriorityOrderOld(regionConfigs []admin20240530.Replicatio
 	return nil
 }
 
+func flattenPinnedFCV(cluster *admin.ClusterDescription20240805) []map[string]string {
+	if cluster.FeatureCompatibilityVersionExpirationDate == nil { // pinned_fcv is defined in state only if featureCompatibilityVersionExpirationDate is present in cluster response
+		return nil
+	}
+	nestedObj := map[string]string{}
+	nestedObj["version"] = cluster.GetFeatureCompatibilityVersion()
+	nestedObj["expiration_date"] = conversion.TimeToString(cluster.GetFeatureCompatibilityVersionExpirationDate())
+	return []map[string]string{nestedObj}
+}
+
 func flattenConnectionStrings(str admin.ClusterConnectionStrings) []map[string]any {
 	return []map[string]any{
 		{