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, then enabled again
  }
}

The apply then runs, in order:

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 or /docdb/upgrade-window exists in SSM. It then writes that marker, disables the rules and scales the services to 0. Next it applies every pending maintenance action on the cluster and its instances now, in rounds because a cluster patch can reveal instance patches, and waits until none remain and everything is available (up to 90 minutes, MAINTENANCE_WAIT_SECONDS). AWS requires this before a major version upgrade, and these actions reboot the cluster. Last, it takes the manual snapshot <cluster>-pre-8-0-2-<UTC yyyymmddHHMM>.
A new parameter group for the new family (<prefix>-docdb80-cluster-parameter-group) and the in-place engine change.
scripts/post-upgrade.sh: fails unless the cluster reports the target version, then starts the services, job rules and hold rules again and deletes the marker, so deploys resume without a manual step. On a wrong version it changes nothing, and the marker keeps every deploy away. The index metadata refresh may still be running after the apply; don't reboot the writer until the cluster's events report it complete.

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, pending maintenance applied, manual snapshot) and scripts/post-upgrade.sh after it (engine version confirmed, app and rules started again, marker deleted). Raise attempt to take a fresh snapshot on a rerun. app_service_names are ECS service names scaled to 0; each must exist in some ECS cluster of the account. job_rule_names are EventBridge rules and hold_rule_name_prefixes EventBridge rule name prefixes, all disabled during the upgrade and enabled again by the post step.	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