Backup Longhorn volumes to a self-hosted Garage server

Longhorn can back up its volumes to any S3-compatible target. Most guides assume you're pointing it at AWS, but it works just as well against a self-hosted Garage instance.

The URL format is the part nobody explains clearly, so here it is.

Create the credentials secret

Longhorn reads the S3 credentials from a Kubernetes secret in the longhorn-system namespace, so you should create it in your cluster:

vim backup-secret.yaml

Replace the stringData values with your own.

apiVersion: v1
kind: Secret
metadata:
  name: backup-secret
  namespace: longhorn-system
type: Opaque
stringData:
  AWS_ACCESS_KEY_ID: <your-garage-access-key>
  AWS_SECRET_ACCESS_KEY: <your-garage-secret-key>
  AWS_ENDPOINTS: http://backups.example.com:9000

kubectl apply -f backup-secret.yaml

AWS_ENDPOINTS is what points Longhorn at Garage instead of AWS. Include the scheme and the port.

If your Garage instance is behind a self-signed certificate, add the CA to the same secret under AWS_CERT and set the protocol to https, otherwise the backup target will fail to connect with a TLS error.

Point Longhorn at the bucket

In the Longhorn UI, go to Settings → General → Backup Target and set:

s3://longhorn@homelab/longhorn

Then set Backup Target Credential Secret to backup-secret.

The syntax reads as s3://<bucket>@<region>/<path>. That @region is not optional even though Garage doesn't really care have regions. Set it to whatever region name you configured in Garage (homelab in my case) and it works. Leave it out and Longhorn refuses the target.

Test it

Go to Backup in the sidebar. If the target is wrong you'll get an error banner immediately.

Then pick a volume under Volume, hit Create Backup, and watch it appear in your Garage bucket:

garage bucket info longhorn

Now you can set up recurring backups per volume with a Recurring Job, and have your data safe and sound.