Give the Kubernetes operator a home in the docs, and point it at its own - #62
Merged
guanzhousongmicrosoft merged 1 commit intoAug 3, 2026
Conversation
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.
guanzhousongmicrosoft
approved these changes
Aug 3, 2026
GuanzhouSong
added a commit
to GuanzhouSong/documentdb.github.io
that referenced
this pull request
Aug 3, 2026
documentdb/docs#62 merged a kubernetes-operator section, and it is unreachable: content.config.json enumerates the folders copied out of the docs repository, so a section missing from that list is never copied, never exported, and 404s permanently rather than until the next deploy. /docs/kubernetes-operator returns the not-found fallback today. Added the mapping alongside the other four. With the section building, the /docs landing entry for the operator can point at documentation instead of at the marketing page, which is what every other entry on that page does. This is the follow-up this branch previously deferred on merge-order grounds; documentdb#62 has landed, so the target exists.
guanzhousongmicrosoft
pushed a commit
to documentdb/documentdb.github.io
that referenced
this pull request
Aug 3, 2026
…nt sync (#135) * Fix the Kubernetes operator links and install command Every "read the documentation" link we point at the Kubernetes operator is a 404. documentdbKubernetesOperatorDocsUrl is /documentdb-kubernetes-operator/preview/, but the operator publishes its docs under a version segment, at /documentdb-kubernetes-operator/latest/ preview/. The constant is used five times - three on the operator page, including its primary call to action, and once on the home page - so every route we offer a reader who wants to learn about the operator ends at GitHub Pages' not-found page. The install command on the operator page is stale in a quieter way. It installs from the classic chart repository at documentdb.github.io/documentdb-kubernetes-operator, whose index still tops out at chart 0.2.0, published 2026-03-26. The current chart is 0.3.0, and the operator has moved to publishing the chart as an OCI artifact on ghcr.io, which is what its README and its own quickstarts now use. Following our page gets you a four-month-old operator - which matters more than the version gap suggests, because 0.3.0 is where the ImageVolume capability check and its admission webhook landed. Replaced with the OCI install the operator documents. Also fixed a moved link in the March operator blog post: the backup and restore guide is now under preview/operations/. All four URLs were checked against the live site, before and after. Not included, to avoid a cross-repo merge order hazard: the /docs landing entry for the operator points at this marketing page rather than at documentation. documentdb/docs#62 adds a /docs/kubernetes-operator section for it to point to, so that entry is worth updating once #62 lands. * Sync the kubernetes-operator section so its pages actually build documentdb/docs#62 merged a kubernetes-operator section, and it is unreachable: content.config.json enumerates the folders copied out of the docs repository, so a section missing from that list is never copied, never exported, and 404s permanently rather than until the next deploy. /docs/kubernetes-operator returns the not-found fallback today. Added the mapping alongside the other four. With the section building, the /docs landing entry for the operator can point at documentation instead of at the marketing page, which is what every other entry on that page does. This is the follow-up this branch previously deferred on merge-order grounds; #62 has landed, so the target exists.
guanzhousongmicrosoft
pushed a commit
that referenced
this pull request
Aug 3, 2026
Two loose ends from #62, both created by pull requests that merged independently of it and could not have known about each other. The contributing instructions in readme.md list the folders that hold documentation articles, and #35 wrote that list while #62 was still open, so it names four folders where there are now five. A contributor following it would not know the kubernetes-operator section exists or that it follows the same rules. The documentdb-local page had no route onward. Someone who has just run the container and wants replication, failover, or rolling upgrades has no reason to guess that the answer is a different section of the site; it is the most likely place in these docs for that question to occur, so it now points at the operator section and at the pre-built packages. This was deliberately held back while #61 was rewriting that page, and lands now that it has merged.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Kubernetes is close to invisible in this repository. Before this change, the only mention anywhere is a single 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.This adds a
kubernetes-operatorsection that orients the reader and hands off to the operator's own documentation.What changed
kubernetes-operator/section — a singleindex.mdplusnavigation.yml, the same shapedocumentdb-local/andarchitecture/already use. It sits alongsidedocumentdb-localrather than nested undergetting-started, because the two are the same kind of thing (a way to run DocumentDB) and the docs landing page enumerates top-level sections.Why it links rather than duplicates
The operator is a separate project publishing around thirty 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. A 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.
#1 shows the cost. It was an accurate operator quickstart when it was opened, and since then its API group (
db.microsoft.com, nowdocumentdb.io) and its chart registry (ghcr.io/microsoft, nowghcr.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 landed.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 at resource creation. Everything past that decision is a deep link. No manifests, no install commands, no resource fields: those are exactly what went stale before.
Verification
Every outbound link was checked against the live site, including a deliberate non-existent control URL to confirm the check distinguishes real pages from soft 404s. The prerequisite claims were checked against the operator source rather than its prose.
Follow-ups, not in this PR
documentdb.github.ioand need a separate PR there: the/docslanding entry for Kubernetes points at the marketing page rather than any documentation, and that page's install snippet uses the classic chart repo, which tops out at chart 0.2.0 (published 2026-03-26) while the current chart is 0.3.0 and the operator has moved to the OCI registry.