Skip to content

fix(backup): simplify UX with default backupclass#547

Open
Andrey Kolkov (androndo) wants to merge 1 commit into
mainfrom
feat/backup-default-class
Open

fix(backup): simplify UX with default backupclass#547
Andrey Kolkov (androndo) wants to merge 1 commit into
mainfrom
feat/backup-default-class

Conversation

@androndo
Copy link
Copy Markdown
Contributor

@androndo Andrey Kolkov (androndo) commented May 22, 2026

Summary by CodeRabbit

  • Documentation
    • Added comprehensive guide for platform-managed cozy-default BackupClass, enabling simplified backup configuration for applications and VMs without manual credential setup.
    • Updated application and virtualization backup documentation to reference the new cozy-default BackupClass system.
    • Reorganized and consolidated backup-related guides for clarity.

@netlify
Copy link
Copy Markdown

netlify Bot commented May 22, 2026

Deploy Preview for cozystack ready!

Name Link
🔨 Latest commit c1a3ff8
🔍 Latest deploy log https://app.netlify.com/projects/cozystack/deploys/6a1fd78788dce20008151e17
😎 Deploy Preview https://deploy-preview-547--cozystack.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 22, 2026

Review Change Stack

📝 Walkthrough

Walkthrough

This PR consolidates Cozystack backup documentation by introducing unified Backup Classes guides for both documentation branches (next and v1.4) and systematically redirecting all application, Kubernetes, and virtualization guides to reference the new documentation instead of three previously separate configuration pages.

Changes

Backup Documentation Migration to Backup Classes

Layer / File(s) Summary
New Backup Classes documentation for next and v1.4
content/en/docs/next/operations/services/backup-classes.md, content/en/docs/v1.4/operations/services/backup-classes.md
Two new comprehensive guides (196 lines each) introduce the cozy-default platform-managed BackupClass, credential projection mechanics, per-application support (Postgres, MariaDB, ClickHouse, Etcd; FoundationDB opt-in), driver-specific endpoint handling, operational caveats (FoundationDB restore, ClickHouse system bucket opt-in), inspection procedures, Package CR overrides, custom BackupClass tuning, external S3 disablement, upgrade notes, and tenant workflow examples.
Admin application backup-and-recovery guides (next and v1.4)
content/en/docs/next/applications/backup-and-recovery.md, content/en/docs/v1.4/applications/backup-and-recovery.md
Core tenant guides revised to describe platform-provisioned cozy-default BackupClass with automatic credential projection, replace per-kind backup class names in examples, expand prerequisites to include Etcd, update troubleshooting escalation to Backup Classes guide, and remove references to deprecated Managed Application Backup Configuration and Velero Backup Configuration.
Application-specific backup docs
content/en/docs/next/applications/postgres.md, content/en/docs/next/applications/mariadb.md, content/en/docs/next/applications/clickhouse.md
PostgreSQL, MariaDB, and ClickHouse guides update backup setup references from Managed Application Backup Configuration to Backup Classes, directing users to the unified platform guide.
Kubernetes Velero addon guides (next and v1.4)
content/en/docs/next/kubernetes/backups-with-velero-addon.md, content/en/docs/v1.4/kubernetes/backups-with-velero-addon.md
Tenant-side Velero addon documentation updates platform-level Velero references and "Related" links from Velero Backup Configuration to Backup Classes.
Virtualization backup-and-recovery guides (next and v1.4)
content/en/docs/next/virtualization/backup-and-recovery.md, content/en/docs/v1.4/virtualization/backup-and-recovery.md
VMInstance and VMDisk backup guidance updated to use cozy-default instead of velero in examples, adds fresh-cluster bootstrap warning for Velero availability, and retargets BackupClass strategy links from Velero Backup Configuration to Backup Classes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

  • cozystack/website#536: Earlier PR updating the same managed-database backup documentation files with related BackupClass workflow and setup reference changes.

Suggested reviewers

  • kvaps
  • lllamnyp
  • myasnikovdaniil

Poem

