OpenMCF logoOpenMCF

Loading...

AWS DocumentDB

Deploys an AWS DocumentDB cluster (MongoDB-compatible) with automatic subnet group creation, managed security group configuration, configurable cluster instances, and optional parameter group customization. The component provisions both the cluster and its instances in a single resource definition.

What Gets Created

When you deploy an AwsDocumentDb resource, OpenMCF provisions:

  • DocumentDB Cluster — a docdb.Cluster with the docdb engine at the specified version, encryption settings, backup configuration, and CloudWatch log exports
  • Cluster Instances — one docdb.ClusterInstance per instanceCount (default 1), each using the specified instanceClass with auto minor version upgrade support
  • DB Subnet Group — a docdb.SubnetGroup created automatically when subnets are provided and dbSubnetGroup is not set, placing the cluster across the specified subnets
  • Security Group — an ec2.SecurityGroup created when securityGroups or allowedCidrs are provided, with ingress rules on the cluster port from the specified sources and unrestricted egress
  • Security Group Ingress Rules — one ec2.SecurityGroupRule per source security group and one for CIDR blocks, scoped to the configured port (default 27017)
  • Security Group Egress Rule — an ec2.SecurityGroupRule allowing all outbound traffic
  • Cluster Parameter Group — a docdb.ClusterParameterGroup created when clusterParameters are provided, with the family auto-derived from the engine version (e.g., docdb5.0)

Prerequisites

  • AWS credentials configured via environment variables or OpenMCF provider config
  • At least two subnets in different Availability Zones, or an existing DB subnet group name
  • A master password for the cluster administrator
  • A VPC ID if creating a managed security group with securityGroups or allowedCidrs
  • A KMS key ARN if using a customer-managed key for storage encryption

Quick Start

Create a file documentdb.yaml:

apiVersion: aws.openmcf.org/v1
kind: AwsDocumentDb
metadata:
  name: my-docdb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.AwsDocumentDb.my-docdb
spec:
  region: us-east-1
  subnets:
    - subnet-0a1b2c3d4e5f00001
    - subnet-0a1b2c3d4e5f00002
  masterPassword: "change-me-before-deploy"
  skipFinalSnapshot: true

Deploy:

openmcf apply -f documentdb.yaml

This creates a single-instance DocumentDB 5.0 cluster with encrypted storage, a docdbadmin master user, and a db.r6g.large instance in the specified subnets.

Configuration Reference

Required Fields

FieldTypeDescriptionValidation
regionstringThe AWS region where the resource will be created.Must be set.
masterPasswordstringMaster user password for the cluster.Must be set.
subnetsStringValueOrRef[]Subnet IDs for the DB subnet group. Provide at least two in distinct AZs.Minimum 2 items unless dbSubnetGroup is set. Can reference AwsVpc resource via valueFrom.
finalSnapshotIdentifierstringIdentifier for the final snapshot on deletion.Required when skipFinalSnapshot is false (the default).

Optional Fields

FieldTypeDefaultDescription
dbSubnetGroupStringValueOrRef—Name of an existing DB subnet group. When set, subnets is not required.
securityGroupsStringValueOrRef[][]Security group IDs used to create ingress rules on the managed security group. Can reference AwsSecurityGroup resources via valueFrom.
allowedCidrsstring[][]IPv4 CIDRs to allow ingress to the managed security group. Must be unique, valid CIDR notation.
vpcStringValueOrRef—VPC ID for the managed security group. Can reference AwsVpc resource via valueFrom.
engineVersionstring"5.0.0"DocumentDB engine version. Examples: 4.0.0, 5.0.0.
portint3227017TCP port on which the cluster accepts connections. Valid range: 1-65535.
masterUsernamestring"docdbadmin"Master user name for the cluster.
instanceCountint321Number of instances to create in the cluster. Minimum: 1.
instanceClassstring"db.r6g.large"Compute and memory capacity of each instance. Examples: db.r5.large, db.r5.xlarge, db.r6g.large.
storageEncryptedbooltrueEncrypts cluster storage at rest.
kmsKeyStringValueOrRef—KMS key ARN for storage encryption. Can reference AwsKmsKey resource via valueFrom.
backupRetentionPeriodint327Number of days to retain automated backups. Valid range: 1-35.
preferredBackupWindowstring—Daily backup window in UTC. Format: hh24:mi-hh24:mi (e.g., 03:00-04:00).
preferredMaintenanceWindowstring—Weekly maintenance window in UTC. Format: ddd:hh24:mi-ddd:hh24:mi (e.g., sun:05:00-sun:06:00).
deletionProtectionboolfalsePrevents accidental cluster deletion when enabled.
skipFinalSnapshotboolfalseWhen true, no final snapshot is created on cluster deletion. When false, finalSnapshotIdentifier is required.
enabledCloudwatchLogsExportsstring[][]Log types to export to CloudWatch. Valid values: audit, profiler.
applyImmediatelyboolfalseWhen true, modifications are applied immediately instead of during the next maintenance window.
autoMinorVersionUpgradebooltrueEnables automatic minor engine version upgrades for instances.
clusterParameterGroupNamestring—Name of an existing cluster parameter group.
clusterParametersAwsDocumentDbParameter[][]Custom cluster parameters. Each entry has name, value, and optional applyMethod (immediate or pending-reboot).

Examples

Single-Instance Development Cluster

A minimal DocumentDB cluster for development with final snapshot skipped:

apiVersion: aws.openmcf.org/v1
kind: AwsDocumentDb
metadata:
  name: dev-docdb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: dev.AwsDocumentDb.dev-docdb
spec:
  region: us-east-1
  subnets:
    - subnet-private-az1
    - subnet-private-az2
  masterPassword: "dev-password-123"
  skipFinalSnapshot: true
  applyImmediately: true

