Skip to content

Added docs covering VMinstance and VMDisk backups #456

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
myasnikovdaniil wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Added docs covering VMinstance and VMDisk backups #456

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d08887f
Added docs covering VMinstance and VMDisk backups
myasnikovdaniil Mar 19, 2026
8871430
Fixed restore instruction
myasnikovdaniil Mar 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 0 additions & 95 deletions content/en/docs/v1/kubernetes/backup-and-recovery.md
View file
Open in desktop

This file was deleted.

80 changes: 66 additions & 14 deletions content/en/docs/v1/operations/services/velero-backup-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ description: "Configure backup storage, strategies, and BackupClasses for cluste
weight: 30
---

This guide is for **cluster administrators** who configure the backup infrastructure in Cozystack: S3 storage, Velero locations, backup **strategies**, and **BackupClasses**. Tenant users then use existing BackupClasses to create [BackupJobs and Plans]({{% ref "/docs/v1/kubernetes/backup-and-recovery" %}}).
This guide is for **cluster administrators** who configure the backup infrastructure in Cozystack: S3 storage, Velero locations, backup **strategies**, and **BackupClasses**. Tenant users then use existing BackupClasses to create [BackupJobs and Plans]({{% ref "/docs/v1/virtualization/backup-and-recovery" %}}).

## Prerequisites

Expand Down Expand Up @@ -119,42 +119,84 @@ kubectl get crd | grep -i backup
kubectl explain <strategy-kind> --recursive
```

Example strategy:
Example strategy for VMInstance (includes all VM resources and attached volumes):

```yaml
apiVersion: strategy.backups.cozystack.io/v1alpha1
kind: Velero
metadata:
name: velero-backup-strategy
name: vminstance-strategy
spec:
template:
restoreSpec:
existingResourcePolicy: update

spec: # see https://velero.io/docs/v1.17/api-types/backup/
includedNamespaces:
- '{{ .Application.metadata.namespace }}'

# Resources related VMInstance
- '{{ .Application.metadata.namespace }}'
orLabelSelectors:
# VM resources (VirtualMachine, DataVolume, PVC, etc.)
- matchLabels:
app.kubernetes.io/instance: 'vm-instance-{{ .Application.metadata.name }}'
# HelmRelease (the Cozystack app object)
- matchLabels:
apps.cozystack.io/application.kind: '{{ .Application.kind }}'
apps.cozystack.io/application.name: '{{ .Application.metadata.name }}'
Copy link
Contributor

@androndo androndo Mar 19, 2026

Choose a reason for hiding this comment

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

lets add:

        # keeps ControllerRevisions used KubeVirt instancetype/preference of VMI
        - matchLabels:
            instancetype.kubevirt.io/object-kind: VirtualMachineClusterInstancetype
        - matchLabels:
            instancetype.kubevirt.io/object-kind: VirtualMachineClusterPreference

includedResources:
- helmreleases.helm.toolkit.fluxcd.io
- virtualmachines.kubevirt.io
- virtualmachineinstances.kubevirt.io
Copy link
Contributor

@androndo androndo Mar 19, 2026

Choose a reason for hiding this comment

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

and please add this

- controllerrevisions.apps  # KubeVirt instancetype/preference refs; VM fails without them

- pods
- datavolumes.cdi.kubevirt.io
- persistentvolumeclaims
- services
- configmaps
- secrets
Comment on lines 145 to 153
Copy link
Contributor

@gemini-code-assist gemini-code-assist bot Mar 18, 2026

Choose a reason for hiding this comment

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

medium

The list of includedResources for the vminstance-strategy example no longer includes services. If a VMInstance is exposed via a Kubernetes Service, it would be beneficial to include the service in the backup to ensure a complete application restore. Consider adding services back to this list for completeness, as it was present in the previous version of the example strategy.

Suggested change
includedResources:
- helmreleases.helm.toolkit.fluxcd.io
- virtualmachines.kubevirt.io
- virtualmachineinstances.kubevirt.io
- pods
- datavolumes.cdi.kubevirt.io
- persistentvolumeclaims
- services
- configmaps
- secrets
includedResources:
- helmreleases.helm.toolkit.fluxcd.io
- virtualmachines.kubevirt.io
- virtualmachineinstances.kubevirt.io
- pods
- datavolumes.cdi.kubevirt.io
- persistentvolumeclaims
- services
- configmaps
- secrets


