Deploying Aerospike Tools with Docker

This page describes how to deploy Aerospike tools with Docker.

Note

Starting with tools 13.0.3, Aerospike provides individual per-tool images in addition to the aerospike/aerospike-tools bundle. For bare-metal or VM installs, see Install tools on Linux with a package manager.

Docker is a platform for running applications in an isolated environment called a container. Containers encapsulate all required dependencies for a process and provide runtime isolation, enabling multiple environments to run securely on the same physical hardware.

The transition from monolithic binaries to dynamic microservices makes containers a natural fit. But while they excel at ephemeral tasks such as short-lived processes that start, perform a function, and stop without saving internal state, managing persistent data and long-running services requires a different approach.

Get started with Docker

Docker is available on multiple desktop, cloud, and server platforms. To learn about installing Docker on these platforms, see Get Docker.

The examples on this page are for Docker Desktop for Mac.

Install Docker

For information about installing Docker Desktop for Mac, see Install Docker Desktop on Mac.

Run Docker

1. Open Docker Desktop. The Docker Desktop Dashboard displays.

2. In a Terminal window, verify Docker is running using the following command:

   docker --version

   If Docker is running, a Docker version and build is returned in the command output. For example:

   Docker version 27.4.0, build bde2b89

Available images

Starting with tools 13.0.3, Aerospike publishes five per-tool images and a bundle. All 13.0.3 images are based on Debian 13 (trixie). Earlier images through 13.0.2 were based on Ubuntu 24.04 LTS.

Image	Docker Hub	Binaries
Aerospike Admin	aerospike/aerospike-asadm	asadm, asinfo
Aerospike Quick Look	aerospike/aerospike-aql	aql
Aerospike Backup Tools (legacy)	aerospike/aerospike-asbackup	asbackup, asrestore
Aerospike Benchmark	aerospike/aerospike-asbench	asbench
Aerospike Configuration Tool	aerospike/aerospike-asconfig	asconfig
All tools (bundle)	aerospike/aerospike-tools	all of the above

Image tags carry the tool’s own version number, not the bundle version. For example, aerospike/aerospike-asadm:5.0.3-5 ships as part of tools 13.0.3 — there is no aerospike-asadm:13.0.3 tag.

Use a per-tool image when you need one tool in a CI job (roughly 150–260 MB each). Use the bundle when you need two or more tools on the same host (roughly 400 MB).

For more information about Aerospike tools, see Aerospike tools.

Pull images

Pull from Docker Hub without authentication:

docker pull aerospike/aerospike-asadm
docker pull aerospike/aerospike-aql
docker pull aerospike/aerospike-asbackup
docker pull aerospike/aerospike-asbench
docker pull aerospike/aerospike-asconfig
docker pull aerospike/aerospike-tools

Append a version tag to pin a specific release:

docker pull aerospike/aerospike-asadm:5.0.3-5

Docker run command syntax

docker run [OPTIONS] IMAGE BINARY [BINARY_ARGS...]

BINARY is required on every Aerospike tools image. Images that ship more than one binary — aerospike/aerospike-asadm ships both asadm and asinfo, and aerospike/aerospike-asbackup ships both asbackup and asrestore — have no default, so Docker needs to know which binary to run.

If you omit the binary name and pass flags, Docker treats the flags as the command and returns an error like exec: "--host": executable file not found in $PATH, which does not indicate the real cause. If you omit the binary name with no flags, the container opens a shell.

Caution

If you are upgrading Docker images from tools 13.0.2 or earlier:

• The wrapper entrypoint used in earlier images has been removed. In earlier images, running docker run <image> with no binary name returned an error and arbitrary commands were rejected. Starting with 13.0.3, omitting the binary opens a shell, and any command runs in the container.
• The working directory changed from /aerospike to /. Relative paths passed to asbackup --directory now resolve from /. Review any scripts or automation that use a relative path with --directory.
• The LC_CTYPE=C.UTF-8 locale setting is no longer set in the container. Pass -e LC_CTYPE=C.UTF-8 to docker run to restore the µ symbol in asadm micro-benchmark output. [TOOLS-4361]

docker run -ti -v HOST_PATH:CONTAINER_PATH --rm IMAGE BINARY [BINARY_ARGS...] -h CLUSTER_HOST --no-config-file