🐰 The documentation hops along,
From velero's old and winding song,
To cozy-default, shiny and bright,
Backup Classes guide the light!
Platform-managed, credentials in flight,
Cross-tenant secrets held safe and tight! 🎒✨

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and accurately describes the main change: simplifying the backup user experience by introducing a default BackupClass (cozy-default) to replace the previous complex multi-document admin setup workflow.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/backup-default-class

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@androndo Andrey Kolkov (androndo) force-pushed the feat/backup-default-class branch 2 times, most recently from 7e9b1ae to 3cd5d7b Compare May 22, 2026 12:17
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request consolidates backup documentation by replacing the 'Managed Application Backup Configuration' and 'Velero Backup Configuration' guides with a new, unified 'Backup Classes' guide across both the 'next' and 'v1.4' documentation versions. Feedback from the review highlights that the new guide is missing critical troubleshooting information ('Tenant escalation: driver-side diagnostics') and detailed strategy examples for ClickHouse and Velero that were present in the deleted files. Additionally, the reviewer pointed out redundant links in the 'See also' sections and minor typos in the new documentation.

Comment on lines +208 to +210
- [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) — how administrators define strategies and `BackupClass` resources.
- [Backup and Recovery (VMs)]({{% ref "/docs/next/virtualization/backup-and-recovery" %}}) — the parallel guide for VMInstance / VMDisk backups (HelmRelease + CRs + PVC snapshots).
- [Velero Backup Configuration]({{% ref "/docs/next/operations/services/velero-backup-configuration" %}}) — administrator setup for the Velero-driven VM backups.
- [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) — administrator setup for the Velero-driven VM backups.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The 'See also' section now contains two identical links to the 'Backup Classes' guide. Since the new guide covers both managed applications and general backup class configuration, these links should be merged to avoid redundancy.

Suggested change
- [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) — how administrators define strategies and `BackupClass` resources.
- [Backup and Recovery (VMs)]({{% ref "/docs/next/virtualization/backup-and-recovery" %}}) — the parallel guide for VMInstance / VMDisk backups (HelmRelease + CRs + PVC snapshots).
- [Velero Backup Configuration]({{% ref "/docs/next/operations/services/velero-backup-configuration" %}}) — administrator setup for the Velero-driven VM backups.
- [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) — administrator setup for the Velero-driven VM backups.
- [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) — how administrators define strategies and BackupClass resources.
- [Backup and Recovery (VMs)]({{% ref "/docs/next/virtualization/backup-and-recovery" %}}) — the parallel guide for VMInstance / VMDisk backups (HelmRelease + CRs + PVC snapshots).

Comment on lines +208 to +210
- [Backup Classes]({{% ref "/docs/v1.4/operations/services/backup-classes" %}}) — how administrators define strategies and `BackupClass` resources.
- [Backup and Recovery (VMs)]({{% ref "/docs/v1.4/virtualization/backup-and-recovery" %}}) — the parallel guide for VMInstance / VMDisk backups (HelmRelease + CRs + PVC snapshots).
- [Velero Backup Configuration]({{% ref "/docs/v1.4/operations/services/velero-backup-configuration" %}}) — administrator setup for the Velero-driven VM backups.
- [Backup Classes]({{% ref "/docs/v1.4/operations/services/backup-classes" %}}) — administrator setup for the Velero-driven VM backups.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The 'See also' section now contains two identical links to the 'Backup Classes' guide. Since the new guide covers both managed applications and general backup class configuration, these links should be merged to avoid redundancy.

Suggested change
- [Backup Classes]({{% ref "/docs/v1.4/operations/services/backup-classes" %}}) — how administrators define strategies and `BackupClass` resources.
- [Backup and Recovery (VMs)]({{% ref "/docs/v1.4/virtualization/backup-and-recovery" %}}) — the parallel guide for VMInstance / VMDisk backups (HelmRelease + CRs + PVC snapshots).
- [Velero Backup Configuration]({{% ref "/docs/v1.4/operations/services/velero-backup-configuration" %}}) — administrator setup for the Velero-driven VM backups.
- [Backup Classes]({{% ref "/docs/v1.4/operations/services/backup-classes" %}}) — administrator setup for the Velero-driven VM backups.
- [Backup Classes]({{% ref "/docs/v1.4/operations/services/backup-classes" %}}) — how administrators define strategies and BackupClass resources.
- [Backup and Recovery (VMs)]({{% ref "/docs/v1.4/virtualization/backup-and-recovery" %}}) — the parallel guide for VMInstance / VMDisk backups (HelmRelease + CRs + PVC snapshots).

Comment thread content/en/docs/next/operations/services/backup-classes.md Outdated
Comment thread content/en/docs/v1.4/operations/services/backup-classes.md Outdated
@androndo Andrey Kolkov (androndo) force-pushed the feat/backup-default-class branch 2 times, most recently from 383e398 to 99e824a Compare May 29, 2026 07:15
…and backupclass

