Repository navigation
DEV-1041 rewrite operator examples page - #971
Merged
Merged
Conversation
Contributor
Code Review by Qodo
1. Wrong .network.loadBalancers key
|
Docs build
|
Contributor
PR Summary by QodoRewrite operator example deployments page with stepwise diffs + validator WalkthroughsDescription• Rewrites operator deployment examples into an opinionated, narrative “From Zero to Prod” flow. • Adds per-step diff + full-manifest tabs to make each incremental change explicit. • Introduces a consistency-check script to validate copied YAML/diff snippets stay in sync. Diagramgraph TD
A[["database-deployment.md"]] --> B["check-diffs.py"] --> C["Parse headings & fences"] --> D["Diff plausibility checks"] --> E{"Consistent?"}
E -->|"Yes"| F["PASS report"] --> G["Exit 0"]
E -->|"No"| H["FAIL report"] --> I["Exit 1"]
subgraph Legend
direction LR
_doc[["Document"]] ~~~ _proc["Process"] ~~~ _dec{"Decision"}
end
High-Level AssessmentThe following are alternative approaches to this PR: 1. Generate examples from a single YAML source (templating/includes)
2. Add a CI docs-lint step that runs the validator
3. Use a stricter diff model (apply unified diff formally)
Recommendation: Keep the current approach: a strongly narrative docs page plus a lightweight validator is a pragmatic fit for documentation-authored examples. If this page becomes frequently edited, the next best incremental improvement would be wiring check-diffs.py into CI to prevent regressions automatically; full templating/generation is higher upfront cost and reduces the “copy/paste runnable manifest” ergonomics. File ChangesTests (1)
Documentation (2)
|
Docs build
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
Comment on lines
+2280
to
+2281
| Configure `.network.loadBalancers.enabled: true` so your external clients can access your KurrentDB | ||
| according to its `fqdnTemplate`. |
Contributor
There was a problem hiding this comment.
1. Wrong .network.loadbalancers key 📘 Rule violation ≡ Correctness
The LetsEncrypt documentation tells users to set .network.loadBalancers.enabled, but the manifest/example YAML and surrounding docs use .network.loadBalancer.enabled (singular). Following the current prose will send readers to an incorrect spec path and can misconfigure external access to the cluster.
Agent Prompt
## Issue description
The LetsEncrypt TLS documentation prose references an incorrect/non-existent field name `.network.loadBalancers.enabled` (plural), while the actual manifests/example YAML and other references use `.network.loadBalancer.enabled` (singular). Update the instructions so the field name is consistent and users configure the correct spec path.
## Issue Context
This occurs in the LetsEncrypt TLS example/step narrative immediately before the diff/example YAML and directly impacts whether external clients can access the cluster; it also violates the expectation (PR Compliance ID 4) that procedural instructions are clear and precise.
## Fix Focus Areas
- docs/server/kubernetes-operator/v1.6.0/operations/database-deployment.md[2278-2283]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Comment on lines
50
to
55
| ```yaml | ||
| apiVersion: cert-manager.io/v1 | ||
| kind: ClusterIssuer | ||
| kind: Issuer | ||
| metadata: | ||
| name: letsencrypt | ||
| spec: |
Contributor
There was a problem hiding this comment.
2. Letsencrypt issuer missing namespace 📘 Rule violation ≡ Correctness
The LetsEncrypt Issuer example is a namespaced resource but omits metadata.namespace: kurrent, and the instructions apply it without -n kurrent, so users will likely create the Issuer in their current/default namespace. This mismatch causes certificate issuance to fail for Certificate resources in the kurrent namespace and makes the setup steps non-copy/paste-safe.
Agent Prompt
## Issue description
The LetsEncrypt `Issuer` example is namespaced but missing `metadata.namespace: kurrent`, and the docs apply it without `-n kurrent`, making the instructions ambiguous and likely to create the Issuer in the wrong namespace (default/current), which breaks certificate issuance for resources in `kurrent`.
## Issue Context
These docs describe certificate usage for KurrentDB deployments that use the `kurrent` namespace, and other `Issuer` examples on the same page (and related docs) explicitly set `namespace: kurrent`. The LetsEncrypt setup flow should be copy/paste-safe, so either the manifest should include the namespace or the command should specify `-n kurrent` (or both) to ensure the Issuer is created where the `Certificate` resources will reference it.
## Fix Focus Areas
- docs/server/kubernetes-operator/v1.6.0/operations/managing-certificates.md[50-70]
- docs/server/kubernetes-operator/v1.6.0/operations/managing-certificates.md[72-79]
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
Deploying documentation with
|
| Latest commit: |
eeadffa
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://395ef559.documentation-21k.pages.dev |
| Branch Preview URL: | https://operator-examples.documentation-21k.pages.dev |
rb-kurrent
force-pushed
the
operator-examples
branch
from
June 10, 2026 17:26
51f71a6 to
faa32b9
Compare
stktung
approved these changes
Jun 10, 2026
The operator examples page had several issues: - It wasn't opinionated enough. Users weren't given a strong idea of what we recommend they do. - It was all written with full manifests rather than diffs. This made the examples mostly runnable but gave the wrong impression about how much we recommend some common options. Even though each example was minimal, it still didn't give the reader a clear idea what specific details in the manifest contributed to the feature the example was describing. - It was just a loosely ordered pile of examples with no real narrative to guide the reader. By contrast, this new rewrite trieds to meet every need: - It is strongly opinionated. You can't miss our recommendations because they're present in every full manifest. - It has diffs and full manifests for all the incremental steps. The reader can clearly see what edits are being made corresponding to each step. - There is a clear narrative covering 2/3 of the page, and the final 1/3 is miscellaneous examples. - A reader who ignores the narrative is presented with "_This is step N of M._" to cue them into the fact that they're skipping the narrative. Even so, each numbered example is useful to illustrate its specific concept, even if the narrative is ignored. - There's a ton of copy-pasta in the source document, and a script to check that the copy-pasta is free of errors after making edits.
rb-kurrent
force-pushed
the
operator-examples
branch
from
June 10, 2026 18:09
faa32b9 to
eeadffa
Compare
Docs Preview
|
Docs build
|
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.
The operator examples page had several issues:
It wasn't opinionated enough. Users weren't given a strong idea of what we recommend they do.
It was all written with full manifests rather than diffs. This made the examples mostly runnable but gave the wrong impression about how much we recommend some common options. Even though each example was minimal, it still didn't give the reader a clear idea what specific details in the manifest contributed to the feature the example was describing.
It was just a loosely ordered pile of examples with no real narrative to guide the reader.
By contrast, this new rewrite trieds to meet every need:
It is strongly opinionated. You can't miss our recommendations because they're present in every full manifest.
It has diffs and full manifests for all the incremental steps. The reader can clearly see what edits are being made corresponding to each step.
There is a clear narrative covering 2/3 of the page, and the final 1/3 is miscellaneous examples.
A reader who ignores the narrative is presented with "This is step N of M." to cue them into the fact that they're skipping the narrative. Even so, each numbered example is useful to illustrate its specific concept, even if the narrative is ignored.
There's a ton of copy-pasta in the source document, and a script to check that the copy-pasta is free of errors after making edits.
Description
Page previews