Migrating Longhorn Backup from MinIO to Garage

merox

Oct 27, 2025

How to replace MinIO with Garage as the S3 backend for Longhorn backups — setup, bucket config, Kubernetes secret, and HelmRelease update.

MinIO’s been moving in a direction that doesn’t make much sense for homelab use anymore — Docker images dropped, source-only distribution, licensing drift. The result is most self-hosted installs sitting on outdated versions with known CVEs and no clean upgrade path. I replaced it with Garage, which is lightweight, actively maintained, S3-compatible, and doesn’t have any of that baggage.

Note

For restoring from Longhorn backups after this migration, see Restoring from Longhorn Backups. The process is identical regardless of whether you’re using MinIO or Garage.

Prerequisites: Ubuntu server with Docker and Docker Compose, Kubernetes cluster with Longhorn installed. Check Garage releases for the latest version before deploying.

Setting Up Garage

Directory and Secrets

sudo mkdir -p /srv/docker/garage/{meta,data}
cd /srv/docker/garage

# Generate RPC secret
openssl rand -hex 32

# Generate admin token
openssl rand -hex 32

`garage.toml`

1
metadata_dir = "/var/lib/garage/meta"
2
data_dir = "/var/lib/garage/data"
3
db_engine = "lmdb"
4

5
replication_factor = 1
6

7
rpc_bind_addr = "0.0.0.0:3901"
8
rpc_public_addr = "127.0.0.1:3901"
9
rpc_secret = "YOUR_RPC_SECRET_HERE"
10

11
[s3_api]
12
s3_region = "us-east-1"
13
api_bind_addr = "0.0.0.0:3900"
14
root_domain = ".s3.garage"
15

16
[admin]
17
api_bind_addr = "0.0.0.0:3903"
18
admin_token = "YOUR_ADMIN_TOKEN_HERE"

Tip

replication_factor = 1 is fine for single-node. Use 3 for multi-node redundancy.

`docker-compose.yml`

1
version: "3"
2
services:
3
  garage:
4
    image: dxflrs/garage:v2.1.0
5
    container_name: garage
6
    network_mode: "host"
7
    restart: unless-stopped
8
    volumes:
9
      - ./garage.toml:/etc/garage.toml
10
      - ./meta:/var/lib/garage/meta
11
      - ./data:/var/lib/garage/data
12

13
  webui:
14
    image: khairul169/garage-webui:latest
15
    container_name: garage-webui
16
    restart: unless-stopped
17
    volumes:
18
      - ./garage.toml:/etc/garage.toml:ro
19
    environment:
20
      API_BASE_URL: "http://127.0.0.1:3903"
21
      S3_ENDPOINT_URL: "http://127.0.0.1:3900"
22
    network_mode: "host"

docker-compose up -d

Configure Storage

alias garage="docker exec -ti garage /garage"

garage node id

# Assign storage capacity
garage layout assign <node-id> -z default -c 100G

garage layout show
garage layout apply --version 1

# Create bucket and key
garage bucket create longhorn
garage key create longhorn-key
garage bucket allow longhorn --read --write --owner --key longhorn-key

# Note the Key ID and Secret key
garage key info longhorn-key --show-secret

Integrate with Longhorn

Kubernetes Secret

1
apiVersion: v1
2
kind: Secret
3
metadata:
4
  name: minio-secret
5
  namespace: longhorn-system
6
type: Opaque
7
stringData:
8
  AWS_ACCESS_KEY_ID: <Key-ID-from-garage>
9
  AWS_SECRET_ACCESS_KEY: <Secret-Key-from-garage>
10
  AWS_ENDPOINTS: http://<GARAGE_SERVER_IP>:3900
11
  AWS_REGION: us-east-1

kubectl apply -f minio-secret.yaml

HelmRelease Update

1
---
2
apiVersion: source.toolkit.fluxcd.io/v1
3
kind: HelmRepository
4
metadata:
5
  name: longhorn
6
  namespace: longhorn-system
7
spec:
8
  interval: 1h
9
  url: https://charts.longhorn.io
10
---
19 collapsed lines
11
apiVersion: helm.toolkit.fluxcd.io/v2
12
kind: HelmRelease
13
metadata:
14
  name: longhorn
15
spec:
16
  interval: 1h
17
  chart:
18
    spec:
19
      chart: longhorn
20
      version: 1.10.0
21
      sourceRef:
22
        kind: HelmRepository
23
        name: longhorn
24
        namespace: longhorn-system
25
  values:
26
    defaultSettings:
27
      backupTarget: "s3://longhorn@us-east-1/"
28
      backupTargetCredentialSecret: "minio-secret"
29
      backupstorePollInterval: "300"

Warning

In Longhorn 1.10.0+, backup settings are under defaultSettings, not a separate defaultBackupStore section.

Verify

Access the Garage WebUI at http://<SERVER_IP>:3909. Then test a backup from Longhorn UI → Volume → Create Backup and confirm it appears in the longhorn bucket.

garage bucket list
garage bucket info longhorn

Troubleshooting

WebUI “Unknown Error” — confirm the [admin] section is in garage.toml and restart:

docker-compose restart
docker logs garage

Port 3903 connection refused:

netstat -tlnp | grep 3903

Longhorn can’t reach Garage:

kubectl run -it --rm debug --image=amazon/aws-cli --restart=Never -- \
  s3 ls s3://longhorn --endpoint-url http://<GARAGE_IP>:3900