Docs Menu

AtlasCluster Custom Resource

On this page

  • Examples
  • Status Example
  • Configuration Example
  • Advanced Cluster Example
  • Multiple Cloud Service Providers Example
  • Parameters

The AtlasCluster custom resource configures your MongoDB cluster in Atlas. When you create the AtlasCluster custom resource, Atlas Kubernetes Operator tries to create or update a cluster in Atlas.

Atlas Kubernetes Operator does one of the following actions using the Atlas Clusters API Resource and Advanced Clusters API Resource:

  • Creates a new cluster.
  • Updates an existing cluster.

Creating or updating a cluster can take up to 10 minutes. Atlas Kubernetes Operator monitors the update process.

You can run the following command to check on the status:

kubectl get atlascluster -o yaml

The following example shows the status section of a cluster that is provisioning:

status:
  conditions:
  - lastTransitionTime: "2021-03-18T16:32:43Z"
    status: "False"
    type: ClusterReady
    reason: ClusterCreating
    message: Cluster is provisioning

The ClusterReady status will change to True when the cluster is ready.

If you remove the AtlasCluster resource from your Kubernetes cluster, Atlas Kubernetes Operator removes the cluster from Atlas.

Examples

Status Example

The following example shows the AtlasCluster resource with a ClusterReady status of True:

apiVersion: atlas.mongodb.com/v1
kind: AtlasCluster
metadata:
  name: my-atlas-cluster
  namespace: default
spec:
  projectRef:
    name: my-project
  clusterSpec:
    name: test-cluster
    providerSettings:
      instanceSizeName: M10
      providerName: AWS
      regionName: US_EAST_1
    mongoDBMajorVersion: "4.4"
status:
  conditions:
  - lastTransitionTime: "2021-03-18T16:32:43Z"
    status: "True"
    type: Ready
  - lastTransitionTime: "2021-03-18T16:32:43Z"
    status: "True"
    type: ClusterReady
  connectionStrings:
    standard: mongodb://test-cluster-shard-00-00.kpc8f.mongodb.net:27017,test-cluster-shard-00-01.kpc8f.mongodb.net:27017,test-cluster-shard-00-02.kpc8f.mongodb.net:27017/?ssl=true&authSource=admin&replicaSet=atlas-1gm1pv-shard-0
    standardSrv: mongodb+srv://test-cluster.kpc8f.mongodb.net
  mongoDBVersion: 4.4.4
  mongoURIUpdated: "2021-03-12T12:21:41Z"
  observedGeneration: 1
  stateName: IDLE

Configuration Example

The following example shows an AtlasCluster custom resource specification configured for auto-scaling multi-region clusters:

apiVersion: atlas.mongodb.com/v1
kind: AtlasCluster
metadata:
  name: test-cluster-name
  namespace: mongodb-atlas-system
spec:
  projectRef:
    name: development
  clusterSpec:
    autoScaling:
      compute:
        enabled: true
        scaleDownEnabled: true
    clusterType: REPLICASET
    name: service-name
    providerBackupEnabled: true
    providerSettings:
      autoScaling:
        compute:
          maxInstanceSize: M40
          minInstanceSize: M30
      instanceSizeName: M30
      providerName: GCP
    replicationSpecs:
      - numShards: 1
        regionsConfig:
          EASTERN_US:
            analyticsNodes: 0
            electableNodes: 1
            priority: 6
            readOnlyNodes: 0
          SOUTH_AMERICA_EAST_1:
            analyticsNodes: 0
            electableNodes: 2
            priority: 7
            readOnlyNodes: 0
        zoneName: Zone 1

Advanced Cluster Example

Advanced clusters can span regions and cloud service providers. To learn more, see the Advanced Cluster Considerations.

Note

While the Atlas Advanced Clusters API Resource send requests using the v1.5 Atlas API versions, the Atlas Kubernetes Operator apiVersion field uses v1. In this case, v1 refers to the version of the Kubernetes API.

The following example shows an advanced AtlasCluster custom resource specification configured for multi-region clusters:

apiVersion: atlas.mongodb.com/v1
kind: AtlasCluster
metadata:
  name: my-atlas-cluster
