Compute Auto-Scaling on Atlas Core

Eligible Clusters for Reactive Auto-Scaling

Atlas cluster tier reactive auto-scaling is available for all dedicated Atlas Core cluster tiers under the General and the Low-CPU cluster classes. Reactive auto-scaling is also available for Atlas Infinite clusters.

How Atlas Scales Cluster Tier

Atlas relies on host ping data for autoscaling decisions. Dedicated cluster data nodes continuously send this ping data to the control plane regardless of whether autoscaling is enabled. When you enable autoscaling, Atlas can use this historical data to scale immediately if scaling conditions are met.

Atlas scales your cluster to another tier in the same class. For example, Atlas scales General clusters to other General cluster classes, but doesn't scale General clusters to Low-CPU cluster classes.

Atlas won't scale your cluster tier if the new cluster tier would fall outside of your specified Minimum and Maximum Cluster Size range.

If you deploy read-only nodes and want your cluster to scale faster, consider adjusting your Replica Set Scaling Mode.

The exact reactive auto-scaling criteria are subject to change in order to ensure appropriate cluster resource utilization.

Atlas uses the following resource utilization and operation admission control concepts to determine when to scale your cluster up or down:

• Absolute System CPU Utilization: Total CPU usage of all processes on the node. Visible as System CPU in Atlas metrics.

• Relative System CPU Utilization: Value Atlas uses for autoscaling decisions on M10 and M20 clusters. This is calculated as:

  Relative System CPU Utilization = Normalized System CPU / Baseline CPU Utilization

  Where:

  • Normalized System CPU: Total CPU usage summed across all cores, normalized to the baseline CPU utilization. Visible as Normalized System CPU in Atlas metrics.

  • Baseline CPU Utilization: Fraction of full CPU guaranteed to your instance by the cloud provider, typically 20%-50% for burstable instance types. Not visible in Atlas metrics. To learn more, see baseline CPU utilization.

    For example, using 20% as a lower-end estimate for the Baseline CPU Utilization, the following Relative System CPU Utilization values correspond to these Normalized System CPU values in Atlas metrics:

    • 75% relative system CPU utilization equals 15% Normalized System CPU (75% of 20%).

    • 90% relative system CPU utilization equals 18% Normalized System CPU (90% of 20%).

  Atlas caps the Relative System CPU Utilization at 100%, even when the calculation exceeds it. If a scale-up occurs when Normalized System CPU appears low, contact MongoDB Support.

• System Memory Utilization: Total memory usage across all processes on the node, expressed as a percentage of total memory available to the node. This is calculated as:

  System Memory Utilization = Memory Used / Total Memory * 100

  Where:

  • Memory Used: Number of bytes of physical memory currently in use on the host. Visible as System Memory: Memory Used (bytes) in Atlas metrics.

  • Total Memory: Total physical memory available to the node, as reported by the operating system. Atlas does not display this value as a separate metric. Not visible in Atlas metrics.

  Note

  The System Memory Utilization value that Atlas uses for autoscaling decisions might differ slightly from the value shown in the Atlas metrics panel. If a scale-down does not occur when System Memory Utilization appears low, contact MongoDB Support.

• Queued or Rejected Operations: Combined rate of operations that Atlas queues or rejects to protect your cluster from overload as part of Intelligent Workload Management (IWM). Atlas calculates this as:

  Queued or Rejected Operations = Queued Operations + Rejected Operations

  Where:

  • Queued Operations: Average rate per minute of incoming operations that Atlas adds to the ingress request rate limiter queue to wait for admission into the cluster. The per-second rate is visible as Operation Rate Limiting: Queued operations in Atlas metrics.

  • Rejected Operations: Average rate per minute of incoming operations that Atlas rejects because the cluster is overloaded and Load Shedding is active. The per-second rate is visible as Operation Rate Limiting: Rejected operations in Atlas metrics.

  To learn how IWM works to queue or reject operations in response to cluster overload, see Intelligent Workload Management.

  A combined value above zero means that your cluster is under overload.

The following sections describe how Atlas uses these metrics to determine when to scale your cluster up or down.

Scaling a Sharded Cluster on Atlas Core

This section applies to Atlas Core clusters. Sharding isn't supported on Atlas Infinite clusters during public preview. Atlas auto-scales the cluster tier for sharded clusters using the same criteria as replica sets. Atlas applies the following rules:

