Skip to content

Working with DocumentDB in Stelvio

This guide explains how to create Amazon DocumentDB clusters with Stelvio. You'll learn how to size a cluster, put it in a VPC, link it to Lambda, and connect with the MongoDB drivers.

DocumentDB is a MongoDB-compatible database that runs inside a VPC. Use it when you need Mongo-compatible queries and always-on capacity. For key-value data billed per request, start with DynamoTable.

By default, DocumentDb creates a private, TLS-required, encrypted cluster on engine 8.0 with one serverless instance and an AWS-managed master password. The cluster sits in the Vpc's isolated subnets and accepts traffic from that Vpc's shared app security group.

DocumentDB costs money

Instances bill while they run, not per request. A default one-instance cluster starts at about $30/month and can reach $240/month at its default ceiling, see Cost. Linked functions also need NAT, which has its own cost.

Creating a DocumentDB cluster

from stelvio.aws.document_db import DocumentDb
from stelvio.aws.vpc import Vpc

vpc = Vpc("main")
db = DocumentDb("todos", vpc=vpc)

That's a one-instance cluster on engine 8.0. You need a Vpc with at least two availability zones. The default Vpc already has that. Vpc(..., az=1) raises ValueError when you construct DocumentDb.

Serverless capacity

Serverless is the default: each instance scales between 0.5 and 4 DocumentDB capacity units (DCUs). instance="serverless" and instance="db.serverless" select it explicitly; instance=None also uses this default.

db = DocumentDb("todos", vpc=vpc)
db = DocumentDb("todos", vpc=vpc, max_capacity=16)
db = DocumentDb("todos", vpc=vpc, replicas=1, min_capacity=1, max_capacity=8)

Supply either or both capacity bounds; omitted bounds use 0.5 and 4. min_capacity must be between 0.5 and 256; max_capacity must be between 1 and 256. Both accept finite numbers in increments of 0.5, and the effective minimum must not exceed the maximum. Equal bounds hold capacity constant. For example, min_capacity=8 alone is invalid because the default maximum is 4. Capacity arguments with a provisioned instance raise ValueError at construction.

Capacity changes can require instance restarts

The cluster receives the new range immediately, but instances need rebooting after any max_capacity change, or when min_capacity crosses between 1 or less and greater than 1. The new limits do not take effect on those instances until rebooted. Stelvio does not perform these reboots during deployment. Reboot readers first, waiting for each to become available, then the writer: aws docdb reboot-db-instance --db-instance-identifier <id>. With replicas, fail over to a rebooted reader before rebooting the old writer to reduce writer unavailability. See AWS's restart guidance.

The range applies to each instance: replicas=1 creates two instances, so a maximum of 8 DCUs allows up to 16 DCUs together. Serverless retains active capacity at its minimum; it does not scale to zero or bill per request. Storage, I/O, Secrets Manager, and network charges still apply. See AWS serverless scaling guidance.

Both engine 5.0 and 8.0 support serverless. Engine 5.0 requires a recent patch, and availability varies by region. Check AWS requirements before deployment. Stelvio does not query AWS availability during construction.

Switching to a provisioned instance leaves the old capacity range on the cluster: AWS cannot remove it, and it has no effect on provisioned instances.

Instance class capacity

Capacity is per zone, and it changes

AWS does not offer every instance class in every availability zone, and which zones have room changes. If creating the instance fails, set a different instance and deploy again, or try later. The zones named in the error are only right for that moment. Changing az on the Vpc is not the fix.

The name is the DocumentDb component name, not a MongoDB database name. Stelvio does not create databases or collections; they appear when you first write. The name must start with a lowercase letter and contain only lowercase letters, digits, and single hyphens, with no trailing hyphen. Invalid names raise ValueError when you construct DocumentDb. See Customization to override the AWS identifiers.

The first deploy takes 10 to 20 minutes

AWS provisions the cluster and every instance before the deploy finishes, and destroying it is slow too. A stuck-looking deploy is usually just AWS.

Destroying the cluster deletes your data

stlv destroy drops the cluster with no final snapshot. For anything you care about, set deletion_protection=True and keep a snapshot through Customization.

