Add Kubernetes operator quick start - #1
Conversation
Documentdb local doc improvement
|
Thanks for this, @abhirockzz, and apologies that it sat for so long without a proper response. I'd like to close it, but I'd rather explain the reasoning than let it quietly go stale. The operator now publishes its own documentation. documentdb/documentdb-kubernetes-operator maintains around thirty pages at https://documentdb.io/documentdb-kubernetes-operator/latest/preview/ — quickstarts for kind and k3s, AKS/EKS/GKE, networking, storage and TLS configuration, high availability, backup and restore, upgrades, monitoring, the kubectl plugin, and an API reference. They are versioned with operator releases and edited in the same pull requests that change the operator's behavior, which is something a copy living in this repo cannot match. This PR has drifted since it was opened, through no fault of its own — it was accurate in October 2025:
That drift is really the argument. A step-by-step guide in this repo has to be re-verified against the operator on every release, and this one went nine months without it, while the operator's own quickstart tracked each of those changes as they landed. Rather than merging, a follow-up here adds a short If you are up for it, the operator repository is where this content would have the most impact: the quickstart lives at |
…own (#62) Kubernetes is close to invisible here. The only mention anywhere in this repo is one link in readme.md, so a reader browsing the documentation site sees VS Code, Python, Node.js, mongosh, and pre-built packages with no sign that DocumentDB runs on Kubernetes at all - even though the operator is a supported project with a preview release and its own documentation site. This adds a kubernetes-operator section alongside documentdb-local, rather than a page nested under getting-started. The two are the same kind of thing - a way to run DocumentDB - and the docs landing page lists top-level sections, so this is where a reader looking for deployment options will actually come across it. The section is a single index.md, the same shape documentdb-local and architecture already use. Cross-links from the getting-started landing page under Deployment Options and from the readme lead into it. What the page deliberately does not do is restate the operator's documentation. The operator is a separate project publishing 30-odd pages of its own - quickstarts, configuration, high availability, operations, monitoring, API reference - versioned with its releases and edited in the same pull requests that change the operator's behavior. Any copy kept here is a second copy maintained against a moving target, in a different publishing system, without the version scoping that makes the original correct. PR #1 shows the cost. It was an accurate operator quickstart when it was opened, and since then its API group (db.microsoft.com, now documentdb.io) and its chart registry (ghcr.io/microsoft, now ghcr.io/documentdb) have both moved, either one enough to stop the walkthrough at its first command. The operator's own quickstart followed both changes as they happened. So the page carries only what a reader needs in order to choose: what the operator does, how it compares with DocumentDB Local and the pre-built packages, and the one prerequisite that decides whether it can run at all - the ImageVolume feature, which pins the cluster to Kubernetes 1.35+ (or 1.33/1.34 with the feature gate) on containerd or CRI-O, and which the operator's admission webhook now enforces when the resource is created. Everything past that decision is a deep link into the operator's documentation. No manifests, no install commands, no resource fields: those are exactly what went stale before. Every outbound link was checked against the live site.
4 participants
This quick start guide provides the steps to install the operator, deploy a DocumentDB cluster, connect to it, and perform basic operations.