• Independent shard scaling is enabled by default for sharded clusters with auto-scaling. When independent shard scaling is enabled, auto-scaling in Atlas evaluates and scales each shard independently. Independent shard scaling requires that the smallest shard size remains no smaller than two cluster tiers below the largest shard, to maintain availability and performance. If Atlas triggers auto-scaling for such a cluster, and scales up the largest shard, it also scales up the smaller shards if necessary to ensure consistent availability and performance.

• If the operational or analytics nodes within a shard meet the criteria to auto-scale, only the operational or analytics nodes on that particular shard change tier.

• The Config server replica set doesn't auto-scale. However, a Config Shard does auto-scale.

Scaling a Gen2 Dedicated Cluster on Atlas Core

This section applies to Atlas Core clusters. To learn about Atlas Infinite cluster auto-scaling, see Compute Auto-Scaling on Atlas Infinite. Atlas auto-scales the cluster tier for Gen2 Dedicated clusters using the same criteria as replica sets. Atlas applies the following rules:

• Your cluster's current tier, minimum auto-scaling bound, and maximum auto-scaling bound must all be within the same generation.

• M10 and M20 clusters are generation agnostic. Atlas can auto-scale M10 or M20 clusters into either Gen1 or Gen2 clusters.

  For example, if the maximum auto-scaling bound is a Gen1 cluster tier, Atlas auto-scales the cluster into Gen1. If the maximum auto-scaling bound is a Gen2 cluster tier, Atlas auto-scales the cluster into Gen2. You can also use M10 or M20 as the minimum auto-scaling bound for both Gen1 and Gen2 clusters.

The Atlas Administration API returns an INVALID_ATTRIBUTE error if you attempt to do either of the following:

• Change a cluster's generation to one that is different from the generation of the cluster's auto-scaling bounds.

• Set a cluster's auto-scaling bounds to be an M30+ tier cluster belonging to a different generation than the cluster.

Behavior of Predictive Auto-Scaling

The following statements describe how predictive auto-scaling works:

• Atlas attempts to scale up your cluster instance size before the forecasted load arrives.

• When Atlas scales your cluster predictively based on forecasted metrics, it can scale up by at most two tiers at a time.

• Predictive auto-scaling applies only to compute, not storage.

• Predictive auto-scaling respects existing auto-scaling minimum and maximum instance sizes.

• In cases when Atlas can't use predictive auto-scaling to scale up the cluster, it falls back to using reactive auto-scaling.

• Predictive auto-scaling only supports upscaling. There is no predictive down-scaling. Atlas uses reactive auto-scaling to automatically scale down the cluster when the workload decreases.

• If predictive up-scaling is scheduled to happen within the next 1 hour, Atlas skips reactive down-scaling.

• If you use independent shard scaling, and add one or more shards after predictive auto-scaling was already enabled and active on the cluster, these new shards don't auto-scale predictively until their workload patterns have been established, two weeks later. In the meantime, these shards use reactive auto-scaling behavior in Atlas.

Eligible Clusters for Predictive Auto-Scaling

Atlas uses predictive auto-scaling for eligible clusters. Eligible clusters for predictive auto-scaling must meet all of the following criteria:

• Belong to General and Low-CPU cluster classes.

• Have a tier that is M30 or greater.

• Have auto-scaling enabled. If you enable down-scaling, auto-scaling minimum instance size must be equal to or greater than M30.

• Have been active for at least two weeks.

• Not use NVMe storage or belong to the Local NVMe SSD cluster class.

• Not be an AWS Gen2 Dedicated Clusters.

In addition, the following criteria affect whether Atlas uses predictive auto-scaling for an eligible cluster:

• Predictive auto-scaling applies only to electable and read-only nodes. Atlas doesn't use predictive auto-scaling for search or analytics nodes.

• Predictive auto-scaling might not be able to predict non-cyclical and highly dynamic workload spikes in any eligible cluster. In these cases, Atlas relies on reactive auto-scaling.

Auto-Scaling Enabled by Default