Signed-off-by: Andrey Kolkov <androndo@gmail.com>
Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)
content/en/docs/v1.4/applications/backup-and-recovery.md (1)

207-210: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Deduplicate “Backup Classes” in the “See also” list.

Line 207 and Line 209 reference the same target, so one of them should be removed to avoid redundant navigation.

🤖 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 `@content/en/docs/v1.4/applications/backup-and-recovery.md` around lines 207 -
210, The "See also" list contains a duplicate entry for "[Backup Classes]" (the
link using the {% ref "/docs/v1.4/operations/services/backup-classes" %}
target); remove the redundant occurrence so the list only references Backup
Classes once, keeping the VM backup link ([Backup and Recovery (VMs)] with the
{% ref "/docs/v1.4/virtualization/backup-and-recovery" %} target) and a single
Backup Classes entry. Ensure the remaining link text and ref token are unchanged
to preserve the correct target and ordering in the list.
content/en/docs/next/applications/backup-and-recovery.md (1)

207-210: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove duplicate “Backup Classes” entry in “See also”.

Line 207 and Line 209 point to the same page, which adds noise in navigation. Keep one entry and adjust the description text if you want to preserve VM-specific context.

🤖 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 `@content/en/docs/next/applications/backup-and-recovery.md` around lines 207 -
210, Remove the duplicated "Backup Classes" See also entry: keep a single
"Backup Classes" bullet (the link text "Backup Classes") and delete the other
duplicate, then update the remaining entry's description to either be generic or
explicitly mention it's for both administrator strategies and Velero-driven VM
backups if VM context is needed; ensure the "Backup and Recovery (VMs)" entry
remains distinct and accurate.
🤖 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 `@content/en/docs/next/applications/clickhouse.md`:
- Line 24: This change was made in an autogenerated file (clickhouse.md) and
must be applied upstream: edit the application's README in the
cozystack/cozystack repo to update the Backup guidance (replace legacy
backup.schedule, backup.cleanupStrategy, backup.resticPassword text with the new
BackupClass + Altinity strategy instructions referencing Plan and RestoreJob),
then regenerate docs by running the corresponding make update-* target so the
change propagates into the generated content; do not edit the generated
clickhouse.md directly.

