Install and test ABS

This page describes how to install and test Aerospike Backup Service (ABS) on Linux or on Docker Compose.

Install ABS on Linux

Linux installation packages are available from the GitHub repository under releases.

Install and verify

1. Download the Linux package for your distribution from the GitHub Releases page. You can also build from the source code following the instructions in the GitHub README.

2. Navigate to the directory where you saved the installation package and run the following command to install the backup service using Linux.

   • Debian
   • RPM

   sudo dpkg -i aerospike-backup-service_3.0.1_amd64.deb

3. Verify the installation.

   sudo systemctl status aerospike-backup-service

   You should see output similar to the following. The exact file paths may differ depending on your machine and Linux distribution.

   ● aerospike-backup-service.service - Aerospike Backup Service
       Loaded: loaded (/lib/systemd/system/aerospike-backup-service.service; enabled; vendor preset: enabled)
       Active: active (running) since Wed 2023-12-20 11:08:58 UTC; 14min ago
     Main P      Tasks: 26 (limit: 19160)
       Memory: 32.3M
           CPU: 6.562s
       CGroup: /system.slice/aerospike-backup-service.service
               └─229439 /usr/bin/aerospike-backup-service --config /etc/aerospike-backup-service/aerospike-backup-service.yml

Modify default configuration

Modify aerospike-backup-service.yaml to update these parameters. By default, this configuration file is stored at /etc/aerospike-backup-service/.

See example ABS configuration files and the ABS configuration parameter reference for details and examples of the different parameters. Restart the service after modifying the parameters.

Service management

Service management commands such as restarting, viewing logs, and stopping the service vary depending on your Linux distribution.

Install ABS on Kubernetes with AKO

We recommend using Aerospike Kubernetes Operator to install Aerospike Database and ABS on a Kubernetes deployment. See Install ABS on AKO for details.

Install ABS on Kubernetes without AKO

If your deployment situation does not allow the use of AKO, you can also install ABS on a Kubernetes deployment without AKO.

1. Add the Aerospike Helm repository.

   helm repo add aerospike-helm https://artifact.aerospike.io/helm --force-update
   helm repo update

2. Create the file values.yaml with your backup service configuration. The following example includes a test ABS configuration as part of the Helm installation.

   backupServiceConfig:
     aerospike-clusters:
         absDefaultCluster:
             seed-nodes:
                 - host-name: asdb-node-0
                   port: 3000
             credentials:
                 user: tester
                 password: psw
     storage:
         local:
           gcp-storage:
               bucket-name: abs-testing-bucket
               path: abs-testing
   
     backup-policies:
         defaultPolicy:
             parallel: 100
             socket-timeout: 1000
     backup-routines:
         fullBackup1:
             backup-policy: defaultPolicy
             source-cluster: absDefaultCluster
             storage: local
             interval-cron: '@yearly'
             namespaces:
                 - source-ns1
   args:
   - -c
   - /etc/aerospike-backup-service/aerospike-backup-service.yml
   
   configmap:
     create: false
   
   image:
     repository: aerospike.jfrog.io/ecosystem-container-prod-local/aerospike-backup-service
     tag: 3.1.0
   
   serviceAccount:
     create: true
     name: aerospike-backup-service
   
   affinity:
     podAntiAffinity:
       requiredDuringSchedulingIgnoredDuringExecution:
       - labelSelector:
           matchExpressions:
           - key: app.kubernetes.io/name
             operator: In
             values:
             - aerospike-backup-service
         topologyKey: kubernetes.io/hostname

3. Install Aerospike Backup service by running the following Helm command.

   helm install abs  aerospike-helm/aerospike-backup-service  --values values.yaml  --atomic --wait --debug --create-namespace --namespace aerospike

Install ABS with Docker Compose

Docker Compose is a way to package a set of Docker containers that are set up to communicate with each other automatically. The Docker Compose stack that Aerospike provides at the ABS GitHub repository is an example, bare-bones configuration that you can modify to your own needs. It includes an Aerospike database, ABS, and a storage container.

By starting with ABS on Docker Compose using the provided sample stack, you can quickly test out backup policies and different configuration parameters in a matter of minutes before going further and eventually integrating ABS into a more complex environment on your own.

Download and set up ABS on Docker Compose

1. Run Docker Compose. If you already have Docker Desktop, then your installation includes Compose and you may directly launch Docker Desktop. If you installed the other Docker services in a different way, see the official Docker documentation for instructions on installing Docker Compose.

2. Clone the ABS GitHub repository.

3. Navigate to the docker-compose directory in your local copy of the ABS repository and run docker compose up -d from your terminal. This command uses the existing docker-compose.yaml file to set up three containers:

   • An Aerospike Database container with data to be backed up.
   • A MinIO container for storing backup data.
   • An ABS container configured with a sample aerospike-backup-service.yml file to back up data from the Aerospike container and store it in the MinIO container.

   The output from docker compose up -d should be similar to the following:

   [+] Running 26/12
   ✔ aerospike-backup-service Pulled                                                                     25.8s
   ✔ minio-client Pulled                                                                                 10.1s
   ✔ aerospike-cluster Pulled                                                                            11.3s
   ✔ minio Pulled                                                                                         5.5s
   
   [+] Running 5/5
   ✔ Network docker-compose_default      Created                                                          0.0s
   ✔ Container minio                     Healthy                                                          0.2s
   ✔ Container aerospike-cluster         Healthy                                                          0.2s
   ✔ Container minio-client              Exited                                                           0.1s
   ✔ Container aerospike-backup-service  Started                                                          0.0s

