Add Branching Same Cluster Docs - #1042
Open
anisurrahman75 wants to merge 3 commits into
Open
Conversation
Signed-off-by: Anisur Rahman <anisur@appscode.com>
|
| GitGuardian id | GitGuardian status | Secret | Commit | Filename | |
|---|---|---|---|---|---|
| 35844849 | Triggered | PostgreSQL Credentials | 9f36cd2 | docs/guides/postgres/branch/customization/index.md | View secret |
🛠 Guidelines to remediate hardcoded secrets
- Understand the implications of revoking this secret by investigating where it is used in your code.
- Replace and store your secret safely. Learn here the best practices.
- Revoke and rotate this secret.
- If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.
To avoid such incidents in the future consider
- following these best practices for managing and storing secrets including API keys and other credentials
- install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.
🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.
📝 WalkthroughWalkthroughAdded PostgreSQL Branching documentation for the Branch resource, same-cluster workflows, customization options, lifecycle behavior, snapshot requirements, cleanup policies, and example manifests. ChangesPostgreSQL Branching
Estimated code review effort: 3 (Moderate) | ~25 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 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: 10
🤖 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/guides/postgres/branch/customization/examples/dev-branch-vsc.yaml`:
- Around line 7-17: Update the volumeSnapshotClassName in the customization
example to use a snapshot class backed by the same CSI driver as the gp3
storageClassName, or change the source and target storage classes consistently
to TopoLVM if that is the intended guide scenario.
In `@docs/guides/postgres/branch/customization/index.md`:
- Around line 357-358: Update the row-count example near the kubectl psql
command so its expected value is independent of the earlier source insert: use
1001, unless this section explicitly adds that mutation as a prerequisite. Keep
the surrounding customization steps unchanged.
- Line 14: Update the introductory link in the documentation to replace the
generic “here” text with descriptive text identifying the KubeDB getting-started
or README destination, while preserving the existing link target.
In `@docs/guides/postgres/branch/overview/index.md`:
- Line 14: Replace the non-descriptive “here” link text with “the KubeDB setup
guide” at docs/guides/postgres/branch/overview/index.md:14,
docs/guides/postgres/branch/same-cluster/index.md:14, and
docs/guides/postgres/branch/same-cluster/index.md:30, preserving the existing
destination URL.
- Around line 62-63: Correct the inheritance wording in
docs/guides/postgres/branch/overview/index.md lines 62-63 by stating that source
fields are inherited by default, with overrides from spec.target plus
spec.configSecret, spec.resetRootPassword, and spec.postActions. Update
docs/guides/postgres/branch/same-cluster/index.md lines 225-231 to replace
“Everything else” with the same default-inheritance and exception wording; both
sites require documentation changes.
In `@docs/guides/postgres/branch/same-cluster/index.md`:
- Around line 441-469: The teardown verification uses resources not created by
this walkthrough. Update the deletion command and all subsequent resource checks
to consistently reference the demonstrated dev-branch and dev-postgres
resources, including the PVC, Secret, Job, and VolumeSnapshot checks, and remove
the post-action Job check unless the walkthrough creates it.
- Around line 475-476: Correct the sample outputs in the branch same-cluster
guide: the initial source count remains 1000, the source-only insert makes the
source 1001, and dev-branch-keep created afterward must also start at 1001.
Update the outputs at both referenced command examples consistently, or add the
missing insert only if the documented workflow requires a 1002 count.
- Around line 31-33: Update the manual Branch CRD installation command in the
guide to reference the CRD file from the installed KubeDB release or its
matching version tag instead of refs/heads/master, keeping the command
compatible with the release installed earlier in the guide.
In `@docs/guides/postgres/concepts/branch.md`:
- Line 13: Update the introductory link text in the “New to KubeDB?” sentence to
describe its destination instead of using the generic “here” label, while
preserving the existing /docs/README.md target.
- Around line 118-121: Update the issuerRef documentation in the branch concepts
guide to distinguish cert-manager scope accurately: an Issuer must exist in the
target namespace, while a ClusterIssuer is cluster-scoped and is not
namespace-bound. Preserve the existing behavior details about fresh
certificates, TLS-enabled sources, and when issuerRef is ignored.
🪄 Autofix
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: ce92e1b7-cc0c-4576-bc77-b9d27b8018d4
⛔ Files ignored due to path filters (1)
docs/guides/postgres/branch/overview/images/branch_overview.svgis excluded by!**/*.svg
📒 Files selected for processing (14)
docs/guides/postgres/branch/_index.mddocs/guides/postgres/branch/customization/examples/dev-branch-ha.yamldocs/guides/postgres/branch/customization/examples/dev-branch-masked.yamldocs/guides/postgres/branch/customization/examples/dev-branch-refresh.yamldocs/guides/postgres/branch/customization/examples/dev-branch-vsc.yamldocs/guides/postgres/branch/customization/examples/dev-branch-xns.yamldocs/guides/postgres/branch/customization/examples/sample-postgres-ha.yamldocs/guides/postgres/branch/customization/index.mddocs/guides/postgres/branch/overview/index.mddocs/guides/postgres/branch/same-cluster/examples/dev-branch-keep.yamldocs/guides/postgres/branch/same-cluster/examples/dev-branch.yamldocs/guides/postgres/branch/same-cluster/examples/sample-postgres.yamldocs/guides/postgres/branch/same-cluster/index.mddocs/guides/postgres/concepts/branch.md
| 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.
Replace here with text that identifies the destination. This improves link navigation and satisfies the markdown lint rule.
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 14-14: 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/postgres/branch/customization/index.md` at line 14, Update the
introductory link in the documentation to replace the generic “here” text with
descriptive text identifying the KubeDB getting-started or README destination,
while preserving the existing link target.
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
Replace non-descriptive setup link text.
docs/guides/postgres/branch/overview/index.md#L14-L14: replace[here]with[the KubeDB setup guide].docs/guides/postgres/branch/same-cluster/index.md#L14-L14: replace[here]with[the KubeDB setup guide].docs/guides/postgres/branch/same-cluster/index.md#L30-L30: replace[here]with[the KubeDB setup guide].
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 14-14: Link text should be descriptive
(MD059, descriptive-link-text)
📍 Affects 2 files
docs/guides/postgres/branch/overview/index.md#L14-L14(this comment)docs/guides/postgres/branch/same-cluster/index.md#L14-L14docs/guides/postgres/branch/same-cluster/index.md#L30-L30
🤖 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/postgres/branch/overview/index.md` at line 14, Replace the
non-descriptive “here” link text with “the KubeDB setup guide” at
docs/guides/postgres/branch/overview/index.md:14,
docs/guides/postgres/branch/same-cluster/index.md:14, and
docs/guides/postgres/branch/same-cluster/index.md:30, preserving the existing
destination URL.
Source: Linters/SAST tools
Comment on lines
+31
to
+33
|
|
||
| ```bash | ||
| kubectl apply -f https://raw.githubusercontent.com/kubedb/apimachinery/refs/heads/master/crds/courier.kubedb.com_branches.yaml |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== file location and size =="
fd -a 'index.md' . | grep '/docs/guides/postgres/branch/same-cluster/index.md' || true
wc -l docs/guides/postgres/branch/same-cluster/index.md 2>/dev/null || true
echo "== relevant documentation excerpt =="
sed -n '1,80p' docs/guides/postgres/branch/same-cluster/index.md 2>/dev/null || true
echo "== version metadata / docs config =="
fd -i 'mkdocs|docusaurus|package.json|hugo|config' docs .github 2>/dev/null | sed -n '1,120p'
git ls-files docs | rg '(^|/)config\.(ya?ml|toml|json)$|mkdocs\.ya?ml|docusaurus\.config|package\.json|vercel\.json|README' | sed -n '1,120p'
echo "== references to manual CRD URL in docs/github =="
rg -n "courier\.kubedb\.com_branches\.yaml|refs/heads/master|kubectl apply -f .*branch" docs .github 2>/dev/null || true
echo "== git diff/stat context if available =="
git diff --stat 2>/dev/null || true
git diff -- docs/guides/postgres/branch/same-cluster/index.md 2>/dev/null | sed -n '1,200p' || trueRepository: kubedb/docs
Length of output: 17244
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== repository files around docs =="
find docs -maxdepth 4 -type f | sort | sed -n '1,200p'
echo "== docs/guides top-level files =="
find docs/guides -maxdepth 3 -type f | sort | sed -n '1,200p'Repository: kubedb/docs
Length of output: 19028
Pin the manual Branch CRD to the installed KubeDB release.
This guide installs KubeDB and then adds the Branch CRD manually when Courier is added to an existing install. The command reads from refs/heads/master, so a user can apply a CRD schema that differs from the installed operator version. Use the CRD file or version tag for the installed release instead.
🤖 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/postgres/branch/same-cluster/index.md` around lines 31 - 33,
Update the manual Branch CRD installation command in the guide to reference the
CRD file from the installed KubeDB release or its matching version tag instead
of refs/heads/master, keeping the command compatible with the release installed
earlier in the guide.
| 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.
Replace [here] with text that identifies the destination.
Suggested wording
-> New to KubeDB? Please start [here](/docs/README.md).
+> New to KubeDB? Start with the [KubeDB documentation](/docs/README.md).📝 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
| > New to KubeDB? Please start [here](/docs/README.md). | |
| > New to KubeDB? Start with the [KubeDB documentation](/docs/README.md). |
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[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/postgres/concepts/branch.md` at line 13, Update the introductory
link text in the “New to KubeDB?” sentence to describe its destination instead
of using the generic “here” label, while preserving the existing /docs/README.md
target.
Source: Linters/SAST tools
|
Visit the preview URL for this PR (updated for commit ec83e66): https://kubedb-v2-hugo--pr1042-branching-ud7csj22.web.app (expires Thu, 13 Aug 2026 12:39:20 GMT) 🔥 via Firebase Hosting GitHub Action 🌎 Sign: 0f29ae8ae0bd54a99bf2b223b6833be47acd5943 |
Switch every example from the `gp3` StorageClass to `topolvm-provisioner-thin`, so the StorageClass, the VolumeSnapshotClass and the CSI driver are one consistent chain. `gp3` was an EKS-era fixture name aliased onto TopoLVM on the test cluster, so the docs showed an AWS EBS name whose provisioner printed `topolvm.io`. Every command output was re-captured from a full re-run on the new class. Fix three regressions introduced when the guide was split into a walkthrough and a customization page: - the Delete-policy section tore down `dev-branch-masked`, which had moved to the customization page, so its commands returned NotFound and demonstrated nothing - row counts read 1002 where the walkthrough's own arithmetic gives 1001; the extra row came from the refresh section, which also moved - the cross-namespace row count contradicted the "each section is independent" claim. The sections do run in sequence, so the claim was corrected rather than the number Other corrections: - post-action Jobs carry `courier.kubedb.com/branch`, not `app.kubernetes.io/instance`; the troubleshooting selector matched nothing - spell out that `resetRootPassword` and `postActions` also change what the branch inherits, not only the fields under `spec.target` - separate `Issuer` (namespace-scoped, must live in the target namespace) from `ClusterIssuer` in the CRD reference - add a `kubectl explain branch.spec.postActions` check so a reader with a pre-rename Branch CRD finds out before following the guide Signed-off-by: Anisur Rahman <anisur@appscode.com>
Member
Author
|
Pushed Applied
Not applied, with reasons
Also found while re-checking (not in the review): post-action Jobs are labelled @coderabbitai full review |
|
✏️ Learnings added
✅ Action performedFull review finished. |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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/guides/postgres/branch/same-cluster/index.md`:
- Around line 40-46: Update the kubectl explain command in the documentation
snippet to run without piping through head, so the output confirms whether
branch.spec.postActions exists and failures are not masked. Keep the surrounding
CRD guidance unchanged.
- Around line 464-492: Update the teardown walkthrough around kubectl delete
branch so it explicitly waits for asynchronous Courier reconciliation and
finalizer cleanup before showing the target Postgres, Secret, PVC, and
VolumeSnapshot deletion results. Also update the dev-branch-keep section at
docs/guides/postgres/branch/same-cluster/index.md:507-520 to wait for branch
readiness before capturing the UID, then wait for orphan reconciliation before
showing ownership metadata removal.
🪄 Autofix
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: 302f2f4f-a664-4afc-b5c4-a981fd4e9e4d
📒 Files selected for processing (13)
docs/guides/postgres/branch/customization/examples/dev-branch-ha.yamldocs/guides/postgres/branch/customization/examples/dev-branch-masked.yamldocs/guides/postgres/branch/customization/examples/dev-branch-refresh.yamldocs/guides/postgres/branch/customization/examples/dev-branch-vsc.yamldocs/guides/postgres/branch/customization/examples/dev-branch-xns.yamldocs/guides/postgres/branch/customization/examples/sample-postgres-ha.yamldocs/guides/postgres/branch/customization/index.mddocs/guides/postgres/branch/overview/index.mddocs/guides/postgres/branch/same-cluster/examples/dev-branch-keep.yamldocs/guides/postgres/branch/same-cluster/examples/dev-branch.yamldocs/guides/postgres/branch/same-cluster/examples/sample-postgres.yamldocs/guides/postgres/branch/same-cluster/index.mddocs/guides/postgres/concepts/branch.md
🚧 Files skipped from review as they are similar to previous changes (8)
- docs/guides/postgres/branch/customization/examples/dev-branch-refresh.yaml
- docs/guides/postgres/branch/customization/examples/dev-branch-masked.yaml
- docs/guides/postgres/branch/customization/examples/sample-postgres-ha.yaml
- docs/guides/postgres/branch/customization/examples/dev-branch-vsc.yaml
- docs/guides/postgres/branch/same-cluster/examples/dev-branch.yaml
- docs/guides/postgres/branch/customization/index.md
- docs/guides/postgres/branch/overview/index.md
- docs/guides/postgres/concepts/branch.md
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 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/guides/postgres/branch/customization/index.md`:
- Line 268: Update the command examples around the kubectl snippets and the
corresponding sections near the other affected locations so Markdown command
fences comply with MD014: remove the leading “$” prompt from commands, or place
each command and its output together in one code fence. For the snippet with no
output, remove the unnecessary command fence or adjust it to contain only the
command without a prompt.
- Line 471: Add the topolvm-vsc-explicit VolumeSnapshotClass prerequisite to
docs/guides/postgres/branch/customization/index.md before applying the example,
and document the same prerequisite for
docs/guides/postgres/branch/customization/examples/dev-branch-vsc.yaml at line
7. Ensure the guide also accounts for the hard-coded topolvm-provisioner-thin
storage class required by the Branch example.
In `@docs/guides/postgres/concepts/branch.md`:
- Line 55: Align the manifest’s storage resources by updating storageClassName
and volumeSnapshotClassName to a matching CSI chain. Prefer the documented
TopoLVM pair, including topolvm-provisioner-thin and its corresponding snapshot
class, and apply the same change to both occurrences.
- Around line 210-211: Update docs/guides/postgres/concepts/branch.md lines
210-211 to describe status.resources as the references tracked in that field,
moving target, snapshot, and deletion-policy behavior into the policy-specific
text. Update docs/guides/postgres/branch/overview/index.md line 123 to include
the optional configSecret entry in the resource list.
🪄 Autofix
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: ae9fa5c4-4d16-4dbb-a3d5-011ffd7114ac
⛔ Files ignored due to path filters (1)
docs/guides/postgres/branch/overview/images/branch_overview.svgis excluded by!**/*.svg
📒 Files selected for processing (14)
docs/guides/postgres/branch/_index.mddocs/guides/postgres/branch/customization/examples/dev-branch-ha.yamldocs/guides/postgres/branch/customization/examples/dev-branch-masked.yamldocs/guides/postgres/branch/customization/examples/dev-branch-refresh.yamldocs/guides/postgres/branch/customization/examples/dev-branch-vsc.yamldocs/guides/postgres/branch/customization/examples/dev-branch-xns.yamldocs/guides/postgres/branch/customization/examples/sample-postgres-ha.yamldocs/guides/postgres/branch/customization/index.mddocs/guides/postgres/branch/overview/index.mddocs/guides/postgres/branch/same-cluster/examples/dev-branch-keep.yamldocs/guides/postgres/branch/same-cluster/examples/dev-branch.yamldocs/guides/postgres/branch/same-cluster/examples/sample-postgres.yamldocs/guides/postgres/branch/same-cluster/index.mddocs/guides/postgres/concepts/branch.md
| # clusterName omitted — same-cluster branch | ||
| namespace: demo | ||
| name: dev-postgres | ||
| storageClassName: gp3 |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Align the example with one CSI storage chain.
The manifest uses storageClassName: gp3 but pins volumeSnapshotClassName: topolvm-vsc-explicit. This page requires both resources to use the same CSI driver. The example can fail during snapshot restore and does not match the documented topolvm-provisioner-thin chain. Use matching TopoLVM resources, or replace both values with matching resources from the gp3 storage stack.
Suggested alignment
- storageClassName: gp3
+ storageClassName: topolvm-provisioner-thinAlso applies to: 86-86
🤖 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/postgres/concepts/branch.md` at line 55, Align the manifest’s
storage resources by updating storageClassName and volumeSnapshotClassName to a
matching CSI chain. Prefer the documented TopoLVM pair, including
topolvm-provisioner-thin and its corresponding snapshot class, and apply the
same change to both occurrences.
Comment on lines
+210
to
+211
| - `resources` — the objects the branch owns, which is exactly what teardown removes: | ||
| `authSecret`, `clonedPVCs`, `configSecret`, and the current generation's `postActionJob`. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Align the status.resources documentation across both pages.
The two pages do not describe the same status contract.
docs/guides/postgres/concepts/branch.md#L210-L211: describestatus.resourcesas the references tracked in that field. Keep target, snapshot, and deletion-policy behavior in the policy-specific text.docs/guides/postgres/branch/overview/index.md#L123-L123: add the optionalconfigSecretentry to the resource list.
🧰 Tools
🪛 LanguageTool
[style] ~210-~210: Consider an alternative for the overused word “exactly”.
Context: ...— the objects the branch owns, which is exactly what teardown removes: authSecret, ...
(EXACTLY_PRECISELY)
📍 Affects 2 files
docs/guides/postgres/concepts/branch.md#L210-L211(this comment)docs/guides/postgres/branch/overview/index.md#L123-L123
🤖 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/postgres/concepts/branch.md` around lines 210 - 211, Update
docs/guides/postgres/concepts/branch.md lines 210-211 to describe
status.resources as the references tracked in that field, moving target,
snapshot, and deletion-policy behavior into the policy-specific text. Update
docs/guides/postgres/branch/overview/index.md line 123 to include the optional
configSecret entry in the resource list.
Signed-off-by: Anisur Rahman <anisur@appscode.com>
Member
Author
|
Addressed the two follow-up CodeRabbit findings in ec83e66:
Validation: live CRD check, @coderabbitai full review |
|
✅ Action performedFull review finished. |
There was a problem hiding this comment.
Actionable comments posted: 6
♻️ Duplicate comments (1)
docs/guides/postgres/concepts/branch.md (1)
55-55: 🗄️ Data Integrity & Integration | 🟠 MajorUse a matching StorageClass and VolumeSnapshotClass.
This example uses
gp3forspec.target.storageClassNameandtopolvm-vsc-explicitforspec.volumeSnapshotClassName. The same-cluster guide identifiestopolvm-vsc-explicitas a TopoLVM class. A snapshot can be restored only by the CSI driver that created it. Use a matching pair.Proposed alignment
- storageClassName: gp3 + storageClassName: topolvm-provisioner-thinAlso applies to: 86-86
🤖 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/postgres/concepts/branch.md` at line 55, Align the example’s storage classes so spec.target.storageClassName and spec.volumeSnapshotClassName use a matching CSI driver pair; update both occurrences of the current gp3 value consistently with the corresponding VolumeSnapshotClass.
🤖 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/guides/postgres/branch/customization/examples/dev-branch-masked.yaml`:
- Around line 40-42: Update the customization example around the customer UPDATE
so it either masks full_name along with email and phone, or narrows the
accompanying anonymization wording and verification output to only the fields
actually changed. Ensure the documented result does not imply that unchanged
personal-data columns are protected.
In `@docs/guides/postgres/branch/customization/index.md`:
- Line 514: Update the post-action troubleshooting guidance in the Branch
failure row to account for the 600-second ttlSecondsAfterFinished retention
window, or remove that setting from the debugging example so failed Job logs
remain available for investigation.
- Around line 525-527: Update the cleanup commands in the tutorial to delete
only the named Branch resources created by this section, including
dev-branch-masked, dev-branch-refresh, dev-branch-xns, dev-branch-ha, and
dev-branch-vsc, instead of using --all. Remove ns dev only when it is
tutorial-created, and replace any immediate delete --wait=false cleanup with a
delete followed by kubectl wait --for=delete.
- Around line 228-236: Add validated kubectl wait --for=condition=Ready steps
after applying resources and before dependent commands in the refresh,
cross-namespace, VolumeSnapshotClass, and HA examples. In the HA flow, wait for
sample-postgres-ha to become Ready before applying dev-branch-ha, while
preserving the existing command order and resource references.
In `@docs/guides/postgres/branch/same-cluster/index.md`:
- Line 410: Revise the verification statement near the walkthrough’s 1,000-row
query to claim only that all 1,000 rows are present on the branch. Remove the
“byte-for-byte” and exact source-state identity assertion, reflecting that the
source remains writable during snapshot creation.
In `@docs/guides/postgres/concepts/branch.md`:
- Around line 19-23: Update the Branch overview to describe restoring volumes
from snapshots rather than universally cloning them copy-on-write. Qualify the
near-instant provisioning and low additional storage benefits as dependent on
the CSI driver supporting copy-on-write restores, while preserving the
declarative branching workflow.
---
Duplicate comments:
In `@docs/guides/postgres/concepts/branch.md`:
- Line 55: Align the example’s storage classes so spec.target.storageClassName
and spec.volumeSnapshotClassName use a matching CSI driver pair; update both
occurrences of the current gp3 value consistently with the corresponding
VolumeSnapshotClass.
🪄 Autofix
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: 5dbdbeea-5c20-4d3e-ba14-1bc09c7dcd08
⛔ Files ignored due to path filters (1)
docs/guides/postgres/branch/overview/images/branch_overview.svgis excluded by!**/*.svg
📒 Files selected for processing (14)
docs/guides/postgres/branch/_index.mddocs/guides/postgres/branch/customization/examples/dev-branch-ha.yamldocs/guides/postgres/branch/customization/examples/dev-branch-masked.yamldocs/guides/postgres/branch/customization/examples/dev-branch-refresh.yamldocs/guides/postgres/branch/customization/examples/dev-branch-vsc.yamldocs/guides/postgres/branch/customization/examples/dev-branch-xns.yamldocs/guides/postgres/branch/customization/examples/sample-postgres-ha.yamldocs/guides/postgres/branch/customization/index.mddocs/guides/postgres/branch/overview/index.mddocs/guides/postgres/branch/same-cluster/examples/dev-branch-keep.yamldocs/guides/postgres/branch/same-cluster/examples/dev-branch.yamldocs/guides/postgres/branch/same-cluster/examples/sample-postgres.yamldocs/guides/postgres/branch/same-cluster/index.mddocs/guides/postgres/concepts/branch.md
Comment on lines
+40
to
+42
| UPDATE customers | ||
| SET email = 'user' || id || '@example.invalid', | ||
| phone = '+1-555-0000'; |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Do not label this action as complete anonymization.
The SQL changes only email and phone. It leaves full_name unchanged, while the guide calls the result “anonymized” and displays that field in the verification output. If the source contains real names, this branch still exposes personal data. Mask all intended personal-data columns or narrow the text to the fields changed by this action.
🤖 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/postgres/branch/customization/examples/dev-branch-masked.yaml`
around lines 40 - 42, Update the customization example around the customer
UPDATE so it either masks full_name along with email and phone, or narrows the
accompanying anonymization wording and verification output to only the fields
actually changed. Ensure the documented result does not imply that unchanged
personal-data columns are protected.
Comment on lines
+228
to
+236
| Create it and wait for the first copy: | ||
|
|
||
| ```bash | ||
| $ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/branch/customization/examples/dev-branch-refresh.yaml | ||
| branch.courier.kubedb.com/dev-branch-refresh created | ||
|
|
||
| $ kubectl exec -n demo dev-postgres-refresh-0 -c postgres -- psql -U postgres -tAc "SELECT count(*) FROM customers;" | ||
| 1001 | ||
| ``` |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file="docs/guides/postgres/branch/customization/index.md"
if [ -f "$file" ]; then
echo "== file exists =="
wc -l "$file"
echo "== relevant line ranges =="
sed -n '210,250p;336,365p;371,395p;479,512p' "$file" | nl -ba
else
echo "file not found: $file"
fi
echo "== branch wait/readiness occurrences =="
grep -nE 'kubectl wait|condition=Ready|branch/dev-branch|dev-postgres-refresh|sample-postgres-ha|dev-branch-ha|VolumeSnapshotClass|cross-namespace' "$file" || true
echo "== diff stat/name if available =="
git diff --stat -- "$file" || trueRepository: kubedb/docs
Length of output: 289
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file="docs/guides/postgres/branch/customization/index.md"
echo "== relevant line ranges =="
sed -n '210,250p;336,365p;371,395p;479,512p' "$file" > /tmp/sections.txt
awk '{printf "%6d\t%s\n", NR+0, $0}' /tmp/sections.txt
echo "== branch wait/readiness occurrences =="
grep -nE 'kubectl wait|condition=Ready|branch/dev-branch|dev-postgres-refresh|sample-postgres-ha|dev-branch-ha|VolumeSnapshotClass|cross-namespace' "$file" || true
echo "== applied resources and subsequent commands =="
python3 - <<'PY'
from pathlib import Path
p=Path('docs/guides/postgres/branch/customization/index.md')
text=p.read_text()
for i,line in enumerate(text.splitlines(),1):
if '$ kubectl apply' in line or '$ kubectl exec' in line or '$ kubectl wait' in line or 'sample-postgres-ha' in line or 'dev-branch-ha' in line:
print(f"{i}: {line}")
PYRepository: kubedb/docs
Length of output: 14488
Add readiness waits before dependent commands.
The refresh, cross-namespace, VolumeSnapshotClass, and HA examples run commands immediately after applying resources that may still be initializing. Add a validated kubectl wait --for=condition=Ready step before each dependent command, and wait for sample-postgres-ha before applying dev-branch-ha.
Suggested readiness step
$ kubectl apply -f .../dev-branch-refresh.yaml
branch.courier.kubedb.com/dev-branch-refresh created
+$ kubectl wait --for=condition=Ready branch/dev-branch-refresh -n demo --timeout=10m
+
$ kubectl exec -n demo dev-postgres-refresh-0 -c postgres -- psql -U postgres -tAc "SELECT count(*) FROM customers;"Also applies to lines 346-358, 381-389, and 489-506.
📝 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
| Create it and wait for the first copy: | |
| ```bash | |
| $ kubectl apply -f https://github.com/kubedb/docs/raw/{{< param "info.version" >}}/docs/guides/postgres/branch/customization/examples/dev-branch-refresh.yaml | |
| branch.courier.kubedb.com/dev-branch-refresh created | |
| $ kubectl exec -n demo dev-postgres-refresh-0 -c postgres -- psql -U postgres -tAc "SELECT count(*) FROM customers;" | |
| 1001 | |
| ``` | |
| Create it and wait for the first copy: | |
🤖 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/postgres/branch/customization/index.md` around lines 228 - 236,
Add validated kubectl wait --for=condition=Ready steps after applying resources
and before dependent commands in the refresh, cross-namespace,
VolumeSnapshotClass, and HA examples. In the HA flow, wait for
sample-postgres-ha to become Ready before applying dev-branch-ha, while
preserving the existing command order and resource references.
|
|
||
| | Symptom | Cause and fix | | ||
| |---|---| | ||
| | `Branch` is `Failed` with `reason: PostActionFailed` | A post-action container exited non-zero. Courier suspends the Job so the failed Pod and its logs survive — read them with `kubectl logs -n <ns> job/<target>-post-action`, then fix `spec.postActions` and re-apply. The edit triggers a retry. | |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Files:"
fd -a 'index.md|dev-branch-masked.yaml' . | sed 's#^\./##'
echo
echo "Relevant occurrences:"
rg -n "ttlSecondsAfterFinished|PostActionFailed|kubectl logs|survive|retention|logs survive" .
echo
echo "index line slice:"
sed -n '500,525p' docs/guides/postgres/branch/customization/index.md | cat -n -v
echo
echo "example relevant slice:"
sed -n '1,220p' docs/guides/postgres/branch/customization/examples/dev-branch-masked.yaml | cat -n -vRepository: kubedb/docs
Length of output: 50368
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Target context:"
sed -n '505,520p' docs/guides/postgres/branch/customization/index.md | cat -n
echo
echo "Example metadata context:"
python3 - <<'PY'
from pathlib import Path
p=Path('docs/guides/postgres/branch/customization/examples/dev-branch-masked.yaml')
lines=p.read_text().splitlines()
for i,l in enumerate(lines,1):
if 'ttlSecondsAfterFinished' in l or i<=30 or i>=len(lines)-10:
print(f'{i:4d}: {l}')
PY
echo
echo "PostActionFailed exact matches only:"
rg -n --glob '!(/tmp/**)' 'PostActionFailed|failure-and-disaster-recovery|failure' docs/guides/postgres docs/guides/neo4j docs/guides/mongodb docs/guides/clickhouse /dev/null | head -80Repository: kubedb/docs
Length of output: 14490
State post-action Job log retention.
The example sets ttlSecondsAfterFinished: 600, so a failed post-action Job can be deleted after 10 minutes. Qualify the troubleshooting guide with the retention window, or omit ttlSecondsAfterFinished for the troubleshooting/debug case.
🤖 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/postgres/branch/customization/index.md` at line 514, Update the
post-action troubleshooting guidance in the Branch failure row to account for
the 600-second ttlSecondsAfterFinished retention window, or remove that setting
from the debugging example so failed Job logs remain available for
investigation.
Comment on lines
+525
to
+527
| $ kubectl delete branch -n demo --all | ||
| $ kubectl delete pg -n demo sample-postgres-ha | ||
| $ kubectl delete ns dev |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Repository files matching guide:"
git ls-files | rg 'docs/guides/postgres/branch/customization/index\.md$' || true
if [ -f docs/guides/postgres/branch/customization/index.md ]; then
echo "File size:"
wc -l docs/guides/postgres/branch/customization/index.md
echo "Relevant lines 460-545:"
sed -n '460,545p' docs/guides/postgres/branch/customization/index.md | nl -ba -v460
fi
echo
echo "Search for cleanup commands in repository:"
rg -n "kubectl delete (branch|pg|ns)|wait --for=delete|--wait=false" . --glob '!node_modules' --glob '!dist' --glob '!build' || trueRepository: kubedb/docs
Length of output: 364
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Relevant lines 460-545:"
sed -n '460,545p' docs/guides/postgres/branch/customization/index.md | awk '{printf "%5d %s\n", NR+459, $0}'
echo
echo "Search for cleanup commands in repository:"
rg -n "kubectl delete (branch|pg|ns)|wait --for=delete|--wait=false" . --glob '!node_modules' --glob '!dist' --glob '!build' || trueRepository: kubedb/docs
Length of output: 50369
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Current page branch/target ns references around setup:"
rg -n "kubectl.*(branch|pg|namespace|ns)|namespace: (demo|dev)|deploy|Postgres|Branch" docs/guides/postgres/branch/customization/index.md | head -n 200
echo
echo "Current page first occurrences around setup:"
sed -n '1,460p' docs/guides/postgres/branch/customization/index.md | awk '{printf "%5d %s\n", NR, $0}' | rg "namespace: (demo|dev)|kubectl|deploy|Postgres|Branch|Branch|volumeSnapshotClassName|target:" || true
echo
echo "Sibling cleanup patterns for wait/no-wait:"
sed -n '440,545p' docs/guides/postgres/branch/same-cluster/index.md | awk '{printf "%5d %s\n", NR+439, $0}'Repository: kubedb/docs
Length of output: 18024
Scope the cleanup to the tutorial resources.
kubectl delete branch -n demo --all removes every Branch in demo; use the names this section creates, such as dev-branch-masked, dev-branch-refresh, dev-branch-xns, dev-branch-ha, and dev-branch-vsc. Delete ns dev only if it was created just for this tutorial. Replace the immediate delete --wait=false cleanup with a documented delete plus kubectl wait --for=delete sequence.
🧰 Tools
🪛 markdownlint-cli2 (0.23.2)
[warning] 525-525: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 526-526: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 527-527: Dollar signs used before commands without showing output
(MD014, commands-show-output)
🤖 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/postgres/branch/customization/index.md` around lines 525 - 527,
Update the cleanup commands in the tutorial to delete only the named Branch
resources created by this section, including dev-branch-masked,
dev-branch-refresh, dev-branch-xns, dev-branch-ha, and dev-branch-vsc, instead
of using --all. Remove ns dev only when it is tutorial-created, and replace any
immediate delete --wait=false cleanup with a delete followed by kubectl wait
--for=delete.
| (3 rows) | ||
| ``` | ||
|
|
||
| All 1000 rows are there, byte-for-byte as they were on the source when the snapshot was taken. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
Do not claim byte-for-byte identity from this live snapshot.
The walkthrough keeps the source serving reads and writes while Courier takes the CSI snapshot. The query proves that 1,000 rows are present on the branch, but it does not prove byte-for-byte identity with the source at one exact instant. Use wording that matches the verification.
Proposed wording
-All 1000 rows are there, byte-for-byte as they were on the source when the snapshot was taken.
+All 1000 rows captured in the snapshot are present on the branch.📝 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
| All 1000 rows are there, byte-for-byte as they were on the source when the snapshot was taken. | |
| All 1000 rows captured in the snapshot are present on the branch. |
🤖 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/postgres/branch/same-cluster/index.md` at line 410, Revise the
verification statement near the walkthrough’s 1,000-row query to claim only that
all 1,000 rows are present on the branch. Remove the “byte-for-byte” and exact
source-state identity assertion, reflecting that the source remains writable
during snapshot creation.
Comment on lines
+19
to
+23
| `Branch` is a Kubernetes `Custom Resource Definition` (CRD). It provides a declarative way to create an | ||
| instant, writable copy of a running KubeDB-managed database — the way you would branch a Git | ||
| repository. You describe the source database and the target you want, and the kubedb-courier operator | ||
| snapshots the source's volumes, clones them copy-on-write, and provisions a second database on top of | ||
| the clone. |
There was a problem hiding this comment.
🚀 Performance & Scalability | 🟡 Minor | ⚡ Quick win
Qualify the copy-on-write guarantee.
This reference presents every branch restore as copy-on-write. The overview limits that behavior to CSI drivers that provide copy-on-write restores. Describe the operation as restoring volumes from snapshots, then qualify the near-instant and low-extra-storage behavior by driver capability.
Proposed wording
- snapshots the source's volumes, clones them copy-on-write, and provisions a second database on top of the clone.
+ snapshots the source's volumes, restores the branch volumes from those snapshots, and provisions a second database on top of the restore. Copy-on-write speed and storage savings depend on the CSI driver.📝 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
| `Branch` is a Kubernetes `Custom Resource Definition` (CRD). It provides a declarative way to create an | |
| instant, writable copy of a running KubeDB-managed database — the way you would branch a Git | |
| repository. You describe the source database and the target you want, and the kubedb-courier operator | |
| snapshots the source's volumes, clones them copy-on-write, and provisions a second database on top of | |
| the clone. | |
| `Branch` is a Kubernetes `Custom Resource Definition` (CRD). It provides a declarative way to create an | |
| instant, writable copy of a running KubeDB-managed database — the way you would branch a Git | |
| repository. You describe the source database and the target you want, and the kubedb-courier operator | |
| snapshots the source's volumes, restores the branch volumes from those snapshots, and provisions a second database on top of the restore. Copy-on-write speed and storage savings depend on the CSI driver. |
🤖 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/postgres/concepts/branch.md` around lines 19 - 23, Update the
Branch overview to describe restoring volumes from snapshots rather than
universally cloning them copy-on-write. Qualify the near-instant provisioning
and low additional storage benefits as dependent on the CSI driver supporting
copy-on-write restores, while preserving the declarative branching workflow.
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.
Summary by CodeRabbit