Option	Description
-t, --tty	Allocate a pseudo-TTY
-i, --interactive	Keep STDIN open even if not attached
-v, --volume	Bind mount a volume
--rm	Remove container after use

Configuration file

asadm, asinfo, aql, asbackup, and asrestore each read /etc/aerospike/astools.conf when the file exists. All tools images ship this file. Pass --no-config-file to ignore it; omitting the flag silently applies the container’s baked-in configuration.

Reaching the cluster

localhost inside a container refers to the container itself, not the Docker host.

Cluster location	How to connect
Another host on the network	--host CLUSTER_HOST
A container on the same Docker network	--network NETWORK_NAME and --host CONTAINER_NAME
The Docker host (Linux)	--network host and --host 127.0.0.1
The Docker host (macOS or Windows)	--host host.docker.internal

Aerospike admin (asadm)

asadm commands use the following format:

docker run -ti --rm aerospike/aerospike-asadm asadm --host CLUSTER_HOST --no-config-file

Enable the CLI (optional)

The following command runs asadm and enables command line input:

docker run -ti --rm aerospike/aerospike-asadm asadm --host 10.0.0.173 --no-config-file
Seed:        [('10.0.0.173', 3000, None)]
Config_file: None
Aerospike Interactive Shell, version 0.1.18

Found 2 nodes
Online:  10.0.0.171:3000, 10.0.0.173:3000

Admin>

You can inspect the Aerospike cluster configuration:

docker run -ti --rm aerospike/aerospike-asadm asadm -e info --host 10.0.0.173 --no-config-file
Seed:        [('10.0.0.173', 3000, None)]
Config_file: None
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Network Information (2018-05-10 08:47:57 UTC)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
           Node               Node                Ip        Build   Cluster   Migrations        Cluster     Cluster         Principal   Client     Uptime
              .                 Id                 .            .      Size            .            Key   Integrity                 .    Conns          .
10.0.0.171:3000   *BB9BC6479270008   10.0.0.171:3000   E-3.15.0.2         2      0.000     6F420A0B3DA7   True        BB9BC6479270008        1   00:16:45
10.0.0.173:3000   BB945718C270008    10.0.0.173:3000   E-4.1.0.1          2      0.000     6F420A0B3DA7   True        BB9BC6479270008        4   00:14:27
Number of rows: 2

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Namespace Usage Information (2018-05-10 08:47:57 UTC)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Namespace              Node     Total   Expirations,Evictions     Stop       Disk    Disk     HWM   Avail%        Mem     Mem    HWM      Stop
        .                 .   Records                       .   Writes       Used   Used%   Disk%        .       Used   Used%   Mem%   Writes%
bar         10.0.0.171:3000   0.000     (0.000,  0.000)         false         N/E   N/E     50      N/E      0.000 B    0       60     90
bar         10.0.0.173:3000   0.000     (0.000,  0.000)         false         N/E   N/E     50      N/E      0.000 B    0       60     90
bar                           0.000     (0.000,  0.000)                  0.000 B                             0.000 B
test        10.0.0.171:3000   0.000     (0.000,  0.000)         false         N/E   N/E     50      N/E      0.000 B    0       60     90
test        10.0.0.173:3000   0.000     (0.000,  0.000)         false         N/E   N/E     50      N/E      0.000 B    0       60     90
test                          0.000     (0.000,  0.000)                  0.000 B                             0.000 B
Number of rows: 6

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~Namespace Object Information (2018-05-10 08:47:57 UTC)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Namespace              Node     Total     Repl                      Objects                   Tombstones             Pending   Rack
        .                 .   Records   Factor   (Master,Prole,Non-Replica)   (Master,Prole,Non-Replica)            Migrates     ID
        .                 .         .        .                            .                            .             (tx,rx)      .
