Skip to content

DocumentDB

This module creates an Amazon DocumentDB cluster with the specified configuration. It allows you to set parameters such as the number of instances, instance class, engine version, and more.

Usage example

module "document_db" {
  source = "s3::https://apro-terraform-modules.s3.eu-west-1.amazonaws.com/SET_VERSION/document_db.zip"

  name_prefix = "uat-core"
  vpc_id      = var.vpc_id
  subnet_ids  = var.database_subnets
}

Serverless Configuration

module "document_db_serverless" {
  source = "s3::https://apro-terraform-modules.s3.eu-west-1.amazonaws.com/SET_VERSION/document_db.zip"

  name_prefix   = "uat-core"
  vpc_id        = var.vpc_id
  subnet_ids    = var.database_subnets
  use_serverless = true

  serverless_scaling_configuration = {
    min_capacity = 0.5
    max_capacity = 5
  }
}

Major version upgrade

Set the new version, both flags and pre_upgrade in the same apply. Leave the flags null on clusters that are not changing major version, so their plans stay empty.

module "document_db" {
  # ...
  engine_version              = "8.0.2"
  allow_major_version_upgrade = true
  apply_immediately           = true

  pre_upgrade = {
    enabled                 = true
    target_version          = "8.0.2"
    attempt                 = 1                                         # raise for a fresh snapshot on a rerun
    app_service_names       = ["librechat"]                             # scaled to 0, then back
    job_rule_names          = ["conversation-history-cleaner-schedule"] # disabled, then enabled again
    hold_rule_name_prefixes = ["uat-core-rds-cluster-"]                 # disabled, left for the operator
  }
}

The apply then runs, in order:

  1. scripts/pre-upgrade.sh: exits early when there is no cluster yet or it is already on the target. It fails when the cluster is not available, MaxCapacity is below 3, maintenance is pending or /docdb/upgrade-window exists in SSM. It then writes that marker, disables the rules, scales the services to 0 and takes the manual snapshot <cluster>-pre-8-0-2-<UTC yyyymmddHHMM>.
  2. A new parameter group for the new family (<prefix>-docdb80-cluster-parameter-group) and the in-place engine change.
  3. scripts/post-upgrade.sh: fails unless the cluster reports the target version, then starts the services and job rules again. The hold rules and the marker stay until the operator deletes them after the index metadata refresh.

The snapshot is not a Terraform resource, so no destroy deletes it. The scripts need the AWS CLI and jq where the apply runs.

Restore from a snapshot

  restore = {
    snapshot_identifier = "uat-core-docdb-cluster-pre-8-0-2-202611061200"
    suffix              = "r1"
    engine_version      = "5.0.0" # default
  }

This creates <prefix>-docdb-cluster-r1 next to the original, with its own parameter group and instance, and points every output at it. The original cluster is left as it is, so keep engine_version describing the original. Removing restore destroys the copy without a final snapshot and points the outputs back at the original.

Inputs

Name Description Type Default Required
allow_major_version_upgrade Allow a change of engine_version to a new major version. Leave null on clusters that are not changing major version, so their plans stay empty bool null no
allowed_security_groups List of Security Groups to be allowed to access the DocumentDB cluster list(string) [] no
apply_immediately Apply cluster changes now instead of in the next maintenance window. Leave null unless a change must not wait bool null no
backup_retention_period Days to keep automated backups (1-35) number 1 no
cluster_parameters List of DB parameters to apply 
list(object({
    apply_method = string
    name         = string
    value        = string
  }))
 [] no
cluster_size Number of instances in the DocumentDB cluster number 1 no
create Create the DocumentDB cluster and associated resources bool true no
db_port Port for the DocumentDB cluster number 27017 no
deletion_protection Prevent the DocumentDB cluster from being deleted until this is set back to false bool false no
enable_performance_insights Enable performance insights for the DocumentDB cluster bool false no
enabled_cloudwatch_logs_exports Log types to export to CloudWatch Logs. Allowed values: audit, profiler list(string) [] no
engine_version Engine version for the DocumentDB cluster string "5.0.0" no
instance_class Instance class for the DocumentDB cluster string "db.t3.medium" no
master_username Master username for the DocumentDB cluster string "root" no
name_prefix Prefix for the resources string n/a yes
pre_upgrade Steps around a major engine upgrade. When enabled, the apply runs scripts/pre-upgrade.sh before the cluster changes
(checks, upgrade-window marker, app and jobs stopped, manual snapshot) and scripts/post-upgrade.sh after it
(engine version confirmed, app and jobs started again). Raise attempt to take a fresh snapshot on a rerun.
app_service_names are ECS service names scaled to 0 in any cluster of the account. job_rule_names are EventBridge
rules disabled during the upgrade and enabled again by the post step. hold_rule_name_prefixes are EventBridge rule
name prefixes disabled during the upgrade and left disabled for the operator to enable once the index refresh is done.		 
object({
    enabled                 = bool
    attempt                 = optional(number, 1)
    target_version          = optional(string, "")
    app_service_names       = optional(list(string), [])
    job_rule_names          = optional(list(string), [])
    hold_rule_name_prefixes = optional(list(string), [])
  })
 
{
  "enabled": false
}
 no
preferred_backup_window Daily UTC window for automated backups, e.g. 04:00-04:30. Must not overlap the maintenance window (mon:05:30-mon:06:00) string "04:00-04:30" no
restore Restore a snapshot to a second cluster named -docdb-cluster- and point every output at it.
The original cluster is left unchanged, so engine_version must keep describing the original cluster.
Removing restore destroys the restored cluster without a final snapshot and points the outputs back at the original.		 
object({
    snapshot_identifier = string
    suffix              = string
    engine_version      = optional(string, "5.0.0")
  })
 null no
serverless_scaling_configuration Serverless scaling configuration for the DocumentDB cluster 
object({
    min_capacity = number
    max_capacity = number
  })
 
{
  "max_capacity": 5,
  "min_capacity": 0.5
}
 no
storage_type Storage type for the DocumentDB cluster string "standard" no
subnet_ids List of subnet IDs where the DocumentDB cluster will be created list(string) n/a yes
use_serverless Use serverless for the DocumentDB cluster bool false no
vpc_id VPC ID where the DocumentDB cluster will be created string n/a yes

Outputs

Name Description
cluster_endpoint The endpoint of the DocumentDB cluster in use
cluster_id The ID of the DocumentDB cluster in use (the restored cluster while restore is set)
cluster_instances List of instances of the DocumentDB cluster in use
cluster_resource_id The Resource ID of the DocumentDB cluster in use
master_user_secret_arn The ARN of the master user secret in AWS Secrets Manager for the cluster in use
master_username The master username of the DocumentDB cluster in use
original_cluster_id The ID of the original DocumentDB cluster, also while restore is set
port The port on which the DocumentDB cluster accepts connections
reader_endpoint The reader endpoint of the DocumentDB cluster in use
security_group_id The security group ID of the DocumentDB cluster