Backup Operator CRD Reference

Complete field reference for BackupPolicy, BackupRun, and RestoreRun custom resource definitions

The PodWarden Backup Operator manages backup and restore lifecycles for workloads running on PodWarden-managed clusters. It uses Restic for incremental, encrypted, deduplicated snapshots stored on S3 or NFS.

API Group: backup.podwarden.com Version: v1alpha1

Installation

The backup operator is a preinstalled system app — it's deployed automatically when PodWarden bootstraps a cluster. No manual installation is needed.

For manual installation or upgrades:

# Via Helm (recommended)
helm install backup-operator ./charts/backup-operator/ \
  -n podwarden-backup-operator-system --create-namespace

# Via kubectl (from rendered manifest)
kubectl apply -f https://www.podwarden.com/operators/backup-operator/install.yaml

Upgrade:

helm upgrade backup-operator ./charts/backup-operator/ \
  -n podwarden-backup-operator-system --set image.tag=<version>

BackupPolicy

Defines what to back up, where to store it, on what schedule, and with what retention.

Spec

Field	Type	Required	Default	Description
`schedule`	string	Yes	—	Cron expression for backup schedule, e.g. `"0 3 * * *"`
`mode`	string	Yes	—	`"hot"` (no downtime) or `"cold"` (scale to zero during backup)
`suspend`	bool	No	`false`	When `true`, skip scheduling new backups
`target.deploymentName`	string	Yes	—	Name of the Kubernetes Deployment to back up
`target.volumeNames`	[]string	No	all	Filter to specific PVC names. Empty means all PVCs attached to the Deployment
`storage.type`	string	Yes	—	`"s3"` or `"nfs"`
`storage.s3.endpoint`	string	No	—	S3-compatible endpoint URL
`storage.s3.bucket`	string	No	—	S3 bucket name
`storage.s3.credentialsSecretRef`	string	No	—	Secret name containing keys `access-key` and `secret-key`
`storage.nfs.server`	string	No	—	NFS server hostname
`storage.nfs.basePath`	string	No	—	NFS base path
`storage.repoPath`	string	Yes	—	Path within storage for the Restic repository
`storage.passwordSecretRef`	string	Yes	—	Secret name containing key `restic-password`
`retention.keepLast`	int	No	`7`	Number of latest snapshots to keep
`retention.keepDaily`	int	No	`7`	Number of daily snapshots to keep
`retention.keepWeekly`	int	No	`4`	Number of weekly snapshots to keep
`hooks.pre.container`	string	No	—	Container name to exec into before backup
`hooks.pre.command`	[]string	No	—	Command to run before backup
`hooks.pre.timeoutSeconds`	int	No	`300`	Timeout for the pre-backup hook
`hooks.post.container`	string	No	—	Container name to exec into after backup
`hooks.post.command`	[]string	No	—	Command to run after backup
`hooks.post.timeoutSeconds`	int	No	`300`	Timeout for the post-backup hook

Status

Field	Type	Description
`lastBackupTime`	timestamp	When the last backup completed
`lastBackupStatus`	string	`"Success"`, `"Failed"`, or `"Running"`
`lastError`	string	Error message from the last failed backup
`currentJob`	string	Name of the currently running BackupRun
`conditions[]`	[]Condition	Standard Kubernetes conditions

Print Columns

Column	Field
Schedule	`.spec.schedule`
Mode	`.spec.mode`
Last Backup	`.status.lastBackupTime`
Status	`.status.lastBackupStatus`

Example

apiVersion: backup.podwarden.com/v1alpha1
kind: BackupPolicy
metadata:
  name: my-app-backup
  namespace: my-app
spec:
  schedule: "0 3 * * *"
  mode: hot
  target:
    deploymentName: my-app
    volumeNames:
      - data
  storage:
    type: s3
    s3:
      endpoint: https://s3.example.com
      bucket: backups
      credentialsSecretRef: s3-credentials
    repoPath: /my-app/restic-repo
    passwordSecretRef: restic-password
  retention:
    keepLast: 7
    keepDaily: 7
    keepWeekly: 4
  hooks:
    pre:
      container: my-app
      command: ["sh", "-c", "pg_dump -U app appdb > /data/dump.sql"]
      timeoutSeconds: 120
    post:
      container: my-app
      command: ["sh", "-c", "rm /data/dump.sql"]

BackupRun

Represents a single backup execution. Created automatically by the operator on schedule, or manually by the user.

Spec

Field	Type	Required	Description
`policyRef`	string	Yes	Name of the parent BackupPolicy
`trigger`	string	Yes	`"scheduled"` or `"manual"`