bar         10.0.0.171:3000   0.000     2        (0.000,  0.000,  0.000)      (0.000,  0.000,  0.000)      (0.000,  0.000)     0
bar         10.0.0.173:3000   0.000     2        (0.000,  0.000,  0.000)      (0.000,  0.000,  0.000)      (0.000,  0.000)     0
bar                           0.000              (0.000,  0.000,  0.000)      (0.000,  0.000,  0.000)      (0.000,  0.000)
test        10.0.0.171:3000   0.000     2        (0.000,  0.000,  0.000)      (0.000,  0.000,  0.000)      (0.000,  0.000)     0
test        10.0.0.173:3000   0.000     2        (0.000,  0.000,  0.000)      (0.000,  0.000,  0.000)      (0.000,  0.000)     0
test                          0.000              (0.000,  0.000,  0.000)      (0.000,  0.000,  0.000)      (0.000,  0.000)
Number of rows: 6

You can issue asinfo commands to return the build version for each node on all cluster nodes at the same time:

docker run -ti --rm aerospike/aerospike-asadm asadm -e 'enable; asinfo -v build' --host 10.0.0.173 --no-config-file
Seed:        [('10.0.0.173', 3000, None)]
Config_file: None
10.0.0.171:3000 (10.0.0.171) returned:
3.15.0.2

10.0.0.173:3000 (10.0.0.173) returned:
4.1.0.1

Aerospike information (asinfo)

Enter the following command to run asinfo:

docker run -ti --rm aerospike/aerospike-asadm asinfo --host CLUSTER_HOST --no-config-file

Example

Enter the following command to run asinfo and display server configuration parameters:

docker run -ti --rm aerospike/aerospike-asadm asinfo --host 1.2.3.4 --no-config-file
Enter Password:
1 :  node
     17713AF706CA0568
2 :  statistics
     cluster_size=1;cluster_key=99D8CA48F383;cluster_generation=1;cluster_principal=17713AF706CA0568;cluster_integrity=true;cluster_is_member=true;cluster_duplicate_nodes=null;cluster_clock_skew_stop_writes_sec=0;cluster_clock_skew_ms=0;cluster_clock_skew_outliers=null;uptime=1889281;system_total_cpu_pct=127;system_user_cpu_pct=49;system_kernel_cpu_pct=78;system_free_mem_pct=16;process_cpu_pct=0;heap_allocated_kbytes=98701;heap_active_kbytes=100524;heap_mapped_kbytes=145408;heap_efficiency_pct=68;heap_site_count=0;objects=0;tombstones=0;info_queue=0;rw_in_progress=0;proxy_in_progress=0;tree_gc_queue=0;client_connections=1;heartbeat_connections=0;fabric_connections=0;heartbeat_received_self=12590090;heartbeat_received_foreign=0;reaped_fds=5;info_complete=992;demarshal_error=0;early_tsvc_client_error=0;early_tsvc_from_proxy_error=0;early_tsvc_batch_sub_error=0;early_tsvc_from_proxy_batch_sub_error=0;early_tsvc_udf_sub_error=0;early_tsvc_ops_sub_error=0;batch_index_initiate=0;batch_index_queue=0:0,0:0,0:0,0:0;batch_index_complete=0;batch_index_error=0;batch_index_timeout=0;batch_index_delay=0;batch_index_unused_buffers=0;batch_index_huge_buffers=0;batch_index_created_buffers=0;batch_index_destroyed_buffers=0;batch_index_proto_uncompressed_pct=0.000;batch_index_proto_compression_ratio=1.000;scans_active=0;query_short_running=0;query_long_running=0;sindex_ucgarbage_found=0;sindex_gc_retries=0;sindex_gc_list_creation_time=594;sindex_gc_list_deletion_time=0;sindex_gc_objects_validated=0;sindex_gc_garbage_found=0;sindex_gc_garbage_cleaned=0;paxos_principal=17713AF706CA0568;time_since_rebalance=1889279;migrate_allowed=true;migrate_partitions_remaining=0;fabric_bulk_send_rate=0;fabric_bulk_recv_rate=0;fabric_ctrl_send_rate=0;fabric_ctrl_recv_rate=0;fabric_meta_send_rate=0;fabric_meta_recv_rate=0;fabric_rw_send_rate=0;fabric_rw_recv_rate=0;dlog_used_objects=0;dlog_free_pct=0;dlog_logged=0;dlog_relogged=0;dlog_processed_main=0;dlog_processed_replica=0;dlog_processed_link_down=0;dlog_overwritten_error=0;xdr_ship_success=0;xdr_ship_delete_success=0;xdr_ship_source_error=0;xdr_ship_destination_error=0;xdr_ship_destination_permanent_error=0;xdr_ship_fullrecord=0;xdr_ship_bytes=0;xdr_ship_inflight_objects=0;xdr_ship_outstanding_objects=0;xdr_ship_latency_avg=0;xdr_ship_compression_avg_pct=0.00;xdr_read_success=0;xdr_read_error=0;xdr_read_notfound=0;xdr_read_latency_avg=0;xdr_read_active_avg_pct=0.00;xdr_read_idle_avg_pct=0.00;xdr_read_reqq_used=0;xdr_read_respq_used=0;xdr_read_reqq_used_pct=0.00;xdr_read_txnq_used=0;xdr_read_txnq_used_pct=0.00;xdr_relogged_incoming=0;xdr_relogged_outgoing=0;xdr_queue_overflow_error=0;xdr_active_failed_node_sessions=0;xdr_active_link_down_sessions=0;xdr_hotkey_fetch=0;xdr_hotkey_skip=0;xdr_unknown_namespace_error=0;xdr_timelag=0;xdr_throughput=0;xdr_global_lastshiptime=18446744073709551615
