Setup Guide

Prerequisites¶

Infrastructure requirements¶

Before deploying DocumentDB in multi-region mode, ensure you have:

Multiple Kubernetes clusters: 2 or more Kubernetes clusters in different regions
Network connectivity: Kubernetes clusters can communicate over private networking or the internet
Storage: CSI-compatible storage class in each Kubernetes cluster with snapshot support
Load balancing: LoadBalancer or Ingress capability for external access (optional)

Required components¶

Install these components on all Kubernetes clusters:

1. cert-manager¶

Required for TLS certificate management between Kubernetes clusters.

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set installCRDs=true

Verify installation:

kubectl get pods -n cert-manager

See Get Started for detailed cert-manager setup.

2. DocumentDB operator¶

Install the operator on each Kubernetes cluster.

# Choose a release version (see https://github.com/documentdb/documentdb-kubernetes-operator/releases)
DOCUMENTDB_VERSION=0.3.0

helm install documentdb-operator oci://ghcr.io/documentdb/documentdb-operator \
  --version ${DOCUMENTDB_VERSION} \
  --namespace documentdb-operator \
  --create-namespace

Verify installation:

kubectl get pods -n documentdb-operator

3. Kubernetes cluster identity ConfigMap¶

Each Kubernetes cluster in a multi-region deployment must identify itself with a unique Kubernetes cluster name. Create a ConfigMap on each Kubernetes cluster:

# Run on each Kubernetes cluster and replace with your actual cluster name.
CLUSTER_NAME="member-eastus2-cluster"  # for example: member-eastus2-cluster, member-westus3-cluster

kubectl create configmap cluster-identity \
  --namespace kube-system \
  --from-literal=cluster-name="${CLUSTER_NAME}"

Note

The Kubernetes cluster name in this ConfigMap must exactly match one of the member Kubernetes cluster names in spec.clusterReplication.clusterList[].name.

This is required because the DocumentDB CRD is the same across primaries and replicas, and each Kubernetes cluster must identify its own role in the topology.

Network configuration¶

VNet/VPC peering (single cloud provider)¶

For Kubernetes clusters in the same cloud provider, configure VNet or VPC peering:

Azure (AKS)AWS (EKS)GCP (GKE)

Create VNet peering between all AKS cluster VNets:

az network vnet peering create \
  --name peer-to-cluster2 \
  --resource-group cluster1-rg \
  --vnet-name cluster1-vnet \
  --remote-vnet /subscriptions/.../cluster2-vnet \
  --allow-vnet-access

Repeat for all Kubernetes cluster pairs in a full mesh topology.

See AKS Fleet Deployment for automated Azure multi-region setup with VNet peering.

Create VPC peering connections between EKS cluster VPCs:

aws ec2 create-vpc-peering-connection \
  --vpc-id vpc-cluster1 \
  --peer-vpc-id vpc-cluster2 \
  --peer-region us-west-2

Update route tables to allow traffic between VPCs.

Enable VPC peering between GKE cluster networks:

gcloud compute networks peerings create peer-to-cluster2 \
  --network=cluster1-network \
  --peer-network=cluster2-network

Networking management¶

Configure inter-cluster networking using spec.clusterReplication.crossCloudNetworkingStrategy:

Valid options:

None (default): Direct service-to-service connections using standard Kubernetes service names for the PostgreSQL backend server
Istio: Use Istio service mesh for cross-cluster connectivity
AzureFleet: Use Azure Fleet Networking for cross-cluster communication (separate from KubeFleet)

Example:

spec:
  clusterReplication:
    primary: member-eastus2-cluster
    crossCloudNetworkingStrategy: Istio  # or AzureFleet, None
    clusterList:
      - name: member-eastus2-cluster
      - name: member-westus3-cluster

Deployment options¶

Choose a deployment approach based on your infrastructure and operational preferences.

With KubeFleet (recommended)¶

KubeFleet systems simplify multi-region operations by:

Centralized control: Define resources once, deploy everywhere
Automatic propagation: Resources sync to member Kubernetes clusters automatically
Coordinated updates: Roll out changes across regions consistently

Step 1: Deploy fleet infrastructure¶

Install KubeFleet or another fleet management system:

Configure member Kubernetes clusters to join the fleet. See deploy-fleet-bicep.sh "KUBEFLEET SETUP" for a complete automated setup example.

Step 2: Install cert-manager and DocumentDB operator¶

Install the cert manager and DocumentDB operator to the hub per the Required Components section, then create ClusterResourcePlacements to deploy them both to all member Kubernetes clusters.

Step 3: Deploy multi-region DocumentDB¶

Create a DocumentDB resource with replication configuration. The example uses substitutions with a script, so you will need to replace all the {{PLACEHOLDERS}}.

DocumentDB CRD, secret, and CRP

Within the CRD The clusterReplication section enables multi-region deployment, primary specifies which Kubernetes cluster accepts write operations, and clusterList lists all member Kubernetes clusters that host DocumentDB instances (including the primary) and accepts a more granular environment and storageClass variable.

Without KubeFleet¶

