Skip to content
SHC Docs

Set a backup destination

A new cluster has nowhere to send a backup until you connect a bucket. Until then shc backup create is refused with X400486BKPNRP: no backup destination is set. The portal doesn’t set one for you.

The bucket is the only off-server copy you need. A second copy (shc backup mirror) stays optional.

  • The shc command line, signed in to the cluster:

    Terminal window
    $ shc auth login --url https://<cluster domain>

    You sign in through the portal. You have to be the cluster’s registrant, an owner or an admin, which gives you platform:manage on it. An organisation member or viewer is refused, and every step below needs that role.

  • A bucket and an S3 key that aren’t on this cluster. The steps below use Hetzner Object Storage. Any S3-compatible store works the same way.

In the Hetzner console, make a bucket in one location, then an S3 key.

  • The bucket has to exist first. shc never creates it.

  • An S3 key is an access key and a secret key. A Cloud API token won’t work.

  • Hetzner shows the secret once, so save it now in a file, hz.json:

    { "access_key": "<access key>", "secret_key": "<secret key>" }
    Terminal window
    $ chmod 600 hz.json
  • A Hetzner key reaches every bucket in its project. To hold one to a single bucket, add a bucket policy at Hetzner naming that key. If the project holds anything you care about, make the key in a project of its own.

Replace fsn1 with your bucket’s location and <bucket> with its name. The endpoint has no scheme, no port and no path.

Terminal window
$ shc connection connect hzbak --type s3 -t master \
--cred s3_endpoint=fsn1.your-objectstorage.com \
--cred region=fsn1 \
--cred probe_bucket=<bucket> \
--value-file hz.json

Grant it to master, and to the tenant your app is in if that’s another one. The grant has to name the bucket, or backup.repo is refused with X403925CONBKT.

Terminal window
$ shc connection grant hzbak -t master --capability s3 --grantee master \
--boundary '{"buckets":["<bucket>"]}'
$ shc connection grant hzbak -t master --capability s3 --grantee <tenant> \
--boundary '{"buckets":["<bucket>"]}'

There’s one grant per connection and grantee. If the same tenant also uses external-s3, which needs an unscoped grant at Hetzner, make a second connection with the same key for it.

Terminal window
$ shc config set --scope global backup.repo @hzbak/<bucket>

--scope global sets it for every tenant, at the scope where the cluster keeps backup.password. Without it, a tenant named by -t, SHC_TENANT or your context would get it alone.

Leave backup.password alone. The cluster made that key when it was built, and it’s the one the next step copies.

A platform admin can set it from the cluster’s Console instead: Manage > Backups, press Backup destination, pick hzbak, type the bucket and press Save.

4. Copy the repository key off the cluster

Section titled “4. Copy the repository key off the cluster”

The archive in your bucket is encrypted, and the key that opens it lives in the cluster’s vault and nowhere else. Lose the cluster without a copy of this key and nobody can open what’s in the bucket, you included. Keep it somewhere that isn’t the cluster.

Terminal window
$ shc vault get backup/password > backup.key
$ chmod 600 backup.key

<env> is default unless you installed the app under another name.

Terminal window
$ shc backup create <app> -t <tenant> -e <env>
$ shc backup ls -s <app> -t <tenant> -e <env> -o json

Then look at the bucket in the Hetzner console. It should hold objects, and its size should have grown by about what the app holds.

You seeIt meansDo this
X400486BKPNRPNo backup.repo is setSteps 2 and 3
X403910CONGRTThe connection isn’t granted to this tenantThe grants in step 2
X403925CONBKTThe grant doesn’t name this bucketThe grants in step 2