---
title: "Aerospike Backup Service architecture"
description: "How Aerospike Backup Service (ABS) is structured at run time, including its main components, asynchronous backup and restore jobs, configuration reload, and deployment options."
---

# Aerospike Backup Service architecture

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

This page describes how Aerospike Backup Service (ABS) is put together: its main components, how backup and restore requests run, how configuration changes are applied, and how the same binary is deployed on Linux, Docker, and Kubernetes.

For the configuration objects a routine ties together, see [Concepts](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/concepts). For YAML field names and defaults, see [Configure ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/configure).

## Applies to

-   Product: Aerospike Backup Service (ABS) 3.7.x.
-   Audience: operators and SREs who plan an ABS deployment or troubleshoot how jobs and configuration changes behave.
-   Prerequisites: none. [Concepts](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/concepts) introduces the objects this page refers to.
-   Outcome: you can trace a backup or restore request from the REST API to storage, tell which configuration changes need a restart, and choose a deployment topology.

## Components

A request flows from the API client into the REST API listener, through service orchestration, and into the backup-go engine, which reads from Aerospike Database clusters and writes to storage backends. The Quartz scheduler triggers periodic jobs through the same orchestration layer. Prometheus scrapes job metrics from `/metrics`.

| Component | Role |
| --- | --- |
| REST API | Validates requests, serves configuration and job status, and triggers backup and restore jobs. Listens on HTTP and/or HTTPS. |
| Service orchestration | Owns the running-backups registry, backup and restore orchestration, retention, history, and the logic that reconciles configuration changes into scheduled jobs. |
| Quartz scheduler | Drives periodic full and incremental backups from each routine’s cron expressions. On-demand backups and restores bypass Quartz and start immediately. |
| backup-go engine | Reads records from Aerospike Database with primary index (PI) queries, writes `.asb` backup files, and restores records. ABS adapts this library to its job model. |
| Storage backends | A common interface for Amazon S3 (and S3-compatible stores), Google Cloud Storage, Azure Blob Storage, and local disk. |
| Prometheus collector | Polls running backup and restore jobs on a fixed interval and exposes the metrics documented in [Monitor ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/monitoring). |

ABS is a single static binary. It needs network access to the Aerospike cluster(s) and to the configured storage backend, and a configuration file or remote configuration source.

## Backup and restore request lifecycle

Backup and restore jobs are asynchronous. A cluster backup or restore can run for hours, longer than an HTTP client can usefully hold a connection open.

1.  A client calls `POST /v1/backups/full/{name}`, `POST /v1/backups/incremental/{name}`, or a restore endpoint such as `POST /v1/restore/full`.
2.  ABS validates the request, looks up the routine or restore policy from the in-memory configuration, and starts the job in the background. The job is registered in the running-backups registry or the restore jobs holder.
3.  The handler returns `202 Accepted` immediately. It does not wait for the job to finish.
4.  The client polls status separately: `GET /v1/backups/currentBackup/{name}` for backups, or `GET /v1/restore/status/{jobId}` for restores. Progress is also exported as Prometheus metrics. See [API usage examples](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/api-examples).
5.  A job that has started is not canceled when the client that triggered it disconnects. Stop a running backup with `POST /v1/backups/cancel/{name}`. Stop a restore with `POST /v1/restore/cancel/{jobId}`.

Scheduled (cron-triggered) backups follow the same execution path, minus the initial HTTP request. Quartz invokes the same orchestration code that on-demand triggers use.

## Configuration sources and reload

ABS loads configuration from a local file path (`-c`), an HTTP(S) URL, or a remote storage location (`-r`). ABS validates configured namespaces against the connected Aerospike cluster(s) at startup and logs warnings if any are missing or unreachable, without blocking service startup.

You can change clusters, storage, policies, and routines without restarting the process. Changes to the `service` section (HTTP and HTTPS listeners, logging, and `service.backup`) require a restart. If the file’s `service` section differs from the running configuration, `POST /v1/config/apply` returns `400`.

| Method | What happens |
| --- | --- |
| `PUT` / `POST` under `/v1/config/...` | ABS validates the change, persists it to the configuration source, and marks affected routines for reschedule. Not available when the configuration source is an HTTP(S) URL. |
| Edit the configuration file or remote store, then `POST /v1/config/apply` | ABS reloads the configuration from its source (file, HTTP URL, or remote object storage) and applies the same reschedule logic. |

An apply reschedules the affected routines and resynchronizes their backup history from storage in the background. Jobs that are already running, including on-demand backups and restores, keep the configuration they started with. For the apply command and how it changes schedules, see [How to apply configuration](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/configure#how-to-apply-configuration). For secret handling during GET and PUT, see [API secrets](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/secure#api-secrets).

## Deployment topologies

The same ABS binary supports each of the following deployment modes. Only how you mount configuration and credentials changes.

| Topology | When to use it |
| --- | --- |
| Linux package + systemd | Run ABS on a host alongside or near the Aerospike cluster. See [Install ABS on Linux](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/install#install-abs-on-linux). |
| Docker | Run ABS in a container with a mounted configuration file and storage credentials. See [Run ABS in Docker](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/install#run-abs-in-docker). |
| Kubernetes (Helm) | Manage ABS as a workload with a mounted `ConfigMap` or Secret, in clusters that already run Aerospike on Kubernetes or want ABS managed like the rest of the stack. See [Install ABS on Kubernetes with Helm](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/install#install-abs-on-kubernetes-with-helm). |

The `-c` and `-r` flags work the same whether the file is mounted from a `ConfigMap`, baked into an image, or read from a path on a VM.

Use `/health` and `/ready` for systemd, Docker health checks, and Kubernetes probes across all topologies. See [Kubernetes probes](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/monitoring#kubernetes-probes).

## Related pages

-   [Concepts](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/concepts): backup objects, incremental chains, and schedule overlap
-   [Configure ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/configure): YAML for every section
-   [Monitor ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/monitoring): metrics, probes, and job outcomes
-   [Secure ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/secure): HTTPS, secrets, and certificate rotation