Status

Field	Type	Description
`phase`	string	`Pending`, `Running`, `Completed`, or `Failed`
`startedAt`	timestamp	When the backup started
`completedAt`	timestamp	When the backup finished
`jobName`	string	Name of the Kubernetes Job executing the backup
`error`	string	Error message if the backup failed
`snapshots[]`	[]Snapshot	Per-volume results (see below)
`totalSizeBytes`	int64	Total size of all snapshots
`sourceSnapshot`	object	Deployment state captured at backup time (see below)

Snapshot Fields

Field	Type	Description
`volumeName`	string	PVC name
`resticSnapshotId`	string	Restic snapshot identifier
`sizeBytes`	int64	Size of new data added
`filesNew`	int	Number of new files
`filesChanged`	int	Number of changed files
`filesUnmodified`	int	Number of unchanged files

Source Snapshot Fields

Field	Type	Description
`deploymentName`	string	Deployment name at backup time
`images[]`	[]string	Container images in use
`volumes[]`	[]string	Volume names attached
`annotations{}`	map[string]string	Deployment annotations

Print Columns

Column	Field
Policy	`.spec.policyRef`
Trigger	`.spec.trigger`
Phase	`.status.phase`
Started	`.status.startedAt`
Size	`.status.totalSizeBytes`

Example

apiVersion: backup.podwarden.com/v1alpha1
kind: BackupRun
metadata:
  name: my-app-backup-20260322-030000
  namespace: my-app
spec:
  policyRef: my-app-backup
  trigger: manual

RestoreRun

Restores data from a BackupRun to a target deployment. The operator performs a compatibility check, scales down the deployment, runs the restore Job, and scales back up.

Spec

Field	Type	Required	Default	Description
`backupRunRef`	string	Yes	—	Name of the BackupRun to restore from
`backupRunNamespace`	string	No	same namespace	Namespace of the BackupRun (for cross-namespace restore)
`targetDeployment`	string	Yes	—	Deployment to restore data to
`requireCompatible`	bool	No	`false`	When `true`, fail if any compatibility issues are detected

Status

Field	Type	Description
`phase`	string	`Pending`, `Running`, `Completed`, or `Failed`
`startedAt`	timestamp	When the restore started
`completedAt`	timestamp	When the restore finished
`error`	string	Error message if the restore failed
`jobName`	string	Name of the Kubernetes Job executing the restore
`compatibility`	object	Compatibility check results (see below)

Compatibility Fields

Field	Type	Description
`compatible`	bool	Whether the restore is fully compatible
`warnings[]`	[]string	Non-blocking compatibility warnings
`errors[]`	[]string	Blocking compatibility errors
`templateChanged`	bool	Whether the Deployment template differs from the backup source

Print Columns

Column	Field
BackupRun	`.spec.backupRunRef`
Target	`.spec.targetDeployment`
Phase	`.status.phase`
Compatible	`.status.compatibility.compatible`

Example

apiVersion: backup.podwarden.com/v1alpha1
kind: RestoreRun
metadata:
  name: my-app-restore-20260322
  namespace: my-app
spec:
  backupRunRef: my-app-backup-20260322-030000
  targetDeployment: my-app
  requireCompatible: true

System App Integration

The Backup Operator registers itself as a PodWarden System App via a ConfigMap with the label podwarden.com/system-app: "true".

apiVersion: v1
kind: ConfigMap
metadata:
  name: backup-operator-system-app
  namespace: podwarden-backup-operator-system
  labels:
    podwarden.com/system-app: "true"
data:
  name: Backup Operator
  description: Kubernetes-native backup and restore for PodWarden workloads
  version: "0.1.0"
  capabilities: "backup:manage,backup:restore,backup:schedule"

Capabilities

Capability	Description
`backup:manage`	Create, update, and delete BackupPolicy resources
`backup:restore`	Create RestoreRun resources to restore from backups
`backup:schedule`	Modify backup schedules and retention settings

Auto-Provisioned Namespace Resources

When a BackupPolicy is created in a namespace, the operator automatically provisions the following resources. All managed resources carry the label backup.podwarden.com/managed-by: operator.

Resource	Name	Purpose
ConfigMap	`backup-scripts`	Contains `backup.sh` and `restore.sh` Restic wrapper scripts
ServiceAccount	`backup-operator`	Identity for backup/restore Jobs
Role	`backup-operator`	Permissions for Jobs to read PVCs, Secrets, and Pods
RoleBinding	`backup-operator`	Binds the Role to the ServiceAccount

These resources are garbage-collected when the last BackupPolicy in a namespace is deleted.