Ensure DocumentDB Cluster Has Multi-AZ Enabled

Overview

This check verifies that your Amazon DocumentDB clusters are deployed across multiple Availability Zones (AZs). Multi-AZ deployment means your cluster has at least one replica instance in a different AZ from your primary instance, providing automatic failover capability.

Risk

Without Multi-AZ deployment, your DocumentDB cluster depends entirely on a single Availability Zone. If that AZ experiences an outage, hardware failure, or requires maintenance, your database becomes unavailable. This can lead to:

• Application downtime and service interruptions
• Failed database connections and transaction errors
• Longer recovery times (higher RTO)
• Potential SLA violations

With Multi-AZ enabled, DocumentDB automatically fails over to a replica in another AZ, typically completing within 30 seconds.

Remediation Steps

Prerequisites

You need:

• Access to the AWS Console with permissions to modify DocumentDB clusters
• The name of the DocumentDB cluster you want to protect

Required IAM permissions

To add a replica instance, you need these IAM permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "rds:CreateDBInstance",
        "rds:DescribeDBClusters",
        "rds:DescribeDBInstances",
        "rds:AddTagsToResource"
      ],
      "Resource": "*"
    }
  ]
}

Note: DocumentDB uses the rds: action prefix for IAM permissions.

AWS Console Method

1. Sign in to the AWS Console and go to Amazon DocumentDB
2. In the left navigation, click Clusters
3. Click on the cluster name that needs Multi-AZ
4. Look at the Instances section to see which AZs currently have instances
5. Click the Actions dropdown, then select Add instance
6. Configure the new replica:
   • Instance class: Choose the same class as your primary (e.g., db.r5.large)
   • Availability Zone: Select a different AZ from your existing instances
   • Promotion tier: Set to 1 or higher (lower numbers have higher failover priority)
7. Click Create to add the replica instance

The new instance will take several minutes to create. Once available, your cluster is Multi-AZ enabled.

AWS CLI (optional)

First, check your cluster's current configuration:

aws docdb describe-db-clusters \
  --db-cluster-identifier my-docdb-cluster \
  --region us-east-1 \
  --query 'DBClusters[0].{ClusterID:DBClusterIdentifier,AZs:AvailabilityZones,Instances:DBClusterMembers}'

Add a replica instance in a different Availability Zone:

aws docdb create-db-instance \
  --db-instance-identifier my-docdb-cluster-replica \
  --db-cluster-identifier my-docdb-cluster \
  --db-instance-class db.r5.large \
  --engine docdb \
  --availability-zone us-east-1b \
  --promotion-tier 1 \
  --region us-east-1

Replace:

• my-docdb-cluster-replica with your desired replica instance name
• my-docdb-cluster with your cluster identifier
• db.r5.large with your preferred instance class
• us-east-1b with an AZ different from your primary instance

CloudFormation (optional)

Add a replica instance to an existing DocumentDB cluster:

AWSTemplateFormatVersion: '2010-09-09'
Description: Add a replica instance to an existing DocumentDB cluster for Multi-AZ

Parameters:
  ClusterIdentifier:
    Type: String
    Description: The identifier of the existing DocumentDB cluster

  InstanceClass:
    Type: String
    Description: The instance class for the replica
    Default: db.r5.large
    AllowedValues:
      - db.r5.large
      - db.r5.xlarge
      - db.r5.2xlarge
      - db.r5.4xlarge
      - db.r6g.large
      - db.r6g.xlarge
      - db.r6g.2xlarge

  AvailabilityZone:
    Type: AWS::EC2::AvailabilityZone::Name
    Description: The Availability Zone for the replica (should differ from primary)

Resources:
  DocumentDBReplicaInstance:
    Type: AWS::DocDB::DBInstance
    Properties:
      DBClusterIdentifier: !Ref ClusterIdentifier
      DBInstanceClass: !Ref InstanceClass
      AvailabilityZone: !Ref AvailabilityZone
      AutoMinorVersionUpgrade: true
      Tags:
        - Key: Name
          Value: !Sub '${ClusterIdentifier}-replica'

Outputs:
  ReplicaInstanceId:
    Description: The identifier of the new replica instance
    Value: !Ref DocumentDBReplicaInstance