4. Verify installation by running docker ps. The minio-client container is necessary for installation, but not for running the service, so while four containers are used during setup, only three need to appear as running for testing.

   The output should be similar to the following:

   CONTAINER ID   IMAGE                                                                              COMMAND                  CREATED              STATUS                             PORTS                              NAMES
   05e7e6247776   aerospike.jfrog.io/ecosystem-container-prod-local/aerospike-backup-service:latest   "./backup -c config.…"   About a minute ago   Up 53 seconds (health: starting)   0.0.0.0:8080->8080/tcp             aerospike-backup-service
   7a359245eb3a   minio/minio:latest                                                                 "/usr/bin/docker-ent…"   About a minute ago   Up About a minute (healthy)        0.0.0.0:9000-9001->9000-9001/tcp   minio
   bf93abfb953c   aerospike/aerospike-server-enterprise:6.4.0.10                                      "/usr/bin/as-tini-st…"   About a minute ago   Up About a minute (healthy)        0.0.0.0:3000-3003->3000-3003/tcp   aerospike-cluster

Test ABS in Docker Compose stack

You can test the different parts of the ABS configuration in any order with the REST endpoints that the service exposes. This section illustrates a short series of steps to examine and make a change to a particular backup policy.

1. Check the health endpoint. Run curl -X GET http://localhost:8080/health from your terminal to send a request to the /health endpoint. You should see Ok as a response.

2. View all backup routines. The Docker Compose package includes one sample backup routine. Send a request to the /v1/backups/full endpoint to view all routines.

   curl -X GET http://localhost:8080/v1/backups/full
   
   {"minioRoutine":
     [
       {
           "created":"2024-06-12T16:28:22.82156221Z",
           "from":"0001-01-01T00:00:00Z",
           "namespace":"test",
           "byte-count":42,
           "file-count":1,
           "key":"minioRoutine/backup/1718209702821/data/test"
           "storage": {
             "s3-storage": {
               "bucket": "as-backup-bucket",
               "path": "backups",
               "s3-region": "eu-central-1"
             }
           }
       }
     ]
   }

3. Check details of a specific routine by providing its name after /v1/config/routines:

   curl -X GET http://localhost:8080/v1/config/routines/minioRoutine
   
   {
       "backup-policy":"defaultPolicy",
       "source-cluster":"absCluster1",
       "storage":"minioStorage",
       "interval-cron":"@daily",
       "incr-interval-cron":"@hourly"
   }

   The routine schedules the defaultPolicy backup policy on the absCluster1 source cluster to minioStorage, with full backups daily and incremental backups hourly.

4. Check details of a specific policy by providing its name after /v1/config/policies:

   curl -X GET http://localhost:8080/v1/config/policies/defaultPolicy
   
   {
       "parallel":1,
   }

   The defaultPolicy backup policy runs single-threaded and does not clear the output directory before saving the files.

5. Modify a policy with a PUT request. Use -H "Content-Type: application/json" to communicate that the data you are sending is of JSON type, and use -d to send the full definition of the new policy. In this example, the updated policy adds a new parameter to set a maximum of three retries. You must send the full JSON schema for the policy, even if you are only adding or changing a few parameters.

   curl -X PUT -H "Content-Type: application/json" -d '{"parallel":1,"max-retries": 3}' http://localhost:8080/v1/config/policies/defaultPolicy

6. Check that the policy modifications took place. There is no response to a PUT request, so send another GET request to check that the policy has been updated.

   curl -X GET http://localhost:8080/v1/config/policies/defaultPolicy
   
   {
       "parallel":1,
       "max-retries": 3
   }

7. Trigger a new backup routine to run immediately, send a POST request to the /v1/backups/schedule/ endpoint with the routine name and, optionally, a delay in milliseconds.

   curl -X POST http://localhost:8080/v1/backups/schedule/minioRoutine?delay=1000

8. There is no feedback response in the terminal, so run another check of all backups to make sure it worked.

   curl -X GET http://localhost:8080/v1/backups/full
   
   {
     "minioRoutine":
       [
         {
           "created":"2024-06-12T16:28:22.82156221Z",
           "from":"0001-01-01T00:00:00Z",
           "namespace":"test",
           "byte-count":42,
           "file-count":1,
           "key":"minioRoutine/backup/1718209702821/data/test",
           "storage": {
             "s3-storage": {
               "bucket": "as-backup-bucket",
               "path": "backups",
               "s3-region": "eu-central-1"
             }
           }
         },
         {
           "created":"2024-06-12T16:55:23.791971461Z",
           "from":"0001-01-01T00:00:00Z",
           "namespace":"test",
           "byte-count":42,
           "file-count":1,
           "key":"minioRoutine/backup/1718211323791/data/test",
           "storage": {
             "s3-storage": {
               "bucket": "as-backup-bucket",
               "path": "backups",
               "s3-region": "eu-central-1"
             }
           }
         }
       ]
   }

   In this example, there is a new backup present in the list. The timestamp is less than one hour from the original backup, which was triggered upon starting ABS, showing that the second backup was the one manually triggered by the POST request.

For more API examples and the full JSON schemas for the request types, see Examples.