When you create a new cluster, Atlas enables auto-scaling (predictive and reactive) for cluster tier and cluster storage. (Predictive auto-scaling only affects cluster tier and doesn't affect storage.) You don't need to explicitly enable auto-scaling. If you prefer, you can opt out for cluster tier and cluster storage.

With auto-scaling enabled, your cluster can automatically:

• Scale up to increase capability with a higher cluster tier, using either reactive or predictive auto-scaling, depending on cluster and workload eligibility.

• Decrease the current cluster tier to a lower cluster tier using reactive auto-scaling.

In the Cluster tier section of the Auto-scale options, you can specify the Maximum Cluster Size and Minimum Cluster Size values that your cluster can automatically scale to. Atlas sets these values as follows:

• The Maximum Cluster Size is set to one tier above your current cluster tier.

• The Minimum Cluster Size is set to the current cluster tier.

In addition, Atlas might use predictive auto-scaling if your cluster is eligible and its workload is cyclical and predictable.

Enable Auto-Scaling with Atlas CLI and Atlas Administration API

You can enable auto-scaling for both compute and storage when creating or updating a cluster using the Atlas CLI or Atlas Administration API. The following examples show how to enable auto-scaling for both electable nodes and analytics nodes. Replace the cluster tiers and provider settings with the ones you need.

{
  "replicationSpecs": [
    {
      "regionConfigs": [
        {
          "providerName": "{CLOUD-PROVIDER}",
          "regionName": "{REGION-NAME}",
          "priority": 7,
          "electableSpecs": {
            "instanceSize": "{INSTANCE-SIZE}",
            "nodeCount": 3
          },
          "analyticsSpecs": {
            "instanceSize": "{ANALYTICS-INSTANCE-SIZE}",
            "nodeCount": 1
          },
          "autoScaling": {
            "compute": {
              "enabled": true,
              "scaleDownEnabled": true,
              "minInstanceSize": "{MIN-INSTANCE-SIZE}",
              "maxInstanceSize": "{MAX-INSTANCE-SIZE}"
            },
            "diskGB": {
              "enabled": true
            }
          },
          "analyticsAutoScaling": {
            "compute": {
              "enabled": true,
              "scaleDownEnabled": true,
              "minInstanceSize": "{MIN-ANALYTICS-INSTANCE-SIZE}",
              "maxInstanceSize": "{MAX-ANALYTICS-INSTANCE-SIZE}"
            },
            "diskGB": {
              "enabled": true
            }
          }
        }
      ]
    }
  ]
}

atlas api clusters updateCluster \
  --version 2024-10-23 \
  --clusterName {CLUSTER-NAME} \
  --groupId {GROUP-ID} \
  --file payload.json

curl --header "Authorization: Bearer {ACCESS-TOKEN}" \
     --header "Accept: application/vnd.atlas.2025-03-12+json" \
     --header "Content-Type: application/json" \
     --include \
     --request PATCH "https://cloud.mongodb.com/api/atlas/v2/groups/{GROUP-ID}/clusters/{CLUSTER-NAME}" \
     --data '{
     "replicationSpecs": [
       {
         "regionConfigs": [
           {
             "providerName": "{CLOUD-PROVIDER}",
             "regionName": "{REGION-NAME}",
             "priority": 7,
             "electableSpecs": {
               "instanceSize": "{INSTANCE-SIZE}",
               "nodeCount": 3
             },
             "autoScaling": {
               "compute": {
                 "enabled": true,
                 "scaleDownEnabled": true,
                 "minInstanceSize": "{MIN-INSTANCE-SIZE}",
                 "maxInstanceSize": "{MAX-INSTANCE-SIZE}"
               },
               "diskGB": {
                 "enabled": true
               }
             },
             "analyticsSpecs": {
               "instanceSize": "{ANALYTICS-INSTANCE-SIZE}",
               "nodeCount": 1
             },
             "analyticsAutoScaling": {
               "compute": {
                 "enabled": true,
                 "scaleDownEnabled": true,
                 "minInstanceSize": "{MIN-ANALYTICS-INSTANCE-SIZE}",
                 "maxInstanceSize": "{MAX-ANALYTICS-INSTANCE-SIZE}"
               },
               "diskGB": {
                 "enabled": true
               }
             }
           }
         ]
       }
     ]'

Review the Cluster Tier Auto-Scaling Options

To review the enabled auto-scaling options for cluster tier and storage:

Opt Out of Cluster Tier Auto-Scaling

To opt out of cluster auto-scaling (increasing the cluster tier), when creating a new cluster, navigate to the Cluster Tier menu, and un-check the Cluster Tier Scaling checkbox in the Auto-scale section.

To opt out of cluster auto-scaling (decreasing the cluster tier), when creating a new cluster, navigate to Cluster Tier menu, and un-check the Allow cluster to be scaled down checkbox in the Auto-scale section.