Elastic clusters, global clusters, and snapshot restore are not supported. stlv dev access to the cluster is not supported yet.

Configuration

from stelvio.aws.document_db import DocumentDb, DocumentDbConfig
from stelvio.aws.vpc import Vpc

vpc = Vpc("main")

# Keyword arguments
db = DocumentDb("todos", vpc=vpc, replicas=1)

# Or using DocumentDbConfig
db = DocumentDb("todos", config=DocumentDbConfig(vpc=vpc, replicas=1))

You can also pass a dict via config=. Don't mix kwargs and config= in the same call.

Available configuration options:

Option Default Description
vpc (required) Existing Vpc. The cluster uses its isolated subnets.
replicas 0 Read replicas beyond the primary (0 to 15); total instances = 1 + replicas.
instance None Provisioned instance size, with or without the db. prefix ("t3.medium" or "db.t3.medium"), or "serverless" / "db.serverless". None uses serverless. See Serverless capacity and Instance class capacity.
min_capacity None Minimum per-instance serverless DCUs; omitted uses 0.5.
max_capacity None Maximum per-instance serverless DCUs; omitted uses 4.
engine "8.0" Engine version: "8.0" (default) or "5.0".
deletion_protection False Block cluster deletion until you flip this off and redeploy.
backup_retention_period 7 Automated backup retention in days (1–35).
secret_rotation 7 Rotate the AWS-managed master password after this many days (1–1000), or set to False to disable automatic rotation until you set a day count again.

Replicas

replicas=0 is a single writer. replicas=1 (up to 15) adds replicas in the same cluster, not a second cluster. Failover to a replica needs more than one instance.

The writer endpoint is host. Read-only traffic can use reader_host, which load-balances across replicas. With one instance, reader_host still exists but points at that same instance.

AWS defaults promotion_tier to 1, so a serverless replica stays at the writer's capacity. Set customize={"instance": {"promotion_tier": 2}} to let replicas scale independently and idle at the minimum. See AWS's promotion-tier guidance.

Engine version

Default is "8.0". Pass engine="5.0" to opt in to 5.0.

Changing engine upgrades the live cluster

Changing engine="5.0" to engine="8.0" is an in-place major version upgrade with downtime. You must meet the AWS upgrade prerequisites. You cannot downgrade by changing engine back.

  1. With serverless, set max_capacity to 3 or more and deploy before changing engine. With a burstable provisioned class, resize to instance="r6g.large" in a separate deploy first.
  2. Wait until the capacity or resize has applied. Instance class changes apply immediately by default and restart the instance; customize can defer them. Follow the reboot guidance when changing a range.
  3. Change engine with customize={"cluster": {"allow_major_version_upgrade": True, "apply_immediately": True}} so the cluster upgrade runs during deployment rather than waiting for maintenance.

Networking

The cluster lives in the Vpc's isolated subnets. Creating DocumentDb opens TCP 27017 from that Vpc's app security group. Functions that join the same Vpc with the default app group (Function(vpc=vpc)) can reach the cluster. See Lambda Functions in VPC.

With your own security_groups on VpcAttachment, the cluster still admits only the app security group. Add an ingress rule on db.resources.security_group yourself:

from pulumi_aws.vpc import SecurityGroupIngressRule

SecurityGroupIngressRule(
    "todos-from-my-sg",
    security_group_id=db.resources.security_group.id,
    referenced_security_group_id=my_sg.id,
    ip_protocol="tcp",
    from_port=27017,
    to_port=27017,
)

Linking

Put the Function in the same Vpc and link it. HttpApi routes take the same vpc= and links= options.

The Function must use the cluster's Vpc

Missing vpc= or a different Vpc raises ValueError. Linking injects connection properties and IAM; it is not networking.

from stelvio.aws.document_db import DocumentDb
from stelvio.aws.function import Function
from stelvio.aws.vpc import Vpc

vpc = Vpc("main", nat="managed")
db = DocumentDb("todos", vpc=vpc)
Function(
    "api",
    handler="functions/todos.handler",
    requirements=["pymongo"],
    vpc=vpc,
    links=[db],
)

