> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ankra.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Backup Vaults
> Register an S3-compatible bucket as a backup vault so your clusters have somewhere to write restore points, verify its credentials, and manage vaults from the dashboard or the CLI.
A **backup vault** is an object-storage bucket your organisation owns that Ankra writes cluster backups to. Vaults are the foundation of Ankra's backup-first data model: every stack backup policy and every restore point lands in a vault, and cloning a stack *with its data* restores from one.
Backup vaults are rolling out gradually, per organisation. Until the **backups** feature is enabled for yours, the **Backups** page under organisation settings explains that it is not enabled yet, and every `ankra backup vaults` command (and the underlying API) answers `Backups are not enabled for this organisation.` See [Not enabled yet?](#not-enabled-yet) below.
## Why a vault first
Ankra's answer to "copy this database to another cluster" is the industry one: take a backup, then restore it on the target. That keeps data off the platform entirely - the source cluster writes to the bucket, the target reads from it over HTTPS - and it means a disaster-recovery copy exists as a side effect of every clone.
That only works with somewhere to write to, which is what a vault is. Registering one is a one-time, organisation-level step.
## What a vault records
| Field | What it is |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | How the vault is referred to in policies and the CLI |
| Provider | The object-storage service, or `other` for any S3-compatible endpoint |
| Endpoint | The S3 endpoint URL |
| Bucket | The bucket backups are written to |
| Region | Only needed when the endpoint does not imply it |
| Path style | `https://endpoint/bucket` addressing - required by most self-hosted S3 services |
| Status | `ready`, `error` (with the failure excerpt), or `provisioning` while Ankra is still creating the bucket or checking the keys |
| Kind | `ankra_provisioned` when Ankra created the bucket from one of your provider credentials, `customer_s3` when you registered a bucket you already had |
The access key ID and secret you provide are written to Ankra's secret store and never returned by the API, the dashboard, or the CLI. Rotating keys means creating a new vault or re-verifying after updating the bucket policy.
## Let Ankra create the bucket
The quickest path: pick one of your organisation's provider credentials and a region, and Ankra creates the bucket, mints or stores the access keys, verifies the bucket and registers the vault. The vault shows **Provisioning** until that has finished, then **Ready** - or **Failed** with the excerpt of what the provider refused.
| Credential | What Ankra does with it | What you still supply |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UpCloud | Creates a Managed Object Storage service in the region, a user with the `ECSS3FullAccess` policy and an access key, then the bucket | Nothing - the region is checked against your account's list |
| DigitalOcean | Mints a Spaces access key with the API token and creates the Space | Nothing |
| Scaleway | Uses the credential's own IAM key pair (Scaleway API keys are S3 keys) and creates the bucket in the credential's project | Nothing |
| Hetzner | Creates the bucket at the chosen location with the Object Storage key pair you provide | The key pair: Hetzner issues it in the Cloud Console (**Object Storage > Manage credentials**), and its Cloud API cannot mint one - so neither can Ankra |
Other credential kinds (OVH, AWS, GCP, Azure, Proxmox, Morpheus) cannot provision a bucket yet - register a bucket you own instead, below.
Go to your organisation's **Settings** and choose **Backups**, then **Add vault** and **Let Ankra create the bucket**.
Pick the credential; the form tells you what that provider needs. Enter the region (the placeholder shows the provider's shape) and, if you want a specific name, the bucket - otherwise Ankra derives a unique one from the vault name.
For a Hetzner credential the form asks for the access key and secret key from the Cloud Console. They are stored in Ankra's secret store and never shown again.
The row shows **Provisioning** with "Creating the bucket on ..."; the page refreshes on its own until it reads **Ready**. A **Failed** vault shows what the provider answered - a region your account cannot use, a bucket name someone else holds, a token without the right scope - and can be deleted and re-added once that is fixed.
```bash theme={null}
ankra backup vaults provision offsite --credential upcloud-main --region europe-1 --wait
```
`--credential` takes a credential name or id. `--wait` blocks until the vault is `ready` (or exits non-zero with the failure excerpt); without it the command returns as soon as the platform has accepted the request, and `ankra backup vaults get offsite` shows progress. `--bucket` names the bucket explicitly.
For a Hetzner credential the command prompts for the Object Storage access key and (hidden) secret key when they are not passed with `--access-key-id` / `--secret-access-key`:
```bash theme={null}
ankra backup vaults provision offsite --credential hetzner-main --region fsn1
```
Ankra records the provider-side handle it created (the UpCloud service, the DigitalOcean key) on the vault. Deleting the vault removes Ankra's record and stored keys only; the bucket, its contents, and the provider resources stay - tear them down in the provider console when the data is no longer needed.
## Bring your own bucket
Go to your organisation's **Settings** and choose **Backups**.
Click **Add vault** and pick the provider first: the dialog fills in the endpoint and region shapes that provider uses, sets **Path-style addressing** to what it expects (off for Amazon S3, on everywhere else), and says where its access keys are issued. Then enter the endpoint, bucket, region (if needed) and the keys.
Ankra immediately checks the credentials against the bucket. A vault that passes shows **Ready**; one that does not shows **Failed** with the excerpt of what the bucket answered and a **Verify again** action - see [When verification fails](#when-verification-fails).
```bash theme={null}
ankra backup vaults create production-backups \
--provider upcloud \
--endpoint https://fi-hel2.upcloudobjects.com \
--bucket ankra-prod-backups \
--region fi-hel2
```
The access key ID and secret are prompted for when not passed as flags - the secret hidden - so they stay out of your shell history. Prefer the prompt over `--access-key-id` / `--secret-access-key`.
A vault that fails its first verification exits non-zero with the failure excerpt instead of a green create.
## Provider notes
| Provider | Endpoint shape | Notes |
| ----------------------- | ----------------------------------------- | ---------------------------------------------------- |
| UpCloud Object Storage | `https://.upcloudobjects.com` | Region is the endpoint prefix, for example `fi-hel2` |
| DigitalOcean Spaces | `https://.digitaloceanspaces.com` | Spaces keys are separate from API tokens |
| Scaleway Object Storage | `https://s3..scw.cloud` | Uses the same key pair as the API |
| Hetzner Object Storage | `https://.your-objectstorage.com` | Keys are issued in the console, not the cloud API |
| Amazon S3 | `https://s3..amazonaws.com` | Turn **path style** off |
| Other | Anything S3-compatible | MinIO, Garage, Ceph RGW; keep path style on |
## When verification fails
A **Failed** vault is still registered - nothing has to be redone from scratch - but the keys you gave it are never read back, so they cannot be edited in place. The recovery depends on what the excerpt says:
| Excerpt | Cause | Fix |
| ---------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `403 Forbidden` / `AccessDenied` | The key is valid but cannot reach this bucket | Fix the bucket policy or the key's permissions, then **Verify again** (`ankra backup vaults verify `) |
| `InvalidAccessKeyId` / `SignatureDoesNotMatch` | The key pair is wrong | Delete the vault and add it again with the corrected keys |
| `NoSuchBucket` | The bucket name or region is wrong | Delete and re-add with the right bucket; on providers whose region is part of the endpoint, check the endpoint too |
| Connection or DNS errors | The endpoint is wrong or unreachable from Ankra | Check the endpoint URL (it must start with `https://`) and re-add, or fix the network path and **Verify again** |
**Verify again** re-runs the same check the create ran; the row updates in place with the new status and the time it last verified.
## Manage vaults
```bash theme={null}
ankra backup vaults list # every vault with status and last verification
ankra backup vaults get production-backups # details, including a failure excerpt
ankra backup vaults verify production-backups # re-run the credential check
ankra backup vaults delete production-backups # confirms first; --yes to skip
```
`get`, `verify` and `delete` accept a vault name or id, and `list` / `get` support `-o json|yaml`. `verify` on a vault that is still provisioning answers that it is still being provisioned rather than recording a failed check.
**Deleting a vault never touches the bucket.** It removes Ankra's record and credentials only. A vault that a backup policy or an in-flight data clone still references cannot be deleted - retire those first.
## Permissions
| Permission | Allows |
| ----------------- | ---------------------------------------------------------------- |
| `backups.read` | Seeing vaults, policies and restore points |
| `backups.operate` | Creating restore points, running restores and data clones |
| `backups.manage` | Creating, verifying and deleting vaults; setting backup policies |
Organisation admins hold all three. A member with only `backups.read` sees the vault list read-only; the page says so and names the permission an admin has to grant for adding, verifying or deleting a vault.
## Not enabled yet?
The feature is switched on per organisation. While it is dark:
* The **Backups** settings page renders an explanation instead of the vault list.
* `ankra backup vaults …` exits non-zero with `Backups are not enabled for this organisation.` followed by what to do about it. A real permission refusal on the same commands keeps its own wording, so the two are never confused.
* The API answers `403` with that same text on every vault route, browser and token alike - a personal access token cannot reach the lane in an organisation where it is dark.
Two things to check before asking for it to be enabled:
1. **The right organisation is selected.** The CLI acts on the current organisation - `ankra org current` shows which, and `ankra org switch ` changes it.
2. **The account is in the organisation that was enabled.** Enablement is per organisation, not per user.
Then ask Ankra to enable the **backups** feature for the organisation.
## Next steps
How vaults, policies and restore points fit together.
Clone a stack's configuration today - data follows via restore points.