spec:
  projectRef:
    name: my-project
  advancedClusterSpec:
    clusterType: REPLICASET
    name: tenantCluster
    replicationSpecs:
      - regionConfigs:
        - electableSpecs:
            instanceSize: M5
          providerName: TENANT
          backingProviderName: AWS
          regionName: US_EAST_1

Multiple Cloud Service Providers Example

The following example shows an advanced AtlasCluster custom resource specification configured to span multiple cloud service providers:

apiVersion: atlas.mongodb.com/v1
kind: AtlasCluster
metadata:
  name: my-atlas-cluster
spec:
  projectRef:
    name: my-project
  advancedClusterSpec:
    clusterType: REPLICASET
    name: tenantCluster
    replicationSpecs:
      - regionConfigs:
        - electableSpecs:
            instanceSize: M10
            nodeCount: 3
          providerName: AWS
          regionName: US_EAST_1
          priority: 7
        - electableSpecs:
            instanceSize: M10
            nodeCount: 2
          providerName: AZURE
          regionName: US_EAST_2
          priority: 6
        - electableSpecs:
            instanceSize: M10
            nodeCount: 2
          providerName: GCP
          regionName: CENTRAL_US
          priority: 5

Parameters

This section describes some of the key AtlasCluster custom resource parameters available. For a full list of parameters available, see the Atlas Clusters API and Atlas Advanced Clusters API. Refer to these descriptions, the available examples, and the API documentation to customize your specifications.

spec.advancedClusterSpec

Type: array

Conditional

List that contains the advanced cluster parameters from the API. For a full list of parameters available, see the Atlas Advanced Clusters API.

Important

You must specify spec.clusterSpec or spec.advancedClusterSpec in your configuration.

spec.advancedClusterSpec.replicationSpecs.regionConfigs

Type: array

Required

Hardware specifications for nodes set for a given region. Each regionConfigs object describes the region's priority in elections and the number and type of MongoDB nodes that Atlas deploys to the region.