Deploy with:

aws cloudformation create-stack \
  --stack-name docdb-multiaz-replica \
  --template-body file://template.yaml \
  --parameters \
    ParameterKey=ClusterIdentifier,ParameterValue=my-docdb-cluster \
    ParameterKey=InstanceClass,ParameterValue=db.r5.large \
    ParameterKey=AvailabilityZone,ParameterValue=us-east-1b \
  --region us-east-1

Terraform (optional)

Add a replica instance to enable Multi-AZ for an existing cluster:

variable "cluster_identifier" {
  description = "The identifier of the existing DocumentDB cluster"
  type        = string
  default     = "my-docdb-cluster"
}

variable "instance_class" {
  description = "The instance class for the replica"
  type        = string
  default     = "db.r5.large"
}

variable "availability_zone" {
  description = "The Availability Zone for the replica instance"
  type        = string
  default     = "us-east-1b"
}

# Add a replica instance to enable Multi-AZ
resource "aws_docdb_cluster_instance" "replica" {
  identifier         = "${var.cluster_identifier}-replica"
  cluster_identifier = var.cluster_identifier
  instance_class     = var.instance_class
  availability_zone  = var.availability_zone
  engine             = "docdb"

  tags = {
    Name = "${var.cluster_identifier}-replica"
  }
}

For a complete Multi-AZ cluster from scratch:

resource "aws_docdb_cluster" "main" {
  cluster_identifier      = "my-docdb-cluster"
  engine                  = "docdb"
  master_username         = "docdbadmin"
  master_password         = var.master_password
  backup_retention_period = 7
  preferred_backup_window = "07:00-09:00"
  skip_final_snapshot     = false

  availability_zones = [
    "us-east-1a",
    "us-east-1b",
    "us-east-1c"
  ]
}

# Primary instance
resource "aws_docdb_cluster_instance" "primary" {
  identifier         = "my-docdb-cluster-primary"
  cluster_identifier = aws_docdb_cluster.main.id
  instance_class     = "db.r5.large"
  availability_zone  = "us-east-1a"
  promotion_tier     = 0
}

# Replica instance for Multi-AZ
resource "aws_docdb_cluster_instance" "replica" {
  identifier         = "my-docdb-cluster-replica"
  cluster_identifier = aws_docdb_cluster.main.id
  instance_class     = "db.r5.large"
  availability_zone  = "us-east-1b"
  promotion_tier     = 1
}

Verification

After adding the replica, verify Multi-AZ is enabled:

1. In the AWS Console, go to Amazon DocumentDB > Clusters
2. Click on your cluster name
3. Check the Instances section - you should see instances in at least two different Availability Zones
4. The cluster status should show as Available

CLI verification

aws docdb describe-db-clusters \
  --db-cluster-identifier my-docdb-cluster \
  --region us-east-1 \
  --query 'DBClusters[0].DBClusterMembers[*].{Instance:DBInstanceIdentifier,IsWriter:IsClusterWriter}'

You should see at least two instances - one writer (primary) and one or more readers (replicas).

To verify they are in different AZs:

aws docdb describe-db-instances \
  --region us-east-1 \
  --query 'DBInstances[?DBClusterIdentifier==`my-docdb-cluster`].{Instance:DBInstanceIdentifier,AZ:AvailabilityZone,Status:DBInstanceStatus}'

Additional Resources

• Amazon DocumentDB High Availability and Replication
• Understanding Amazon DocumentDB Failover
• Amazon DocumentDB Instance Classes
• Best Practices for Amazon DocumentDB

Notes

• Cost consideration: Adding replica instances increases costs. Each instance is billed separately based on its instance class.
• Instance class matching: For predictable failover performance, use the same instance class for replicas as your primary.
• Promotion tiers: Set promotion tiers (0-15) to control failover priority. Lower numbers are promoted first. The primary typically has tier 0.
• Minimum instances for HA: For true high availability, consider at least 3 instances across 3 AZs.
• Connection strings: Update your application's connection string to use the cluster endpoint (not the instance endpoint) so it automatically routes to the current primary after failover.
• Testing failover: Periodically test failover using the failover-db-cluster CLI command to ensure your application handles it correctly.