connection_uri has no password, so the Function reads it from Secrets Manager and needs a route there: nat="managed" for private subnets, or a Secrets Manager interface VPC endpoint for isolated subnets (Stelvio does not create the endpoint). The cluster itself stays in isolated subnets.

For a cluster named todos, the linked function receives these properties:

stlv_resources property Description
Resources.todos.host Cluster writer endpoint
Resources.todos.reader_host Cluster reader endpoint
Resources.todos.port Port (default 27017)
Resources.todos.username Master username (default stelvio)
Resources.todos.secret_arn Secrets Manager ARN for the AWS-managed password
Resources.todos.replica_set Replica set name (rs0)
Resources.todos.ca_file Path to Amazon's CA bundle (see below)
Resources.todos.connection_uri Writer mongodb:// URI without username or password (tls, CA file, replica set, retryWrites=false). Safe to use with rotation.

ca_file and the CA bundle

On stlv deploy, stlv diff and stlv dev, linking downloads Amazon's global RDS CA bundle and caches it at .stelvio/aws/documentdb/global-bundle.pem for 24 hours. Deploy packages that bundle into each linked Function as stlv_docdb_ca.pem, and ca_file (and the URI's tlsCAFile) use that package-relative path. In stlv dev, the same properties use the absolute cache path so the local handler can open the file without staging. This needs network access to truststore.pki.rds.amazonaws.com. If the download fails and there is no cached copy younger than 24 hours, the command fails.

Linked Lambda functions receive:

  • secretsmanager:GetSecretValue on the AWS-managed master-user secret

DocumentDB authenticates with username and password. There are no DocumentDB data-plane IAM actions.

Using the cluster from Lambda

Fetch the password and create the MongoClient at module level, so warm invocations reuse both:

import json

import boto3
from pymongo import MongoClient
from pymongo.errors import OperationFailure
from stlv_resources import Resources

AUTHENTICATION_FAILED = 18

secrets = boto3.client("secretsmanager")


def connect() -> MongoClient:
    secret = secrets.get_secret_value(SecretId=Resources.todos.secret_arn)
    return MongoClient(
        Resources.todos.connection_uri,
        username=Resources.todos.username,
        password=json.loads(secret["SecretString"])["password"],
    )


client = connect()


def handler(event, context):
    global client
    try:
        item = client.app.items.find_one({"_id": event["id"]})
    except OperationFailure as error:
        if error.code != AUTHENTICATION_FAILED:
            raise
        refreshed = connect()
        client.close()
        client = refreshed
        item = client.app.items.find_one({"_id": event["id"]})
    return {"item": item}

After a password rotation, new connections from a warm function fail with AuthenticationFailed (code 18). The handler then fetches the current password and opens a new client; only after that succeeds does it close the stale client and swap it in. Only the read is retried. Don't replay a write automatically. You can't tell whether it went through. Never log the secret or a connection string containing the password.

host, port, ca_file, and replica_set are still injected if you need the pieces.

DocumentDB is not full MongoDB

TLS is required. The URI already sets replicaSet=rs0 and retryWrites=false. DocumentDB does not support retryable writes. APIs and defaults that assume MongoDB Atlas or a self-hosted replica set may not apply.

Password rotation

DocumentDB's AWS-managed master password rotates every seven days by default. See AWS-managed password rotation. Set secret_rotation to another number of days to change that schedule. Set secret_rotation=False to disable automatic rotation. Then the password never changes on its own. A leaked one stays valid until you rotate it by hand in Secrets Manager.

Keep the AWS-managed password

Leave manage_master_user_password enabled (the default). Disabling it through customize means the default link cannot resolve a secret ARN, and Stelvio creates no rotation schedule, so secret_rotation has no effect. Stelvio rejects deferred values such as Pulumi Output. If you encrypt the secret with your own key (master_user_secret_kms_key_id), linked functions also need kms:Decrypt on that key. Add it with db.link().add_permissions(...).

Cost