includeClusterResources: false
storageLocation: '{{ .Parameters.backupStorageLocationName }}'

volumeSnapshotLocations:
- '{{ .Parameters.backupStorageLocationName }}'
snapshotVolumes: true
snapshotMoveData: true
ttl: 720h0m0s
itemOperationTimeout: 24h0m0s
```

Example strategy for VMDisk (disk and its volume only):

```yaml
apiVersion: strategy.backups.cozystack.io/v1alpha1
kind: Velero
metadata:
name: vmdisk-strategy
spec:
template:
restoreSpec:
existingResourcePolicy: update

spec:
includedNamespaces:
- '{{ .Application.metadata.namespace }}'
orLabelSelectors:
- matchLabels:
app.kubernetes.io/instance: 'vm-disk-{{ .Application.metadata.name }}'
- matchLabels:
apps.cozystack.io/application.kind: '{{ .Application.kind }}'
apps.cozystack.io/application.name: '{{ .Application.metadata.name }}'
includedResources:
- helmreleases.helm.toolkit.fluxcd.io
- datavolumes.cdi.kubevirt.io
- persistentvolumeclaims
includeClusterResources: false
storageLocation: '{{ .Parameters.backupStorageLocationName }}'
volumeSnapshotLocations:
- '{{ .Parameters.backupStorageLocationName }}'
snapshotVolumes: true
snapshotMoveData: true
ttl: 720h0m0s
itemOperationTimeout: 24h0m0s
```

Template context for substitutions in template spec will be resolved according to defined Parameters in BackupClass and desired ApplicationRef defined in BackupJob / Plan.
Template variables (`{{ .Application.* }}` and `{{ .Parameters.* }}`) are resolved from the ApplicationRef in the BackupJob/Plan and the parameters defined in the BackupClass.

Don't forget to apply it into management cluster:

Expand Down Expand Up @@ -183,9 +225,19 @@ spec:
- strategyRef:
apiGroup: strategy.backups.cozystack.io
kind: Velero
name: velero-backup-strategy
name: vminstance-strategy
application:
kind: VMInstance
apiGroup: apps.cozystack.io
parameters:
backupStorageLocationName: default
- strategyRef:
apiGroup: strategy.backups.cozystack.io
kind: Velero
name: vmdisk-strategy
application:
kind: VMDisk
apiGroup: apps.cozystack.io
parameters:
backupStorageLocationName: default
```
Expand All @@ -201,8 +253,8 @@ kubectl get backupclasses

Once strategies and BackupClasses are in place, **tenant users** can run backups without touching Velero or storage configuration:

- **One-off backup**: create a [BackupJob]({{% ref "/docs/v1/kubernetes/backup-and-recovery#create-a-one-off-backup-backupjob" %}}) that references a BackupClass.
- **Scheduled backups**: create a [Plan]({{% ref "/docs/v1/kubernetes/backup-and-recovery#create-scheduled-backups-plan" %}}) with a cron schedule and a BackupClass reference.
- **One-off backup**: create a [BackupJob]({{% ref "/docs/v1/virtualization/backup-and-recovery#one-off-backup" %}}) that references a BackupClass.
- **Scheduled backups**: create a [Plan]({{% ref "/docs/v1/virtualization/backup-and-recovery#scheduled-backup" %}}) with a cron schedule and a BackupClass reference.

Direct use of Velero CRDs (`Backup`, `Schedule`, `Restore`) remains available for advanced or recovery scenarios:

Expand All @@ -228,4 +280,4 @@ kubectl logs -n cozy-velero -l app.kubernetes.io/name=velero --tail=100

## 5. Restore from a backup

For a description of restore procedures (including listing backups and checking restore progress), see [Restore from a backup (all resources)]({{% ref "/docs/v0/kubernetes/backup-and-recovery#3-restore-from-a-backup-all-resources" %}}).
Once strategies and BackupClasses are in place, tenant users can restore from a backup using **RestoreJob** resources. See the [Backup and Recovery]({{% ref "/docs/v1/virtualization/backup-and-recovery" %}}) guide for restore instructions covering VMInstance and VMDisk in-place restores.
Loading