Backups

NetBox Enterprise integrates with Velero for Kubernetes-native backup and restore. The operator labels every resource it manages, so Velero can capture the whole deployment with label selectors.

From 2.3.0 the chart renders the Velero objects for you. You no longer write them by hand.

Prerequisites

• A running NetBox Enterprise Helm deployment
• A storage class that provisions local, csi, or network PersistentVolumes -- see Storage requirements
• Velero 1.13 or newer
• S3-compatible object storage (AWS S3, MinIO, and similar) for the backup target
• The velero CLI installed locally (installation guide)

Install Velero

Install Velero with the node-agent enabled, which is what performs filesystem-level volume backups. The example below uses the AWS S3 provider. See Velero supported providers for the others.

1. Create a credentials file for your S3 bucket:

[default]
aws_access_key_id=<YOUR_ACCESS_KEY>
aws_secret_access_key=<YOUR_SECRET_KEY>

2. Install Velero into the cluster:

velero install \
  --provider aws \
  --plugins velero/velero-plugin-for-aws:v1.11.1 \
  --bucket <BUCKET_NAME> \
  --secret-file ./credentials-velero \
  --backup-location-config \
    region=<REGION>,s3ForcePathStyle="true",s3Url=<S3_ENDPOINT> \
  --use-node-agent

For MinIO or another S3-compatible store, set s3Url to the endpoint, such as https://minio.example.com. For AWS S3, omit s3Url and s3ForcePathStyle.

If more than one cluster backs up to the same bucket, give each one its own prefix with --prefix <CLUSTER_NAME>. A shared bucket and prefix puts every cluster's backups in one pool, so velero backup get lists them all with nothing to tell them apart. This matters at restore time: a restore from another cluster's backup completes, reports success, and brings the cluster up over someone else's data.

3. Verify that Velero is ready:

velero version
kubectl -n velero get pods

Enable the chart's disaster-recovery objects

Set one value:

disasterRecovery:
  createVeleroSpecs: true

The chart then renders four objects into the velero namespace.

The chart deliberately ships no Restore. A Backup is a declaration that Velero acts on when the schedule says so. A Restore is an action that runs the moment the object exists, and Helm applies every chart manifest on every install and upgrade. A Restore in the chart would therefore restore over your live cluster as soon as a matching backup existed. See Restoring a pure-Helm install for the manifest to apply by hand at recovery time.

How label selection works

The operator labels every Kubernetes resource it manages. Velero uses these labels with OR semantics to select what to back up:

Do not widen these selectors, and do not replace them with a namespace-wide backup. See Do not widen the backup selectors for what breaks.

The PostgreSQL data volume is excluded on purpose. The pgBackRest repository volume carries the label instead, and that repository is the restorable copy of your database. See Why the data volume is not backed up.

Create a backup

Every command below writes netbox as the release namespace. Set NS to yours in the same shell, and the commands then follow it:

NS=netbox

A backup whose --include-namespaces matches nothing is not an error to Velero. It reports Completed with zero items.

On-demand backup

BACKUP="netbox-backup-$(date +%Y%m%d%H%M)"

velero backup create "$BACKUP" \
  --or-selector "app.kubernetes.io/managed-by=netbox-operator or netboxlabs.com/managed-by=netbox-operator or app.kubernetes.io/part-of=netbox-enterprise or postgres-operator.crunchydata.com/control-plane=pgo" \
  --include-namespaces "$NS",velero \
  --include-cluster-resources=true \
  --default-volumes-to-fs-backup \
  --wait

If you set up a schedule, you can also trigger an immediate backup from it:

velero backup create --from-schedule netbox-enterprise-daily --wait

Scheduled backup

The chart renders a one-shot Backup, not a Schedule. Create a Schedule for recurring backups. This example runs daily at 02:00 UTC with 30-day retention, and it mirrors the chart's own selectors and volume policy:

apiVersion: velero.io/v1
kind: Schedule
metadata:
  name: netbox-enterprise-daily
  namespace: velero
spec:
  schedule: "0 2 * * *"
  template:
    includeClusterResources: true
    includedNamespaces:
      - netbox # your release namespace
      - velero
    defaultVolumesToFsBackup: true
    ttl: 720h
    resourcePolicy:
      kind: ConfigMap
      name: netbox-enterprise-backup-resource-filters
    orLabelSelectors:
      - matchLabels:
          app.kubernetes.io/managed-by: netbox-operator
      - matchLabels:
          netboxlabs.com/managed-by: netbox-operator
      - matchLabels:
          app.kubernetes.io/part-of: netbox-enterprise
      - matchLabels:
          postgres-operator.crunchydata.com/control-plane: pgo

Check backup status

Name the backup you just took. $BACKUP from the create step above holds it. A cluster that followed the pre-2.3.0 guidance may still hold an old backup literally named netbox-backup, and velero backup describe on that reports Completed for a backup months old.

velero backup get
velero backup describe "$BACKUP" --details
velero backup logs "$BACKUP"

Do not trust Completed on its own. Confirm that volume data was captured:

kubectl -n velero get podvolumebackups \
  -l velero.io/backup-name="$BACKUP" \
  -o custom-columns='VOLUME:.spec.volume,PHASE:.status.phase,BYTES:.status.progress.bytesDone'

Expect one Completed row per persistent volume, each with a non-zero byte count. The pgBackRest repository volume must be among them: it is the only copy of your database in the archive.

An empty result has two causes, and they need different responses. Check the cheap one first: confirm the name against velero backup get, because a name that matches nothing returns exactly the same empty list. Once the name is known good, an empty result means no volume data was backed up at all, and the likely cause is a hostPath storage class.

Confirm separately that pgBackRest holds a backup set. See Verifying backups are working.

Restore from backup

The short form below recovers a named resource into a cluster that is still running. It is not a database recovery, and it is not a whole-namespace recovery.

1. Enable maintenance mode to stop the application:

kubectl -n "$NS" patch netboxenterprise netbox \
  --type merge \
  -p '{"spec":{"maintenanceMode":true}}'

2. Restore the object you are recovering. Substitute the backup name and the resource:

RESTORE="netbox-restore-$(date +%Y%m%d%H%M)"

velero restore create "$RESTORE" \
  --from-backup "$BACKUP" \
  --include-namespaces "$NS" \
  --include-resources <resource> \
  --wait

3. Check restore status, and read the warning count. A non-zero count is Velero listing what it skipped:

velero restore describe "$RESTORE" --details

4. Disable maintenance mode to resume:

kubectl -n "$NS" patch netboxenterprise netbox \
  --type merge \
  -p '{"spec":{"maintenanceMode":false}}'

5. Confirm your data is present. A healthy pod is not evidence. See Verify.

Data preservation

When a NetBoxEnterprise resource is deleted, its PersistentVolumeClaims are preserved rather than deleted. This prevents accidental data loss, and it lets you re-create the cluster and reattach the existing volumes.

Next Steps

• PostgreSQL Backups and Disaster Recovery - pgBackRest, the repository volume, and the restore procedure
• Maintenance Mode - Take NetBox offline during a restore
• Security - Protect backup credentials
• Velero documentation - Full Velero reference