Back up a cluster with Velero

Last updated on Aug 7, 2026

This guide outlines how to back up your entire Kubernetes cluster with Velero, backed by STACKIT Object Storage.

What is Velero?

Velero is an open-source tool to safely back up, recover, and migrate Kubernetes clusters and volumes. It works both on-premises and in the public cloud. Velero runs as a Deployment in your cluster and comes with a CLI that lets you run scheduled backups, restores, and more.

It was designed to have certain advantages over classic etcd backups. Velero uses the Kubernetes API discovery capabilities to collect the data it needs to back up. As a result, Velero does not need to be updated to support new APIs. Thanks to this discovery approach, Velero can back up clusters that include aggregated API servers, which would otherwise require a complete etcd backup.

Setup

S3 backend

To store backup data, Velero requires a configured storage provider. In this guide, you use STACKIT Object Storage, an S3-compatible blob storage implementation.

To configure STACKIT Object Storage as a Velero provider, you need an access key ID and a secret access key. Visit the STACKIT Object Storage docs to learn how to manage credentials and buckets.

Save your credentials in a file named velero-s3 in the following format:
```
[default]
aws_access_key_id=$ACCESS_KEY_ID
aws_secret_access_key=$SECRET_ACCESS_KEY
```
The velero-s3 file contains the Object Storage access key and secret in clear text. After running velero install, delete the local file via rm velero-s3 to avoid leaking credentials. The credentials are stored as a Kubernetes Secret in the velero namespace; treat it as sensitive and restrict access accordingly.
Create a new backup bucket for Velero. Keep in mind that the bucket name must be globally unique. To create a bucket, visit the STACKIT Portal, go to Storage > Object Storage, and create a new bucket.

With the credentials file and backup bucket in place, Velero has everything it needs to connect to STACKIT Object Storage.

Velero CLI

Velero uses CRDs to manage backups and restores, which you can create manually with a YAML definition. To make this easier, Velero provides a CLI with a range of utility functions for working with these resources.

Download from GitHub Releases or visit the official documentation for more installation instructions.

Velero server components

You can install the Velero server components via CLI or Helm chart. This guide shows the installation via CLI only. To learn more about the installation via Helm chart, visit the VMware Tanzu Helm repository page.

Replace the plugin version in the following command with a current release.

velero install \
    --provider aws \
    --plugins velero/velero-plugin-for-aws:v1.13.0 \
    --bucket $BUCKET_NAME \
    --backup-location-config region=eu01,s3ForcePathStyle=true,s3Url=https://object.storage.eu01.onstackit.cloud,checksumAlgorithm="" \
    --use-volume-snapshots=false \
    --secret-file ./velero-s3

For more detailed instructions visit the velero-plugin-for-aws repository.

Velero file system backup

A default Velero installation does not provide file system backup capabilities. The previous installation example sets --use-volume-snapshots=false, so it only backs up Kubernetes objects (Deployments, Services, ConfigMaps, etc.), not the contents of PVCs.

Decide what you need to back up:

Kubernetes objects only: The installation example on this page is sufficient.
PVC contents as well: Enable Velero File System Backup by adding --use-node-agent to the velero install command, and optionally --default-volumes-to-fs-backup to back up all PVC volumes by default. For details, read Velero’s documentation about File System Backup.

Manual backup

Run an on-demand backup and verify that Velero can restore it. The following steps create a backup, simulate data loss, and then recover from that backup.

Back up a full namespace:
Terminal window
```
velero backup create example-backup --include-namespaces $NAMESPACE
```
Alternatively, back up only the resources that match a specific label instead of an entire namespace:
Terminal window
```
velero backup create nginx-backup --selector app=$SELECTOR
```
Delete the namespace to simulate a disaster:

Deleting a namespace permanently removes all its resources, and — depending on the PersistentVolume reclaim policy — the underlying volume data may be lost as well. Only run this against a disposable test namespace, never in production.
Terminal window
```
kubectl delete namespace $NAMESPACE
```

Restore the namespace:

velero restore create --from-backup example-backup

After the restore completes, the namespace and its resources are back in the cluster, confirming that your backup is valid.

Schedule backups

Instead of running backups by hand, define a schedule so Velero creates them automatically at a fixed interval.

Create a schedule that creates a backup every hour:
Terminal window
```
velero schedule create example-schedule --schedule="0 * * * *" --include-namespaces $NAMESPACE
```
Alternatively, schedule a backup of only the resources that match a specific label instead of an entire namespace:
Terminal window
```
velero schedule create example-schedule --schedule="@hourly" --selector app=$SELECTOR
```

Trigger it manually:

velero backup create --from-schedule example-schedule

The schedule now runs in the background and produces recurring backups without further action.

Manage your backups

List all backups

List all existing backups together with their phase, creation time, and expiration date:

velero backup get

Restore a specific backup

Pass the name of an existing backup to the following command to recover its contents into the cluster:

velero restore create --from-backup $BACKUP_NAME

Velero derives the restore name automatically from the backup name and a timestamp. To list all restores and their current status, use the following command:

velero restore get

To inspect a single restore in detail, pass its name to the following command:

velero restore describe <restore-name>