In `@content/en/docs/next/applications/mariadb.md`:
- Line 114: Revert the edit in the autogenerated file and instead add the
deprecation note to the upstream README in the cozystack/cozystack repository
(the bold line starting "**The chart-level `backup.*` values documented below
are deprecated.**") so the source contains the new text, then run the
appropriate make update-* target to regenerate this file; ensure the upstream
README change preserves the same wording and the existing refs to Application
Backup and Recovery and Backup Classes so the regenerated doc includes the
updated paragraph.

In `@content/en/docs/next/applications/postgres.md`:
- Line 31: The change was made in an autogenerated file (see the autogenerated
declaration at the top) so do not edit
content/en/docs/next/applications/postgres.md directly; instead edit the
upstream README entry that contains the paragraph starting "Backups: prefer the
`BackupClass` flow." in the cozystack/cozystack source, then regenerate the docs
by running the appropriate make update-* target so the updated text is
propagated into the generated postgresql application doc.

In `@content/en/docs/next/virtualization/backup-and-recovery.md`:
- Line 45: The inline shell snippet `kubectl -n cozy-velero get bsl cozy-default
-o jsonpath='{.status.phase}' = Available` is invalid; replace it with a
two-step check: run `kubectl -n cozy-velero get bsl cozy-default -o
jsonpath='{.status.phase}'` to print the phase and then compare that output to
"Available" (or show how to test equality in shell, e.g., using `[ "$(kubectl
...)" = "Available" ]`). Update the paragraph so the command is executable and
clearly instructs readers to compare the command output to "Available" rather
than using `= Available` inline.

---

Outside diff comments:
In `@content/en/docs/next/applications/backup-and-recovery.md`:
- Around line 207-210: Remove the duplicated "Backup Classes" See also entry:
keep a single "Backup Classes" bullet (the link text "Backup Classes") and
delete the other duplicate, then update the remaining entry's description to
either be generic or explicitly mention it's for both administrator strategies
and Velero-driven VM backups if VM context is needed; ensure the "Backup and
Recovery (VMs)" entry remains distinct and accurate.

In `@content/en/docs/v1.4/applications/backup-and-recovery.md`:
- Around line 207-210: The "See also" list contains a duplicate entry for
"[Backup Classes]" (the link using the {% ref
"/docs/v1.4/operations/services/backup-classes" %} target); remove the redundant
occurrence so the list only references Backup Classes once, keeping the VM
backup link ([Backup and Recovery (VMs)] with the {% ref
"/docs/v1.4/virtualization/backup-and-recovery" %} target) and a single Backup
Classes entry. Ensure the remaining link text and ref token are unchanged to
preserve the correct target and ordering in the list.
🪄 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

Run ID: 184bd75b-f28e-46a0-9165-9f0e1ed3d7a6

📥 Commits

Reviewing files that changed from the base of the PR and between 6a32349 and c1a3ff8.

📒 Files selected for processing (15)
  • content/en/docs/next/applications/backup-and-recovery.md
  • content/en/docs/next/applications/clickhouse.md
  • content/en/docs/next/applications/mariadb.md
  • content/en/docs/next/applications/postgres.md
  • content/en/docs/next/kubernetes/backups-with-velero-addon.md
  • content/en/docs/next/operations/services/backup-classes.md
  • content/en/docs/next/operations/services/managed-app-backup-configuration.md
  • content/en/docs/next/operations/services/velero-backup-configuration.md
  • content/en/docs/next/virtualization/backup-and-recovery.md
  • content/en/docs/v1.4/applications/backup-and-recovery.md
  • content/en/docs/v1.4/kubernetes/backups-with-velero-addon.md
  • content/en/docs/v1.4/operations/services/backup-classes.md
  • content/en/docs/v1.4/operations/services/managed-app-backup-configuration.md
  • content/en/docs/v1.4/operations/services/velero-backup-configuration.md
  • content/en/docs/v1.4/virtualization/backup-and-recovery.md
💤 Files with no reviewable changes (4)
  • content/en/docs/v1.4/operations/services/velero-backup-configuration.md
  • content/en/docs/next/operations/services/velero-backup-configuration.md
  • content/en/docs/next/operations/services/managed-app-backup-configuration.md
  • content/en/docs/v1.4/operations/services/managed-app-backup-configuration.md


{{% alert color="warning" %}}
**Backups: prefer the `BackupClass` flow.** `backup.enabled` and the S3 fields (`s3Region`, `s3Bucket`, `endpoint`, `s3PathOverride`, `s3AccessKey`/`s3SecretKey` or `s3CredentialsSecret`) are still required — they materialise the in-pod `clickhouse-backup` sidecar that the Altinity backup strategy talks to. However, `backup.schedule`, `backup.cleanupStrategy`, and `backup.resticPassword` (which drive the legacy chart-managed CronJob doing dump + restic, and the matching restic restore flow documented below) are **superseded** by the Cozystack backups framework: define a `BackupClass` + `Altinity` strategy once, then drive scheduled backups via `Plan` and restores via `RestoreJob`. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Managed Application Backup Configuration]({{% ref "/docs/next/operations/services/managed-app-backup-configuration" %}}) (admin setup).
**Backups: prefer the `BackupClass` flow.** `backup.enabled` and the S3 fields (`s3Region`, `s3Bucket`, `endpoint`, `s3PathOverride`, `s3AccessKey`/`s3SecretKey` or `s3CredentialsSecret`) are still required — they materialise the in-pod `clickhouse-backup` sidecar that the Altinity backup strategy talks to. However, `backup.schedule`, `backup.cleanupStrategy`, and `backup.resticPassword` (which drive the legacy chart-managed CronJob doing dump + restic, and the matching restic restore flow documented below) are **superseded** by the Cozystack backups framework: define a `BackupClass` + `Altinity` strategy once, then drive scheduled backups via `Plan` and restores via `RestoreJob`. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) (admin setup).
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

This update must be applied upstream, not in the generated doc.

Line 24 changes a file marked autogenerated (Line 12). Please edit the upstream application README and regenerate docs; direct edits here are non-durable.

As per coding guidelines: “Autogenerated files from cozystack/cozystack … To change the body, edit the upstream README … then re-run the corresponding make update-* target.”

