Skip to content

Module Structure

terraform-aws-arc-document-db

Latest Release Last Updated Terraform GitHub Actions

Quality gate

Overview

The SourceFuse AWS Reference Architecture (ARC) Terraform module for managing AWS DocumentDB offers a streamlined solution for provisioning, configuring, and managing DocumentDB clusters within the Amazon Web Services (AWS) environment. This Terraform module is specifically designed to simplify the deployment and maintenance of DocumentDB clusters with enterprise-grade features including:

  • Multi-AZ Deployment: High availability across multiple availability zones
  • Global Clusters: Cross-region replication for disaster recovery
  • Security: Encryption at rest and in transit, VPC security groups, and Secrets Manager integration
  • Monitoring: CloudWatch logs, metrics, and event subscriptions
  • Backup & Recovery: Automated backups with configurable retention periods
  • Parameter Groups: Custom database parameter configurations

For more information about this repository and its usage, please see Terraform AWS ARC Document DB Usage Guide.

Usage

To see full examples, check out the examples folder.

Examples

Basic Cluster

This example demonstrates a simple DocumentDB cluster setup with basic configuration:

  • Single-AZ deployment
  • Basic security group configuration
  • Standard backup settings
  • Minimal configuration for development/testing
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
module "documentdb_cluster" {
  source = "sourcefuse/arc-document-db/aws"

   cluster_identifier = var.cluster_identifier
  master_username    = var.master_username

  instance_count = var.instance_count
  instance_class = var.instance_class

  subnet_config = {
    subnet_ids = data.aws_subnets.private.ids
  }
  vpc_id = data.aws_vpc.vpc.id

  security_group_data = local.security_group_data

  backup_retention_period      = var.backup_retention_period
  preferred_backup_window      = var.preferred_backup_window
  preferred_maintenance_window = var.preferred_maintenance_window
  skip_final_snapshot          = var.skip_final_snapshot

  storage_encrypted   = var.storage_encrypted
  deletion_protection = var.deletion_protection

  tags = module.tags.tags
}

Multi-AZ Cluster

This example shows a production-ready multi-AZ DocumentDB cluster with advanced features:

  • Multiple instances across availability zones
  • Secrets Manager integration for credential management
  • KMS encryption with custom keys
  • CloudWatch monitoring and alarms
  • Custom parameter groups
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
module "documentdb_cluster" {
  source = "sourcefuse/arc-document-db/aws"

cluster_identifier = var.cluster_identifier
  master_username    = var.master_username

  instance_count = var.instance_count
  instance_class = var.instance_class

  subnet_config = {
    subnet_ids = data.aws_subnets.private.ids
  }
  vpc_id = data.aws_vpc.main.id

  security_group_data = local.security_group_data

  # Enable Secrets Manager integration
  secret_config = {
    create                  = true
    name                    = null # Use auto-generated name with random suffix
    recovery_window_in_days = var.secret_recovery_window_in_days
  }

  # Enable KMS encryption
  kms_config = {
    create_key  = true
    description = var.kms_key_description
  }

  # Enhanced backup configuration
  backup_retention_period      = var.backup_retention_period
  preferred_backup_window      = var.preferred_backup_window
  preferred_maintenance_window = var.preferred_maintenance_window

  storage_encrypted   = true
  deletion_protection = var.deletion_protection
  skip_final_snapshot = true

  # Enable CloudWatch logs
  enabled_cloudwatch_logs_exports = var.enabled_cloudwatch_logs_exports

  # Parameter group configuration
  parameter_group_config = {
    create     = true
    family     = var.db_cluster_parameter_group_family
    parameters = var.db_cluster_parameter_group_parameters
  }

  tags = module.tags.tags
}

Global Cluster Multi-Region

This example demonstrates a global DocumentDB cluster spanning multiple AWS regions:

  • Primary cluster in us-east-1
  • Secondary cluster in us-east-2
  • Cross-region replication
  • Region-specific configurations
  • Disaster recovery setup
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
# Primary cluster in us-east-1
module "primary_cluster" {
  source = "sourcefuse/arc-document-db/aws"

  providers = {
    aws = aws.primary
  }

