Change backup storage destination

What this is

Aerospike Backup Service (ABS) does not copy backup files when you change a routine’s storage name. After the change, ABS sees only the backups that already exist in the new destination. Incremental backups depend on metadata.yaml in that destination.

The examples use BASE_URL for the ABS listen address, for example http://localhost:8080.

Change the storage destination for a routine

To change the storage destination, edit the destination in the configuration file and reload the configuration. On Linux, the configuration file is /etc/aerospike-backup-service/aerospike-backup-service.yml by default.

1. Perform a full backup before you change storage destinations. See Trigger an on-demand backup.

2. Pause the routine:

   curl -X PUT "$BASE_URL/v1/config/routines/ROUTINE_NAME/disable"

   You can also set disabled: true on the routine in the YAML file. Do not comment out interval-cron; it is required.

3. Choose one of the following:

   • Migrate existing data: Manually copy the routine’s backup/ directory, including metadata.yaml, to the new storage location. If the routine also has incremental backups, copy the incremental/ directory too, so ABS finds the full incremental history.
   • New backup: Plan a full backup in the new storage location.

4. Modify the routine’s storage value in the configuration file. Verify that the destination does not contain an older metadata.yaml file under backup/ or incremental/.

5. Resume scheduling:

   curl -X PUT "$BASE_URL/v1/config/routines/ROUTINE_NAME/enable"

   If you edited YAML, set disabled: false again.

6. Reload configuration:

   curl -X POST "$BASE_URL/v1/config/apply"

   Restarting ABS also reloads the file. On Linux, restart ABS with systemctl restart aerospike-backup-service. See Service management.

You can verify that the new destination works by triggering a backup with POST /v1/backups/full/ROUTINE_NAME, then calling GET /v1/backups/full to verify that a new full backup appears in the returned list. The legacy POST /v1/backups/schedule/ROUTINE_NAME endpoint is deprecated, but still supported.

How ABS finds backups after a reload

After ABS restarts or reloads the configuration, it stores all new backups in the new destination. It also performs a one-time scan of the configured storage for each routine. It searches ROUTINE_NAME/backup/ and ROUTINE_NAME/incremental/ for the most recent metadata.yaml files.

If it finds a full backup’s metadata.yaml, ABS treats it as the full backup baseline, regardless of the age of the backup. If a later incremental backup’s metadata.yaml also exists, ABS uses that later timestamp instead. The next incremental backup saves all data changed since that timestamp.

Note

The first incremental backup may be unusually large if metadata.yaml is outdated, for example if switching back to a previously-used older storage bucket. To avoid unexpectedly large incremental backups, trigger a full backup or copy the latest metadata.yaml from your old storage to the new bucket.

If it does not find metadata.yaml, ABS does not run incremental jobs and logs incremental backup skipped with an error value such as backup skipped: initial full backup not yet completed. Incremental backups are skipped until you complete a new full backup. See Backup skip outcomes.

View your backups

The API endpoint GET /v1/backups/full lists only the backups that exist in the storage configured for the routine. After a storage change, this list reflects the new destination until you perform a new backup or copy a full backup there. This endpoint does not show any of the existing backups in the old destination after switching storage destinations.