🤖 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 `@content/en/docs/next/applications/clickhouse.md` at line 24, This change was
made in an autogenerated file (clickhouse.md) and must be applied upstream: edit
the application's README in the cozystack/cozystack repo to update the Backup
guidance (replace legacy backup.schedule, backup.cleanupStrategy,
backup.resticPassword text with the new BackupClass + Altinity strategy
instructions referencing Plan and RestoreJob), then regenerate docs by running
the corresponding make update-* target so the change propagates into the
generated content; do not edit the generated clickhouse.md directly.

### Backup parameters
{{% alert color="warning" %}}
**The chart-level `backup.*` values documented below are deprecated.** The legacy `mariadb-dump` + `restic` flow is superseded by the Cozystack backups framework: define a `BackupClass` + `MariaDB` strategy once, then drive backups via `BackupJob` / `Plan` and restores via `RestoreJob`. Existing tenants with `backup.enabled=true` continue to render the legacy resources unchanged. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Managed Application Backup Configuration]({{% ref "/docs/next/operations/services/managed-app-backup-configuration" %}}) (admin setup).
**The chart-level `backup.*` values documented below are deprecated.** The legacy `mariadb-dump` + `restic` flow is superseded by the Cozystack backups framework: define a `BackupClass` + `MariaDB` strategy once, then drive backups via `BackupJob` / `Plan` and restores via `RestoreJob`. Existing tenants with `backup.enabled=true` continue to render the legacy resources unchanged. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) (admin setup).
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Move this change to the upstream source and regenerate.

Line 114 modifies an autogenerated file (see Line 11), so this edit should be done in the source README under cozystack/cozystack and then synced via the update target.

As per coding guidelines: “Autogenerated files from cozystack/cozystack … To change the body, edit the upstream README … then re-run the corresponding make update-* target.”

🤖 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 `@content/en/docs/next/applications/mariadb.md` at line 114, Revert the edit in
the autogenerated file and instead add the deprecation note to the upstream
README in the cozystack/cozystack repository (the bold line starting "**The
chart-level `backup.*` values documented below are deprecated.**") so the source
contains the new text, then run the appropriate make update-* target to
regenerate this file; ensure the upstream README change preserves the same
wording and the existing refs to Application Backup and Recovery and Backup
Classes so the regenerated doc includes the updated paragraph.


{{% alert color="warning" %}}
**Backups: prefer the `BackupClass` flow.** The chart-level `backup.*` values documented below still configure the Barman object store and S3 credentials that backups read from, but the chart-emitted `ScheduledBackup` and the `bootstrap`-based recovery flow have been **superseded** by the Cozystack backups framework: define a `BackupClass` + `CNPG` strategy once, then drive scheduled backups via `Plan` and restores via `RestoreJob`. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Managed Application Backup Configuration]({{% ref "/docs/next/operations/services/managed-app-backup-configuration" %}}) (admin setup).
**Backups: prefer the `BackupClass` flow.** The chart-level `backup.*` values documented below still configure the Barman object store and S3 credentials that backups read from, but the chart-emitted `ScheduledBackup` and the `bootstrap`-based recovery flow have been **superseded** by the Cozystack backups framework: define a `BackupClass` + `CNPG` strategy once, then drive scheduled backups via `Plan` and restores via `RestoreJob`. See [Application Backup and Recovery]({{% ref "/docs/next/applications/backup-and-recovery" %}}) (tenant guide) and [Backup Classes]({{% ref "/docs/next/operations/services/backup-classes" %}}) (admin setup).
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Do not edit autogenerated application docs in-place.

This file declares itself autogenerated (Line 11), so Line 31 should be changed in the upstream source README and regenerated; otherwise the change will be lost on next sync.

As per coding guidelines: “Autogenerated files from cozystack/cozystack … To change the body, edit the upstream README … then re-run the corresponding make update-* target.”

🤖 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 `@content/en/docs/next/applications/postgres.md` at line 31, The change was
made in an autogenerated file (see the autogenerated declaration at the top) so
do not edit content/en/docs/next/applications/postgres.md directly; instead edit
the upstream README entry that contains the paragraph starting "Backups: prefer
the `BackupClass` flow." in the cozystack/cozystack source, then regenerate the
docs by running the appropriate make update-* target so the updated text is
propagated into the generated postgresql application doc.

`cozy-default` is the platform-shipped BackupClass; its `strategies[]` array binds the Velero driver for both `VMInstance` and `VMDisk`. Use this name when creating a BackupJob or Plan, or substitute a sibling class name if your administrator has created one.