  cluster_identifier = var.primary_cluster_identifier
  master_username    = var.master_username

  instance_count = var.primary_instance_count
  instance_class = var.primary_instance_class

  subnet_config = {
    subnet_ids = data.aws_subnets.primary_private.ids
  }
  vpc_id = data.aws_vpc.primary.id
  # Use security group rules
  security_group_data = local.primary_security_group_data

  # Global cluster configuration
  create_global_cluster     = true
  global_cluster_identifier = var.global_cluster_identifier

  # Security features
  secret_config = {
    create = true
  }
  kms_config = {
    create_key = true
  }
  storage_encrypted   = true
  deletion_protection = var.deletion_protection

  # Monitoring
  enabled_cloudwatch_logs_exports = var.enabled_cloudwatch_logs_exports

  # Enhanced backup
  backup_retention_period = var.backup_retention_period
  skip_final_snapshot     = var.skip_final_snapshot

  tags = module.tags.tags
}

# Secondary cluster in us-west-2
module "secondary_cluster" {
  source = "../../"

  providers = {
    aws = aws.secondary
  }

  cluster_identifier = var.secondary_cluster_identifier

  instance_count = var.secondary_instance_count
  instance_class = var.secondary_instance_class

  subnet_config = {
    subnet_ids = data.aws_subnets.secondary_private.ids
  }
  vpc_id = data.aws_vpc.secondary.id

  # Use security group rules
  security_group_data = local.secondary_security_group_data

  # Global cluster configuration
  existing_global_cluster_identifier = module.primary_cluster.global_cluster_identifier
  is_secondary_cluster               = true

  # Security features (inherit from global cluster)
  kms_config = {
    create_key = true
  }
  storage_encrypted   = true
  deletion_protection = var.deletion_protection
  skip_final_snapshot = var.skip_final_snapshot

  # Monitoring
  enabled_cloudwatch_logs_exports = var.enabled_cloudwatch_logs_exports
  tags                            = module.tags.tags

  depends_on = [module.primary_cluster]
}

Features

Core Features

  • DocumentDB Cluster Management: Complete lifecycle management of DocumentDB clusters
  • Instance Configuration: Flexible instance count and class configuration
  • Network Security: VPC integration with security group management
  • Backup & Recovery: Automated backup with configurable retention and windows

Advanced Features

  • Global Clusters: Cross-region replication for disaster recovery
  • Secrets Manager Integration: Secure credential management
  • KMS Encryption: Custom encryption key management
  • Parameter Groups: Custom database parameter configurations
  • CloudWatch Integration: Comprehensive monitoring and logging
  • Event Subscriptions: SNS notifications for database events

Security Features

  • Encryption: At-rest and in-transit encryption
  • Network Isolation: VPC and security group integration
  • Access Control: IAM integration and credential management
  • Audit Logging: Comprehensive audit trail

Configuration Options

Consolidated Variables

This module uses consolidated configuration objects to reduce complexity and improve usability:

kms_config

1
2
3
4
5
kms_config = {
  create_key  = true
  key_id      = null
  description = "DocumentDB encryption key"
}

subnet_config

1
2
3
4
5
subnet_config = {
  group_name   = null
  create_group = true
  subnet_ids   = ["subnet-12345", "subnet-67890"]
}

secret_config

1
2
3
4
5
6
secret_config = {
  create                  = true
  name                    = null
  description             = "DocumentDB credentials"
  recovery_window_in_days = 7
}

parameter_group_config

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
parameter_group_config = {
  create = true
  family = "docdb4.0"
  parameters = [
    {
      name  = "tls"
      value = "enabled"
    }
  ]
}

alarm_config

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
alarm_config = {
  create_alarms = true
  cpu = {
    threshold          = 80
    evaluation_periods = 2
    period             = 300
  }
  connections = {
    threshold          = 80
    evaluation_periods = 2
    period             = 300
  }
  alarm_actions = ["arn:aws:sns:us-east-1:123456789012:alerts"]
}

event_subscription_config

1
2
3
4
5
6
7
8
event_subscription_config = {
  create        = true
  name          = "docdb-events"
  sns_topic_arn = "arn:aws:sns:us-east-1:123456789012:docdb-events"
  enabled       = true
  source_type   = "db-cluster"
  event_categories = ["backup", "failure", "maintenance"]
}

