doc: Docs improvements for preview provider 2.0.0 (#3147)

* TF format

* reference migration guide in Move section

* start best-practices

* typo

* resource doc changes

* fix link

* refactor doc changes.

* revert some copied changes.

* minor fix.

* small changes

* apply feedback

* changelog

* changelog mention

* aws lambda mention

* change aws lambda mention

* add recommendation in adv_config

* get back current cluster note

---------

Co-authored-by: Marco Suma <[email protected]>

Author: lantoli

.changelog/3147.txt

@@ -0,0 +1,11 @@
+```release-note:enhancement
+resource/mongodbatlas_advanced_cluster: Available as Preview of MongoDB Atlas Provider 2.0.0
+```
+
+```release-note:enhancement
+data-source/mongodbatlas_advanced_cluster: Available as Preview of MongoDB Atlas Provider 2.0.0
+```
+
+```release-note:enhancement
+data-source/mongodbatlas_advanced_clusters: Available as Preview of MongoDB Atlas Provider 2.0.0
+```

docs/guides/1.29.0-upgrade-guide.md

@@ -12,6 +12,10 @@ The Terraform MongoDB Atlas Provider version 1.29.0 has a number of new and exci
   - If you are already using `mongodbatlas_advanced_cluster`, you can continue doing so with no changes.
   - If you need to migrate from `mongodbatlas_cluster` to `mongodbatlas_advanced_cluster`, see the [Migration Guide: Cluster to Advanced Cluster](cluster-to-advanced-cluster-migration-guide).
 
+- You can now use AWS Lambda connections with the `mongodbatlas_stream_connection` resource. To learn more, see the [mongodbatlas_stream_connection](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/resources/stream_connection) resource documentation.
+
+1.29.0 also includes general improvements, bug fixes and several key documentation updates. See the [CHANGELOG](https://github.com/mongodb/terraform-provider-mongodbatlas/blob/master/CHANGELOG.md) for more specific information.
+
 ## Helpful Links
 
 * [Report bugs](https://github.com/mongodb/terraform-provider-mongodbatlas/issues)

docs/resources/advanced_cluster (preview provider 2.0.0).md

@@ -38,7 +38,7 @@ replication_specs {
 }
 ```
 goes to:
-```
+```terraform
 replication_specs = [
   {
     region_configs = [
@@ -137,7 +137,7 @@ The process to migrate from current `mongodbatlas_advanced_cluster` to the one i
 
 ## Important notes
 
-More information on considerations for using advanced clusters please see [Considerations](https://docs.atlas.mongodb.com/reference/api/cluster-advanced/create-one-cluster-advanced/#considerations)
+Please refer to our [Considerations and Best Practices](#considerations-and-best-practices) section for additional guidance on this resource.
 
 ~> **IMPORTANT:** We recommend all new MongoDB Atlas Terraform users start with the [`mongodbatlas_advanced_cluster`](advanced_cluster) resource.  Key differences between [`mongodbatlas_cluster`](cluster) and [`mongodbatlas_advanced_cluster`](advanced_cluster) include support for [Multi-Cloud Clusters](https://www.mongodb.com/blog/post/introducing-multicloud-clusters-on-mongodb-atlas), [Asymmetric Sharding](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema), and [Independent Scaling of Analytics Node Tiers](https://www.mongodb.com/blog/post/introducing-ability-independently-scale-atlas-analytics-node-tiers). For existing [`mongodbatlas_cluster`](cluster) resource users see our [Migration Guide](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/cluster-to-advanced-cluster-migration-guide).
 
@@ -616,7 +616,7 @@ This parameter defaults to false.
 * `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`.
 * `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)
+* `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_specs` a `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. The `replication_specs` configuration for all shards within the same zone must be the same, with the exception of `instance_size` and `disk_iops` that can scale independently. Note that independent `disk_iops` values are only supported for AWS provisioned IOPS, or Azure regions that support Extended IOPS. 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.
 * `version_release_system` - (Optional) - Release cadence that Atlas uses for this cluster. This parameter defaults to `LTS`. If you set this field to `CONTINUOUS`, you must omit the `mongo_db_major_version` field. Atlas accepts:
@@ -662,7 +662,7 @@ bi_connector_config = {
 
 -> **NOTE:** Prior to setting these options please ensure you read https://docs.atlas.mongodb.com/cluster-config/additional-options/.
 
--> **NOTE:** This argument has been changed to type list make sure you have the proper syntax. The list can have only one  item maximum.
+-> **NOTE:** Once you set some `advanced_configuration` attributes, we recommended to explicitly set those attributes to their intended value instead of removing them from the configuration. For example, if you set `javascript_enabled` to `false`, and later you want to go back to the default value (true), you must set it back to `true` instead of removing it.
 
 Include **desired options** within advanced_configuration:
 
@@ -677,13 +677,11 @@ Include **desired options** within advanced_configuration:
 * `default_read_concern` - (Optional) [Default level of acknowledgment requested from MongoDB for read operations](https://docs.mongodb.com/manual/reference/read-concern/) set for this cluster. MongoDB 4.4 clusters default to [available](https://docs.mongodb.com/manual/reference/read-concern-available/). **(DEPRECATED)** MongoDB 5.0 and later clusters default to `local`. To use a custom read concern level, please refer to your driver documentation.
 * `default_write_concern` - (Optional) [Default level of acknowledgment requested from MongoDB for write operations](https://docs.mongodb.com/manual/reference/write-concern/) set for this cluster. MongoDB 4.4 clusters default to [1](https://docs.mongodb.com/manual/reference/write-concern/).
 * `fail_index_key_too_long` - (Optional) When true, documents can only be updated or inserted if, for all indexed fields on the target collection, the corresponding index entries do not exceed 1024 bytes. When false, mongod writes documents that exceed the limit but does not index them. **(DEPRECATED)** This parameter has been removed as of [MongoDB 4.4](https://www.mongodb.com/docs/manual/reference/parameters/#mongodb-parameter-param.failIndexKeyTooLong).
-* `javascript_enabled` - (Optional) When true, the cluster allows execution of operations that perform server-side executions of JavaScript. When false, the cluster disables execution of those operations.
+* `javascript_enabled` - (Optional) When true (default), the cluster allows execution of operations that perform server-side executions of JavaScript. When false, the cluster disables execution of those operations.
 * `minimum_enabled_tls_protocol` - (Optional) Sets the minimum Transport Layer Security (TLS) version the cluster accepts for incoming connections. Valid values are:
-
   - TLS1_0
   - TLS1_1
   - TLS1_2
-
 * `no_table_scan` - (Optional) When true, the cluster disables the execution of any query that requires a collection scan to return results. When false, the cluster allows the execution of those operations.
 * `oplog_size_mb` - (Optional) The custom oplog size of the cluster. Without a value that indicates that the cluster uses the default oplog size calculated by Atlas.
 * `oplog_min_retention_hours` - (Optional) Minimum retention window for cluster's oplog expressed in hours. A value of null indicates that the cluster uses the default minimum oplog window that MongoDB Cloud calculates.
@@ -842,6 +840,7 @@ 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
   ]
 }
 ```
@@ -865,6 +864,7 @@ lifecycle {
   ignore_changes = [
     replication_specs[0].region_configs[0].analytics_specs.disk_size_gb,
     replication_specs[0].region_configs[0].analytics_specs.instance_size,
+    replication_specs[0].region_configs[0].analytics_specs.disk_iops // instance_size change can affect disk_iops in case that you are using it
   ]
 }
 ```
@@ -941,4 +941,77 @@ moved {
 }
 ```
 
-More information about moving resources can be found in the Terraform documentation [here](https://developer.hashicorp.com/terraform/language/moved) and [here](https://developer.hashicorp.com/terraform/language/modules/develop/refactoring).
+More information about moving resources can be found in our [Migration Guide](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/cluster-to-advanced-cluster-migration-guide) and in the Terraform documentation [here](https://developer.hashicorp.com/terraform/language/moved) and [here](https://developer.hashicorp.com/terraform/language/modules/develop/refactoring).
+
+## Considerations and Best Practices
+
+### "known after apply" verbosity
+
+When making changes to your cluster, it is expected that your Terraform plan might show `known after apply` entries in attributes that have not been modified and does not have any side effects. The reason why this is happening is because some of the changes you make can affect other values of the cluster, hence the provider plugin will show the inability to know the future value until MongoDB Atlas provides those value in the response. As an example, a change in `instance_size` can affect `disk_iops`. This behaviour is related to how [Terraform Plugin Framework](https://developer.hashicorp.com/terraform/plugin/framework) behaves when the resource schema makes use of computed attributes.
+
+If you want to reduce the `known after apply` verbosity in Terraform plan output, explicitly declare expected values for those attributes in your configuration where possible. This approach gives Terraform more information upfront, resulting in clearer, more predictable plan output.
+
+### Remove or disable functionality
+
+To disable or remove functionalities, we recommended to explicitly set those attributes to their intended value instead of removing them from the configuration. This will ensure no ambiguity in what the final terraform resource state will be. For example, if you have a `read_only_specs` block in your cluster definition like this one:
+```terraform
+...
+region_configs = [
+  {
+    read_only_specs =  {
+      instance_size = "M10"
+      node_count    = 1
+    }
+    electable_specs = {
+      instance_size = "M10"
+      node_count    = 3
+    }
+    provider_name = "AWS"
+    priority      = 7
+    region_name   = "US_WEST_1"
+  }
+]
+...
+```
+and your intention is to delete the read-only nodes, you should set the `node_count` attribute to `0` instead of removing the block:
+```terraform
+...
+region_configs = [
+  {
+    read_only_specs =  {
+      instance_size = "M10"
+      node_count    = 0
+    }
+    electable_specs = {
+      instance_size = "M10"
+      node_count    = 3
+    }
+    provider_name = "AWS"
+    priority      = 7
+    region_name   = "US_WEST_1"
+  }
+]
+...
+```
+Similarly, if you have compute and disk auto-scaling enabled:
+```terraform
+...
+auto_scaling = {
+  disk_gb_enabled = true
+  compute_enabled = true
+  compute_scale_down_enabled = true
+  compute_min_instance_size = "M30"
+  compute_max_instance_size = "M50"
+}
+...
+``` 
+and you want to disable them, you should set the `disk_gb_enabled` and `compute_enabled` attributes to `false` instead of removing the block:
+```terraform
+...
+auto_scaling = {
+  disk_gb_enabled = false
+  compute_enabled = false
+  compute_scale_down_enabled = false
+}
+...
+```