{{% alert color="info" %}}
**Fresh-cluster bootstrap window.** On a fresh-cluster install, the Velero `BackupStorageLocation` `cozy-default` reports `Unavailable` for tens of seconds after `helm install` returns, until the platform's credentials projector lands `cozy-backups-creds` into `cozy-velero`. Velero rejects new `Backup` and `Restore` requests against `storageLocation: cozy-default` during that window. If a BackupJob you submit fails immediately with a Velero error referencing storage, wait and retry, or ask your administrator to check `kubectl -n cozy-velero get bsl cozy-default -o jsonpath='{.status.phase}' = Available`. See the [Backup Classes admin guide]({{% ref "/docs/next/operations/services/backup-classes" %}}) for details.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Fix invalid shell command in bootstrap check.

The inline command is not executable as written (...jsonpath='{.status.phase}' = Available). Copy-pasting this will fail; compare output in a second step instead.

Proposed doc fix
-**Fresh-cluster bootstrap window.** On a fresh-cluster install, the Velero `BackupStorageLocation` `cozy-default` reports `Unavailable` for tens of seconds after `helm install` returns, until the platform's credentials projector lands `cozy-backups-creds` into `cozy-velero`. Velero rejects new `Backup` and `Restore` requests against `storageLocation: cozy-default` during that window. If a BackupJob you submit fails immediately with a Velero error referencing storage, wait and retry, or ask your administrator to check `kubectl -n cozy-velero get bsl cozy-default -o jsonpath='{.status.phase}' = Available`. See the [Backup Classes admin guide]({{% ref "/docs/next/operations/services/backup-classes" %}}) for details.
+**Fresh-cluster bootstrap window.** On a fresh-cluster install, the Velero `BackupStorageLocation` `cozy-default` reports `Unavailable` for tens of seconds after `helm install` returns, until the platform's credentials projector lands `cozy-backups-creds` into `cozy-velero`. Velero rejects new `Backup` and `Restore` requests against `storageLocation: cozy-default` during that window. If a BackupJob you submit fails immediately with a Velero error referencing storage, wait and retry, or ask your administrator to run `kubectl -n cozy-velero get bsl cozy-default -o jsonpath='{.status.phase}'` and confirm it returns `Available`. See the [Backup Classes admin guide]({{% ref "/docs/next/operations/services/backup-classes" %}}) for details.
📝 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
**Fresh-cluster bootstrap window.** On a fresh-cluster install, the Velero `BackupStorageLocation` `cozy-default` reports `Unavailable` for tens of seconds after `helm install` returns, until the platform's credentials projector lands `cozy-backups-creds` into `cozy-velero`. Velero rejects new `Backup` and `Restore` requests against `storageLocation: cozy-default` during that window. If a BackupJob you submit fails immediately with a Velero error referencing storage, wait and retry, or ask your administrator to check `kubectl -n cozy-velero get bsl cozy-default -o jsonpath='{.status.phase}' = Available`. See the [Backup Classes admin guide]({{% ref "/docs/next/operations/services/backup-classes" %}}) for details.
**Fresh-cluster bootstrap window.** On a fresh-cluster install, the Velero `BackupStorageLocation` `cozy-default` reports `Unavailable` for tens of seconds after `helm install` returns, until the platform's credentials projector lands `cozy-backups-creds` into `cozy-velero`. Velero rejects new `Backup` and `Restore` requests against `storageLocation: cozy-default` during that window. If a BackupJob you submit fails immediately with a Velero error referencing storage, wait and retry, or ask your administrator to run `kubectl -n cozy-velero get bsl cozy-default -o jsonpath='{.status.phase}'` and confirm it returns `Available`. See the [Backup Classes admin guide]({{% ref "/docs/next/operations/services/backup-classes" %}}) for details.
🤖 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 `@content/en/docs/next/virtualization/backup-and-recovery.md` at line 45, The
inline shell snippet `kubectl -n cozy-velero get bsl cozy-default -o
jsonpath='{.status.phase}' = Available` is invalid; replace it with a two-step
check: run `kubectl -n cozy-velero get bsl cozy-default -o
jsonpath='{.status.phase}'` to print the phase and then compare that output to
"Available" (or show how to test equality in shell, e.g., using `[ "$(kubectl
...)" = "Available" ]`). Update the paragraph so the command is executable and
clearly instructs readers to compare the command output to "Available" rather
than using `= Available` inline.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant