Dora NodaIn November 2025, Microsoft needed a Kubernetes operator for DocumentDB, its open-source document database — and instead of writing one, it wrote half of one. The DocumentDB operator contains no high-availability logic, no failover code, and no backup machinery. It creates CloudNativePG Cluster resources and lets CNPG do all of that, then injects its own gateway container into the resulting Postgres pods through a plugin. A hyperscaler looked at the problem of running a stateful database on Kubernetes and decided the solved part should stay solved.
That decision is the verdict this post is about. If you operate a self-hosted fleet and your Postgres layer is still a bespoke StatefulSet, a second database stack waiting to happen, or a managed service you pay to avoid thinking about — here is the case for standardizing on CNPG, the mechanism that makes it more than one operator's opinion, and the honest conditions under which you shouldn't.
What Microsoft actually shipped
DocumentDB itself is two MIT-licensed Postgres extensions Microsoft open-sourced in early 2025: pg_documentdb_core, which teaches Postgres a native BSON type, and an API layer implementing document CRUD, queries, and index management. It is the same engine family behind vCore-based Azure Cosmos DB for MongoDB. Adoption was fast enough — nearly 2,000 GitHub stars and hundreds of contributions in six months — that Microsoft handed governance to the Linux Foundation in August 2025, with AWS and Google backing the move.
The Kubernetes operator followed on November 5, 2025, and its architecture is the interesting part. There are three components, and only the thinnest one is DocumentDB-specific:
- The CNPG operator, installed automatically by the DocumentDB Helm chart as a dependency into the
cnpg-systemnamespace. It owns everything Postgres-shaped: instance lifecycle, streaming replication, failover, backups. - The DocumentDB operator, which watches its own
DocumentDBresources (apiVersion: documentdb.io/preview) and translates them into CNPGClusterresources carrying the DocumentDB extension. It never touches a pod directly. - The CNPG Sidecar Injector, an admission webhook that injects the DocumentDB Gateway container into every CNPG-managed Postgres pod at deploy time, handling TLS certificate mounting, credential injection, and image defaults.
One precision worth keeping: this is an operator on CNPG plus a CNPG-I plugin injection, not a pure plugin. The DocumentDB team still owns a controller — but the controller's entire job is manifest translation. Every hard distributed-systems problem (leader election, split-brain fencing, point-in-time recovery) stays inside CNPG, which is somebody else's tested, released, CVE-patched code. That is the shape to notice, because it repeats.
The interface that makes this a pattern, not a one-off
The sidecar injector works because CloudNativePG exposes CNPG-I, a gRPC plugin protocol deliberately modeled on the Kubernetes Container Storage Interface. Plugins implement versioned interfaces — identity, operator, operator_lifecycle, plus newer ones for Postgres internals, backups, and metrics.
The operator interface is the key: it hooks a plugin into the Cluster resource webhooks themselves, with MutateCluster enriching pod specs at admission and ValidateClusterCreate / ValidateClusterChange extending validation. DocumentDB's injector uses exactly these three to add its gateway sidecar to pods of clusters it doesn't own.
That same surface already hosts unrelated plugins. Barman Cloud backups plug in through the backup interface (pluginConfiguration: barman-cloud.cloudnative-pg.io). Xata's cnpg-i-scale-to-zero plugin parks idle clusters. And CNPG 1.26+ manages extensions and schemas declaratively, with the newest path delivering extensions as OCI image volumes via Kubernetes' ImageVolume feature — adding an extension becomes a manifest edit, no custom image rebuild. CNPG is behaving less like an operator and more like a database platform kernel with a driver ABI.
The velocity behind that kernel matters too. CNPG 1.30 shipped June 29, 2026, supports Kubernetes 1.34 through 1.36 and Postgres 14 through 18, and entered the CNCF Sandbox in January 2025 after EDB open-sourced it in 2022. Compare Zalando's postgres-operator at v1.15.1 from December 2025: capable, but a slower train. Public architecture decision records for new Postgres-on-Kubernetes builds have converged on the same sentence — use CNPG, not Zalando — and Microsoft just corroborated the community's ADR with a shipping hyperscaler product.
The scoreboard: what standardizing on CNPG buys a fleet
Three ways to run tenant-facing Postgres on machines you own, scored on the rows that actually cost ops time:
| Row | CNPG as the standard substrate | A bespoke operator per database | Managed Postgres (RDS/Neon/etc.) |
|---|---|---|---|
| HA + failover | Inherited: streaming replication, automated failover, fencing | Reimplemented per stack, tested by you | Inherited, priced per GB-hour |
| Backups + PITR | Declarative Backup/ScheduledBackup, object-store targets | Second backup story per engine | Included, retention tiers extra |
| Second engine (document/Mongo API) | DocumentDB operator or FerretDB v2 on the same clusters | A whole new operator to learn and page on | A second managed product to pay for |
| Extension rollout | Manifest edit (ImageVolume path on PG 18 / K8s 1.35+) | Custom image pipeline per stack | Whatever the vendor allows |
| Node drains / upgrades | Operator reschedules primaries; replicas re-sync | Your runbook, per engine | Somebody else's maintenance window |
| Marginal cost per database | Near zero (same operator, same skill) | One more stack to staff | One more bill line |
The row that decides it for most self-hosted fleets is the third. The day a tenant wants a MongoDB connection string, the CNPG-standardized fleet answers with the DocumentDB operator or FerretDB v2 on its existing clusters — one operator's mental model, one backup story, one paging rotation. Every alternative answers with a new stack.
The honest objections, with their win conditions
"Don't run databases on Kubernetes." The oldest objection, and still the right default for a team with no Postgres skill in-house: if nobody on call can read a replication-lag graph, managed Postgres wins regardless of operator quality. But notice what the objection concedes — it is about staffing, not architecture.
CNPG exists precisely to shrink the staffing side: declarative clusters, automated failover, and scheduled backups move the common cases into YAML. The objection wins when the team is small and stateless-first; it loses the moment tenant state has to live on your machines anyway, at which point the question is only which operator, and this post's answer is CNPG.
"Zalando's operator is fine." It is — Patroni-based, battle-tested, and simpler to reason about. It wins on clusters that will never need more than Postgres: no plugin surface to learn, no second CRD family. It loses on velocity and surface: CNPG's steadier release train, CNCF stewardship, and the CNPG-I plugin ecosystem mean the next requirement (document API, scale-to-zero, declarative extensions) arrives as a plugin, not a migration. Pick Zalando for one database forever; pick CNPG if "one database forever" has ever been wrong before.
"CNPG is still Sandbox, and the sharp edges are real." Fair on both counts. CNCF Sandbox is not Graduated. And the DocumentDB operator itself demands Kubernetes 1.35 or later, conflicts if CNPG is already installed (the chart has a skip-dependency escape hatch — read it before installing into a cluster that already runs CNPG), and the ImageVolume extension path needs Postgres 18.
These are adoption costs, not disqualifiers: pin versions, test the chart's skip flag in staging, and keep Postgres 17's classic extension path until your fleet is on 1.35+. The direction of travel — every hard problem accreting into one tested operator — is worth more than any single version's rough edges.
A five-gate checklist before you standardize
If four of these five answer yes, make CNPG the fleet default before tenant state — not just tenant apps — has to survive its first node drain:
- Kubernetes 1.35+ on the fleet? Required for the DocumentDB operator and the ImageVolume extension path; older fleets can still run CNPG core but lose the newest plugin surface.
- Object storage for backups? CNPG's backup story assumes an S3-compatible target. No bucket, no PITR — fix that first.
- More than one database engine on the roadmap? Relational today plus document/vector/Mongo-API tomorrow is exactly the case the plugin surface exists for.
- Someone on call who knows Postgres? CNPG automates the common cases, not the 3 a.m. ones. One Postgres-literate human is the minimum viable paging rotation.
- GitOps already in place?
ClusterCRs are designed for declarative management; if the fleet still applies YAML by hand, the operator's value halves.
The signal in one sentence
When even the company that sells you managed databases ships its own document store as manifests-into-CNPG plus a sidecar, "which Postgres operator" stops being an open question for self-hosted fleets. Standardize the stateful layer the way you standardized the stateless one — one reconciler, declarative desired state, extensions as data — and spend the saved ops budget on the tenant features only you can build.
Bex.co is the open-source, AI-native Render alternative — push a git repo, get a running HTTPS service on machines you own. Star the repo on GitHub or deploy your first app today.
