NewDocumentDB 1.0 is here. See what's new
Kubernetes Operator navigation

Kubernetes Operator

The DocumentDB Kubernetes Operator runs and manages DocumentDB clusters on Kubernetes. You describe a cluster as a DocumentDB resource, and the operator provisions it and handles high availability, failover, backups, and upgrades, building on CloudNativePG for the PostgreSQL layer. Every instance pairs a PostgreSQL container with a DocumentDB gateway sidecar, so applications connect using MongoDB-compatible drivers exactly as they would to any other DocumentDB deployment.

The operator is a separate project, with its own repository, release cadence, and documentation. This page covers when to reach for it and what your cluster needs; the operator's own documentation covers everything else.

Versions

Operator 1.1.1 runs DocumentDB engine 1.0-0. Pin the chart version for repeatable installs (cert-manager must be installed first; see the quickstarts below):

helm install documentdb-operator oci://ghcr.io/documentdb/documentdb-operator \
  --version 1.1.1 \
  --namespace documentdb-operator \
  --create-namespace \
  --wait

When to use it

OptionBest for
DocumentDB LocalA single container for development, prototyping, and integration tests.
Pre-built packagesAdding DocumentDB to a PostgreSQL server you already run and operate yourself.
Kubernetes OperatorRunning DocumentDB as a replicated service, with automatic failover, rolling upgrades, backup and restore, and multi-region deployments.

What your cluster needs

The operator needs Kubernetes 1.32 or later. Check one more thing before you plan a deployment: how the DocumentDB extension reaches PostgreSQL pods. By default the operator mounts it with the Kubernetes ImageVolume feature when the cluster supports it:

  • Kubernetes 1.35 or later. ImageVolume is GA from 1.36. In 1.35 it is beta and on by default, so check that your cluster hasn't turned the ImageVolume feature gate off. On 1.33 and 1.34 it is off by default, and works only if you enable the gate on the API server and the kubelets.
  • containerd 2.1 or later, or CRI-O 1.33 or later as the container runtime. The Docker runtime does not support ImageVolume.

Otherwise the operator uses a combined image that ships PostgreSQL 18 and the extension together. It decides when a DocumentDB cluster is created, and the cluster keeps that layout. Managed Kubernetes offerings vary in the versions and runtimes they expose, and local tools often need an explicit flag to select a supported runtime, so confirm both up front if you want ImageVolume. Before You Start has the full prerequisite list, including supported tooling versions and resource sizing.

Operator documentation

The operator's documentation is versioned and published alongside its releases:

Report operator issues in the operator repository rather than this one.