Requirements

Name Version
terraform ~> 1.3, < 2.0.0
aws >= 5.0, < 7.0
random >= 3.1

Providers

Name Version
aws 5.100.0
random 3.7.2

Modules

Name Source Version
kms sourcefuse/arc-kms/aws 0.0.1
security_group sourcefuse/arc-security-group/aws 0.0.2

Resources

Name Type
aws_cloudwatch_log_group.audit resource
aws_cloudwatch_log_group.profiler resource
aws_cloudwatch_metric_alarm.cpu_utilization resource
aws_cloudwatch_metric_alarm.database_connections resource
aws_docdb_cluster.this resource
aws_docdb_cluster_instance.this resource
aws_docdb_cluster_parameter_group.this resource
aws_docdb_event_subscription.this resource
aws_docdb_global_cluster.this resource
aws_docdb_subnet_group.this resource
aws_iam_role.enhanced_monitoring resource
aws_iam_role_policy_attachment.additional resource
aws_iam_role_policy_attachment.enhanced_monitoring resource
aws_secretsmanager_secret.this resource
aws_secretsmanager_secret_version.this resource
random_id.secret_suffix resource
random_password.master resource
random_string.suffix resource
aws_caller_identity.current data source

Inputs

Name Description Type Default Required
additional_policy_arns List of additional IAM policy ARNs to attach to the Lambda role list(string) [] no
alarm_config CloudWatch alarm configuration for DocumentDB monitoring 
object({
    create_alarms = optional(bool, false)
    cpu = optional(object({
      threshold          = optional(number, 80)
      evaluation_periods = optional(number, 2)
      period             = optional(number, 300)
    }), {})
    connections = optional(object({
      threshold          = optional(number, 80)
      evaluation_periods = optional(number, 2)
      period             = optional(number, 300)
    }), {})
    alarm_actions = optional(list(string), [])
    ok_actions    = optional(list(string), [])
  })
 {} no
allow_major_version_upgrade Enable to allow major engine version upgrades when changing engine versions bool false no
apply_immediately Specifies whether any cluster modifications are applied immediately, or during the next maintenance window bool true no
auto_minor_version_upgrade Indicates that minor engine upgrades will be applied automatically to the DB cluster during the maintenance window bool true no
availability_zones A list of EC2 Availability Zones for the DB cluster storage where DB cluster instances can be created list(string) null no
backup_retention_period The days to retain backups for number 7 no
ca_cert_identifier The identifier of the CA certificate for the DB instance string null no
cloudwatch_log_kms_key_id The ARN of the KMS Key to use when encrypting log data string null no
cloudwatch_log_retention_in_days Specifies the number of days you want to retain log events in the specified log group number 7 no
cluster_identifier The cluster identifier. If omitted, Terraform will assign a random, unique identifier string null no
cluster_identifier_prefix Creates a unique cluster identifier beginning with the specified prefix string null no
copy_tags_to_snapshot Copy all Cluster tags to snapshots bool false no
create_global_cluster Whether to create a DocumentDB Global Cluster bool false no
create_monitoring_role Whether to create an IAM role for enhanced monitoring bool false no
create_security_group Whether to create a security group for the DocumentDB cluster bool true no
database_name The name of the database to create when the DB cluster is created string null no
db_cluster_parameter_group_description Description for the DB cluster parameter group string "DocumentDB cluster parameter group" no
db_parameter_group_name Name of the DB parameter group to associate with instances string null no
db_subnet_group_description Description for the DB subnet group string "DocumentDB subnet group" no
deletion_protection A value that indicates whether the DB cluster has deletion protection enabled bool false no
enabled_cloudwatch_logs_exports List of log types to export to cloudwatch list(string) [] no
engine The name of the database engine to be used for this DB cluster string "docdb" no
engine_version The database engine version string "4.0.0" no
environment Environment name string "dev" no
event_subscription_config Configuration for RDS event subscription 
object({
    create           = optional(bool, false)
    name             = optional(string, null)
    sns_topic_arn    = optional(string, null)
    enabled          = optional(bool, true)
    source_type      = optional(string, "db-cluster")
    source_ids       = optional(list(string), [])
    event_categories = optional(list(string), [])
  })
 {} no
