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.
- With serverless, set
max_capacityto 3 or more and deploy before changingengine. With a burstable provisioned class, resize toinstance="r6g.large"in a separate deploy first. - 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.
- Change
enginewithcustomize={"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.
Link Properties
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.
Link Permissions
Linked Lambda functions receive:
secretsmanager:GetSecretValueon 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
- Working with VPC: Isolated subnets, NAT, and Lambda in a VPC
- Working with Lambda Functions: Functions that connect to the cluster
- Working with HTTP APIs: Routes that pass
vpc=andlinks=[db] - Linking: How Stelvio injects connection properties and IAM
- Customization: Override Pulumi resource properties
- Tags: Tag your resources