Multi-Instance Production Cluster

A three-instance cluster with encryption, backup retention, deletion protection, and audit logging:

apiVersion: aws.openmcf.org/v1
kind: AwsDocumentDb
metadata:
  name: prod-docdb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.AwsDocumentDb.prod-docdb
spec:
  region: us-east-1
  subnets:
    - subnet-private-az1
    - subnet-private-az2
    - subnet-private-az3
  masterUsername: prodadmin
  masterPassword: "prod-secure-password"
  instanceCount: 3
  instanceClass: db.r6g.xlarge
  storageEncrypted: true
  kmsKey: arn:aws:kms:us-east-1:123456789012:key/abc-12345
  deletionProtection: true
  backupRetentionPeriod: 14
  preferredBackupWindow: "03:00-04:00"
  preferredMaintenanceWindow: "sun:05:00-sun:06:00"
  skipFinalSnapshot: false
  finalSnapshotIdentifier: prod-docdb-final
  enabledCloudwatchLogsExports:
    - audit
    - profiler

Cluster with Security Group and CIDR Access

A cluster with a managed security group allowing access from a VPC CIDR and specific application security groups:

apiVersion: aws.openmcf.org/v1
kind: AwsDocumentDb
metadata:
  name: secured-docdb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.AwsDocumentDb.secured-docdb
spec:
  region: us-east-1
  subnets:
    - subnet-private-az1
    - subnet-private-az2
  vpc: vpc-0a1b2c3d4e5f00001
  securityGroups:
    - sg-app-servers
  allowedCidrs:
    - "10.0.0.0/16"
  masterPassword: "secure-password-456"
  instanceCount: 2
  storageEncrypted: true
  deletionProtection: true
  skipFinalSnapshot: false
  finalSnapshotIdentifier: secured-docdb-final

Cluster with Custom Parameters

A cluster using DocumentDB 5.0 with custom parameter group settings for profiler and TLS:

apiVersion: aws.openmcf.org/v1
kind: AwsDocumentDb
metadata:
  name: custom-docdb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: staging.AwsDocumentDb.custom-docdb
spec:
  region: us-east-1
  subnets:
    - subnet-private-az1
    - subnet-private-az2
  masterPassword: "custom-password-789"
  engineVersion: "5.0.0"
  instanceCount: 2
  instanceClass: db.r5.large
  clusterParameters:
    - name: profiler
      value: enabled
      applyMethod: immediate
    - name: profiler_threshold_ms
      value: "100"
      applyMethod: immediate
    - name: tls
      value: enabled
      applyMethod: pending-reboot
  enabledCloudwatchLogsExports:
    - profiler
  skipFinalSnapshot: true

Using Foreign Key References

Reference other OpenMCF-managed resources instead of hardcoding IDs:

apiVersion: aws.openmcf.org/v1
kind: AwsDocumentDb
metadata:
  name: ref-docdb
  labels:
    openmcf.org/provisioner: pulumi
    pulumi.openmcf.org/organization: my-org
    pulumi.openmcf.org/project: my-project
    pulumi.openmcf.org/stack.name: prod.AwsDocumentDb.ref-docdb
spec:
  region: us-east-1
  subnets:
    - valueFrom:
        kind: AwsVpc
        name: my-vpc
        field: status.outputs.private_subnets.[0].id
    - valueFrom:
        kind: AwsVpc
        name: my-vpc
        field: status.outputs.private_subnets.[1].id
  vpc:
    valueFrom:
      kind: AwsVpc
      name: my-vpc
      field: status.outputs.vpc_id
  securityGroups:
    - valueFrom:
        kind: AwsSecurityGroup
        name: docdb-sg
        field: status.outputs.security_group_id
  kmsKey:
    valueFrom:
      kind: AwsKmsKey
      name: docdb-key
      field: status.outputs.key_arn
  masterPassword: "ref-password-000"
  instanceCount: 2
  storageEncrypted: true
  skipFinalSnapshot: false
  finalSnapshotIdentifier: ref-docdb-final

Stack Outputs

After deployment, the following outputs are available in status.outputs:

OutputTypeDescription
cluster_endpointstringThe primary writer endpoint for connecting to the DocumentDB cluster
cluster_reader_endpointstringThe reader endpoint for load-balanced read traffic across replica instances
cluster_idstringThe AWS identifier of the DocumentDB cluster
cluster_arnstringThe Amazon Resource Name (ARN) of the DocumentDB cluster
cluster_portint32The port on which the DocumentDB cluster accepts connections
cluster_resource_idstringThe internal AWS resource identifier for the cluster
connection_stringstringA MongoDB-compatible connection string in the format mongodb://user:<password>@endpoint:port/?tls=true&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false
db_subnet_group_namestringThe name of the DB subnet group associated with the cluster (only when created by the module)
security_group_idstringThe security group ID associated with the cluster (only when created by the module)
cluster_parameter_group_namestringThe cluster parameter group name in use (only when created by the module)

Related Components

  • AwsVpc — provides subnets and VPC ID for cluster placement
  • AwsSecurityGroup — controls network access to the cluster
  • AwsKmsKey — provides KMS keys for storage encryption

Next article

AWS DynamoDB

AWS DynamoDB Deploys an AWS DynamoDB table with configurable key schema, billing mode, secondary indexes, streams, encryption, and point-in-time recovery. The component manages all attribute definitions and index configurations through a single declarative manifest. What Gets Created When you deploy an AwsDynamodb resource, OpenMCF provisions: DynamoDB Table — a dynamodb.Table resource with the specified key schema, billing mode, and attribute definitions Global Secondary Indexes — created when...
Read next article
Presets
2 ready-to-deploy configurationsView presets →