WRITTEN BY
/en-us/opensource/blog/author/abhishek-gupta
Today, we're excited to announce the DocumentDB Kubernetes Operator, an open-source, cloud-native solution to deploy, manage, and scale DocumentDB instances on Kubernetes. DocumentDB is a MongoDB-compatible, open-source document database built on PostgreSQL. The DocumentDB Kubernetes Operator represents a natural evolution of the DocumentDB ecosystem, following our open source announcement and recent joining of the Linux Foundation.
When it comes to distributed databases, there is no one-size-fits-all solution. Database-as-a-Service (DBaaS) options may not always meet customers' data sovereignty or portability needs. On the other hand, managing database clusters manually is complex and resource intensive.
What’s needed is a balanced approach: one that automates routine tasks like updates and backups, while simplifying operations such as scaling, failover, and recovery. This is precisely where Kubernetes excels—bridging automation with operational simplicity.
However, unlike stateless applications that can be easily scaled and replaced, running stateful workloads in Kubernetes has always posed unique challenges. The DocumentDB Kubernetes Operator addresses these by using the operator pattern to extend Kubernetes, making it possible to manage DocumentDB clusters as native Kubernetes resources.
This approach creates a clear separation of responsibilities:
- The database platform team can focus solely on system health.
- App developers enjoy a DBaaS-like experience, without the need to build custom automation between container orchestration and database operations.
- The operator handles the complexity of PostgreSQL cluster orchestration, MongoDB protocol translation, and other critical operations.
- Application development teams can integrate services using MongoDB-compatible drivers and tools, thereby simplifying the process of migrating existing workloads to DocumentDB, or building new cloud-native applications.
DocumentDB operator architecture overview
To understand how this works, let’s take a look under the hood, to explore the key components and architecture that make this seamless Kubernetes integration possible.
A DocumentDB cluster deployed on Kubernetes consists of multiple DocumentDB instances that are orchestrated by the operator. A DocumentDB instance consists of the following core components that run inside a Kubernetes Pod:
- PostgreSQL with DocumentDB Extension: This is the core database engine enhanced with document storage and querying capabilities.It is deployed in customer application namespaces on Kubernetes worker nodes.
- Gateway Container: A protocol translator that runs as a sidecar container, converting MongoDB wire protocol requests into PostgreSQL DocumentDB extension calls.
By default, the DocumentDB instance is accessible within the cluster. If configured, the operator creates a Kubernetes Service for external client applications to connect to the DocumentDB cluster (via the Gateway) using any MongoDB-compatible client or tooling.
CloudNative-PG operator for PostgreSQL orchestration
The DocumentDB operator uses the CloudNative-PG (CNPG) operator for PostgreSQL cluster management. CNPG is a Cloud Native Computing Foundation (CNCF) Sandbox project that provides an open-source Kubernetes operator for managing PostgreSQL workloads. The CNPG operator runs in the cnpg-system namespace on Kubernetes worker nodes. Behind the scenes, the DocumentDB operator creates the required CNPG resources to manage the lifecycle of PostgreSQL instances with the DocumentDB extension.
DocumentDB is addressing a real need as an open-source, document-oriented NoSQL database built on PostgreSQL. By offering MongoDB API compatibility without vendor lock-in, it tackles a long-standing challenge for developers. We are thrilled to see the DocumentDB Kubernetes Operator joining the Linux Foundation, and proud that under the hood, it's powered by CloudNativePG, a CNCF Sandbox project. The future of PostgreSQL on Kubernetes just got even brighter!
Getting started with DocumentDB Kubernetes Operator
Ready to try it out? Getting started with the operator is straightforward. You can use a local Kubernetes cluster such as minikube or kind and use Helm for installation.
First, execute the commands below to install cert-manager to manage TLS certificates for the DocumentDB cluster:
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
helm install documentdb-operator oci://ghcr.io/microsoft/documentdb-operator --namespace documentdb-operator --create-namespace
This will install the latest version of the operator. To specify a version, use -- version.
Wait for the operator to start. Run this command to verify its status:
kubectl get pods -n documentdb-operator
NAME READY STATUS RESTARTS AGE
documentdb-operator-65d6b97878-ns5wk 1/1 Running 0 1m
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Namespace
metadata:
name: documentdb-preview-ns
---
apiVersion: v1
kind: Secret
metadata:
name: documentdb-credentials
namespace: documentdb-preview-ns
type: Opaque
stringData:
username: k8s_secret_user
password: DemoPwd
EOF
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Namespace
metadata:
name: documentdb-preview-ns
---
apiVersion: db.microsoft.com/preview
kind: DocumentDB
metadata:
name: documentdb-preview
namespace: documentdb-preview-ns
spec:
nodeCount: 1
instancesPerNode: 1
documentDbCredentialSecret: documentdb-credentials
resource:
storage:
pvcSize: 10Gi
exposeViaService:
serviceType: ClusterIP
EOF
kubectl get pods -n documentdb-preview-ns
NAME READY STATUS RESTARTS AGE
documentdb-preview-1 2/2 Running 0 1m
kubectl port-forward pod/documentdb-preview-1 10260:10260 -n documentdb-preview-ns
mongosh 127.0.0.1:10260 -u k8s_secret_user -p DemoPwd --authenticationMechanism SCRAM-SHA-256 --tls --tlsAllowInvalidCertificates
Join us in our mission to advance the open-source document database ecosystem
The DocumentDB Kubernetes Operator represents an important milestone in our broader mission and our commitment to vendor-neutral, community-driven development that puts developer needs first.
We invite you to join the community and help shape the future of cloud-native document databases.
Get started by exploring the GitHub repository, documentation, or participate in discussions on our Discord community. As the project continues to evolve under Linux Foundation governance, you can expect to see contributions that expand functionality and integrate with other Kubernetes and CNCF projects.