Close
logoStacktape docs



Mongo Db Atlas Clusters

Overview

By using mongo-db-atlas-cluster resource you are able to deploy MongoDB clusters managed by cloud database service provider Atlas MongoDB. Moreover, with Stacktape, you can seamlessly integrate Atlas MongoDB clusters with the rest of your stack resources, while keeping your database isolated and secured. The self-healing clusters are made up of distributed database instances to ensure there is no single point of failure.

When using mongo-db-atlas-cluster resources in your stack, a new Atlas MongoDB project is created for each different stage deployed. This ensures absolute isolation between multiple stages (copies) of your stack.

Usage

Setting Atlas provider

When using mongo-db-atlas-cluster resources, you need to setup mongoDbAtlas section in providerConfiguration section of you template file.

MongoDbAtlasProviderConfig  API reference
Required
apiCredentials
specifies api credentials used to interact with Atlas MongoDB provider
Required
organizationId
Type: string
specifies id of your Atlas MongoDB organization
accessibility
connectivity settings of the Atlas MongoDB project
MongoDbAtlasApiCredentials  API reference
Parent API reference: MongoDbAtlasProviderConfig
Required
publicKey
Type: string
Atlas MongoDB public api key
Required
privateKey
Type: string
Atlas MongoDB private api key

providerConfiguration:
mongoDbAtlas:
# as Atlas MongoDB is a third service provider it is neccessary to provide API keys with sufficient rights
apiCredentials:
privateKey: 'xxxxfa523543fxxxx42543xx'
publicKey: 'xxxxxxx'
# organization id, identifying your Atlas MongoDb organization
organizationId: 'xxxxxxxxxxx07a593cbe63dd'

MongoDbAtlasCluster  API reference
Required
type
Type: string "mongo-db-atlas-cluster"
Type of the resource
properties.diskSizeGB
Type: number

Size of the disk

Required
properties.clusterTier
Type: string ENUM

Configures resources (memory, default storage, IOPS specification) for each data-bearing node in the cluster

Default: REPLICASET
properties.clusterType
Type: string ENUM

Type of the cluster (default is REPLICASET)

properties.numShards
Type: number

Amount of shards for the cluster

properties.replicationSpecs

Amount of nodes that make-up you cluster

properties.backup

Configures backups for the cluster

properties.biConnector

Configures BI (Business Intelligence) connector

properties.autoScaling

Configures scaling behavior of the cluster

properties.credentials

Creates and configures MongoDb Atlas user atlasAdmin with specified credentials

Cluster tier

The following template shows mongo-db-atlas-cluster.

providerConfiguration:
mongoDbAtlas:
apiCredentials:
privateKey: 'xxxxfa523543fxxxx42543xx'
publicKey: 'xxxxxxx'
organizationId: 'xxxxxxxxxxx07a593cbe63dd'
resources:
myMongoCluster:
Type: 'mongo-db-atlas-cluster'
Properties:
clusterTier: M2

Accessibility

MongoDbAtlasAccessibility  API reference
Parent API reference: MongoDbAtlasProviderConfig
Required
restrictAccess
Type: string ENUM
Specifies the mongo cluster network restriction mode
additionalWhitelistedIps
Type: Array of string
list of ip addresses or ip ranges(in CIDR form)

providerConfiguration:
mongoDbAtlas:
apiCredentials:
privateKey: 'xxxxfa523543fxxxx42543xx'
publicKey: 'xxxxxxx'
# "accessibility" option is shared between "mongo-db-atlas-cluster" resources of your stack
accessibility:
restrictAccess: 'vpc'
organizationId: 'xxxxxxxxxxx07a593cbe63dd'
resources:
myMongoCluster:
Type: 'mongo-db-atlas-cluster'
Properties:
clusterTier: M10

When using Atlas MongoDB shared tier clusters (M2 and M5) restrictAccess property should be set to"internet" (default option). This is because shared clusters are not using same level of network isolation as dedicated clusters(M10+). and therefore do not allow for same level of network inter-connection.

Nevertheless, even when using restrictAccess set to internet, clusters are still tightly protected as Stacktape utilizes strict identity access management between your stack workloads (functions, container-workloads, batch-jobs) and atlas mongo clusters. See sectionAccessing clusters from workloads

Accessing clusters from workloads

Following example demonstrates how to grant a lambda function myMongoFunction a permission to access your mongo-db-atlas-cluster myMongoCluster.

By listing myMongoCluster in allowAccessTo of myMongoFunction, function is injected with credentials needed for accessing the cluster.

providerConfiguration:
mongoDbAtlas:
apiCredentials:
privateKey: 'xxxxfa523543fxxxx42543xx'
publicKey: 'xxxxxxx'
organizationId: 'xxxxxxxxxxx07a593cbe63dd'
resources:
myMongoCluster:
Type: 'mongo-db-atlas-cluster'
Properties:
clusterTier: M2
myMongoFunction:
Type: function
Properties:
packageConfig:
filePath: 'lambdas/mongo-lambda.ts'
memory: 512
# by allowing access to cluster, lambda receives permissions for reading and writing into cluster databases
allowAccessTo:
- 'myMongoCluster'
environment:
# injecting the connection string as environment variable
MONGODB_CONNECTION_STRING: "$GetParam('myMongoCluster', 'AtlasMongoCluster::SrvConnectionString')"

Code example

The following example shows how we connect to myMongoCluster from the myMongoFunction using the popular mongoose library.

When using auth mechanism MONGODB_AWS, credentials for authentication are automatically loaded from the function's environment variables. As mentioned above, function (or any other type of workload) receives the permissions by having the myMongoCluster listed in its allowAccessTo list.