3 :  features
     batch-index;blob-bits;cdt-list;cdt-map;cluster-stable;float;geo;sindex-exists;peers;pipelining;relaxed-sc;replicas;replicas-all;replicas-master;truncate-namespace;udf;xdr
4 :  partition-generation
     0
5 :  build_time
     Fri Jan  3 21:50:01 UTC 2020
6 :  dcs

7 :  edition
     Aerospike Enterprise Edition
8 :  version
     Aerospike Enterprise Edition build 4.8.0.3
9 :  compatibility-id
     5
10 :  services

11 :  services-alumni

12 :  build_os
     el7
13 :  build
     4.8.0.3

Enter the following command to run asinfo and display all namespaces:

docker run -ti --rm aerospike/aerospike-asadm asinfo -v "namespaces" -h 10.0.0.173 --no-config-file
test;bar

Enter the following command to run asinfo and display all statistics:

docker run -ti --rm aerospike/aerospike-asadm asinfo -v statistics -h 10.0.0.173 --no-config-file
cluster_size=2;cluster_key=BD70190EBEC1;cluster_generation=1;cluster_principal=BB945718C270008;cluster_integrity=true;cluster_is_member=true;cluster_duplicate_nodes=null;cluster_clock_skew_stop_writes_sec=56;cluster_clock_skew_ms=0;cluster_clock_skew_outliers=null;uptime=21500;system_free_mem_pct=88;heap_allocated_kbytes=171468;heap_active_kbytes=173940;heap_mapped_kbytes=322560;heap_efficiency_pct=53;heap_site_count=41;objects=0;tombstones=0;info_queue=0;rw_in_progress=0;proxy_in_progress=0;tree_gc_queue=0;client_connections=1;heartbeat_connections=0;fabric_connections=24;heartbeat_received_self=42987;heartbeat_received_foreign=42986;reaped_fds=7;info_complete=5120;demarshal_error=0;early_tsvc_client_error=0;early_tsvc_from_proxy_error=0;early_tsvc_batch_sub_error=0;early_tsvc_from_proxy_batch_sub_error=0;early_tsvc_udf_sub_error=0;batch_index_initiate=0;batch_index_queue=0:0,0:0;batch_index_complete=0;batch_index_error=0;batch_index_timeout=0;batch_index_delay=0;batch_index_unused_buffers=0;batch_index_huge_buffers=0;batch_index_created_buffers=0;batch_index_destroyed_buffers=0;scans_active=0;query_short_running=0;query_long_running=0;sindex_ucgarbage_found=0;sindex_gc_retries=0;sindex_gc_list_creation_time=861;sindex_gc_list_deletion_time=0;sindex_gc_objects_validated=514;sindex_gc_garbage_found=0;sindex_gc_garbage_cleaned=0;paxos_principal=BB945718C270008;time_since_rebalance=21494;migrate_allowed=true;migrate_partitions_remaining=0;fabric_bulk_send_rate=0;fabric_bulk_recv_rate=0;fabric_ctrl_send_rate=0;fabric_ctrl_recv_rate=0;fabric_meta_send_rate=298;fabric_meta_recv_rate=298;fabric_rw_send_rate=0;fabric_rw_recv_rate=0;dlog_used_objects=61;dlog_free_pct=100;dlog_logged=30761;dlog_relogged=5508;dlog_processed_main=30761;dlog_processed_replica=145;dlog_processed_link_down=0;dlog_overwritten_error=0;xdr_ship_success=0;xdr_ship_delete_success=0;xdr_ship_source_error=5508;xdr_ship_destination_error=0;xdr_ship_destination_permanent_error=0;xdr_ship_fullrecord=5508;xdr_ship_bytes=0;xdr_ship_inflight_objects=0;xdr_ship_outstanding_objects=0;xdr_ship_latency_avg=0;xdr_ship_compression_avg_pct=0.00;xdr_read_success=5508;xdr_read_error=0;xdr_read_notfound=528;xdr_read_latency_avg=0;xdr_read_active_avg_pct=0.00;xdr_read_idle_avg_pct=100.00;xdr_read_reqq_used=0;xdr_read_respq_used=0;xdr_read_reqq_used_pct=0.00;xdr_read_txnq_used=0;xdr_read_txnq_used_pct=0.00;xdr_relogged_incoming=0;xdr_relogged_outgoing=5508;xdr_queue_overflow_error=0;xdr_active_failed_node_sessions=0;xdr_active_link_down_sessions=0;xdr_hotkey_fetch=1638;xdr_hotkey_skip=26363;xdr_unknown_namespace_error=0;xdr_timelag=0;xdr_throughput=0;xdr_global_lastshiptime=1551340161340

