/amazon-documentdb

DocumentDB — Connection and Cluster Setup

Workflow for reaching a working DocumentDB connection. Two entry points:

• A. New cluster — no cluster yet, create with serverless defaults
• B. Existing cluster — can't connect, need driver config, or want TLS/VPC diagnosis

Ask one question to route: "Do you already have a DocumentDB cluster, or are we starting from scratch?"

What to ask upfront

• New cluster: cluster id, master password (or use Secrets Manager), region, where the app runs (same VPC / local dev / different VPC)
• Existing cluster: cluster id, region, the error message
• Programming language (Python, Node, Java, Go, C#, Ruby)

Recommend serverless on 8.0 (db.serverless) — auto-scales, costs up to 90% less when idle, and supports all 8.0 features ($vectorSearch, Zstd compression). Suggest a fixed instance class only for sustained 24/7 high throughput. Never recommend Elastic Clusters (a separate sharding product lacking transactions, change streams, and many operators).

Workflow — Entry Point A (new cluster)

Step 1: Launch everything in parallel

DocumentDB instance creation takes ~7 minutes. Do not create resources sequentially — run these three tracks at the same time.

Track A — DocumentDB cluster + instance. You MUST run these exact commands — serverless is mandatory unless the user said "provisioned" or "instance-based":

aws docdb create-db-cluster \
  --db-cluster-identifier <cluster_id> \
  --engine docdb \
  --engine-version 8.0.0 \
  --serverless-v2-scaling-configuration MinCapacity=1,MaxCapacity=16 \
  --master-username adminuser \
  --master-user-password '<password>' \
  --region <region>

aws docdb create-db-instance \
  --db-instance-identifier <cluster_id>-instance \
  --db-instance-class db.serverless \
  --engine docdb \
  --db-cluster-identifier <cluster_id> \
  --region <region>

Do NOT substitute db.t3.medium, db.r5.large, or any other instance class — db.serverless is the only correct value here.

For production, prefer --manage-master-user-password over the inline --master-user-password shown above — DocumentDB generates the password into Secrets Manager with rotation (the two flags are mutually exclusive). Retrieve it via aws secretsmanager get-secret-value --secret-id <MasterUserSecret-arn> when building the connection string in Step 3.

Track B — Access from outside the VPC (local dev or admin access — pick one option):

Option 1 (preferred): SSM Session Manager port forwarding — no SSH key, IAM-controlled.

Prerequisites: SSM Agent on EC2 (pre-installed on AL2023), IAM role with AmazonSSMManagedInstanceCore, Session Manager plugin installed locally.

INSTANCE_ID=$(aws ec2 run-instances \
  --image-id resolve:ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-default-x86_64 \
  --instance-type t3.micro --iam-instance-profile Name=SSMInstanceProfile \
  --subnet-id <any-subnet-in-docdb-vpc> --no-associate-public-ip-address \
  --region <region> --query 'Instances[0].InstanceId' --output text)

aws ssm start-session --target $INSTANCE_ID \
  --document-name AWS-StartPortForwardingSessionToRemoteHost \
  --parameters '{"host":["<docdb-cluster-endpoint>"],"portNumber":["27017"],"localPortNumber":["27017"]}' \
  --region <region>

Add inbound TCP 27017 on DocumentDB SG from the bastion's SG.

Option 2 (fallback): SSH bastion + tunnel — use when SSM is not available.

Launch a t3.micro in a public subnet with a key pair and SG allowing SSH from your IP only. Add inbound TCP 27017 on DocumentDB SG from the bastion SG.

Track C — Download TLS cert: curl -s https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem -o global-bundle.pem

Step 2: Poll the DocumentDB instance until available

Don't use aws docdb wait — not present in all CLI versions. Use a polling loop:

for i in $(seq 1 20); do
  STATUS=$(aws docdb describe-db-instances --db-instance-identifier <id>-instance \
    --query 'DBInstances[0].DBInstanceStatus' --output text --region <region>)
  [ "$STATUS" = "available" ] && break
  sleep 30
done

Step 3: Build the connection string

All five parameters are required — DocumentDB rejects or behaves incorrectly without them:

mongodb://adminuser:<password>@<endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false

The string above uses the primary (master) user, which is always password-based.

IAM authentication is also supported for application / non-admin users (not the primary user) on cluster version 5.0+. It is password-less — connections use short-lived STS tokens — suiting Lambda/ECS/EC2 workloads that run with an IAM role. Trade-offs: requires instance-based 5.0+, a MONGODB-AWS-capable driver (pip install 'pymongo[aws]'; Node.js >= 6.13.1), and an STS dependency at connect time (watch STS throttling at high connection rates).

Create an IAM-backed user as the master user in the $external database, then connect with authSource=$external&authMechanism=MONGODB-AWS (no credentials in the URI — the driver fetches them from the attached role):

use $external;
db.createUser({ user: "arn:aws:iam::<account-id>:role/<app-role>",
  mechanisms: ["MONGODB-AWS"], roles: [ { role: "readWrite", db: "<app-db>" } ] });

mongodb://<endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false&authSource=%24external&authMechanism=MONGODB-AWS

Step 4: Connect from outside the VPC (local dev only)

If using SSM (Option 1): the aws ssm start-session command in Track B already establishes the port-forward tunnel. No separate SSH step needed. Connect directly:

mongosh --tls --tlsAllowInvalidHostnames --tlsCAFile global-bundle.pem \
  --host 127.0.0.1 --port 27017 --username adminuser --password '<pw>' \
  --eval "db.runCommand({ping:1})"

If using SSH bastion (Option 2): wait 15 seconds after the bastion is running (sshd needs to start), then:

ssh -i <key-pair-name>.pem \
  -L 27017:<cluster-endpoint>:27017 \
  -o StrictHostKeyChecking=no -o ServerAliveInterval=30 \
  ec2-user@<bastion-public-ip> -N -f

Then connect the same way — mongosh needs --tlsAllowInvalidHostnames because the hostname resolves to 127.0.0.1, not the cluster endpoint.

Expected: { ok: 1 }.

Step 5: Return a ready-to-use driver snippet

Read references/connection-drivers.md and substitute the actual endpoint, password, and database name.

Workflow — Entry Point B (existing cluster)

Diagnostic commands (always run first)

aws docdb describe-db-clusters --db-cluster-identifier <name> \
  --query 'DBClusters[*].[DBClusterIdentifier,Endpoint,Port]' --region <region>

aws docdb describe-db-instances --db-instance-identifier <instance-name> \
  --query 'DBInstances[*].DBSubnetGroup.VpcId' --region <region>

nc -zv <cluster-endpoint> 27017

Match the error and apply the fix

VPC checklist

• EC2/Lambda and DocumentDB in the same region and same VPC (or VPC peering)
• DocumentDB SG inbound TCP 27017 from the app SG (preferred) or from a specific IP
• Never open to 0.0.0.0/0

aws ec2 authorize-security-group-ingress \
  --group-id <docdb-sg> --protocol tcp --port 27017 \
  --source-group <app-sg> --region <region>

TLS verification

Check the tls parameter in the cluster's parameter group (enabled default, disabled, or fips-140-3).

Serverless constraints

• Supported on engine 5.0.0 and 8.0.0 — not 3.6 or 4.0
• Supported with Global Clusters
• DCU scaling in 0.5 increments via MinCapacity / MaxCapacity
• Verify regional availability: aws docdb describe-orderable-db-instance-options --region <r> --db-instance-class db.serverless --engine docdb

For driver snippets (Python, Node, Java, Go, C#, Ruby, mongosh), see references/connection-drivers.md.