When to use

Advantages

• Secure
• Scalable
• Performant
• Supports backups and Point-In-Time recovery
• High availability
• Supports Multi-Document ACID Transactions

Disadvantages

• Separate billing - Even tho Stacktape seamlessly integrates MongoDb to your stacks, you still need to manage your billing separately.

Provider configuration

• You must have a MongoDb Atlas account. To create one, head over to MongoDb Atlas registration page.

• You need to configure:

  • organizationId: The easiest way to get it is logging to MongoDb Atlas console and copying it from the URL. Example: https://cloud.mongodb.com/v2/<<your-organization-id>>#clusters.
  • API credentials (publicKey and privateKey). Stacktape uses those to interact with your MongoDb atlas account. You can get API Keys for you organization by following MongoDB Atlas tutorial. For security reasons, you shouldn't input these directly. The recommended way is using a .env file together with a File directive or using secrets.

providerConfig:
  mongoDbAtlas:
    privateKey: xxxxxxxxxxxxxxxxx42543xx
    publicKey: xxxxxxx
    organizationId: xxxxxxxxxxxxxxxxxcbe63dd

Basic Usage

resources:
  myMongoDbCluster:
    type: mongo-db-atlas-cluster
    properties:
      clusterTier: M2
  myLambda:
    type: function
    properties:
      packageConfig:
        filePath: path/to/my/lambda.ts
      environment:
        - name: MONGODB_CONNECTION_STRING
          value: $Param('myMongoDbCluster', 'AtlasMongoCluster::SrvConnectionString')
      accessControl:
        allowAccessTo:
          - myMongoDbCluster

import { MongoClient } from 'mongodb';

const client = new MongoClient(process.env.MONGODB_CONNECTION_STRING);

const handler = async (event, context) => {
  await client.connect();

  const db = client.db('mydb');

  await db.collection('posts').insertOne({
    title: 'My first post',
    content: 'Hello!'
  });

  const post = await db.collection('posts').findOne({ title: 'My first post' });

  await client.close();
};

Cluster tier

• Configures resources (memory, default storage, IOPS specification) for each data-bearing node in the cluster
• To learn more about cluster tiers, refer to MongoDb Atlas cluster tier docs and list of available cluster tier.

providerConfiguration:
  mongoDbAtlas:
    apiCredentials:
      privateKey: 'xxxxfa523543fxxxx42543xx'
      publicKey: 'xxxxxxx'
    organizationId: 'xxxxxxxxxxx07a593cbe63dd'

resources:
  myMongoCluster:
    type: 'mongo-db-atlas-cluster'
    properties:
      clusterTier: M2

Disk size

• Each cluster tier comes with a default storage size.
• All M10+ clusters autoscale the storage without any manual intervention. You can disable this behavior by configuring autoscaling properties
• All M10+ clusters also provide the ability to customize your storage capacity.

resources:
  myMongoCluster:
    type: mongo-db-atlas-cluster
    properties:
      clusterTier: M2
      diskSizeGB: 60

Auto-scaling

resources:
  myMongoDbCluster:
    type: mongo-db-atlas-cluster
    properties:
      clusterTier: M10
      autoScaling:
        minClusterTier: M10
        maxClusterTier: M30
        disableDiskScaling: true
        disableScaleDown: true

Sharding

resources:
  myMongoCluster:
    type: mongo-db-atlas-cluster
    properties:
      clusterTier: M30
      numShards: 3

Backups

There are different types of snapshots with different retention period and frequency:

• Hourly snapshot: every 6 hours, retained for 2 days
• Daily snapshot: every day, retained for 7 days
• Weekly snapshot: every Saturday, retained for 4 weeks
• Monthly snapshot: last day of the month, retained for 12 months

resources:
  myMongoDbCluster:
    type: mongo-db-atlas-cluster
    properties:
      clusterTier: M10
      enableBackups: true

Point-in-time recovery

resources:
  myMongoDbCluster:
    type: mongo-db-atlas-cluster
    properties:
      clusterTier: M10
      enablePointInTimeRecovery: true

Accessing clusters from workloads

• Following example shows 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
      accessControl:
        allowAccessTo:
          - 'myMongoCluster'
      environment:
        # injecting the connection string as environment variable
        - name: MONGODB_CONNECTION_STRING
          value: $Param('myMongoCluster', 'AtlasMongoCluster::SrvConnectionString')

Accessibility