Each regionConfigs object must have either an analyticsSpecs object, electableSpecs object, or readOnlySpecs object.

  • TENANT clusters (M0, M2, or M5`) require only ``electableSpecs.
  • Dedicated clusters can specify any of these specifications, but must have at least one electableSpecs object within a replicationSpec.
  • Every hardware specification must use the same instanceSize.
spec.advancedClusterSpec.replicationSpecs.regionConfigs.analyticsSpecs

Type: object

Optional

Hardware specifications for analytics nodes needed in the region. Analytics nodes handle analytic data such as reporting queries from BI Connector for Atlas. Analytics nodes are read-only and can never become the primary.

If you don't specify this parameter, Atlas deploys no analytics to this region.

spec.advancedClusterSpec.replicationSpecs.regionConfigs.electableSpecs

Type: object

Optional

Hardware specifications for electable nodes in the region. Electable nodes can become the primary and can enable local reads.

If you don't specify this option, Atlas deploys no electable nodes to the region.

spec.advancedClusterSpec.replicationSpecs.regionConfigs.electableSpecs.instanceSize

Type: string

Conditional

Hardware specification for the instance sizes in this region. Each instance size has a default storage and memory capacity. The instance size you select applies to all the data-bearing hosts in your instance size. To learn more, see the AWS, GCP, and Azure custom storage sizes.

If you deploy a sharded cluster, or global cluster, you must choose an instance size of M30 or greater.

spec.advancedClusterSpec.replicationSpecs.regionConfigs.electableSpecs.nodeCount

Type: integer

Conditional

Number of electable nodes for Atlas to deploy to the region. Electable nodes can become the primary and can enable local reads.

The combined electableSpecs.nodeCount across all replicationSpecs.regionConfigs objects must total 3, 5, or 7.

You can't create electable nodes if spec.advancedClusterSpec.replicationSpecs.regionConfigs.priority is 0.

spec.advancedClusterSpec.replicationSpecs.regionConfigs.priority

Type: integer

Required

Precedence is given to this region when a primary election occurs.

If your regionConfigs has only readOnlySpecs, analyticsSpecs, or both, set this value to 0.

If you have multiple regionConfigs objects (your cluster is multi-region or multi-cloud), they must have priorities in descending order. The highest priority is 7.

Example

Set your highest priority region to 7, your second-highest priority to 6, and your third-priority region to 5. If you have no electable nodes, set this value to 0.

If your region has set electableSpecs.nodeCount to 1 or higher, it must have a priority of exactly one less than another region in the replicationSpecs.regionConfigs array unless it is the primary. The highest-priority region must have a priority of 7. The lowest possible priority is 1.

The priority 7 region identifies the Preferred Region of the cluster. Atlas places the primary node in the Preferred Region. Priorities 1 through 7 are exclusive: you can't assign a given priority to more than one region per cluster.

Example

If you have three regions, their priorities would be 7, 6, and 5 respectively. If you added two more regions for supporting electable nodes, the priorities of those regions would be 4 and 3 respectively.

spec.advancedClusterSpec.replicationSpecs.regionConfigs.readOnlySpecs

Type: object

Optional

Hardware specifications for read-only nodes in the region. Read-only nodes can never become the primary member, but can enable local reads.

If you don't specify this parameter, Atlas deploys no read-only nodes to the region.

spec.clusterSpec

Type: array

Conditional

List that contains the cluster parameters from the API. For a full list of parameters available, see the Atlas Clusters API.

Important

You must specify spec.clusterSpec or spec.advancedClusterSpec in your configuration.

spec.clusterSpec.clusterType

Type: string

Conditional

Human-readable label that identifies cluster type to create.

When should you use this parameter?

Condition
Necessity
You set spec.clusterSpec.replicationSpecs.
Required
You are deploying Global Clusters.
Required
You are deploying non-Global replica sets and sharded clusters.
Optional

Atlas accepts:

Value
Cluster Type
REPLICASET
replica set
SHARDED
sharded cluster
GEOSHARDED
global cluster
spec.clusterSpec.mongoDBMajorVersion

Type: string

Optional

Version of the cluster to deploy. Atlas supports the following MongoDB versions for M10+ clusters:

  • 4.0
  • 4.2
  • 4.4
  • 5.0

The following conditions produce the following results:

Condition
Result
You omit this parameter and you omit the spec.clusterSpec.versionReleaseSystem parameter.
Atlas deploys a cluster that runs MongoDB 5.0.
You omit this parameter and you set the spec.clusterSpec.versionReleaseSystem parameter to LTS.
Atlas deploys a cluster that runs MongoDB 5.0.
You set the spec.clusterSpec.providerSettings.instanceSizeName parameter to M0, M2, or M5.
You must deploy MongoDB 5.0.
You specify this parameter.
Atlas always deploys the cluster with the latest stable patch release of the specified version.
You set the spec.clusterSpec.versionReleaseSystem parameter to CONTINUOUS.
You must omit this parameter.
spec.clusterSpec.providerSettings

Type: Object

Required

Configuration that specifies the settings for the provisioned hosts on which MongoDB runs. The available options are specific to the cloud service provider. To learn more, see the AWS, GCP, and Azure cluster configuration options.

spec.clusterSpec.providerSettings.providerName

Type: string

Required

Cloud service provider on which Atlas provisions the hosts.

AWS
Amazon AWS
GCP
Google Cloud Platform
AZURE
Microsoft Azure
TENANT

M0, M2, or M5 multi-tenant cluster.

Use spec.clusterSpec.providerSettings.backingProviderName to set the cloud service provider.

M0, M2, and M5 clusters are multi-tenant deployments. You must set this parameter to TENANT and specify the cloud service provider in spec.clusterSpec.providerSettings.backingProviderName.

spec.clusterSpec.providerSettings.backingProviderName

Type: string

Conditional

Cloud service provider on which Atlas provisions the host for a multi-tenant cluster.

This setting works only when you set spec.clusterSpec.providerSettings.providerName to TENANT and spec.clusterSpec.providerSettings.instanceSizeName to M0, M2, or M5.

Atlas accepts the following values:

AWS
Amazon AWS
GCP
Google Cloud Platform
AZURE
Microsoft Azure
spec.clusterSpec.providerSettings.instanceSizeName

Type: string

Required

Atlas provides different cluster tiers, each with a default storage capacity and RAM size. The cluster you select is used for all the data-bearing servers in your cluster. To learn more, see the AWS, GCP, and Azure custom storage sizes.

spec.clusterSpec.providerSettings.regionName

Type: string

Conditional

Physical location of your MongoDB cluster. The region you choose can affect network latency for clients accessing your databases.

For a complete list of region name values, refer to the the cloud provider reference pages:

For multi-region clusters, see spec.clusterSpec.replicationSpecs. You must set either spec.clusterSpec.providerSettings.regionName or spec.clusterSpec.replicationSpecs.

spec.clusterSpec.replicationSpecs

Type: array of objects

Conditional

List that contains the configurations for your cluster regions. Use this parameter for multi-region clusters. You must set either spec.clusterSpec.providerSettings.regionName or spec.clusterSpec.replicationSpecs.

When should you use this parameter?

Condition
Necessity
Values
You are deploying Global Clusters.
Required
Each object in the array represents a zone where Atlas deploys your cluster's nodes.
You are deploying non-Global replica sets and sharded clusters.
Optional
This array has one object representing where Atlas deploys your cluster's nodes.

If you specify this parameter, you must also specify spec.clusterSpec.clusterType and spec.clusterSpec.replicationSpecs.numShards.

spec.clusterSpec.replicationSpecs.numShards

Positive integer that specifies the number of shards to deploy for a sharded cluster.

If you use the spec.clusterSpec.replicationSpecs parameter, you must set this parameter.

Atlas accepts 1 through 50, inclusive. The default value is 1.

  • If you specify a value of 1 and you set spec.clusterSpec.clusterType to SHARDED, Atlas deploys a single-shard sharded cluster.

  • If you specify 1 and you set spec.clusterSpec.clusterType to REPLICASET, Atlas deploys a replica set.

    Don't create a sharded cluster with a single shard for production environments. Single-shard sharded clusters don't provide the same benefits as multi-shard configurations.

    Tip
    See also:
spec.clusterSpec.replicationSpecs.zoneName

Type: string

Optional

Human-readable label that identifies the zone in a Global Cluster. Provide this value only if you set spec.clusterSpec.clusterType to GEOSHARDED.

spec.clusterSpec.versionReleaseSystem

Type: string

Conditional

Release cadence that Atlas uses for this cluster. Atlas accepts:

  • CONTINUOUS: Atlas creates your cluster using the most recent MongoDB release. Atlas automatically updates your cluster to the latest major and rapid MongoDB releases as they become available.

  • LTS: Atlas creates your cluster using the latest patch release of the MongoDB version that you specify in the spec.clusterSpec.mongoDBMajorVersion parameter. Atlas automatically updates your cluster to subsequent patch releases of this MongoDB version. Atlas doesn't update your cluster to newer rapid or major MongoDB releases as they become available.

    If omitted, defaults to LTS.

    If you set this parameter to CONTINUOUS, you must omit the spec.clusterSpec.mongoDBMajorVersion parameter.

spec.projectRef.name

Type: string

Required

Name of the project where the cluster belongs. You must specify an existing AtlasProject Custom Resource.

status.connectionStrings

Type: array

Required

List that contains the connection URLs for accessing the cluster. This parameter appears after you create or update a cluster.

Note

You can't use a connection URL directly. Atlas clusters require authentication. You must create at least one AtlasDatabaseUser Custom Resource before the application in your Kubernetes cluster can connect to the Atlas cluster. Atlas Kubernetes Operator creates a special secret for each cluster and database user combination in the project. The application in your Kubernetes cluster can use this secret to connect to the Atlas cluster. The spec.scopes parameter in the AtlasDatabaseUser custom resource restricts the clusters that create the database user.

For the configuration parameters available for a cluster and advanced cluster from the API, see the Atlas Clusters API, and Advanced Clusters API.

Note

The following parameters are deprecated in the Atlas API and Atlas Kubernetes Operator does not support them:

  • replicationSpec
  • replicationFactor
←  AtlasProject Custom ResourceAtlasDatabaseUser Custom Resource →

On this page

Give Feedback
MongoDB logo
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center

Support

Social

© 2022 MongoDB, Inc.