If you are not using KubeFleet, deploy DocumentDB resources to each Kubernetes cluster individually.

Step 1: Identify Kubernetes cluster names¶

Determine the name for each Kubernetes cluster. These names are used in the replication configuration:

# List your clusters
kubectl config get-contexts

# Or for cloud-managed clusters:
az aks list --query "[].name" -o table  # Azure
aws eks list-clusters --query "clusters" --output table  # AWS
gcloud container clusters list --format="table(name)"  # GCP

Step 2: Create Kubernetes cluster identification¶

On each Kubernetes cluster, create a ConfigMap to identify the Kubernetes cluster name:

# Run on each Kubernetes cluster
CLUSTER_NAME="cluster-region-name"  # for example: member-eastus2-cluster

kubectl create configmap cluster-identity \
  --namespace kube-system \
  --from-literal=cluster-name="${CLUSTER_NAME}"

Step 3: Deploy cert-manager and DocumentDB operator to each cluster¶

Install the cert manager and DocumentDB operator to the hub per the Required Components section on each Kubernetes cluster. When making changes to any resource, you must make that same change across each Kubernetes cluster so they are all in sync, as the operator works under the assumption that all members have the same resources.

Storage configuration¶

Each Kubernetes cluster in a multi-region deployment can use different storage classes. Configure storage at the global level or override per member Kubernetes cluster:

Global storage configuration:

spec:
  resource:
    storage:
      pvcSize: 100Gi
      storageClass: default-storage-class  # Used by all Kubernetes clusters

Per-Kubernetes-cluster storage override:

spec:
  resource:
    storage:
      pvcSize: 100Gi
      storageClass: default-storage-class  # Fallback
  clusterReplication:
    primary: member-eastus2-cluster
    clusterList:
      - name: member-westus3-cluster
        storageClass: managed-csi-premium  # Override for this Kubernetes cluster
      - name: member-uksouth-cluster
        storageClass: azuredisk-standard-ssd  # Override for this Kubernetes cluster
      - name: member-eastus2-cluster
        # Uses global storageClass

Cloud-specific storage classes:

Azure (AKS)AWS (EKS)GCP (GKE)

- name: member-eastus2-cluster
  storageClass: managed-csi  # Azure Disk managed CSI driver
  environment: aks

- name: member-us-east-1-cluster
  storageClass: gp3  # AWS EBS GP3 volumes
  environment: eks

- name: member-us-central1-cluster
  storageClass: standard-rwo  # GCP Persistent Disk
  environment: gke

Service exposure¶

Configure how DocumentDB is exposed in each region:

LoadBalancerClusterIP

Best for: Production deployments with external access

spec:
  exposeViaService:
    serviceType: LoadBalancer

Each Kubernetes cluster gets a public IP for client connections. When you use the environment configuration at either the DocumentDB cluster or Kubernetes cluster level, the tags for the LoadBalancer change. See the cloud-specific setup docs for more details.

Best for: In-cluster access only or Ingress-based routing

spec:
  exposeViaService:
    serviceType: ClusterIP

Clients must access DocumentDB through Ingress or service mesh.

Troubleshooting¶

Replication not established¶

If replicas don't receive data from the primary:

Verify network connectivity:

# From a replica Kubernetes cluster, test connectivity to primary
kubectl --context replica1 run test-pod --rm -it --image=nicolaka/netshoot -- \
  nc -zv primary-service-endpoint 5432

Check PostgreSQL replication status on primary:

kubectl --context primary exec -it -n documentdb-preview-ns \
  documentdb-preview-1 -- psql -U postgres -c "SELECT * FROM pg_stat_replication;"

Review operator logs:

kubectl --context primary logs -n documentdb-operator \
  -l app.kubernetes.io/name=documentdb-operator --tail=100

Kubernetes cluster name mismatch¶

If a Kubernetes cluster doesn't recognize itself as primary or replica:

Check cluster-identity ConfigMap:

kubectl --context cluster1 get configmap cluster-identity \
  -n kube-system -o jsonpath='{.data.cluster-name}'

Verify the name matches the DocumentDB spec:

The returned name must exactly match one of the Kubernetes cluster names in spec.clusterReplication.clusterList[*].name.

Update ConfigMap if incorrect:

kubectl --context cluster1 create configmap cluster-identity \
  --namespace kube-system \
  --from-literal=cluster-name="correct-cluster-name" \
  --dry-run=client -o yaml | kubectl apply -f -

Storage issues¶

If PVCs aren't provisioning:

Verify storage class exists:

kubectl --context cluster1 get storageclass

Check for VolumeSnapshotClass (required for backups):

kubectl --context cluster1 get volumesnapshotclass

Review PVC events:

kubectl --context cluster1 get events -n documentdb-preview-ns \
  --field-selector involvedObject.kind=PersistentVolumeClaim

Next steps¶

Failover procedures - Learn how to perform planned and unplanned failovers
Backup and restore - Configure multi-region backup strategies
TLS configuration - Secure connections with proper TLS certificates
AKS Fleet deployment example - Automated Azure multi-region setup