Enter the following command to run asinfo and display all features, replacing semicolons with line breaks in the response:

docker run -ti --rm aerospike/aerospike-asadm asinfo -v features -l -h 10.0.0.173 --no-config-file
peers
cdt-list
cdt-map
pipelining
geo
float
batch-index
replicas
replicas-all
replicas-master
replicas-prole
udf
xdr

Enter the following command to get the configuration value of the proto-fd-max service context, piping the output to grep for the specific configuration value:

docker run -ti --rm aerospike/aerospike-asadm asinfo -v "get-config:context=service" -l -h 10.0.0.173 --no-config-file | grep proto-fd-max
proto-fd-max=15000

To set the configuration value for the service context proto-fd-max, run the following asinfo -v set-config command:

docker run -ti --rm aerospike/aerospike-asadm asinfo -v 'set-config:context=service;proto-fd-max=100000' -h 10.0.0.173 --no-config-file
ok

Aerospike Quick Look (AQL)

Enter the following command to run AQL:

docker run -ti --rm aerospike/aerospike-aql aql --host CLUSTER_HOST --no-config-file

Example

Enter the following command to run AQL and enable command line input:

docker run -ti --rm aerospike/aerospike-aql aql -h 10.0.0.173 --no-config-file
Seed:         10.0.0.173
User:         None
Config File:  None
Aerospike Query Client
Version 3.15.3.6
C Client Version 4.3.11
Copyright 2012-2017 Aerospike. All rights reserved.
aql>

You can run AQL in a Docker container to insert and query some data into the Aerospike server.

docker run -ti --rm aerospike/aerospike-aql aql --host 10.0.0.173 --no-config-file
Seed:         10.0.0.173
User:         None
Config File:  None
Aerospike Query Client
Version 3.15.3.6
C Client Version 4.3.11
Copyright 2012-2017 Aerospike. All rights reserved.
aql> insert into test.foo (PK, foo) values ('123','my string')
OK, 1 record affected.

aql> select * from test.foo
+-------------+
| foo         |
+-------------+
| "my string" |
+-------------+
1 row in set (0.126 secs)

OK

aql>

To execute AQL directly and insert a record, enter the following command:

docker run -ti --rm aerospike/aerospike-aql aql -c "INSERT INTO test.demo (PK, foo, bar) VALUES ('key1', 123, 'abc')" -h 10.0.0.173 --no-config-file
INSERT INTO test.demo (PK, foo, bar) VALUES ('key1', 123, 'abc')
OK, 1 record affected.

Enter the following command to run AQL and display the query execution plan for a SELECT statement:

