Warning

Reference only — no longer maintained

This source code has not been updated since 2021. Due to changes in AWS services, Terraform providers, APIs, and runtime dependencies, it may no longer work as originally intended. The project is preserved solely as a reference and should be carefully reviewed, updated, and tested before being used in any environment.

AWS consulting

Need help designing, reviewing, or improving your AWS infrastructure? I offer AWS consulting services. Contact me through this form to discuss your project.

---

docdb-autoscaling

An auto-scaling solution for Amazon DocumentDB.

This project is an AWS Lambda written in Python and deployed with Terraform that easily implements auto-scaling functionality for Amazon DocumentDB.

Why?

Amazon DocumentDB (with MongoDB compatibility) supports up to 15 read replicas, but by default AWS does not provide an easy way to set up an auto-scaling policy for them.

The solution

Follow below how the system works:

Resources created by Terraform:

• CloudWatch alarm ─ will watch a CloudWatch metric from the Document Database cluster (e.g. CPUUtilization).
• Simple Notification Service (SNS) ─ will be triggered by CloudWatch when any metrics are matched.
• AWS Lambda ─ will be triggered by the SNS and will be responsible for adding or removing read replicas in the Document Database cluster.

Terraform module

You can deploy the function with Terraform using the following syntax:

module "docdb-autoscaling-prod" {
  source             = "github.com/theuves/docdb-autoscaling"
  cluster_identifier = "my-prod-cluster"
  name               = "docdb-autoscaling-prod"
  min_capacity       = 3
  max_capacity       = 6

  scaling_policy = [
    {
      metric_name = "CPUUtilization"
      target      = 80
      statistic   = "Average"
      cooldown    = 300
    }
  ]
}

Deployment

To create the resources:

terraform init
terraform plan
terraform apply

To destroy:

terraform destroy

Input variables

Variable	Description	Type	Default value
cluster_identifier	DocumentDB cluster identifier.	string	n/a
name	Resources name.	string	"docdb-autoscaling"
min_capacity	The minimum capacity.	number	0
max_capacity	The maximum capacity.	number	15
scaling_policy	The auto-scaling policy.	see here	see here

scaling_policy

Type:

list(object({
  metric_name = string
  target      = number
  statistic   = string
  cooldown    = number
}))

Default value:

[
  {
    metric_name = "CPUUtilization"
    target      = 60
    statistic   = "Average"
    cooldown    = 120
  }
]

Options:

• metric_name ─ Amazon DocumentDB metric name (see the list).
• target ─ The value against which the specified statistic is compared.
• statistic ─ The statistic to apply to the alarm's associated metric (supported values: SampleCount, Average, Sum, Minimum, Maximum).
• cooldown ─ The cooldown period between scaling actions.

Output values

n/a

License

MIT