Core CRDs¶

Velero's entire surface area is expressed as CRDs. These are the objects you need to know deeply: BBoth spec fields and status lifecycle.

BackupStorageLocation (BSL)¶

The BSL is the most critical config object. It tells Velero where to store backups and which plugin to use. Multiple BSLs are supported; one is marked default: true.

Field	Type	Description
`spec.provider`	`string`	Plugin identifier, e.g. `velero.io/aws`. Must match a registered ObjectStore plugin.
`spec.objectStorage.bucket`	`string`	Bucket/container name in the object store.
`spec.objectStorage.prefix`	`string`	Optional prefix for all objects. Enables multiple clusters sharing one bucket.
`spec.config`	`map[string]string`	Provider-specific config (region, s3Url, checksumAlgorithm, etc.).
`spec.credential`	`SecretKeySelector`	Secret containing credentials. If absent, uses the plugin's default credential chain.
`spec.accessMode`	`ReadWrite \\| ReadOnly`	`ReadOnly` for a restore-only BSL (e.g. DR cluster pointing at a backup source cluster's bucket).
`spec.validationFrequency`	`duration`	How often BSLController validates availability. Defaults to `1m`.
`status.phase`	`Available \\| Unavailable`	BSLController writes this after probing the object store. Backups only proceed against `Available` BSLs.

apiVersion: velero.io/v1
kind: BackupStorageLocation
metadata:
  name: default
  namespace: velero
spec:
  provider: velero.io/aws
  objectStorage:
    bucket: my-velero-backups
    prefix: cluster-prod
  config:
    region: us-west-2
    checksumAlgorithm: ""
  credential:
    name: cloud-credentials
    key: cloud
  default: true
  accessMode: ReadWrite
  validationFrequency: 1m

Backup¶

The top-level object that describes what to back up. Created by CLI, Schedule, or directly via kubectl.

Field	Type	Description
`spec.includedNamespaces`	`[]string`	Namespaces to include. Wildcard `*` = all (default).
`spec.excludedNamespaces`	`[]string`	Always exclude these, even if included above.
`spec.includedResources`	`[]string`	Resource types to include (e.g. `deployments`, `persistentvolumeclaims`). Default: all.
`spec.excludedResources`	`[]string`	Always skip these. Velero has a built-in excludeList for ephemeral objects (Events, etc.).
`spec.labelSelector`	`LabelSelector`	Only include resources matching this selector.
`spec.orLabelSelectors`	`[]LabelSelector`	Union of label selectors. Added in v1.10 to address the "must match ALL labels" limitation.
`spec.snapshotVolumes`	`*bool`	Enable/disable cloud provider volume snapshotting. Set to `false` to skip volume data.
`spec.ttl`	`duration`	After this duration, GCController will delete the backup. Default `720h` (30 days).
`spec.storageLocation`	`string`	Name of the BSL to use. Defaults to BSL with `default: true`.
`spec.hooks`	`BackupHooks`	Pre/post backup hooks on pods. See Hooks.
`spec.defaultVolumesToFsBackup`	`bool`	If true, all PVCs get Kopia file-level backup in addition to (or instead of) snapshots.
`status.phase`	`enum`	`New → InProgress → Completed \\| PartiallyFailed \\| Failed \\| Deleting`
`status.startTimestamp`	`time`	Used by TTL calculation. Expiration = `startTimestamp + TTL`.

Backup Lifecycle¶

New ──► InProgress ──► Completed
                   └──► PartiallyFailed
                   └──► Failed
                           └──► Deleting  (via DeleteBackupRequest)

Restore¶

Restores are immutable after creation. The RestoreController reconciles them exactly once to completion.

Field	Type	Description
`spec.backupName`	`string`	Required. Name of the Backup object to restore from.
`spec.namespaceMapping`	`map[string]string`	Remap namespace names during restore. Essential for migration scenarios.
`spec.includedResources` / `excludedResources`	`[]string`	Fine-grained resource filtering, independent of what was backed up.
`spec.restorePVs`	`*bool`	Whether to restore PV data (via snapshot or file copy).
`spec.existingResourcePolicy`	`none,update`	`none` (default) = skip existing resources. `update` = patch existing resources from backup.
`spec.hooks`	`RestoreHooks`	Init container hooks executed during pod restore. See Hooks.

VolumeSnapshotLocation (VSL)¶

VSL configures a cloud provider's volume snapshot API. Less critical since the push toward CSI snapshots, but still required for legacy cloud provider snapshot plugins.

Field	Type	Description
`spec.provider`	`string`	Plugin identifier for the VolumeSnapshotter implementation.
`spec.config`	`map[string]string`	Provider-specific config (region, apiTimeout, etc.).

Schedule¶

Field	Type	Description
`spec.schedule`	`string`	Standard cron expression. Also supports `@every 6h` shorthand.
`spec.template`	`BackupSpec`	Backup spec to instantiate on each tick. All Backup fields apply.
`spec.useOwnerReferencesInBackup`	`bool`	If true, created Backups are owned by the Schedule and GC'd with it.
`status.lastBackup`	`time`	When the last Backup was created. Used to compute the next trigger.

DeleteBackupRequest¶

Creating this object triggers the BackupDeletionController to delete both the object store artifacts and the Backup CRD.

Do not delete the Backup CRD directly: the object store artifacts will be orphaned.

Operational Rule

Always use velero backup delete <name> (or create a DeleteBackupRequest CRD).

Never kubectl delete backup <name>.

apiVersion: velero.io/v1
kind: DeleteBackupRequest
metadata:
  name: delete-my-backup
  namespace: velero
spec:
  backupName: my-backup

Next Up¶

Backup Mechanics