Stelvio uses Standard storage (pay-per-use I/O). Prices below are on-demand in us-east-1; check AWS DocumentDB pricing and the AWS Pricing Calculator for your region.

Compute estimates for Standard storage in us-east-1, using 730 hours/month, before storage, I/O, backup, networking, and CPU credits:

Compute per instance Hourly Monthly (730 hours)
Default serverless idle floor (0.5 DCU) $0.0411 $30.00
Default serverless ceiling (4 DCUs) $0.3288 $240.02
Fixed t3.medium (instance="t3.medium") $0.078 $56.94

The idle floor also determines available resources: at 0.5 DCU, each instance has approximately 1 GiB of memory, 250 total connections, 39 active connections, 6 cursors, and 12 open transactions. These limits depend on the instance's current capacity; see AWS's serverless instance limits. Choose a higher minimum if the limits at the floor are insufficient for your workload. When min_capacity is 1 DCU or less, the caps on cursors, open transactions, and active connections stay lower at every capacity. See AWS's minimum-capacity guidance.

Serverless costs $0.0822 per DCU-hour. A replica is a full instance billed like the primary; multiply compute estimates by 1 + replicas. Actual serverless compute varies with usage within the range. See AWS's serverless pricing examples.

Additional charges include storage ($0.10/GB-month), I/O ($0.20 per million requests), and Secrets Manager storage for the managed password (about $0.40/month).

The Function needs NAT or a Secrets Manager VPC endpoint to read the password. See VPC cost.

Customization

The DocumentDb component supports the customize parameter to override underlying Pulumi resource properties. For an overview of how customization works, see the Customization guide.

By default the AWS identifiers start with {app}-{env}-{name}- (instances include the instance number before the trailing hyphen), and the Pulumi AWS provider appends a unique suffix. You can override cluster_identifier, cluster_identifier_prefix, identifier, or identifier_prefix through customize. The identifier and prefix forms are mutually exclusive for each AWS resource.

Resource Keys

Resource Key Pulumi Args Type Description
cluster ClusterArgs The DocumentDB cluster
instance ClusterInstanceArgs Every cluster instance. Use a callable for per-instance values.
subnet_group SubnetGroupArgs Subnet group (isolated subnets)
parameter_group ClusterParameterGroupArgs Cluster parameter group
security_group SecurityGroupArgs Cluster security group
secret_rotation SecretRotationArgs AWS-managed master-secret rotation schedule

Example

To keep a cluster whose data must survive accidental deletion:

from stelvio.aws.document_db import DocumentDb
from stelvio.aws.vpc import Vpc

vpc = Vpc("main")
db = DocumentDb(
    "todos",
    vpc=vpc,
    deletion_protection=True,
    customize={
        "cluster": {
            "skip_final_snapshot": False,
            "final_snapshot_identifier": "myapp-prod-todos-final-20260918",
        },
    },
)

Choose a snapshot identifier that is not already in use in your account and region. To destroy this cluster, first set deletion_protection=False and deploy, keeping the snapshot settings. Then destroy it. The final snapshot stays available for restoration and incurs storage charges until deleted. Stelvio cannot restore snapshots. Do that in the AWS console or CLI.

Customizing parameters replaces the whole list

parameter_group.parameters replaces Stelvio's list rather than appending. TLS stays on either way because AWS enables it by default and Stelvio's default list sets tls=enabled. Add a tls entry only to change it. Intentionally disabling TLS also requires a corresponding link-property override for connection_uri, which always emits the default TLS URI.

Do not set inline security-group rules through customize

DocumentDB already manages a standalone ingress rule on the cluster security group. Mixing inline ingress / egress with standalone rules can overwrite rules or produce perpetual deployment differences. Add a separate SecurityGroupIngressRule that references db.resources.security_group instead. That grants network access only. The client still needs credentials.

Replacing vpc_security_group_ids drops the generated group

Stelvio always creates a cluster security group and attaches app-SG ingress to that generated group. A dict override of cluster.vpc_security_group_ids replaces the list, so the generated group is no longer on the cluster. Append with a callable if you need extra groups and want to keep generated ingress; replace the list only when you own ingress on the groups you supply.

Next Steps