docker run -ti --rm aerospike/aerospike-aql aql -c "explain select * from test.foo where PK='123'" -h 10.0.0.173 --no-config-file
explain select * from test.foo where PK='123'
+-------+--------------------------------------------+-----------+-----------+--------+---------+----------+----------------------------+-------------------+-------------------------+---------+
| SET   | DIGEST                                     | NAMESPACE | PARTITION | STATUS | UDF     | KEY_TYPE | POLICY_REPLICA             | NODE              | POLICY_KEY              | TIMEOUT |
+-------+--------------------------------------------+-----------+-----------+--------+---------+----------+----------------------------+-------------------+-------------------------+---------+
| "foo" | "44E3571220664C352DFCC7EFD681920D37F414AC" | "test"    | 836       | ""     | "FALSE" | "STRING" | "AS_POLICY_REPLICA_MASTER" | "BB945718C270008" | "AS_POLICY_KEY_DEFAULT" | 1000    |
+-------+--------------------------------------------+-----------+-----------+--------+---------+----------+----------------------------+-------------------+-------------------------+---------+
1 row in set (0.001 secs)

OK

To execute AQL directly and truncate the demo set in the test namespace, enter the following command:

docker run -ti --rm aerospike/aerospike-aql aql -c "TRUNCATE test.demo" -h 10.0.0.173 --no-config-file
TRUNCATE test.demo
OK

Aerospike Benchmark (asbench)

Run a benchmark workload against a cluster:

docker run --rm aerospike/aerospike-asbench asbench -h CLUSTER_HOST -n test -w RU,50 -o S:100 -t 30

For all available options, see Aerospike Benchmark Tool.

Aerospike Configuration Tool (asconfig)

asconfig operates on files. Bind-mount a directory so the tool can read and write configuration files on the host:

docker run --rm -v "${PWD}:/work" aerospike/aerospike-asconfig asconfig validate -a 8.1.0 /work/aerospike.yaml

Pass the container-side path (/work/...) to asconfig. For all available options, see Aerospike Configuration Tool.

Aerospike backup (asbackup)

Enter the following command to run asbackup:

docker run -ti -v HOST_PATH:CONTAINER_PATH --rm aerospike/aerospike-asbackup asbackup --host CLUSTER_HOST --directory CONTAINER_PATH --no-config-file

Example

In this example, asbackup generates a backup in the bind-mounted /tmp/asbackup directory.

docker run -ti -v ${PWD}/asbackup:/tmp/asbackup --rm aerospike/aerospike-asbackup asbackup --namespace test --directory /tmp/asbackup -r --host 10.0.0.173 --no-config-file
2018-06-21 02:18:14 GMT [INF] [    8] Starting 100% backup of 10.0.0.173 (namespace: test, set: [all], bins: [all], after: [none], before: [none]) to /tmp/asbackup
2018-06-21 02:18:14 GMT [INF] [    8] [src/main/aerospike/as_cluster.c:124][as_cluster_add_nodes_copy] Add node BB945718C270008 10.0.0.173:3000
2018-06-21 02:18:14 GMT [INF] [    8] [src/main/aerospike/as_cluster.c:124][as_cluster_add_nodes_copy] Add node BB9BC6479270008 10.0.0.171:3000
2018-06-21 02:18:14 GMT [INF] [    8] Processing 2 node(s)
2018-06-21 02:18:14 GMT [INF] [    8] Node ID             Objects        Replication
2018-06-21 02:18:14 GMT [INF] [    8] BB945718C270008     2              2
2018-06-21 02:18:14 GMT [INF] [    8] BB9BC6479270008     2              2
2018-06-21 02:18:14 GMT [INF] [    8] Namespace contains 2 record(s)
2018-06-21 02:18:14 GMT [INF] [    8] Directory /tmp/asbackup prepared for backup
2018-06-21 02:18:14 GMT [INF] [   27] Starting backup for node BB9BC6479270008
2018-06-21 02:18:14 GMT [INF] [   28] Starting backup for node BB945718C270008
2018-06-21 02:18:14 GMT [INF] [   27] Created new backup file /tmp/asbackup/BB9BC6479270008_00000.asb
2018-06-21 02:18:14 GMT [INF] [   28] Created new backup file /tmp/asbackup/BB945718C270008_00000.asb
2018-06-21 02:18:14 GMT [INF] [   28] Backing up 1 secondary index(es)
2018-06-21 02:18:14 GMT [INF] [   28] Backing up 1 UDF file(s)
2018-06-21 02:18:14 GMT [INF] [   27] Completed backup for node BB9BC6479270008, records: 1, size: 137 (~137 B/rec)
2018-06-21 02:18:14 GMT [INF] [   28] Completed backup for node BB945718C270008, records: 1, size: 244 (~244 B/rec)
2018-06-21 02:18:15 GMT [INF] [   26] Backed up 2 record(s), 1 secondary index(es), 1 UDF file(s) from 2 node(s), 381 byte(s) in total (~190 B/rec)