• Stacktape allows you to restrict the accessibility of your MongoDb cluster to only certain resources or hosts.
• In contrary to other Stacktape database resources, accesibility is set globally in your MongoDb Atlas provider configuration, and not on the resource itself. This means every MongoDb cluster in the given stack must have the same accessibility mode.
• When using shared cluster tiers (M2 and M5), you must set accessibility mode to internet. This is because shared clusters does not support VPC peering. clusters(M10+). and therefore do not allow for same level of network inter-connection. Nevertheless, even when using accessibility set to internet, clusters are still 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

Internet mode

• Default mode. Least restrictive. The database can be accessed from anywhere on the internet.
• Your MongoDb cluster is still protected, because any host or resource trying to access your cluster requires IAM (Identity and Access management) permissions.
• You can grant these permission to your workloads in 2 ways:
  • configuring allowAccessTo on your workload (functions, container workloads, batch jobs)
  • configuring iamRoleStatements on your workload (functions, container workloads, batch jobs)

VPC mode

• The database can be accessed only from resources within the default VPC.
• Any function (provided it has joinDefaultVpc set to true), batch job or container workload within your stack can access the cluster.
• Additionally, IP addresses configured in whitelistedIps can also access the cluster (even from the internet).

resources:
  auroraSlsPostgres:
    type: 'relational-database'
    properties:
      credentials:
        masterUserName: congor
        masterUserPassword: mySecretPass
      accessibility:
        restrictAccess: 'vpc'
        additionalWhitelistedIps:
          - '147.25.33.12'
      engine:
        type: aurora-postgresql
        properties:
          instances:
            - dbInstanceSize: db.t3.medium
          port: 5432

Scoping workloads in VPC mode

• Similar to vpc mode, but even more restrictive. In addition to resource being in the VPC, any host or resource trying to access your cluster must also have the sufficient IAM (Identity and Access management) permissions. You can grant these permission to your workloads in 2 ways:
  • configuring allowAccessTo on your workload (functions, container workloads, batch jobs)
  • configuring iamRoleStatements on your workload (functions, container workloads, batch jobs)
• Additionally, IP addresses configured in whitelistedIps can also access the database (even from the internet).

resources:
  # functionOne does NOT have access to database eventhough it is joined in vpc
  functionOne:
    type: function
    properties:
      packageConfig:
        filePath: 'path/to/my-lambda.ts'
      joinDefaultVpc: true

  # functionTwo does have access to database, because it is scoping the database in allowAccessTo list
  functionTwo:
    type: function
    properties:
      packageConfig:
        filePath: 'path/to/my-lambda-2.ts'
      joinDefaultVpc: true
      accessControl:
        allowAccessTo:
          - 'myPgSql'

  myPgSql:
    type: 'relation-database'
    properties:
      accessibility:
        restrictAccess: 'scoping-workloads-in-vpc'
      credentials:
        masterUserName: commander
        masterUserPassword: mySecretPassword
      engine:
        type: postgres
        properties:
          dbName: appdatabase
          port: 5432
          storage:
            diskSizeGB: 20
          instance:
            dbInstanceSize: db.t3.micro

Whitelisted IPs only mode

• The database can only be accessed from an IP addresses and CIDR blocks listed in the whitelistedIps list.

resources:
  auroraSlsPostgres:
    type: 'relational-database'
    properties:
      credentials:
        masterUserName: congor
        masterUserPassword: mySecretPass
      accessibility:
        restrictAccess: 'whitelisted-ips-only'
        additionalWhitelistedIps:
          - '147.25.33.12'
      engine:
        type: aurora-postgresql
        properties:
          instances:
            - dbInstanceSize: db.t3.medium
          port: 5432

Admin 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: "$Secret('mongo-master-password')"

Business Intelligence Connector (SQL)

• Traditional business intelligence tools are designed to work with tabular, row-and-column data. The MongoDB Connector for BI allows you to query MongoDB data with SQL using tools such as Tableau, Power BI or Excel.

providerConfiguration:
  mongoDbAtlas:
    apiCredentials:
      privateKey: 'xxxxfa523543fxxxx42543xx'
      publicKey: 'xxxxxxx'
    organizationId: 'xxxxxxxxxxx07a593cbe63dd'

resources:
  myMongoCluster:
    type: 'mongo-db-atlas-cluster'
    properties:
      clusterTier: 'M10'
      biConnector:
        enabled: true

Pricing

You are charged for:

• Cluster tier:
  • Starting from $9 / month for M2 shared cluster and scales to $100s for dedicated instances
  • List of tiers and their prices
• Data transfer:
  • For most customers, data transfer fees amount to less than 10% of their bill.
  • Data transfer fees are not assessed on M0, M2, and M5 instances.
  • Same region: $0.01/GB, Cross-region: $0.02/GB, Internet: $0.09/GB
  • For a more detailed overview, refer to MongoDb billing docs

API reference