feat: Support auto-scaling per shard for cluster tier in advanced_cluster

.changelog/2814.txt

@@ -0,0 +1,3 @@
+```release-note:enhancement
+resource/mongodbatlas_advanced_cluster: Adjusts update operation to support cluster tier auto scaling per shard.
+```

.changelog/2836.txt

@@ -0,0 +1,3 @@
+```release-note:enhancement
+resource/mongodbatlas_advanced_cluster: Adjusts create operation to support cluster tier auto scaling per shard.
+```

docs/data-sources/advanced_cluster.md

@@ -139,7 +139,7 @@ Key-value pairs that categorize the cluster. Each key and value has a maximum le
 
 ### replication_specs
 
-* `id` - **(DEPRECATED)** Unique identifer of the replication document for a zone in a Global Cluster. This value corresponds to the legacy sharding schema (no independent shard scaling) and is different from the Shard ID you may see in the Atlas UI.
+* `id` - **(DEPRECATED)** Unique identifer of the replication document for a zone in a Global Cluster. This value corresponds to the legacy sharding schema (no independent shard scaling) and is different from the Shard ID you may see in the Atlas UI. This value is not populated (empty string) when a sharded cluster has independently scaled shards.
 * `external_id` - Unique 24-hexadecimal digit string that identifies the replication object for a shard in a Cluster. This value corresponds to Shard ID displayed in the UI. When using old sharding configuration (replication spec with `num_shards` greater than 1) this value is not populated.
 * `num_shards` - Provide this value if you set a `cluster_type` of `SHARDED` or `GEOSHARDED`. **(DEPRECATED.)** To learn more, see the [Migration Guide](../guides/1.18.0-upgrade-guide.html.markdown).
 * `region_configs` - Configuration for the hardware specifications for nodes set for a given regionEach `region_configs` object describes the region's priority in elections and the number and type of MongoDB nodes that Atlas deploys to the region. Each `region_configs` object must have either an `analytics_specs` object, `electable_specs` object, or `read_only_specs` object. See [below](#region_configs)

docs/data-sources/advanced_clusters.md

@@ -141,7 +141,7 @@ Key-value pairs that categorize the cluster. Each key and value has a maximum le
 
 ### replication_specs
 
-* `id` - **(DEPRECATED)** Unique identifer of the replication document for a zone in a Global Cluster. This value corresponds to the legacy sharding schema (no independent shard scaling) and is different from the Shard ID you may see in the Atlas UI.
+* `id` - **(DEPRECATED)** Unique identifer of the replication document for a zone in a Global Cluster. This value corresponds to the legacy sharding schema (no independent shard scaling) and is different from the Shard ID you may see in the Atlas UI. This value is not populated (empty string) when a sharded cluster has independently scaled shards.
 * `external_id` - Unique 24-hexadecimal digit string that identifies the replication object for a shard in a Cluster. This value corresponds to Shard ID displayed in the UI. When using old sharding configuration (replication spec with `num_shards` greater than 1) this value is not populated.
 * `num_shards` - Provide this value if you set a `cluster_type` of SHARDED or GEOSHARDED. **(DEPRECATED.)** To learn more, see the [Migration Guide](../guides/1.18.0-upgrade-guide.html.markdown) for more details.
 * `region_configs` - Configuration for the hardware specifications for nodes set for a given regionEach `region_configs` object describes the region's priority in elections and the number and type of MongoDB nodes that Atlas deploys to the region. Each `region_configs` object must have either an `analytics_specs` object, `electable_specs` object, or `read_only_specs` object. See [below](#region_configs)

docs/guides/advanced-cluster-new-sharding-schema.md

@@ -4,7 +4,7 @@ page_title: "Migration Guide: Advanced Cluster New Sharding Configurations"
 
 # Migration Guide: Advanced Cluster New Sharding Configurations
 
-**Objective**: Use this guide to migrate your existing `advanced_cluster` resources to support new sharding configurations introduced in version 1.18.0. The new sharding configurations allow you to scale shards independently. Existing sharding configurations continue to work, but you will receive deprecation messages if you continue to use them.
+**Objective**: Use this guide to migrate your existing `advanced_cluster` resources to support new sharding configurations introduced in version 1.18.0. The new sharding configurations allow you to scale shards independently. Additionally, as of version 1.23.0, compute auto-scaling supports scaling instance sizes independently for each shard when using the new sharding configuration. Existing sharding configurations continue to work, but you will receive deprecation messages if you continue to use them.
 
 Note: Once applied, the `advanced_cluster` resource making use of the new sharding configuration will not be able to transition back to the old sharding configuration.
 