Always use an absolute container-side path with --directory. The working directory in all tools images is /, so relative paths resolve from the root.

To allow for pipelines, run the following command:

• Specify - as the --output-file; asbackup writes the backup to stdout.
• Specify - as the --input-file; asrestore reads the backup from stdin.

docker run -i --rm aerospike/aerospike-asbackup asbackup --namespace test --output-file - --host 10.0.0.173 --no-config-file | docker run -i --rm aerospike/aerospike-asbackup asrestore --namespace test -g --host 10.0.0.173 --no-config-file --input-file -
2018-06-22 03:19:02 GMT [INF] [    8] Starting 100% backup of 10.0.0.173 (namespace: test, set: [all], bins: [all], after: [none], before: [none]) to [stdout]
2018-06-22 03:19:02 GMT [INF] [    8] Starting restore to 10.0.0.173 (bins: [all], sets: [all]) from [stdin]
2018-06-22 03:19:02 GMT [INF] [    8] [src/main/aerospike/as_cluster.c:124][as_cluster_add_nodes_copy] Add node BB945718C270008 10.0.0.173:3000
2018-06-22 03:19:03 GMT [INF] [    8] [src/main/aerospike/as_cluster.c:124][as_cluster_add_nodes_copy] Add node BB9BC6479270008 10.0.0.171:3000
2018-06-22 03:19:03 GMT [INF] [    8] Processing 2 node(s)
2018-06-22 03:19:03 GMT [INF] [    8] Node ID             Objects        Replication
2018-06-22 03:19:03 GMT [INF] [    8] Processing 2 node(s)
2018-06-22 03:19:03 GMT [INF] [    8] Restoring -
2018-06-22 03:19:03 GMT [INF] [    8] BB945718C270008     5              2
2018-06-22 03:19:03 GMT [INF] [    8] BB9BC6479270008     5              2
2018-06-22 03:19:03 GMT [INF] [    8] Namespace contains 5 record(s)
2018-06-22 03:19:03 GMT [INF] [   27] Starting backup for node BB945718C270008
2018-06-22 03:19:03 GMT [INF] [   28] Starting backup for node BB9BC6479270008
2018-06-22 03:19:03 GMT [INF] [   27] Backing up 1 secondary index(es)
2018-06-22 03:19:03 GMT [INF] [   27] Backing up 1 UDF file(s)
2018-06-22 03:19:03 GMT [INF] [   27] Completed backup for node BB945718C270008, records: 2, size: 349 (~174 B/rec)
2018-06-22 03:19:03 GMT [INF] [   28] Completed backup for node BB9BC6479270008, records: 3, size: 315 (~105 B/rec)
2018-06-22 03:19:03 GMT [INF] [    8] Restoring 1 UDF file(s)
2018-06-22 03:19:03 GMT [INF] [    8] Restoring 1 secondary index(es)
2018-06-22 03:19:03 GMT [INF] [    8] Skipped 1 matched index(es)
2018-06-22 03:19:03 GMT [INF] [    8] Restoring records
2018-06-22 03:19:04 GMT [INF] [   26] 1 UDF file(s), 0 secondary index(es), 5 record(s) (0 KiB/s, 5 rec/s, 132 B/rec, backed off: 0)
2018-06-22 03:19:04 GMT [INF] [   26] Expired 0 : skipped 0 : inserted 5 : failed 0 (existed 0, fresher 0)
2018-06-22 03:19:04 GMT [INF] [   26] Backed up 5 record(s), 1 secondary index(es), 1 UDF file(s) from 2 node(s), 664 byte(s) in total (~132 B/rec)
2018-06-22 03:19:05 GMT [INF] [   26] 1 UDF file(s), 0 secondary index(es), 5 record(s) (0 KiB/s, 0 rec/s, 0 B/rec, backed off: 0)
2018-06-22 03:19:05 GMT [INF] [   26] Expired 0 : skipped 0 : inserted 5 : failed 0 (existed 0, fresher 0)