existing_global_cluster_identifier The identifier of an existing global cluster to join string null no
final_snapshot_identifier The name of your final DB snapshot when this DB cluster is deleted string null no
force_overwrite_replica_secret Accepts boolean value to specify whether to overwrite a secret with the same name in the destination Region bool false no
global_cluster_identifier The global cluster identifier string null no
instance_availability_zones List of availability zones for instances. If not specified, instances will be distributed across available AZs list(string) null no
instance_class The instance class to use string "db.t3.medium" no
instance_count Number of instances in the cluster number 1 no
instance_identifier_prefix Creates a unique identifier beginning with the specified prefix string null no
instance_promotion_tiers Map of instance index to promotion tier (0-15). Lower number = higher priority for promotion map(number) {} no
is_secondary_cluster Whether this cluster is a secondary cluster in a global cluster bool false no
kms_config KMS configuration for DocumentDB encryption 
object({
    key_id      = optional(string, null)
    create_key  = optional(bool, false)
    description = optional(string, "DocumentDB cluster encryption key")
  })
 {} no
manage_master_user_password Set to true to allow RDS to manage the master user password in Secrets Manager bool true no
master_password Password for the master DB user. If not provided and create_secret is true, will be auto-generated string null no
master_username Username for the master DB user string "docdbadmin" no
monitoring_interval The interval for collecting enhanced monitoring metrics. Valid values: 0, 1, 5, 10, 15, 30, 60 number 0 no
name_prefix Name prefix for resources string "docdb" no
parameter_group_config DB cluster parameter group configuration 
object({
    name   = optional(string, null)
    create = optional(bool, false)
    family = optional(string, "docdb4.0")
    parameters = optional(list(object({
      name  = string
      value = string
    })), [])
  })
 {} no
port The port on which the DB accepts connections number 27017 no
preferred_backup_window The daily time range during which automated backups are created string "07:00-09:00" no
preferred_maintenance_window The weekly time range during which system maintenance can occur string "sun:05:00-sun:06:00" no
replica_kms_key_id KMS key ID for replica secret encryption string null no
replica_region Region for replicating the secret string null no
secret_config Secrets Manager configuration for DocumentDB credentials 
object({
    create                  = optional(bool, false)
    name                    = optional(string, null)
    description             = optional(string, "DocumentDB cluster master credentials")
    recovery_window_in_days = optional(number, 7)
  })
 {} no
secret_version_stages Specifies text data that you want to encrypt and store in this version of the secret list(string) null no
security_group_data (optional) Security Group data 
object({
    security_group_ids_to_attach = optional(list(string), [])
    create                       = optional(bool, true)
    description                  = optional(string, null)
    ingress_rules = optional(list(object({
      description              = optional(string, null)
      cidr_block               = optional(string, null)
      source_security_group_id = optional(string, null)
      from_port                = number
      ip_protocol              = string
      to_port                  = string
      self                     = optional(bool, false)
    })), [])
    egress_rules = optional(list(object({
      description                   = optional(string, null)
      cidr_block                    = optional(string, null)
      destination_security_group_id = optional(string, null)
      from_port                     = number
      ip_protocol                   = string
      to_port                       = string
      prefix_list_id                = optional(string, null)
    })), [])
  })
 
{
  "create": false
}
 no
security_group_ids List of security group IDs to associate with the DocumentDB cluster list(string) [] no
skip_final_snapshot Determines whether a final DB snapshot is created before the DB cluster is deleted bool false no
snapshot_identifier Specifies whether or not to create this cluster from a snapshot string null no
source_db_cluster_identifier The identifier of the source cluster for global cluster string null no
storage_encrypted Specifies whether the DB cluster is encrypted bool true no
subnet_config Subnet configuration for DocumentDB cluster 
object({
    group_name   = optional(string, null)
    create_group = optional(bool, true)
    subnet_ids   = optional(list(string), [])
  })
 {} no
tags A map of tags to assign to the resource map(string) {} no
treat_missing_data Sets how this alarm is to handle missing data points string "missing" no
vpc_id VPC ID where the security group will be created string null no

