AtlasDeployment
Custom Resource
On this page
The AtlasDeployment
custom resource configures your MongoDB
cluster or serverless instance in Atlas. When you create
the AtlasDeployment
custom resource, Atlas Kubernetes Operator tries to create or
update a cluster or serverless instance in Atlas.
Atlas Kubernetes Operator does one of the following actions depending on the
values you specify in the AtlasDeployment
custom resource:
- If you specify values for fields under
spec.deploymentSpec
, Atlas Kubernetes Operator uses the Atlas Clusters API Resource and Advanced Clusters API Resource to create a new cluster or update an existing cluster. - If you specify values for fields under
spec.serverlessSpec
, Atlas Kubernetes Operator uses the Atlas Serverless Instance API Resource to create a new serverless instance or update an existing serverless instance.
Creating or updating a cluster or serverless instance 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 atlasdeployment -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 or serverless instance is ready.
If you remove the AtlasDeployment
resource from your Kubernetes
cluster, Atlas Kubernetes Operator removes the cluster or serverless instance
from Atlas.
Examples
Status Example
The following example shows the AtlasDeployment
resource with a
ClusterReady
status of True
:
apiVersion: atlas.mongodb.com/v1 kind: AtlasDeployment metadata: name: my-atlas-cluster namespace: default spec: projectRef: name: my-project deploymentSpec: 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 AtlasDeployment
custom resource
specification configured for auto-scaling multi-region clusters:
apiVersion: atlas.mongodb.com/v1 kind: AtlasDeployment name: test-cluster-name namespace: mongodb-atlas-system spec: projectRef: name: development deploymentSpec: 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 Options Example
The following example shows an AtlasDeployment
custom resource
specification configured with advanced options.
apiVersion: atlas.mongodb.com/v1 kind: AtlasDeployment metadata: name: my-atlas-cluster spec: projectRef: name: my-project deploymentSpec: name: Test-cluster providerSettings: instanceSizeName: M10 providerName: AWS regionName: US_EAST_1 processArgs: javascriptEnabled: false
Serverless Instance Example
The following example shows an AtlasDeployment
custom resource
specification configured for a serverless instance:
apiVersion: atlas.mongodb.com/v1 kind: AtlasDeployment metadata: name: test-cluster-name namespace: mongodb-atlas-system spec: projectRef: name: development serverlessSpec: name: serverless-instance providerSettings: providerName: AWS regionName: US_EAST_1
Advanced Cluster Example
Advanced clusters can span regions and cloud service providers. To learn more, see the Advanced Cluster Considerations.
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 AtlasDeployment
custom
resource specification configured for multi-region clusters:
apiVersion: atlas.mongodb.com/v1 kind: AtlasDeployment metadata: name: my-atlas-cluster spec: projectRef: name: my-project advancedDeploymentSpec: clusterType: REPLICASET name: tenantCluster replicationSpecs: - regionConfigs: - electableSpecs: instanceSize: M5 providerName: AWS regionName: US_EAST_1
Multiple Cloud Service Providers Example
The following example shows an advanced AtlasDeployment
custom
resource specification configured to span multiple cloud service
providers:
apiVersion: atlas.mongodb.com/v1 kind: AtlasDeployment metadata: name: my-atlas-cluster spec: projectRef: name: my-project advancedDeploymentSpec: 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 AtlasDeployment
custom
resource parameters available. For a full list of parameters available
for clusters, see the Atlas Clusters API and Atlas
Advanced Clusters API.
For a full list of parameters available for serverless instances,
see the Atlas Serverless Instances API.
Refer to these descriptions, the available examples, and the API documentation to customize your specifications.
spec.advancedDeploymentSpec
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.
ImportantYou must specify
spec.deploymentSpec
,spec.advancedDeploymentSpec
, orspec.serverlessSpec
in your configuration.
spec.advancedDeploymentSpec.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 ananalyticsSpecs
object,electableSpecs
object, orreadOnlySpecs
object.M0
,M2
, orM5` clusters require only ``electableSpecs
.- Dedicated clusters can specify any of these specifications,
but must have at least one
electableSpecs
object within areplicationSpec
. - Every hardware specification must use the same
instanceSize
.
spec.advancedDeploymentSpec.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.advancedDeploymentSpec.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.advancedDeploymentSpec.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.advancedDeploymentSpec.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 allreplicationSpecs.regionConfigs
objects must total3
,5
, or7
.You can't create electable nodes if
spec.advancedDeploymentSpec.replicationSpecs.regionConfigs.priority
is0
.
spec.advancedDeploymentSpec.replicationSpecs.regionConfigs.priority
Type: integer
Required
Precedence is given to this region when a primary election occurs.
If your
regionConfigs
has onlyreadOnlySpecs
,analyticsSpecs
, or both, set this value to0
.If you have multiple
regionConfigs
objects (your cluster is multi-region or multi-cloud), they must have priorities in descending order. The highest priority is7
.ExampleSet your highest priority region to
7
, your second-highest priority to6
, and your third-priority region to5
. If you have no electable nodes, set this value to0
.If your region has set
electableSpecs.nodeCount
to1
or higher, it must have a priority of exactly one less than another region in thereplicationSpecs.regionConfigs
array unless it is the primary. The highest-priority region must have a priority of7
. The lowest possible priority is1
.The priority
7
region identifies the Preferred Region of the cluster. Atlas places the primary node in the Preferred Region. Priorities1
through7
are exclusive: you can't assign a given priority to more than one region per cluster.ExampleIf you have three regions, their priorities would be
7
,6
, and5
respectively. If you added two more regions for supporting electable nodes, the priorities of those regions would be4
and3
respectively.
spec.advancedDeploymentSpec.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.backupRef
Type: object
Optional
List that contains the details for the
AtlasBackupSchedule
Custom Resource that you want to apply. You can specify one backup schedule per cluster.
spec.backupRef.name
Type: string
Optional
metadata.name
value within theAtlasBackupSchedule
Custom Resource for the backup schedule that you want to apply. You can specify only one backup schedule per cluster, but you can use the same backup schedule for multiple clusters.If you don't specify this parameter, Atlas doesn't apply your backup configuration to this cluster.
spec.backupRef.namespace
Type: string
Optional
String that indicates the namespace that contains the
AtlasBackupSchedule
Custom Resource for the backup schedule that you want to apply.
spec.deploymentSpec
Type: array
Conditional
List that contains the cluster parameters from the API. For a full list of parameters available, see the Atlas Clusters API.
ImportantYou must specify
spec.deploymentSpec
,spec.advancedDeploymentSpec
, orspec.serverlessSpec
in your configuration.
spec.deploymentSpec.clusterType
Type: string
Conditional
Human-readable label that identifies cluster type to create.
When should you use this parameter?
ConditionNecessityYou setspec.deploymentSpec.replicationSpecs
.RequiredYou are deploying Global Clusters.RequiredYou are deploying non-Global replica sets and sharded clusters.OptionalAtlas accepts:
ValueCluster TypeREPLICASETSHARDEDGEOSHARDED
spec.deploymentSpec.mongoDBMajorVersion
Type: string
Optional
Version of the cluster to deploy. Atlas supports the following MongoDB versions for
M10+
clusters:- 4.2
- 4.4
- 5.0
The following conditions produce the following results:
ConditionResultYou omit this parameter and you omit thespec.deploymentSpec.versionReleaseSystem
parameter.Atlas deploys a cluster that runs MongoDB 5.0.You omit this parameter and you set thespec.deploymentSpec.versionReleaseSystem
parameter toLTS
.Atlas deploys a cluster that runs MongoDB 5.0.You set thespec.deploymentSpec.providerSettings.instanceSizeName
parameter toM0
,M2
, orM5
.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 thespec.deploymentSpec.versionReleaseSystem
parameter toCONTINUOUS
.You must omit this parameter.
spec.deploymentSpec.providerSettings
Type: Object
Conditional
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.
If you want to create or update a cluster, you must specify this setting.
spec.deploymentSpec.providerSettings.providerName
Type: string
Conditional
Cloud service provider on which Atlas provisions the hosts.
AWSAmazon AWSGCPGoogle Cloud PlatformAZUREMicrosoft Azure
spec.deploymentSpec.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.
NoteYou can change this setting to upgrade an
M0
,M2
, orM5
cluster to anM10+
cluster. However, you can't upgrade anM0
,M2
, orM5
cluster to another free or shared cluster. For example, you can't upgrade anM0
cluster to anM5
cluster.
spec.deploymentSpec.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.deploymentSpec.replicationSpecs
. You must set eitherspec.deploymentSpec.providerSettings.regionName
orspec.deploymentSpec.replicationSpecs
.
spec.deploymentSpec.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.deploymentSpec.providerSettings.regionName
orspec.deploymentSpec.replicationSpecs
.When should you use this parameter?
ConditionNecessityValuesYou are deploying Global Clusters.RequiredEach object in the array represents a zone where Atlas deploys your cluster's nodes.You are deploying non-Global replica sets and sharded clusters.OptionalThis array has one object representing where Atlas deploys your cluster's nodes.If you specify this parameter, you must also specify
spec.deploymentSpec.clusterType
andspec.deploymentSpec.replicationSpecs.numShards
.
spec.deploymentSpec.replicationSpecs.numShards
Type: integer
Conditional
Positive integer that specifies the number of shards to deploy for a sharded cluster.
If you use the
spec.deploymentSpec.replicationSpecs
parameter, you must set this parameter.Atlas accepts
1
through50
, inclusive. The default value is1
.- If you specify a value of
1
and you setspec.deploymentSpec.clusterType
toSHARDED
, Atlas deploys a single-shard sharded cluster. If you specify
1
and you setspec.deploymentSpec.clusterType
toREPLICASET
, 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.
TipSee also:
- If you specify a value of
spec.deploymentSpec.replicationSpecs.zoneName
Type: string
Optional
Human-readable label that identifies the zone in a Global Cluster. Provide this value only if you set
spec.deploymentSpec.clusterType
toGEOSHARDED
.
spec.deploymentSpec.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 thespec.deploymentSpec.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 thespec.deploymentSpec.mongoDBMajorVersion
parameter.
spec.processArgs
Type: object
Optional
Object that contains the advanced configuration options for your cluster.
spec.processArgs.defaultReadConcern
Type: string
Optional
String that indicates the default level of acknowledgment requested from MongoDB for read operations set for this cluster.
MongoDB 4.4 clusters default to available.
MongoDB 5.0 clusters default to local /reference/read-concern-local.
spec.processArgs.defaultWriteConcern
Type: string
Optional
String that indicates the default level of acknowledgment requested from MongoDB for write operations set for this cluster.
MongoDB 4.4 clusters default to 1.
MongoDB 5.0 clusters default to majority.
spec.processArgs.failIndexKeyTooLong
Type: boolean
Optional
Flag that indicates whether to fail the operation and return an error when you insert or update documents where all indexed entries exceed 1024 bytes. If you set this to
false
,mongod
writes documents that exceed this limit, but doesn't index them.This option corresponds to the
failIndexKeyTooLong
mongod
parameter.
spec.processArgs.javascriptEnabled
Type: boolean
Optional
Flag that indicates whether the cluster allows execution of operations that perform server-side executions of JavaScript.
- If your cluster runs a MongoDB version less than 4.4, this
option corresponds to modifying the
security.javascriptEnabled
configuration file option for eachmongod
in the cluster. - If your cluster runs MongoDB version 4.4 or greater, this
option corresponds to modifying the
security.javascriptEnabled
configuration file option for eachmongod
andmongos
in the cluster.
- If your cluster runs a MongoDB version less than 4.4, this
option corresponds to modifying the
spec.processArgs.minimumEnabledTlsProtocol
Type: integer
Optional
String that indicates the minimum TLS version that the cluster accepts for incoming connections. Clusters using TLS 1.0 or 1.1 should consider setting TLS 1.2 as the minimum TLS protocol version.
To learn more, see What versions of TLS does Atlas support?.
This option corresponds to the
net.ssl.disabledProtocols
mongod
configuration file option.
spec.processArgs.noTableScan
Type: boolean
Optional
Flag that indicates whether the cluster disables executing any query that requires a collection scan to return results.
This option corresponds to the
notablescan
mongod
parameter.
spec.processArgs.oplogSizeMB
Type: integer
Optional
Number that indicates the storage limit of a cluster's oplog expressed in megabytes. A value of
null
indicates that the cluster uses the default oplog size that Atlas calculates.This option corresponds to the
replication.oplogSizeMB
mongod
configuration file option.
spec.processArgs.sampleRefreshIntervalBIConnector
Type: integer
Optional
Number that indicates the documents per database to sample when gathering schema information.
This parameter corresponds to the sampleSize mongosqld option.
spec.processArgs.sampleSizeBIConnector
Type: integer
Optional
Number that indicates the interval in seconds at which the mongosqld process re-samples data to create its relational schema.
This parameter corresponds to the sampleRefreshIntervalSecs mongosqld option.
spec.projectRef.name
Type: string
Required
Name of the project where the cluster belongs. You must specify an existing
AtlasProject
Custom Resource.
spec.serverlessSpec
Type: array
Conditional
List that contains the serverless instance parameters from the API. For a full list of parameters available, see the Atlas Serverless Instances API.
ImportantYou must specify
spec.deploymentSpec
,spec.advancedDeploymentSpec
, orspec.serverlessSpec
in your configuration.
spec.serverlessSpec.providerSettings
Type: Object
Conditional
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 serverless instance configuration options.
If you want to create or update a serverless instance, you must specify this setting.
spec.serverlessSpec.providerSettings.providerName
Type: string
Conditional
Cloud service provider on which Atlas provisions the host for a serverless instance.
Atlas accepts the following values:
AWSAmazon AWSGCPGoogle Cloud PlatformAZUREMicrosoft Azure
spec.serverlessSpec.providerSettings.regionName
Type: string
Conditional
Physical location of your MongoDB serverless instance. 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:
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.
NoteYou 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. Thespec.scopes
parameter in theAtlasDatabaseUser
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.
The following parameters are deprecated in the Atlas API and Atlas Kubernetes Operator does not support them:
replicationSpec
replicationFactor