Use -i without -t on both containers in a pipeline; a TTY corrupts the binary stream.

Aerospike restore (asrestore)

To run asrestore, enter the following:

docker run -ti -v HOST_PATH:CONTAINER_PATH --rm aerospike/aerospike-asbackup asrestore --host CLUSTER_HOST --directory CONTAINER_PATH --no-config-file

Example

In this example, asrestore reads a backup from the bind-mounted /tmp/asbackup directory.

docker run -ti -v ${PWD}/asbackup:/tmp/asbackup --rm aerospike/aerospike-asbackup asrestore --namespace test --directory /tmp/asbackup -g --host 10.0.0.173 --no-config-file
2018-06-21 02:19:25 GMT [INF] [    8] Starting restore to 10.0.0.173 (bins: [all], sets: [all]) from /tmp/asbackup
2018-06-21 02:19:26 GMT [INF] [    8] Processing 2 node(s)
2018-06-21 02:19:26 GMT [INF] [    8] Found 2 backup file(s) in /tmp/asbackup
2018-06-21 02:19:26 GMT [INF] [    8] Opened backup file /tmp/asbackup/BB945718C270008_00000.asb
2018-06-21 02:19:26 GMT [INF] [    8] Opened backup file /tmp/asbackup/BB9BC6479270008_00000.asb
2018-06-21 02:19:26 GMT [INF] [    8] Restoring 1 UDF file(s)
2018-06-21 02:19:26 GMT [INF] [    8] Restoring 1 secondary index(es)
2018-06-21 02:19:26 GMT [INF] [    8] Skipped 1 matched index(es)
2018-06-21 02:19:26 GMT [INF] [    8] Restoring records
2018-06-21 02:19:26 GMT [INF] [   27] Restoring /tmp/asbackup/BB945718C270008_00000.asb
2018-06-21 02:19:26 GMT [INF] [   28] Restoring /tmp/asbackup/BB9BC6479270008_00000.asb
2018-06-21 02:19:26 GMT [INF] [   28] Opened backup file /tmp/asbackup/BB9BC6479270008_00000.asb
2018-06-21 02:19:26 GMT [INF] [   27] Opened backup file /tmp/asbackup/BB945718C270008_00000.asb
2018-06-21 02:19:27 GMT [INF] [   26] 1 UDF file(s), 0 secondary index(es), 2 record(s) (0 KiB/s, 2 rec/s, 190 B/rec, backed off: 0)
2018-06-21 02:19:27 GMT [INF] [   26] Expired 0 : skipped 0 : inserted 2 : failed 0 (existed 0, fresher 0)
2018-06-21 02:19:27 GMT [INF] [   26] 100% complete, ~0s remaining

Air-gapped installs

On a connected machine, pull the image for each platform you need and save it to a tar archive:

docker pull --platform linux/amd64 aerospike/aerospike-asadm:VERSION_TAG
docker save aerospike/aerospike-asadm:VERSION_TAG -o asadm-VERSION_TAG-amd64.tar

On the air-gapped machine, load the archive:

docker load -i asadm-VERSION_TAG-amd64.tar

docker save writes only the platforms present in the local image store, so pull each platform you need before saving.

Troubleshooting

Symptom	Cause	Fix
exec: "--version": executable file not found in $PATH	Binary name omitted; Docker tried to execute the flag	Include the binary name: docker run IMAGE asadm --version
Container opens or exits a shell with no output	Binary name omitted from bundle image	Include the binary name: docker run aerospike/aerospike-tools asadm ...
Backup files missing after the run	Output written inside the container, not to the host	Bind-mount a directory and pass the container-side absolute path to --directory
Cannot reach the cluster on localhost	localhost refers to the container, not the Docker host	See Reaching the cluster
exec format error	Image architecture does not match the host	Add --platform linux/ARCH to the pull command

Source Code

The source code is available on GitHub.