Outputs

Name Description
cloudwatch_alarm_connection_arns List of ARNs for database connection CloudWatch alarms
cloudwatch_alarm_cpu_arns List of ARNs for CPU utilization CloudWatch alarms
cloudwatch_log_group_audit_arn The ARN of the CloudWatch log group for audit logs
cloudwatch_log_group_audit_name The name of the CloudWatch log group for audit logs
cloudwatch_log_group_profiler_arn The ARN of the CloudWatch log group for profiler logs
cloudwatch_log_group_profiler_name The name of the CloudWatch log group for profiler logs
cluster_arn Amazon Resource Name (ARN) of the cluster
cluster_availability_zones The availability zones of the cluster
cluster_backup_retention_period The backup retention period
cluster_database_name The name of the database
cluster_deletion_protection Specifies whether the cluster has deletion protection enabled
cluster_enabled_cloudwatch_logs_exports List of log types to export to cloudwatch
cluster_endpoint The DNS address of the DocumentDB instance
cluster_engine The database engine
cluster_engine_version The database engine version
cluster_hosted_zone_id The Route53 Hosted Zone ID of the endpoint
cluster_id The DocumentDB cluster identifier
cluster_identifier The DocumentDB cluster identifier
cluster_kms_key_id The ARN for the KMS encryption key
cluster_members List of DocumentDB Instances that are a part of this cluster
cluster_port The database port
cluster_preferred_backup_window The daily time range during which the backups happen
cluster_preferred_maintenance_window The weekly time range during which system maintenance can occur
cluster_reader_endpoint A read-only endpoint for the DocumentDB cluster, automatically load-balanced across replicas
cluster_resource_id The DocumentDB Cluster Resource ID
cluster_storage_encrypted Specifies whether the DB cluster is encrypted
cluster_vpc_security_group_ids List of VPC security groups associated to the cluster
db_cluster_parameter_group_arn The ARN of the DB cluster parameter group
db_cluster_parameter_group_name The name of the DB cluster parameter group
db_parameter_group_arn The ARN of the DB parameter group
db_parameter_group_name The name of the DB parameter group
db_subnet_group_arn The ARN of the DB subnet group
db_subnet_group_name The name of the DB subnet group
enhanced_monitoring_role_arn The ARN of the enhanced monitoring IAM role
enhanced_monitoring_role_name The name of the enhanced monitoring IAM role
event_subscription_arn The ARN of the DocumentDB event subscription
event_subscription_id The ID of the DocumentDB event subscription
global_cluster_arn Amazon Resource Name (ARN) of the global cluster
global_cluster_id The DocumentDB global cluster identifier
global_cluster_identifier The DocumentDB global cluster identifier
global_cluster_members List of DocumentDB Clusters that are part of this global cluster
global_cluster_resource_id The DocumentDB Global Cluster Resource ID
instance_arns List of DocumentDB instance ARNs
instance_availability_zones List of availability zones for the instances
instance_ca_cert_identifiers List of CA certificate identifiers for the instances
instance_classes List of DocumentDB instance classes
instance_endpoints List of DocumentDB instance endpoints
instance_engine_versions List of database engine versions for the instances
instance_engines List of database engines for the instances
instance_identifiers List of DocumentDB instance identifiers
instance_ids List of DocumentDB instance identifiers
instance_performance_insights_kms_key_ids List of KMS key identifiers for Performance Insights encryption
instance_ports List of database ports for the instances
instance_promotion_tiers List of promotion tiers for the instances
instance_writers List indicating which instances are writers
kms_key_arn The Amazon Resource Name (ARN) of the key
kms_key_id The globally unique identifier for the key
master_username The master username for the DB cluster
secret_arn The ARN of the secret
secret_id The ID of the secret
security_group_arn The ARN of the security group created for the DocumentDB cluster
security_group_id The ID of the security group created for the DocumentDB cluster

Versioning

This project uses a 3-digit Semantic Versioning scheme.

Contributing

Bug Reports & Feature Requests

Please use the issue tracker to report any bugs or file feature requests.

License

Apache 2 Licensed. See LICENSE for full details.