import mongoose from 'mongoose';
let connection;
export default async (event, context) => {
// lambda handler code
// we are using the injected connection string to create connection
// ...
connection =
connection ||
(await mongoose.connect(process.env.MONGODB_CONNECTION_STRING, {
authMechanism: 'MONGODB-AWS',
authSource: '$external',
useNewUrlParser: true,
useUnifiedTopology: true,
dbName: 'my-test-database'
}));
// do whatever you wish with the connection
// rest of the lambda code
// ...
};

Disk size

You can set disk size using the parameter diskSizeGB.

providerConfiguration:
mongoDbAtlas:
apiCredentials:
privateKey: 'xxxxfa523543fxxxx42543xx'
publicKey: 'xxxxxxx'
organizationId: 'xxxxxxxxxxx07a593cbe63dd'
resources:
myMongoCluster:
Type: 'mongo-db-atlas-cluster'
Properties:
clusterTier: M2
diskSizeGB: 60

Auto-scaling

  • You can configure your Atlas cluster to automatically scale its cluster tier, storage capacity, or both in response based on the cluster usage.
  • To help control the costs, you can select a range of cluster tiers to which your cluster can scale.
  • Cluster is scaled up (to the next tier), if one the following criteria is met:
    • Average CPU Utilization has exceeded 75% for the past hour
    • Memory Utilization has exceeded 75% for the past hour
  • Cluster is scaled down (to the lower tier), if both of the following criteria are met:
    • The average CPU Utilization and Memory Utilization over the past 24 hours is below 50%
    • The cluster has not been scaled down (manually or automatically) in the past 24 hours
MongoAutoScaling  API reference
Parent API reference: MongoDbAtlasCluster
minClusterTier
Type: string ENUM

Minimum cluster tier to scale DOWN to

maxClusterTier
Type: string ENUM

Maximum cluster tier to scale UP to

disableDiskScaling
Type: boolean

Disables disk size scaling

disableScaleDown
Type: boolean

Disables scale down of cluster tier

providerConfiguration:
mongoDbAtlas:
apiCredentials:
privateKey: 'xxxxfa523543fxxxx42543xx'
publicKey: 'xxxxxxx'
organizationId: 'xxxxxxxxxxx07a593cbe63dd'
resources:
myMongoCluster:
Type: 'mongo-db-atlas-cluster'
Properties:
clusterTier: 'M10'
autoScaling:
# OPTIONAL minimal instance size, cluster can scale DOWN to
minInstanceSize: 'M10'
# OPTIONAL maximal instance size, cluster can scale UP to
maxInstanceSize: 'M30'
# OPTIONAL set disableDiskScaling to "true" to avoid automatic disk scaling when disk is close to full
disableDiskScaling: true # default is false, i.e diskScaling is ENABLED
# OPTIONAL by disabling scale down you are ensuring
# that the cluster can only scale UP to bigger instance but not back DOWN to smaller one
disableScaleDown: true # default is false, i.e scaleDown is ENABLED

Credentials

Optionally, you can create a master database user with atlasAdmin priviliges over your cluster.

  • Accessing the cluster from your workloads (batch-jobs, container-workloads or functions), is possible even without creating this user, by scoping them using allowAccessTo.
  • Creating an admin user can be useful for performing administrative tasks, or when connecting to the cluster from a local machine.
MongoMasterCredentials  API reference
Parent API reference: MongoDbAtlasCluster
Required
masterUserName
Type: string

Name of the atlasAdmin user

Required
masterUserPassword
Type: string

Password of the atlasAdmin user

providerConfiguration:
mongoDbAtlas:
apiCredentials:
privateKey: 'xxxxfa523543fxxxx42543xx'
publicKey: 'xxxxxxx'
organizationId: 'xxxxxxxxxxx07a593cbe63dd'
resources:
myMongoCluster:
Type: 'mongo-db-atlas-cluster'
Properties:
clusterTier: M2
credentials:
masterUserName: 'my-master-user'
masterUserPassword: "$GetSecret('mongo-master-password')"

Backup

Atlas Cloud Backups provide localized backup storage using the native snapshot functionality of the underlying AWS provider.

MongoCloudBackup  API reference
Parent API reference: MongoDbAtlasCluster
Required
enabled
Type: boolean

Enables automatic backups

continuousCloudBackup
Type: boolean

Enables continuous cloud backup

providerConfiguration:
mongoDbAtlas:
apiCredentials:
privateKey: 'xxxxfa523543fxxxx42543xx'
publicKey: 'xxxxxxx'
organizationId: 'xxxxxxxxxxx07a593cbe63dd'
resources:
myMongoCluster:
Type: 'mongo-db-atlas-cluster'
Properties:
instanceSize: 'M10'
backup:
# enable cloud backup
enabled: true
# enable continous cloud backup
continousCloudBackup: true

Backup property is not available for shared tier clusters (tier M2 and M5). However, Atlas takes daily snapshots of your M2 and M5 clusters which you can restore to cluster tiers M2 or greater.

Bi Connector

The BI Connector is a powerful tool that provides users SQL-based access to their MongoDB databases.

MongoBiConnector  API reference
Parent API reference: MongoDbAtlasCluster
readPreference
Type: string ENUM

Configures the type of node to which the BI connector will connect

Required
enabled
Type: boolean

Enables BI connector

providerConfiguration:
mongoDbAtlas:
apiCredentials:
privateKey: 'xxxxfa523543fxxxx42543xx'
publicKey: 'xxxxxxx'
organizationId: 'xxxxxxxxxxx07a593cbe63dd'
resources:
myMongoCluster:
Type: 'mongo-db-atlas-cluster'
Properties:
clusterTier: 'M10'
biConnector:
enabled: true