From f47081ce225149f1da80f420d09b99e4b03267dc Mon Sep 17 00:00:00 2001 From: Agustin Bettati Date: Tue, 16 Jul 2024 18:18:24 +0200 Subject: [PATCH 1/6] define 1.18.0 migration guide --- .../guides/1.18.0-upgrade-guide.html.markdown | 28 ++ ...-cluster-new-sharding-schema.html.markdown | 344 ++++++++++++++++++ 2 files changed, 372 insertions(+) create mode 100644 website/docs/guides/1.18.0-upgrade-guide.html.markdown create mode 100644 website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown diff --git a/website/docs/guides/1.18.0-upgrade-guide.html.markdown b/website/docs/guides/1.18.0-upgrade-guide.html.markdown new file mode 100644 index 0000000000..d68a5056b7 --- /dev/null +++ b/website/docs/guides/1.18.0-upgrade-guide.html.markdown @@ -0,0 +1,28 @@ +--- +page_title: "Upgrade Guide 1.18.0" +--- + +# MongoDB Atlas Provider 1.18.0: Upgrade and Information Guide + +The Terraform MongoDB Atlas Provider version 1.18.0 has a number of new and exciting features. + +**New Resources, Data Sources, and Features:** + +- Sharded and geo-sharded cluster defined with `mongodbatlas_advanced_cluster` are now capable of scaling the instance size and disk IOPS independently for each individual shard. For more details and migration guidelines please reference [advanced_cluster - Migration to new sharding schema and leveraging Independent Shard Scaling](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema). + +**Deprecations:** + +- Deprecations in `mongodbatlas_advanced_cluster` resource and data sources: + - `replication_specs.*.num_shards`: The `replication_specs` list now supports defining an object for each inidividual shard and this new schema is favoured over using `num_shards` attribute. For more details and migration guidelines please reference [advanced_cluster - Migration to new sharding schema and leveraging Independent Shard Scaling](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema). + - `disk_size_gb`: The same attribute is now defined under `replication_specs.*.region_configs.*.(electable_specs|analytics_specs|read_only_specs).disk_size_gb`. Replacing the root value into existing inner specs will have no change in the underlying cluster. The motivation behind this change in location is to align with the new API schema and facilitate new features related to independent storage size scaling in the future. + - `replication_specs.*.id`: This attribute was being used by `cloud_backup_schedule` to identify cluster zones. As of 1.18.0 `cloud_backup_schedule` can reference cluster zones using the new `zone_id` attribute. + - `advanced_configuration.default_read_concern`: This attribute only has one valid value. + - `advanced_configuration.fail_index_key_too_long`: This attribute only applies to older versions of MongoDB (removed in 4.4). + +### Helpful Links + +* [Report bugs](https://github.com/mongodb/terraform-provider-mongodbatlas/issues) + +* [Request Features](https://feedback.mongodb.com/forums/924145-atlas?category_id=370723) + +* [Contact Support](https://docs.atlas.mongodb.com/support/) covered by MongoDB Atlas support plans, Developer and above. diff --git a/website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown b/website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown new file mode 100644 index 0000000000..352ab39db1 --- /dev/null +++ b/website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown @@ -0,0 +1,344 @@ +--- +page_title: "advanced_cluster - Migration to new sharding schema and leveraging Independent Shard Scaling" +--- + +**Objective**: Guide users to migrate their existing advanced_cluster configurations to use the new sharding schema which was introduced in version `1.18.0`. Additionally, a section is included to describe how Independent Shard Scaling can be used once the new sharding schema is adopted. Exiting configurations will continue to work but will have deprecation messages if not using the new sharding schema. + +- [Overview of schema changes](#overview) +- [Migrating existing advanced_cluster type SHARDED](#migration-sharded) +- [Migrating existing advanced_cluster type GEOSHARDED](#migration-geosharded) +- [Migrating existing advanced_cluster type REPLICASET](#migration-replicaset) +- [Leveraging Independent Shard Scaling](#leveraging-iss) + + +# Overview of schema changes + +`replication_specs` attribute has been modified to now be able to represent each individual shard of a cluster with a unique replication spec element. This implies that when using the new sharding schema the existing attribute `num_shards` will no longer be defined, and instead the number of shards will be defined by the number of `replication_specs` elements. + + +## Migrating existing advanced_cluster type SHARDED + +Considering the following configuration of a SHARDED cluster using the deprecated `num_shards`: +``` +resource "mongodbatlas_advanced_cluster" "test" { + project_id = var.project_id + name = "SymmetricShardedCluster" + cluster_type = "SHARDED" + + replication_specs { + # deprecation warning will be encoutered for using num_shards + num_shards = 2 + region_configs { + electable_specs { + instance_size = "M30" + disk_iops = 3000 + node_count = 3 + } + provider_name = "AWS" + priority = 7 + region_name = "EU_WEST_1" + } + } +} +``` + +In order to update our configuration to the new schema we will remove the use of `num_shards` and add a new identical `replication_specs` element for each shard. Note that these 2 changes must be done at the same time. + +``` +resource "mongodbatlas_advanced_cluster" "test" { + project_id = var.project_id + name = "SymmetricShardedCluster" + cluster_type = "SHARDED" + + replication_specs { # first shard + region_configs { + electable_specs { + instance_size = "M30" + disk_iops = 3000 + node_count = 3 + } + provider_name = "AWS" + priority = 7 + region_name = "EU_WEST_1" + } + } + + replication_specs { # second shard + region_configs { + electable_specs { + instance_size = "M30" + disk_iops = 3000 + node_count = 3 + } + provider_name = "AWS" + priority = 7 + region_name = "EU_WEST_1" + } + } +} +``` + +This updated configuration will trigger a terraform update plan, however the underlying cluster will not face any changes after the apply as both configurations represent a sharded cluster composed of 2 shards. + + +## Migrating existing advanced_cluster type GEOSHARDED + +Considering the following configuration of a GEOSHARDED cluster using the deprecated `num_shards`: + +``` +resource "mongodbatlas_advanced_cluster" "test" { + project_id = var.project_id + name = "GeoShardedCluster" + cluster_type = "GEOSHARDED" + + replication_specs { + zone_name = "zone n1" + num_shards = 2 + region_configs { + electable_specs { + instance_size = "M10" + node_count = 3 + } + provider_name = "AWS" + priority = 7 + region_name = "US_EAST_1" + } + } + + replication_specs { + zone_name = "zone n2" + num_shards = 2 + + region_configs { + electable_specs { + instance_size = "M10" + node_count = 3 + } + provider_name = "AWS" + priority = 7 + region_name = "EU_WEST_1" + } + } +} +``` + +In order to update our configuration to the new schema we will remove the use of `num_shards` and add a new identical `replication_specs` element for each shard. Note that these 2 changes must be done at the same time. + +``` +resource "mongodbatlas_advanced_cluster" "test" { + project_id = var.project_id + name = "GeoShardedCluster" + cluster_type = "GEOSHARDED" + + replication_specs { # first shard for zone n1 + zone_name = "zone n1" + region_configs { + electable_specs { + instance_size = "M10" + node_count = 3 + } + provider_name = "AWS" + priority = 7 + region_name = "US_EAST_1" + } + } + + replication_specs { # second shard for zone n1 + zone_name = "zone n1" + region_configs { + electable_specs { + instance_size = "M10" + node_count = 3 + } + provider_name = "AWS" + priority = 7 + region_name = "US_EAST_1" + } + } + + replication_specs { # first shard for zone n2 + zone_name = "zone n2" + region_configs { + electable_specs { + instance_size = "M10" + node_count = 3 + } + provider_name = "AWS" + priority = 7 + region_name = "EU_WEST_1" + } + } + + replication_specs { # second shard for zone n2 + zone_name = "zone n2" + region_configs { + electable_specs { + instance_size = "M10" + node_count = 3 + } + provider_name = "AWS" + priority = 7 + region_name = "EU_WEST_1" + } + } +} +``` + + + +This updated configuration will trigger a terraform update plan, however the underlying cluster will not face any changes after the apply as both configurations represent a geo sharded cluster with 2 zones and 2 shards in each one. + + +## Migrating existing advanced_cluster type REPLICASET + +-> **NOTE:** Please consider the following complementary documentation providing details on transitioning from a replicaset to a sharded cluster: https://www.mongodb.com/docs/atlas/scale-cluster/#convert-a-replica-set-to-a-sharded-cluster. + +Considering the following replica set configuration: +``` +resource "mongodbatlas_advanced_cluster" "test" { + project_id = var.project_id + name = "ReplicaSetTransition" + cluster_type = "REPLICASET" + + replication_specs { + region_configs { + electable_specs { + instance_size = "M10" + node_count = 3 + } + provider_name = "AZURE" + priority = 7 + region_name = "US_EAST" + } + } +} +``` + +To transition a replica set to sharded cluster 2 separate updates must be applied. First the cluster type must be adjusted to SHARDED, and apply this change without any other additional changes. + +``` +resource "mongodbatlas_advanced_cluster" "test" { + project_id = var.project_id + name = "ReplicaSetTransition" + cluster_type = "SHARDED" + + replication_specs { + region_configs { + electable_specs { + instance_size = "M10" + node_count = 3 + } + provider_name = "AZURE" + priority = 7 + region_name = "US_EAST" + } + } +} +``` + +Once the cluster type is adjusted accordingly, we can proceed to add a new shard using the new schema: + +``` +resource "mongodbatlas_advanced_cluster" "test" { + project_id = var.project_id + name = "ReplicaSetTransition" + cluster_type = "SHARDED" + + replication_specs { # first shard + region_configs { + electable_specs { + instance_size = "M10" + node_count = 3 + } + provider_name = "AZURE" + priority = 7 + region_name = "US_EAST" + } + } + + replication_specs { # second shard + region_configs { + electable_specs { + instance_size = "M10" + node_count = 3 + } + provider_name = "AZURE" + priority = 7 + region_name = "US_EAST" + } + } +} +``` + + +## Leveraging Independent Shard Scaling + +Prerequisite: The new sharding schema must be used, meaning the advanced_cluster configuration is not using `num_shards` and therefore each shard is represented with a unique `replication_specs` element. Please refer to documentation above to transition into this schema if not already. + +Considering the following configuration of a SHARDED cluster that has a symmetric configuration for its 2 shards: + +``` +resource "mongodbatlas_advanced_cluster" "test" { + project_id = var.project_id + name = "SymmetricShardedCluster" + cluster_type = "SHARDED" + + replication_specs { # first shard + region_configs { + electable_specs { + instance_size = "M30" + node_count = 3 + } + provider_name = "AWS" + priority = 7 + region_name = "EU_WEST_1" + } + } + + replication_specs { # second shard + region_configs { + electable_specs { + instance_size = "M30" + node_count = 3 + } + provider_name = "AWS" + priority = 7 + region_name = "EU_WEST_1" + } + } +} +``` + +It is now possible to define a different `instance_size`, and `disk_iops` in the case of AWS, for each individual shard. In the following update we will define an upgraded instance size of M40 only for the first shard. One criteria for defining which shard to scaling independently is by looking into the metrics dashboard in the UI (e.g. https://cloud.mongodb.com/v2/#/clusters/detail/SymmetricShardedCluster) + +``` +resource "mongodbatlas_advanced_cluster" "test" { + project_id = var.project_id + name = "SymmetricShardedCluster" + cluster_type = "SHARDED" + + replication_specs { # first shard upgraded to M40 + region_configs { + electable_specs { + instance_size = "M40" + node_count = 3 + } + provider_name = "AWS" + priority = 7 + region_name = "EU_WEST_1" + } + } + + replication_specs { # second shard preserves M30 + region_configs { + electable_specs { + instance_size = "M30" + node_count = 3 + } + provider_name = "AWS" + priority = 7 + region_name = "EU_WEST_1" + } + } +} +``` From fa1065555e3babe137b8a48747d8b7e75244cf55 Mon Sep 17 00:00:00 2001 From: Agustin Bettati Date: Wed, 17 Jul 2024 11:38:05 +0200 Subject: [PATCH 2/6] small fixes --- website/docs/guides/1.18.0-upgrade-guide.html.markdown | 4 +++- .../guides/advanced-cluster-new-sharding-schema.html.markdown | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/website/docs/guides/1.18.0-upgrade-guide.html.markdown b/website/docs/guides/1.18.0-upgrade-guide.html.markdown index d68a5056b7..69a43b9985 100644 --- a/website/docs/guides/1.18.0-upgrade-guide.html.markdown +++ b/website/docs/guides/1.18.0-upgrade-guide.html.markdown @@ -8,7 +8,9 @@ The Terraform MongoDB Atlas Provider version 1.18.0 has a number of new and exci **New Resources, Data Sources, and Features:** -- Sharded and geo-sharded cluster defined with `mongodbatlas_advanced_cluster` are now capable of scaling the instance size and disk IOPS independently for each individual shard. For more details and migration guidelines please reference [advanced_cluster - Migration to new sharding schema and leveraging Independent Shard Scaling](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema). +- Sharded and geo-sharded clusters defined with `mongodbatlas_advanced_cluster` are now capable of scaling the instance size and disk IOPS independently for each individual shard. For more details and migration guidelines please reference [advanced_cluster - Migration to new sharding schema and leveraging Independent Shard Scaling](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema). As part of these changes 2 new attributes have been included: + - New attribute `replication_specs.*.zone_id` is added in the resource and data sources to enable identifying the zone of each `replication_specs` object. + - New attribute `use_replication_spec_per_shard` defined in both data sources to configure if the users want to obtain `replication_specs` objects for each shard. **Deprecations:** diff --git a/website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown b/website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown index 352ab39db1..15c6aabd23 100644 --- a/website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown +++ b/website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown @@ -2,7 +2,7 @@ page_title: "advanced_cluster - Migration to new sharding schema and leveraging Independent Shard Scaling" --- -**Objective**: Guide users to migrate their existing advanced_cluster configurations to use the new sharding schema which was introduced in version `1.18.0`. Additionally, a section is included to describe how Independent Shard Scaling can be used once the new sharding schema is adopted. Exiting configurations will continue to work but will have deprecation messages if not using the new sharding schema. +**Objective**: Guide users to migrate their existing advanced_cluster configurations to use the new sharding schema which was introduced in version `1.18.0`. Additionally, a section is included to describe how Independent Shard Scaling can be used once the new sharding schema is adopted. Exiting sharding configurations will continue to work but will have deprecation messages if not using the new sharding schema. - [Overview of schema changes](#overview) - [Migrating existing advanced_cluster type SHARDED](#migration-sharded) From 292d7363caf3d207a705c26a7f2f1ebfe409728c Mon Sep 17 00:00:00 2001 From: Agustin Bettati Date: Wed, 17 Jul 2024 15:01:59 +0200 Subject: [PATCH 3/6] Update website/docs/guides/1.18.0-upgrade-guide.html.markdown Co-authored-by: maastha <122359335+maastha@users.noreply.github.com> --- website/docs/guides/1.18.0-upgrade-guide.html.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/1.18.0-upgrade-guide.html.markdown b/website/docs/guides/1.18.0-upgrade-guide.html.markdown index 69a43b9985..6770132f92 100644 --- a/website/docs/guides/1.18.0-upgrade-guide.html.markdown +++ b/website/docs/guides/1.18.0-upgrade-guide.html.markdown @@ -18,7 +18,7 @@ The Terraform MongoDB Atlas Provider version 1.18.0 has a number of new and exci - `replication_specs.*.num_shards`: The `replication_specs` list now supports defining an object for each inidividual shard and this new schema is favoured over using `num_shards` attribute. For more details and migration guidelines please reference [advanced_cluster - Migration to new sharding schema and leveraging Independent Shard Scaling](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema). - `disk_size_gb`: The same attribute is now defined under `replication_specs.*.region_configs.*.(electable_specs|analytics_specs|read_only_specs).disk_size_gb`. Replacing the root value into existing inner specs will have no change in the underlying cluster. The motivation behind this change in location is to align with the new API schema and facilitate new features related to independent storage size scaling in the future. - `replication_specs.*.id`: This attribute was being used by `cloud_backup_schedule` to identify cluster zones. As of 1.18.0 `cloud_backup_schedule` can reference cluster zones using the new `zone_id` attribute. - - `advanced_configuration.default_read_concern`: This attribute only has one valid value. + - `advanced_configuration.default_read_concern`: MongoDB 5.0 and later clusters default to `local`. To use a custom read concern level, please refer to your driver documentation. - `advanced_configuration.fail_index_key_too_long`: This attribute only applies to older versions of MongoDB (removed in 4.4). ### Helpful Links From f4c50e4cdf64ec1c92425f327600713c875990e1 Mon Sep 17 00:00:00 2001 From: Agustin Bettati Date: Wed, 17 Jul 2024 15:02:27 +0200 Subject: [PATCH 4/6] Update website/docs/guides/1.18.0-upgrade-guide.html.markdown Co-authored-by: maastha <122359335+maastha@users.noreply.github.com> --- website/docs/guides/1.18.0-upgrade-guide.html.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/guides/1.18.0-upgrade-guide.html.markdown b/website/docs/guides/1.18.0-upgrade-guide.html.markdown index 6770132f92..643c04657b 100644 --- a/website/docs/guides/1.18.0-upgrade-guide.html.markdown +++ b/website/docs/guides/1.18.0-upgrade-guide.html.markdown @@ -17,7 +17,7 @@ The Terraform MongoDB Atlas Provider version 1.18.0 has a number of new and exci - Deprecations in `mongodbatlas_advanced_cluster` resource and data sources: - `replication_specs.*.num_shards`: The `replication_specs` list now supports defining an object for each inidividual shard and this new schema is favoured over using `num_shards` attribute. For more details and migration guidelines please reference [advanced_cluster - Migration to new sharding schema and leveraging Independent Shard Scaling](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema). - `disk_size_gb`: The same attribute is now defined under `replication_specs.*.region_configs.*.(electable_specs|analytics_specs|read_only_specs).disk_size_gb`. Replacing the root value into existing inner specs will have no change in the underlying cluster. The motivation behind this change in location is to align with the new API schema and facilitate new features related to independent storage size scaling in the future. - - `replication_specs.*.id`: This attribute was being used by `cloud_backup_schedule` to identify cluster zones. As of 1.18.0 `cloud_backup_schedule` can reference cluster zones using the new `zone_id` attribute. + - `replication_specs.*.id`: This attribute was being used by `mongodbatlas_cloud_backup_schedule` resource to identify cluster zones. As of 1.18.0 `mongodbatlas_cloud_backup_schedule` resource can reference cluster zones using the new `zone_id` attribute. - `advanced_configuration.default_read_concern`: MongoDB 5.0 and later clusters default to `local`. To use a custom read concern level, please refer to your driver documentation. - `advanced_configuration.fail_index_key_too_long`: This attribute only applies to older versions of MongoDB (removed in 4.4). From 4fcb403e82d20945e361cf593f6f71e1a38915eb Mon Sep 17 00:00:00 2001 From: Agustin Bettati Date: Thu, 18 Jul 2024 10:34:18 +0200 Subject: [PATCH 5/6] addressing comments and suggestions --- .../guides/1.18.0-upgrade-guide.html.markdown | 8 +++---- ...-cluster-new-sharding-schema.html.markdown | 24 +++++++++---------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/website/docs/guides/1.18.0-upgrade-guide.html.markdown b/website/docs/guides/1.18.0-upgrade-guide.html.markdown index 643c04657b..76d5040d44 100644 --- a/website/docs/guides/1.18.0-upgrade-guide.html.markdown +++ b/website/docs/guides/1.18.0-upgrade-guide.html.markdown @@ -8,14 +8,14 @@ The Terraform MongoDB Atlas Provider version 1.18.0 has a number of new and exci **New Resources, Data Sources, and Features:** -- Sharded and geo-sharded clusters defined with `mongodbatlas_advanced_cluster` are now capable of scaling the instance size and disk IOPS independently for each individual shard. For more details and migration guidelines please reference [advanced_cluster - Migration to new sharding schema and leveraging Independent Shard Scaling](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema). As part of these changes 2 new attributes have been included: - - New attribute `replication_specs.*.zone_id` is added in the resource and data sources to enable identifying the zone of each `replication_specs` object. - - New attribute `use_replication_spec_per_shard` defined in both data sources to configure if the users want to obtain `replication_specs` objects for each shard. +- Sharded and geo-sharded clusters defined with `mongodbatlas_advanced_cluster` are now capable of scaling the instance size and disk IOPS independently for each individual shard. For more details and migration guidelines, please reference [advanced_cluster - Migration to new sharding schema and leveraging Independent Shard Scaling](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema). As part of these changes 2 new attributes have been included: + - New attribute `replication_specs.*.zone_id` is added in `mongodbatlas_advanced_cluster` resource and data sources to enable identifying the zone of each `replication_specs` object. + - New attribute `use_replication_spec_per_shard` defined in `mongodbatlas_advanced_cluster` data sources to configure if the users want to obtain `replication_specs` objects for each shard. **Deprecations:** - Deprecations in `mongodbatlas_advanced_cluster` resource and data sources: - - `replication_specs.*.num_shards`: The `replication_specs` list now supports defining an object for each inidividual shard and this new schema is favoured over using `num_shards` attribute. For more details and migration guidelines please reference [advanced_cluster - Migration to new sharding schema and leveraging Independent Shard Scaling](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema). + - `replication_specs.*.num_shards`: The `replication_specs` list now supports defining an object for each inidividual shard. This new schema is favoured over using `num_shards` attribute. For more details and migration guidelines, please reference [advanced_cluster - Migration to new sharding schema and leveraging Independent Shard Scaling](https://registry.terraform.io/providers/mongodb/mongodbatlas/latest/docs/guides/advanced-cluster-new-sharding-schema). - `disk_size_gb`: The same attribute is now defined under `replication_specs.*.region_configs.*.(electable_specs|analytics_specs|read_only_specs).disk_size_gb`. Replacing the root value into existing inner specs will have no change in the underlying cluster. The motivation behind this change in location is to align with the new API schema and facilitate new features related to independent storage size scaling in the future. - `replication_specs.*.id`: This attribute was being used by `mongodbatlas_cloud_backup_schedule` resource to identify cluster zones. As of 1.18.0 `mongodbatlas_cloud_backup_schedule` resource can reference cluster zones using the new `zone_id` attribute. - `advanced_configuration.default_read_concern`: MongoDB 5.0 and later clusters default to `local`. To use a custom read concern level, please refer to your driver documentation. diff --git a/website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown b/website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown index 15c6aabd23..53f759ded0 100644 --- a/website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown +++ b/website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown @@ -13,7 +13,7 @@ page_title: "advanced_cluster - Migration to new sharding schema and leveraging # Overview of schema changes -`replication_specs` attribute has been modified to now be able to represent each individual shard of a cluster with a unique replication spec element. This implies that when using the new sharding schema the existing attribute `num_shards` will no longer be defined, and instead the number of shards will be defined by the number of `replication_specs` elements. +`replication_specs` attribute has been modified to now be able to represent each individual shard of a cluster with a unique replication spec element. As such, when using the new sharding schema the existing attribute `num_shards` will no longer be defined, and instead the number of shards will be defined by the number of `replication_specs` elements. ## Migrating existing advanced_cluster type SHARDED @@ -42,7 +42,7 @@ resource "mongodbatlas_advanced_cluster" "test" { } ``` -In order to update our configuration to the new schema we will remove the use of `num_shards` and add a new identical `replication_specs` element for each shard. Note that these 2 changes must be done at the same time. +In order to update our configuration to the new schema, we will remove the use of `num_shards` and add a new identical `replication_specs` element for each shard. Note that these 2 changes must be done at the same time. ``` resource "mongodbatlas_advanced_cluster" "test" { @@ -78,7 +78,7 @@ resource "mongodbatlas_advanced_cluster" "test" { } ``` -This updated configuration will trigger a terraform update plan, however the underlying cluster will not face any changes after the apply as both configurations represent a sharded cluster composed of 2 shards. +This updated configuration will trigger a terraform update plan. However, the underlying cluster will not face any changes after the apply, as both configurations represent a sharded cluster composed of 2 shards. ## Migrating existing advanced_cluster type GEOSHARDED @@ -122,7 +122,7 @@ resource "mongodbatlas_advanced_cluster" "test" { } ``` -In order to update our configuration to the new schema we will remove the use of `num_shards` and add a new identical `replication_specs` element for each shard. Note that these 2 changes must be done at the same time. +In order to update our configuration to the new schema, we will remove the use of `num_shards` and add a new identical `replication_specs` element for each shard. Note that these 2 changes must be done at the same time. ``` resource "mongodbatlas_advanced_cluster" "test" { @@ -186,7 +186,7 @@ resource "mongodbatlas_advanced_cluster" "test" { -This updated configuration will trigger a terraform update plan, however the underlying cluster will not face any changes after the apply as both configurations represent a geo sharded cluster with 2 zones and 2 shards in each one. +This updated configuration will trigger a terraform update plan. However, the underlying cluster will not face any changes after the apply, as both configurations represent a geo sharded cluster with 2 zones and 2 shards in each one. ## Migrating existing advanced_cluster type REPLICASET @@ -214,7 +214,7 @@ resource "mongodbatlas_advanced_cluster" "test" { } ``` -To transition a replica set to sharded cluster 2 separate updates must be applied. First the cluster type must be adjusted to SHARDED, and apply this change without any other additional changes. +To transition a replica set to sharded cluster 2 separate updates must be applied. First, update the `cluster_type` to SHARDED, and apply this change to the cluster. ``` resource "mongodbatlas_advanced_cluster" "test" { @@ -273,14 +273,12 @@ resource "mongodbatlas_advanced_cluster" "test" { ## Leveraging Independent Shard Scaling -Prerequisite: The new sharding schema must be used, meaning the advanced_cluster configuration is not using `num_shards` and therefore each shard is represented with a unique `replication_specs` element. Please refer to documentation above to transition into this schema if not already. - -Considering the following configuration of a SHARDED cluster that has a symmetric configuration for its 2 shards: +The new sharding schema must be used. Each shard must be represented with a unique replication_specs element and `num_shards` must not be used, as illustrated in the following example. ``` resource "mongodbatlas_advanced_cluster" "test" { project_id = var.project_id - name = "SymmetricShardedCluster" + name = "ShardedCluster" cluster_type = "SHARDED" replication_specs { # first shard @@ -309,12 +307,14 @@ resource "mongodbatlas_advanced_cluster" "test" { } ``` -It is now possible to define a different `instance_size`, and `disk_iops` in the case of AWS, for each individual shard. In the following update we will define an upgraded instance size of M40 only for the first shard. One criteria for defining which shard to scaling independently is by looking into the metrics dashboard in the UI (e.g. https://cloud.mongodb.com/v2/#/clusters/detail/SymmetricShardedCluster) +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. + +Consider reviewing the Metrics Dashboard in the MongoDB Atlas UI (e.g. https://cloud.mongodb.com/v2/#/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. ``` resource "mongodbatlas_advanced_cluster" "test" { project_id = var.project_id - name = "SymmetricShardedCluster" + name = "ShardedCluster" cluster_type = "SHARDED" replication_specs { # first shard upgraded to M40 From 455a6c1ca3d8c03e89a480b7edae46011429b04d Mon Sep 17 00:00:00 2001 From: Agustin Bettati Date: Thu, 18 Jul 2024 17:06:31 +0200 Subject: [PATCH 6/6] rename and move files anticipating to new structure --- .../guides/1.18.0-upgrade-guide.md | 0 .../guides/advanced-cluster-new-sharding-schema.md | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename website/docs/guides/1.18.0-upgrade-guide.html.markdown => docs/guides/1.18.0-upgrade-guide.md (100%) rename website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown => docs/guides/advanced-cluster-new-sharding-schema.md (100%) diff --git a/website/docs/guides/1.18.0-upgrade-guide.html.markdown b/docs/guides/1.18.0-upgrade-guide.md similarity index 100% rename from website/docs/guides/1.18.0-upgrade-guide.html.markdown rename to docs/guides/1.18.0-upgrade-guide.md diff --git a/website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown b/docs/guides/advanced-cluster-new-sharding-schema.md similarity index 100% rename from website/docs/guides/advanced-cluster-new-sharding-schema.html.markdown rename to docs/guides/advanced-cluster-new-sharding-schema.md