Add DocumentDB guides#935
Open
tamalsaha wants to merge 1 commit into
Open
Conversation
Add user-facing guides for KubeDB managed DocumentDB (MongoDB wire-protocol compatible, PostgreSQL-backed), modeled on the Postgres guides with mongosh/port-10260 verification. Topics: custom configuration (secret/inline/tuning), restart, horizontal & vertical scaling, reconfigure, rotate authentication, volume expansion, storage migration, automatic (raft) failover, and compute & storage autoscaling. Each guide embeds live output captured from a running cluster (ops-request status, pod roles, PVC sizes, secret rotation, mongosh pings). Example manifests added under docs/examples/documentdb. Signed-off-by: Tamal Saha <tamal@appscode.com>
![kodiak-appscode[bot]](https://avatars.githubusercontent.com/in/92481?s=60&v=4){kind=small}
📝 WalkthroughWalkthroughAdds a complete documentation suite for KubeDB DocumentDB, including example Kubernetes YAML manifests and guide pages covering custom configuration, restart, reconfigure, authentication rotation, automatic failover, horizontal/vertical scaling, volume expansion, storage migration, and compute/storage autoscaling. ChangesDocumentDB Documentation Suite
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 19
🧹 Nitpick comments (9)
docs/guides/documentdb/restart/restart.md (2)
160-166: 📐 Maintainability & Code Quality | 🔵 TrivialClarify standalone caveat wording.
The note states "the internal PostgreSQL is never initialized." If DocumentDB is PostgreSQL-based, this is accurate but surprising to users expecting MongoDB. Consider clarifying the architecture upfront: "DocumentDB uses PostgreSQL as its storage engine with MongoDB wire-protocol compatibility."
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guides/documentdb/restart/restart.md` around lines 160 - 166, Clarify the standalone caveat in the restart guide by updating the note near the bootstrap/Ready discussion to explicitly state that DocumentDB is PostgreSQL-based with MongoDB wire-protocol compatibility, so “internal PostgreSQL” is expected. Keep the existing explanation about the missing documentdb-coordinator sidecar and the database never reaching Ready, but rewrite the wording in the note to remove ambiguity for readers expecting MongoDB terminology.
13-13: 📐 Maintainability & Code Quality | 🔵 TrivialFix non-descriptive link text.
The markdownlint warnings indicate "here" links on lines 13 and 27 lack descriptive text. Replace with meaningful link text.
- > New to KubeDB? Please start [here](/docs/README.md). + > New to KubeDB? Please start with [the KubeDB overview](/docs/README.md).- - Install KubeDB following the steps [here](/docs/setup/README.md). + - Install KubeDB following the [installation steps](/docs/setup/README.md).Also applies to: 27-27
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guides/documentdb/restart/restart.md` at line 13, The markdown link text in the restart guide is non-descriptive in the introductory and later “here” references; update both occurrences to use meaningful anchor text instead of generic wording. Edit the links in the restart document so they clearly describe the destination, keeping the existing targets but replacing the vague link labels with descriptive text that matches the referenced documentation.Source: Linters/SAST tools
docs/guides/documentdb/scaling/_index.md (1)
5-5: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueAlign identifier naming convention with sibling pages.
The identifier
guides-documentdb-scalinguses aguides-prefix while all other DocumentDB navigation index pages in this cohort usedc-(e.g.,dc-configuration,dc-restart,dc-reconfigure,dc-auto-scaling). Consider renaming todc-scalingfor consistency.- identifier: guides-documentdb-scaling + identifier: dc-scaling🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guides/documentdb/scaling/_index.md` at line 5, The frontmatter identifier for the scaling guide is inconsistent with the other DocumentDB navigation pages and should be renamed for cohesion. Update the identifier in the scaling page’s frontmatter from the current guides-documentdb-scaling value to the dc- prefixed naming pattern used by sibling pages like dc-configuration and dc-auto-scaling, so the page aligns with the existing DocumentDB cohort convention.docs/guides/documentdb/reconfigure/reconfigure.md (1)
13-13: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueUse descriptive link text for accessibility.
The word "here" is not descriptive for screen-reader users. Consider rephrasing to something like "start with the KubeDB overview" and "following the KubeDB setup guide".
This is a common pattern across KubeDB documentation; fixing it here would improve accessibility consistency.
Also applies to: 32-32
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guides/documentdb/reconfigure/reconfigure.md` at line 13, The markdown link text in the reconfigure guide is too generic for accessibility, so update the existing links in the document to use descriptive phrases instead of “here.” Use the surrounding copy in the reconfigure page to rewrite the links with meaningful text that identifies the destination, and apply the same fix consistently in the other referenced occurrence. Focus on the affected markdown in this document rather than changing the URLs themselves.docs/guides/documentdb/configuration/using-config-file.md (1)
13-13: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueUse descriptive link text for accessibility.
The word "here" is not descriptive for screen-reader users. Consider rephrasing to something like "start with the KubeDB overview" and "following the KubeDB setup guide".
This is a common pattern across KubeDB documentation; fixing it here would improve accessibility consistency.
Also applies to: 46-46
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guides/documentdb/configuration/using-config-file.md` at line 13, The link text in the introductory “New to KubeDB?” sentence is too vague for accessibility; update the markdown in the document intro to use descriptive text instead of “here,” and do the same for the related setup reference mentioned in the review so screen-reader users can understand each destination from the link text alone.docs/guides/documentdb/volume-expansion/volume-expansion.md (2)
30-30: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider more descriptive link text.
The link text "here" is not descriptive of the destination.
- - Install KubeDB following the steps [here](/docs/setup/README.md). + - Install KubeDB following the [setup guide](/docs/setup/README.md).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guides/documentdb/volume-expansion/volume-expansion.md` at line 30, The markdown link text in the volume expansion guide is too generic; replace “here” with descriptive text that identifies the destination. Update the sentence containing the setup link so the anchor text clearly refers to the KubeDB installation/setup guide, making the reference understandable without relying on the URL.
13-13: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider more descriptive link text.
The link text "here" is not descriptive of the destination. While this pattern appears elsewhere in the docs, improving it aids accessibility.
- > New to KubeDB? Please start [here](/docs/README.md). + > New to KubeDB? Please start [with the KubeDB overview](/docs/README.md).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guides/documentdb/volume-expansion/volume-expansion.md` at line 13, The link text in the introductory sentence is too generic and should be made more descriptive for accessibility. Update the markdown in the volume expansion guide near the opening reference to point to the same destination but replace the vague “here” text with something that describes the linked docs, using the existing introductory sentence as the location cue.docs/guides/documentdb/storage-migration/storage-migration.md (2)
31-31: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider more descriptive link text.
The link text "here" is not descriptive of the destination.
- - Install KubeDB following the steps [here](/docs/setup/README.md). + - Install KubeDB following the [setup guide](/docs/setup/README.md).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guides/documentdb/storage-migration/storage-migration.md` at line 31, The link text in the storage migration guide is too vague, so update the markdown around the KubeDB setup reference to use descriptive text instead of “here.” Keep the same destination, but make the anchor text clearly indicate it points to the KubeDB installation/setup instructions so readers know what they’re clicking.
13-13: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider more descriptive link text.
The link text "here" is not descriptive of the destination.
- > New to KubeDB? Please start [here](/docs/README.md). + > New to KubeDB? Please start [with the KubeDB overview](/docs/README.md).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guides/documentdb/storage-migration/storage-migration.md` at line 13, The link text in the storage migration guide is too vague, so update the existing markdown link to use more descriptive wording that clearly reflects the destination. Locate the introductory sentence containing the README link and replace the generic “here” text with a meaningful label that matches the target page, keeping the same link destination.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/examples/documentdb/autoscaler/compute/autoscaling-compute-object.yaml`:
- Around line 1-5: The example in autoscaling-compute-object.yaml uses a broken
multi-replica DocumentDB setup with storageClassName set to local-path, which
prevents the database from reaching Ready before compute autoscaling can
trigger. Update the manifest and its surrounding comments in the DocumentDB
example to avoid the unsupported replicas/local-path combination, using a
storage/topology configuration that is known to become Ready, so the compute
autoscaler can proceed to create the VerticalScaling OpsRequest as intended.
In `@docs/examples/documentdb/autoscaler/storage/autoscaling-storage.yaml`:
- Around line 7-11: The autoscaling example in the storage DocumentDB YAML has
inconsistent growth math between the `scalingRules[].threshold` explanation and
the later generated-size output. Update the example and surrounding text to
match the actual sizing behavior used by `GetVolumeForOpsReq`, or explicitly
document the formula that converts a 50% threshold into the shown capacity, so
readers can trace the result from the `scalingRules` values.
In `@docs/examples/documentdb/configuration/cluster-config-secret.yaml`:
- Around line 1-27: The DocumentDB sample is using a PostgreSQL-style version
value in the DocumentDB manifest, so update the spec.version in the DocumentDB
example to a valid MongoDB/DocumentDB version string instead of the copied
pg17-0.109.0 value. Use the DocumentDB sample resource in the
cluster-config-secret example and replace the version with the correct
KubeDB-supported DocumentDB version that matches the rest of the guide.
In `@docs/examples/documentdb/configuration/documentdb-custom-config-secret.yaml`:
- Around line 1-9: The Secret example in documentdb-custom-config-secret.yaml is
using PostgreSQL-only settings in user.conf, so update the DocumentDB example to
use MongoDB-compatible DocumentDB parameters instead. Replace the current
max_connections and work_mem entries with valid DocumentDB-style options in the
Secret manifest, keeping the change localized to the user.conf block so the
documentdb-custom-config example matches the rest of the DocumentDB guides.
In `@docs/examples/documentdb/configuration/standalone-config-secret.yaml`:
- Around line 7-12: The standalone DocumentDB example in this config is
misleading because the PR notes that replicas: 1 does not bootstrap on this
build. Update the example to avoid implying it works as-is by either removing
the standalone-config-secret.yaml example or adding a prominent warning in the
example/docs near the configuration block that explicitly states standalone
bootstrap is currently broken. Make sure the guidance is tied to this DocumentDB
standalone configuration example so users don’t treat it as a supported setup.
In `@docs/examples/documentdb/restart/cluster.yaml`:
- Around line 10-20: The multi-replica restart example is using a storage class
that leaves DocumentDB pods stuck not ready, so the manifest is not runnable as
written. Update the cluster restart example to use the working storage
configuration referenced by cluster-longhorn.yaml, or explicitly mark this
manifest unsupported until local-path is fixed. Check the storage section in the
cluster YAML and the restart example naming so the default tutorial path points
to a Ready=True setup.
In `@docs/examples/documentdb/restart/standalone.yaml`:
- Around line 7-10: The standalone DocumentDB restart example is marked runnable
even though `replicas: 1` does not bootstrap on the documented build. Update the
`standalone.yaml` example so it is not presented as a normal walkthrough item:
either remove it from the runnable restart examples or clearly label it as
unsupported until standalone bootstrap is fixed. Keep the change localized to
the standalone restart example content so the `replicas`-based bootstrap
limitation is obvious.
In
`@docs/examples/documentdb/scaling/vertical-scaling/standalone-vertical-scaling.yaml`:
- Around line 19-23: The standalone vertical scaling example still includes a
coordinator resources block even though the standalone topology omits the
documentdb-coordinator sidecar. Remove the coordinator section from the
standalone manifest in the vertical scaling example, and keep the standalone
PetSet focused only on containers that actually exist in that topology.
In `@docs/guides/documentdb/autoscaler/compute/index.md`:
- Around line 27-29: The intro sentence in the autoscaler compute guide is
incomplete because the “You should be familiar with the following KubeDB
concepts:” lead-in is not followed by any concept list. Update this section by
either adding the missing list of KubeDB concepts immediately after that
sentence or removing the lead-in entirely so the surrounding paragraph reads
naturally and the section is self-contained.
- Around line 50-81: The DocumentDB 3-replica bootstrap example in the
autoscaler guide is using `storageClassName: "local-path"`, which prevents the
cluster from becoming Ready before the autoscaler demo begins. Update the
`DocumentDB` manifest in this section to use a storage class that supports
replicated workloads, or add a clear limitation note with an alternate setup;
keep the `DocumentDB` CR example aligned with the intended 3-replica autoscaler
flow.
In `@docs/guides/documentdb/autoscaler/storage/index.md`:
- Line 71: The heading hierarchy in the DocumentDB autoscaler storage guide
skips levels, so adjust the Deploy DocumentDB Cluster heading to match the
surrounding outline. Update the markdown heading in the affected section to use
the correct intermediate level (for example, make it an H3) and keep the
structure consistent with the nearby headings in the same document.
- Around line 29-31: The introduction in the guide has a dangling “You should be
familiar with the following KubeDB concepts:” lead-in with no list following it;
either remove that sentence entirely or add the missing concept list in the same
section. Update the opening text in this document so the transition into the
“demo” namespace explanation is complete and the reader is not left expecting
omitted content.
- Line 13: The markdown links in this guide use non-descriptive text like
“here,” which fails markdownlint and is less accessible; update the affected
link text in this document to be descriptive and meaningful while keeping the
same targets. Fix the occurrences near the intro and the other referenced links
by replacing “here” with context-specific phrasing so the link text clearly
describes the destination.
In `@docs/guides/documentdb/failure-and-disaster-recovery/failover.md`:
- Line 13: The Markdown link text uses a generic “here,” which triggers MD059
and hurts accessibility. Update the affected link(s) in the failover guide to
use descriptive anchor text that names the destination, and apply the same fix
to the other linked occurrence noted in the review so the reader can understand
the target without relying on “here.”
- Around line 119-125: The failover verification step hardcodes a specific pod
name as the primary, which makes the docs brittle because leader election can
choose a different pod. Update the example around the kubectl exec/mongosh
command to determine the elected primary dynamically first, using the same
role-based pod selection pattern shown in the comment, then exec into that pod
and run the read check so the step always targets the current primary.
In `@docs/guides/documentdb/restart/restart.md`:
- Around line 148-153: The mongosh example in the DocumentDB restart guide uses
an insecure TLS verification bypass, so update the command in the restart
documentation to avoid tlsAllowInvalidCertificates=true or clearly mark it as
demo-only with a security warning. If the example must remain runnable, adjust
the connection flow in the documented mongosh command to use proper certificate
handling instead of disabling validation, and keep the guidance aligned with
secure usage.
In `@docs/guides/documentdb/rotate-authentication/rotate-authentication.md`:
- Line 13: The markdown in the rotate-authentication guide uses generic “here”
link text, which triggers MD059 and hurts accessibility. Update the link text in
the affected intro and the later reference so each points to the same
destinations with descriptive wording that names what the reader will find. Keep
the existing targets in the markdown, and adjust the surrounding sentence in the
guide content so the link text is explicit instead of “here”.
In `@docs/guides/documentdb/scaling/vertical-scaling/vertical-scaling.md`:
- Around line 134-144: The standalone scaling guidance conflicts with the
documented standalone topology by mentioning the optional `coordinator`
container even though standalone PetSets omit `documentdb-coordinator`. Update
the standalone instructions in the vertical scaling guide so they only reference
`spec.databaseRef.name` pointing to `documentdb-sa-sample` and
`spec.verticalScaling.documentdb`, and remove any standalone mention of
`coordinator` from that path while leaving the cluster-wide
`DocumentDBOpsRequest` guidance intact.
- Line 13: The markdown link text in the document intro uses a vague “here”
label, which triggers the lint issue and is less accessible. Update the link in
the opening sentence to use descriptive text that names the destination
directly, and apply the same fix to the other matching occurrence mentioned in
the review so the docs read clearly out of context.
---
Nitpick comments:
In `@docs/guides/documentdb/configuration/using-config-file.md`:
- Line 13: The link text in the introductory “New to KubeDB?” sentence is too
vague for accessibility; update the markdown in the document intro to use
descriptive text instead of “here,” and do the same for the related setup
reference mentioned in the review so screen-reader users can understand each
destination from the link text alone.
In `@docs/guides/documentdb/reconfigure/reconfigure.md`:
- Line 13: The markdown link text in the reconfigure guide is too generic for
accessibility, so update the existing links in the document to use descriptive
phrases instead of “here.” Use the surrounding copy in the reconfigure page to
rewrite the links with meaningful text that identifies the destination, and
apply the same fix consistently in the other referenced occurrence. Focus on the
affected markdown in this document rather than changing the URLs themselves.
In `@docs/guides/documentdb/restart/restart.md`:
- Around line 160-166: Clarify the standalone caveat in the restart guide by
updating the note near the bootstrap/Ready discussion to explicitly state that
DocumentDB is PostgreSQL-based with MongoDB wire-protocol compatibility, so
“internal PostgreSQL” is expected. Keep the existing explanation about the
missing documentdb-coordinator sidecar and the database never reaching Ready,
but rewrite the wording in the note to remove ambiguity for readers expecting
MongoDB terminology.
- Line 13: The markdown link text in the restart guide is non-descriptive in the
introductory and later “here” references; update both occurrences to use
meaningful anchor text instead of generic wording. Edit the links in the restart
document so they clearly describe the destination, keeping the existing targets
but replacing the vague link labels with descriptive text that matches the
referenced documentation.
In `@docs/guides/documentdb/scaling/_index.md`:
- Line 5: The frontmatter identifier for the scaling guide is inconsistent with
the other DocumentDB navigation pages and should be renamed for cohesion. Update
the identifier in the scaling page’s frontmatter from the current
guides-documentdb-scaling value to the dc- prefixed naming pattern used by
sibling pages like dc-configuration and dc-auto-scaling, so the page aligns with
the existing DocumentDB cohort convention.
In `@docs/guides/documentdb/storage-migration/storage-migration.md`:
- Line 31: The link text in the storage migration guide is too vague, so update
the markdown around the KubeDB setup reference to use descriptive text instead
of “here.” Keep the same destination, but make the anchor text clearly indicate
it points to the KubeDB installation/setup instructions so readers know what
they’re clicking.
- Line 13: The link text in the storage migration guide is too vague, so update
the existing markdown link to use more descriptive wording that clearly reflects
the destination. Locate the introductory sentence containing the README link and
replace the generic “here” text with a meaningful label that matches the target
page, keeping the same link destination.
In `@docs/guides/documentdb/volume-expansion/volume-expansion.md`:
- Line 30: The markdown link text in the volume expansion guide is too generic;
replace “here” with descriptive text that identifies the destination. Update the
sentence containing the setup link so the anchor text clearly refers to the
KubeDB installation/setup guide, making the reference understandable without
relying on the URL.
- Line 13: The link text in the introductory sentence is too generic and should
be made more descriptive for accessibility. Update the markdown in the volume
expansion guide near the opening reference to point to the same destination but
replace the vague “here” text with something that describes the linked docs,
using the existing introductory sentence as the location cue.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: a7ed30ed-4d8d-48c0-b400-d1185a54ba5e
📒 Files selected for processing (50)
docs/examples/documentdb/autoscaler/compute/autoscaling-compute-object.yamldocs/examples/documentdb/autoscaler/compute/autoscaling-compute.yamldocs/examples/documentdb/autoscaler/storage/autoscaling-storage-object.yamldocs/examples/documentdb/autoscaler/storage/autoscaling-storage.yamldocs/examples/documentdb/configuration/cluster-config-secret.yamldocs/examples/documentdb/configuration/documentdb-custom-config-secret.yamldocs/examples/documentdb/configuration/standalone-config-inline.yamldocs/examples/documentdb/configuration/standalone-config-secret.yamldocs/examples/documentdb/configuration/standalone-config-tuning.yamldocs/examples/documentdb/reconfigure/cluster-reconfigure-remove.yamldocs/examples/documentdb/reconfigure/cluster-reconfigure.yamldocs/examples/documentdb/reconfigure/standalone-reconfigure.yamldocs/examples/documentdb/restart/cluster-longhorn.yamldocs/examples/documentdb/restart/cluster-restart.yamldocs/examples/documentdb/restart/cluster.yamldocs/examples/documentdb/restart/standalone-restart.yamldocs/examples/documentdb/restart/standalone.yamldocs/examples/documentdb/rotate-authentication/cluster-rotate-auth.yamldocs/examples/documentdb/rotate-authentication/standalone-rotate-auth.yamldocs/examples/documentdb/scaling/horizontal-scaling/cluster-hscale-down.yamldocs/examples/documentdb/scaling/horizontal-scaling/cluster-hscale-up.yamldocs/examples/documentdb/scaling/vertical-scaling/cluster-vertical-scaling.yamldocs/examples/documentdb/scaling/vertical-scaling/standalone-vertical-scaling.yamldocs/examples/documentdb/storage-migration/cluster-storage-migration.yamldocs/examples/documentdb/storage-migration/standalone-storage-migration.yamldocs/examples/documentdb/volume-expansion/cluster-volume-expansion.yamldocs/examples/documentdb/volume-expansion/standalone-volume-expansion.yamldocs/guides/documentdb/_index.mddocs/guides/documentdb/autoscaler/_index.mddocs/guides/documentdb/autoscaler/compute/index.mddocs/guides/documentdb/autoscaler/storage/index.mddocs/guides/documentdb/configuration/_index.mddocs/guides/documentdb/configuration/using-config-file.mddocs/guides/documentdb/failure-and-disaster-recovery/_index.mddocs/guides/documentdb/failure-and-disaster-recovery/failover.mddocs/guides/documentdb/reconfigure/_index.mddocs/guides/documentdb/reconfigure/reconfigure.mddocs/guides/documentdb/restart/_index.mddocs/guides/documentdb/restart/restart.mddocs/guides/documentdb/rotate-authentication/_index.mddocs/guides/documentdb/rotate-authentication/rotate-authentication.mddocs/guides/documentdb/scaling/_index.mddocs/guides/documentdb/scaling/horizontal-scaling/_index.mddocs/guides/documentdb/scaling/horizontal-scaling/horizontal-scaling.mddocs/guides/documentdb/scaling/vertical-scaling/_index.mddocs/guides/documentdb/scaling/vertical-scaling/vertical-scaling.mddocs/guides/documentdb/storage-migration/_index.mddocs/guides/documentdb/storage-migration/storage-migration.mddocs/guides/documentdb/volume-expansion/_index.mddocs/guides/documentdb/volume-expansion/volume-expansion.md
Comment on lines
+1
to
+5
| # Base DocumentDB for COMPUTE autoscaling tests. | ||
| # Resources are deliberately LOW (cpu 500m / memory 1Gi) so a compute autoscaler | ||
| # with minAllowed above these values deterministically recommends a scale-UP to | ||
| # minAllowed (the recommendation floor), which creates a VerticalScaling ops request. | ||
| # local-path is fine for compute tests (no volume expansion involved). |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
This example uses a storage/topology combination the PR already calls out as broken.
The PR notes that multi-replica DocumentDB clusters on local-path stay Ready=False, but this manifest sets replicas: 3 with storageClassName: local-path and even says that combination is fine. Because compute autoscaling needs a Ready database first, readers following this example will get stuck before any VerticalScaling OpsRequest is created.
Also applies to: 15-28
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/examples/documentdb/autoscaler/compute/autoscaling-compute-object.yaml`
around lines 1 - 5, The example in autoscaling-compute-object.yaml uses a broken
multi-replica DocumentDB setup with storageClassName set to local-path, which
prevents the database from reaching Ready before compute autoscaling can
trigger. Update the manifest and its surrounding comments in the DocumentDB
example to avoid the unsupported replicas/local-path combination, using a
storage/topology configuration that is known to become Ready, so the compute
autoscaler can proceed to create the VerticalScaling OpsRequest as intended.
Comment on lines
+7
to
+11
| # IMPORTANT: the DocumentDB storage autoscaler computes the scaled size ONLY from | ||
| # `scalingRules[].threshold` (see GetVolumeForOpsReq) -- the simpler top-level | ||
| # `scalingThreshold` field is NOT read by this controller path. You MUST provide | ||
| # scalingRules or NO ops request is ever created. A single rule with empty | ||
| # appliesUpto applies to all sizes; threshold "50%" grows capacity by 50%. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Align the documented growth math with the captured output.
This example says threshold: 50% grows 2Gi to 3Gi, but the guide later shows the generated size as about 2.85Gi. Those two explanations can't both be true, so readers won't know what size to expect from this rule. Either fix the example/output pair or explain the actual sizing formula.
Also applies to: 29-31
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/examples/documentdb/autoscaler/storage/autoscaling-storage.yaml` around
lines 7 - 11, The autoscaling example in the storage DocumentDB YAML has
inconsistent growth math between the `scalingRules[].threshold` explanation and
the later generated-size output. Update the example and surrounding text to
match the actual sizing behavior used by `GetVolumeForOpsReq`, or explicitly
document the formula that converts a 50% threshold into the shown capacity, so
readers can trace the result from the `scalingRules` values.
Comment on lines
+1
to
+27
| apiVersion: kubedb.com/v1alpha2 | ||
| kind: DocumentDB | ||
| metadata: | ||
| name: documentdb-cls-sample | ||
| namespace: demo | ||
| spec: | ||
| version: 'pg17-0.109.0' | ||
| storageType: Durable | ||
| deletionPolicy: Delete | ||
| replicas: 3 | ||
| configuration: | ||
| secretName: documentdb-custom-config | ||
| podTemplate: | ||
| spec: | ||
| containers: | ||
| - name: documentdb | ||
| resources: | ||
| requests: | ||
| cpu: 500m | ||
| memory: 2Gi | ||
| storage: | ||
| storageClassName: "local-path" | ||
| accessModes: | ||
| - ReadWriteOnce | ||
| resources: | ||
| requests: | ||
| storage: 5Gi |
There was a problem hiding this comment.
🎯 Functional Correctness | 🔴 Critical | 🏗️ Heavy lift
DocumentDB CR specifies PostgreSQL version string pg17-0.109.0.
DocumentDB is a MongoDB-compatible database; the version should reflect a MongoDB/DocumentDB version (e.g., 4.0.0 or a KubeDB-specific DocumentDB version string), not a PostgreSQL version. This pg17-0.109.0 value is clearly carried over from the Postgres guides and will prevent proper cluster provisioning.
🛠️ Suggested correction
- version: 'pg17-0.109.0'
+ version: '5.1.0' # or appropriate KubeDB DocumentDB version📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| apiVersion: kubedb.com/v1alpha2 | |
| kind: DocumentDB | |
| metadata: | |
| name: documentdb-cls-sample | |
| namespace: demo | |
| spec: | |
| version: 'pg17-0.109.0' | |
| storageType: Durable | |
| deletionPolicy: Delete | |
| replicas: 3 | |
| configuration: | |
| secretName: documentdb-custom-config | |
| podTemplate: | |
| spec: | |
| containers: | |
| - name: documentdb | |
| resources: | |
| requests: | |
| cpu: 500m | |
| memory: 2Gi | |
| storage: | |
| storageClassName: "local-path" | |
| accessModes: | |
| - ReadWriteOnce | |
| resources: | |
| requests: | |
| storage: 5Gi | |
| apiVersion: kubedb.com/v1alpha2 | |
| kind: DocumentDB | |
| metadata: | |
| name: documentdb-cls-sample | |
| namespace: demo | |
| spec: | |
| version: '5.1.0' # or appropriate KubeDB DocumentDB version | |
| storageType: Durable | |
| deletionPolicy: Delete | |
| replicas: 3 | |
| configuration: | |
| secretName: documentdb-custom-config | |
| podTemplate: | |
| spec: | |
| containers: | |
| - name: documentdb | |
| resources: | |
| requests: | |
| cpu: 500m | |
| memory: 2Gi | |
| storage: | |
| storageClassName: "local-path" | |
| accessModes: | |
| - ReadWriteOnce | |
| resources: | |
| requests: | |
| storage: 5Gi |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/examples/documentdb/configuration/cluster-config-secret.yaml` around
lines 1 - 27, The DocumentDB sample is using a PostgreSQL-style version value in
the DocumentDB manifest, so update the spec.version in the DocumentDB example to
a valid MongoDB/DocumentDB version string instead of the copied pg17-0.109.0
value. Use the DocumentDB sample resource in the cluster-config-secret example
and replace the version with the correct KubeDB-supported DocumentDB version
that matches the rest of the guide.
Comment on lines
+1
to
+9
| apiVersion: v1 | ||
| kind: Secret | ||
| metadata: | ||
| name: documentdb-custom-config | ||
| namespace: demo | ||
| stringData: | ||
| user.conf: | | ||
| max_connections=250 | ||
| work_mem=8MB |
There was a problem hiding this comment.
🎯 Functional Correctness | 🔴 Critical | 🏗️ Heavy lift
DocumentDB config Secret contains PostgreSQL settings, not DocumentDB/MongoDB settings.
The user.conf key holds max_connections=250 and work_mem=8MB, which are PostgreSQL parameters. DocumentDB (MongoDB-compatible) uses an entirely different configuration surface (e.g., net.maxIncomingConnections, storage.wiredTiger.engineConfig.cacheSizeGB, operationProfiling.slowOpThresholdMs). Users applying this Secret will have invalid configuration or no effect.
This appears to be a copy-paste carryover from the Postgres guides that was not adapted for DocumentDB.
🛠️ Proposed fix (illustrative DocumentDB parameters)
stringData:
user.conf: |
net.maxIncomingConnections=250
storage.wiredTiger.engineConfig.cacheSizeGB=0.5
operationProfiling.slowOpThresholdMs=100🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/examples/documentdb/configuration/documentdb-custom-config-secret.yaml`
around lines 1 - 9, The Secret example in documentdb-custom-config-secret.yaml
is using PostgreSQL-only settings in user.conf, so update the DocumentDB example
to use MongoDB-compatible DocumentDB parameters instead. Replace the current
max_connections and work_mem entries with valid DocumentDB-style options in the
Secret manifest, keeping the change localized to the user.conf block so the
documentdb-custom-config example matches the rest of the DocumentDB guides.
Comment on lines
+7
to
+12
| version: 'pg17-0.109.0' | ||
| storageType: Durable | ||
| deletionPolicy: Delete | ||
| replicas: 1 | ||
| configuration: | ||
| secretName: documentdb-custom-config |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Standalone bootstrap issue noted in PR objectives.
The PR objectives explicitly state "standalone (replicas: 1) DocumentDB does not bootstrap on this build." Including this example may mislead users into thinking it works. Consider adding a prominent warning or omitting this example until the operator issue is resolved.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/examples/documentdb/configuration/standalone-config-secret.yaml` around
lines 7 - 12, The standalone DocumentDB example in this config is misleading
because the PR notes that replicas: 1 does not bootstrap on this build. Update
the example to avoid implying it works as-is by either removing the
standalone-config-secret.yaml example or adding a prominent warning in the
example/docs near the configuration block that explicitly states standalone
bootstrap is currently broken. Make sure the guidance is tied to this DocumentDB
standalone configuration example so users don’t treat it as a supported setup.
Comment on lines
+119
to
+125
| Reconnect to the **new** primary and read the document written before the failover — it is | ||
| intact: | ||
|
|
||
| ```bash | ||
| $ kubectl exec -n demo documentdb-cls-sample-2 -c documentdb -- \ | ||
| mongosh "mongodb://default_user:${PASS}@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true" \ | ||
| --quiet --eval 'printjson(db.getSiblingDB("failover").coll.findOne({k:"before-failover"}));' |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Don't hardcode documentdb-cls-sample-2 as the post-failover primary.
Leader election is nondeterministic, so another pod can become primary on a different run. This makes the verification step brittle and can send readers to a standby instead of the elected leader.
Suggested doc fix
-Reconnect to the **new** primary and read the document written before the failover — it is
+Reconnect to the **current** primary and read the document written before the failover — it is
intact:
```bash
-$ kubectl exec -n demo documentdb-cls-sample-2 -c documentdb -- \
+$ NEW_PRIMARY=$(kubectl get pods -n demo -l app.kubernetes.io/instance=documentdb-cls-sample,kubedb.com/role=primary -o jsonpath='{.items[0].metadata.name}')
+$ kubectl exec -n demo "${NEW_PRIMARY}" -c documentdb -- \
mongosh "mongodb://default_user:${PASS}`@localhost`:10260/?tls=true&tlsAllowInvalidCertificates=true" \
--quiet --eval 'printjson(db.getSiblingDB("failover").coll.findOne({k:"before-failover"}));'</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
Reconnect to the **current** primary and read the document written before the failover — it is
intact:
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/guides/documentdb/failure-and-disaster-recovery/failover.md` around
lines 119 - 125, The failover verification step hardcodes a specific pod name as
the primary, which makes the docs brittle because leader election can choose a
different pod. Update the example around the kubectl exec/mongosh command to
determine the elected primary dynamically first, using the same role-based pod
selection pattern shown in the comment, then exec into that pod and run the read
check so the step always targets the current primary.
Comment on lines
+148
to
+153
| $ PASS=$(kubectl get secret -n demo documentdb-cls-sample-auth -o jsonpath='{.data.password}' | base64 -d) | ||
| $ kubectl exec -n demo documentdb-cls-sample-0 -c documentdb -- \ | ||
| mongosh "mongodb://default_user:${PASS}@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true" \ | ||
| --quiet --eval 'db.runCommand({ ping: 1 })' | ||
| { ok: 1 } | ||
| ``` |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Remove insecure TLS verification bypass from example command.
The mongosh command uses tlsAllowInvalidCertificates=true, which disables certificate validation. Documentation examples should promote secure practices. Replace with proper certificate handling or document that this is only for demo purposes with a security warning.
- mongosh "mongodb://default_user:${PASS}`@localhost`:10260/?tls=true&tlsAllowInvalidCertificates=true" \
+ mongosh "mongodb://default_user:${PASS}`@localhost`:10260/?tls=true" \Or add an explicit warning that this flag is demo-only and insecure for production.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| $ PASS=$(kubectl get secret -n demo documentdb-cls-sample-auth -o jsonpath='{.data.password}' | base64 -d) | |
| $ kubectl exec -n demo documentdb-cls-sample-0 -c documentdb -- \ | |
| mongosh "mongodb://default_user:${PASS}@localhost:10260/?tls=true&tlsAllowInvalidCertificates=true" \ | |
| --quiet --eval 'db.runCommand({ ping: 1 })' | |
| { ok: 1 } | |
| ``` | |
| $ PASS=$(kubectl get secret -n demo documentdb-cls-sample-auth -o jsonpath='{.data.password}' | base64 -d) | |
| $ kubectl exec -n demo documentdb-cls-sample-0 -c documentdb -- \ | |
| mongosh "mongodb://default_user:${PASS}`@localhost`:10260/?tls=true" \ | |
| --quiet --eval 'db.runCommand({ ping: 1 })' | |
| { ok: 1 } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/guides/documentdb/restart/restart.md` around lines 148 - 153, The
mongosh example in the DocumentDB restart guide uses an insecure TLS
verification bypass, so update the command in the restart documentation to avoid
tlsAllowInvalidCertificates=true or clearly mark it as demo-only with a security
warning. If the example must remain runnable, adjust the connection flow in the
documented mongosh command to use proper certificate handling instead of
disabling validation, and keep the guidance aligned with secure usage.
| section_menu_id: guides | ||
| --- | ||
|
|
||
| > New to KubeDB? Please start [here](/docs/README.md). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Replace the generic here links with descriptive text.
These two links trip MD059 and are less accessible in navigation and screen-reader contexts. Please name the destination explicitly instead of using here.
Also applies to: 41-41
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 13-13: Link text should be descriptive
(MD059, descriptive-link-text)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/guides/documentdb/rotate-authentication/rotate-authentication.md` at
line 13, The markdown in the rotate-authentication guide uses generic “here”
link text, which triggers MD059 and hurts accessibility. Update the link text in
the affected intro and the later reference so each points to the same
destinations with descriptive wording that names what the reader will find. Keep
the existing targets in the markdown, and adjust the surrounding sentence in the
guide content so the link text is explicit instead of “here”.
Source: Linters/SAST tools
| section_menu_id: guides | ||
| --- | ||
|
|
||
| > New to KubeDB? Please start [here](/docs/README.md). |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Use descriptive link text here.
[here] trips MD059 and is harder to understand out of context. Naming the destination directly keeps these docs more accessible.
Also applies to: 30-30
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 13-13: Link text should be descriptive
(MD059, descriptive-link-text)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/guides/documentdb/scaling/vertical-scaling/vertical-scaling.md` at line
13, The markdown link text in the document intro uses a vague “here” label,
which triggers the lint issue and is less accessible. Update the link in the
opening sentence to use descriptive text that names the destination directly,
and apply the same fix to the other matching occurrence mentioned in the review
so the docs read clearly out of context.
Source: Linters/SAST tools
Comment on lines
+134
to
+144
| The same `DocumentDBOpsRequest` works for a standalone (`replicas: 1`) instance — point | ||
| `spec.databaseRef.name` at the standalone database (`documentdb-sa-sample`) and address the | ||
| `documentdb` (and optionally `coordinator`) container under `spec.verticalScaling`. | ||
|
|
||
| > [!NOTE] | ||
| > On the build used to capture this guide (`pg17-0.109.0`), standalone instances did not finish | ||
| > bootstrapping (the standalone PetSet omits the `documentdb-coordinator` sidecar, so the | ||
| > internal PostgreSQL is never initialized and the database never reaches `Ready`). Because | ||
| > OpsRequests are admitted only against a `Ready` database, the standalone variant could not be | ||
| > exercised live; the cluster procedure above applies verbatim once a standalone instance is | ||
| > healthy. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
The standalone instructions contradict the known topology.
These lines tell readers they can scale coordinator, but the note immediately below says standalone PetSets omit the documentdb-coordinator sidecar. Please scope the standalone path to spec.verticalScaling.documentdb only; otherwise the prose conflicts with the standalone example manifest and points users at a non-existent container.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/guides/documentdb/scaling/vertical-scaling/vertical-scaling.md` around
lines 134 - 144, The standalone scaling guidance conflicts with the documented
standalone topology by mentioning the optional `coordinator` container even
though standalone PetSets omit `documentdb-coordinator`. Update the standalone
instructions in the vertical scaling guide so they only reference
`spec.databaseRef.name` pointing to `documentdb-sa-sample` and
`spec.verticalScaling.documentdb`, and remove any standalone mention of
`coordinator` from that path while leaving the cluster-wide
`DocumentDBOpsRequest` guidance intact.
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
1 participant
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.
What
User-facing guides for KubeDB managed DocumentDB (MongoDB wire-protocol compatible, PostgreSQL-backed), modeled on the Postgres guides. All verification uses
mongoshover port10260(the MongoDB surface) rather thanpsqlon the internal9712.New guides under
docs/guides/documentdb/:AddRaftNode/RemoveRaftNode)Each guide embeds real output captured from a running cluster (ops-request status conditions, pod roles, PVC sizes, before/after secret rotation,
mongosh { ok: 1 }pings). Example manifests are included underdocs/examples/documentdb/.Notes for reviewers
The guides were captured on a live cluster running DocumentDBVersion
pg17-0.109.0. While writing them I hit three operator issues:replicas: 1) DocumentDB never bootstraps (no coordinator sidecar,SKIP_INIT_DATA=true→ noinitdb). The standalone topology cannot be provisioned on this build, so standalone sections document the intended procedure with an explicit caveat, and the live captures use the clustered topology.local-pathstaysReady=False(standbys cannotpg_basebackupdue to adfmount check). The cluster captures therefore uselonghorn; this is called out in the Volume Expansion and Storage Migration guides.Reconfigurefails (references a custom-config Secret the operator never creates →FailedMount). The Reconfigure guide documents the intended apply/remove flow plus the captured failure and a recovery caution.Once these are fixed, the standalone captures and the Reconfigure success path can be filled in.