@@ -13,7 +13,8 @@ Note: Once applied, the `advanced_cluster` resource making use of the new shardi
     - [Migrate advanced\_cluster type `SHARDED`](#migrate-advanced_cluster-type-sharded)
     - [Migrate advanced\_cluster type `GEOSHARDED`](#migrate-advanced_cluster-type-geosharded)
     - [Migrate advanced\_cluster type `REPLICASET`](#migrate-advanced_cluster-type-replicaset)
-    - [Use Independent Shard Scaling](#use-independent-shard-scaling)
+- [Use Independent Shard Scaling](#use-independent-shard-scaling)
+- [Use Auto-Scaling Per Shard](#use-auto-scaling-per-shard)
 
 <a id="overview"></a>
 ## Changes Overview
@@ -287,7 +288,7 @@ resource "mongodbatlas_advanced_cluster" "test" {
 Note: The first time `terraform apply` command is run **after** updating the configuration, you may receive a `500 Internal Server Error (Error code: "SERVICE_UNAVAILABLE")` error. This is a known temporary issue. If you encounter this, please re-run `terraform apply` and this time the update should succeed. 
 
 <a id="use-iss"></a>
-### Use Independent Shard Scaling 
+## Use Independent Shard Scaling 
 
 Use the new sharding configurations. Each shard must be represented with a unique `replication_specs` element and `num_shards` must not be used, as illustrated in the following example.
 
@@ -323,7 +324,7 @@ resource "mongodbatlas_advanced_cluster" "test" {
 }
 ```
 
-With each shard's `replication_specs` defined independently, we can now define distinct `instance_size`, and `disk_iops` (only for AWS) values for each shard in the cluster. In the following example, we define an upgraded instance size of M40 only for the first shard in the cluster.
+With each shard's `replication_specs` defined independently, we can now define distinct `instance_size` and `disk_iops` values for each shard in the cluster. Note that independent `disk_iops` values are only supported for AWS provisioned IOPS, or Azure regions that support Extended IOPS. In the following example, we define an upgraded instance size of M40 only for the first shard in the cluster.
 
 Consider reviewing the Metrics Dashboard in the MongoDB Atlas UI (e.g. https://cloud.mongodb.com/v2/<PROJECT-ID>#/clusters/detail/ShardedCluster) for insight into how each shard within your cluster is currently performing, which will inform any shard-specific resource allocation changes you might require.
 
@@ -360,3 +361,80 @@ resource "mongodbatlas_advanced_cluster" "test" {
 ```
 
 -> **NOTE:** For any cluster leveraging the new sharding configurations and defining independently scaled shards, users should also update corresponding `mongodbatlas_cloud_backup_schedule` resource & data sources. This involves updating any existing Terraform configurations of the resource to use `copy_settings.#.zone_id` instead of `copy_settings.#.replication_spec_id`. This is needed as `mongodbatlas_advanced_cluster` resource and data source will no longer have `replication_specs.#.id` present when shards are scaled independently. To learn more, review the [1.18.0 Migration Guide](1.18.0-upgrade-guide.md#transition-cloud-backup-schedules-for-clusters-to-use-zones).
+
+<a id="use-auto-scaling-per-shard"></a>
+## Use Auto-Scaling Per Shard
+
+As of version 1.23.0, enabled `compute` auto-scaling (either `auto_scaling` or `analytics_auto_scaling`) will scale the `instance_size` of each shard independently. Each shard must be represented with a unique `replication_specs` element and `num_shards` must not be used. On the contrary, if using deprecated `num_shards` or a lower version, enabled compute auto-scaling will scale uniformily across all shards in the cluster. 
+
+The following example illustrates a configuration that has compute auto-scaling per shard for electable and analytic nodes.
+
+```
+resource "mongodbatlas_advanced_cluster" "test" {
+  project_id   = var.project_id
+  name         = "AutoScalingCluster"
+  cluster_type = "SHARDED"
+  replication_specs { # first shard
+    region_configs {
+      electable_specs {
+        instance_size = "M40"
+        node_count    = 3
+      }
+      analytics_specs {
+        instance_size = "M40"
+        node_count = 1
+      }
+      auto_scaling {
+        compute_enabled = true
+        compute_max_instance_size = "M60"
+      }
+      analytics_auto_scaling {
+        compute_enabled = true
+        compute_max_instance_size = "M60"
+      }
+      provider_name = "AWS"
+      priority      = 7
+      region_name   = "EU_WEST_1"
+    }
+    zone_name = "Zone 1"
+  }
+  replication_specs { # second shard
+    region_configs {
+      electable_specs {
+        instance_size = "M40"
+        node_count    = 3
+      }
+      analytics_specs {
+        instance_size = "M40"
+        node_count = 1
+      }
+      auto_scaling {
+        compute_enabled = true
+        compute_max_instance_size = "M60"
+      }
+      analytics_auto_scaling {
+        compute_enabled = true
+        compute_max_instance_size = "M60"
+      }
+      provider_name = "AWS"
+      priority      = 7
+      region_name   = "EU_WEST_1"
+    }
+    zone_name = "Zone 1"
+  }
+  lifecycle { # avoids future non-empty plans as instance size start to scale from initial values
+    ignore_changes = [ 
+      replication_specs[0].region_configs[0].electable_specs[0].instance_size, 
+      replication_specs[0].region_configs[0].analytics_specs[0].instance_size, 
+      replication_specs[1].region_configs[0].electable_specs[0].instance_size,
+      replication_specs[1].region_configs[0].analytics_specs[0].instance_size
+    ]
+  }
+}
+```
+
+While the example initially defines 2 symmetric shards, auto-scaling of `electable_specs` or `analytic_specs` can lead to asymmetric shards due to changes in `instance_size`.
+
+-> **NOTE:** After you upgrade to version 1.23.0 of the provider, you must update the cluster configuration to activate the auto-scaling per shard feature.
+
+-> **NOTE:** When auto-scaling per shard, it is possible that the cluster will transition to having asymmetric shards. This will impact the computed attribute `replication_specs.#.id`, which is not populated when shards are scaled independently. Please make sure to update the corresponding `mongodbatlas_cloud_backup_schedule` resource & data sources. This involves updating any existing Terraform configurations of the resource to use `copy_settings.#.zone_id` instead of `copy_settings.#.replication_spec_id`. To learn more, review the [1.18.0 Migration Guide](1.18.0-upgrade-guide.md#transition-cloud-backup-schedules-for-clusters-to-use-zones).