Installation and Configuration
The Aerospike REST Gateway is a Spring Boot Application. It can either be run directly from the git repo with
./gradlew bootRun, or built into a
.jar file or Docker image.
The REST Gateway was previously referred to as the REST Client.
1 - Dependencies
- Java 17 for Gateway 2.0.1 and newer. Java 8 for Gateway 1.11.0 and older.
- An Aerospike Server to be installed and reachable.
2 - Installation
Downloading a JAR file
The latest version of the REST Gateway
.jar file can be found at: REST Gateway Releases
Running From Source
For development purposes it is possible to
- Clone the Aerospike REST Gateway
- From the root directory run
Building a JAR file
To build a copy of the
.jar file for the REST Gateway:
Clone the Aerospike REST Gateway
From the root directory run
.jarwill be located in the
Running from an executable JAR
java -jar build/libs/aerospike-rest-gateway-<VERSION>.jar
The fully executable jar contains an extra script at the front of the file which allows you to symlink your Spring Boot jar to init.d or use a systemd script. For more information, click the following links:
Complete example of running the REST gateway using a jar
java -server -Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=8082 -Dcom.sun.management.jmxremote.rmi.port=8082 -Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -XX:+UseG1GC -Xms2048m -Xmx2048m -jar ./as-rest-client-X.X.X.jar --aerospike.restclient.hostname=localhost --aerospike.restclient.clientpolicy.user=*** --aerospike.restclient.clientpolicy.password=*** --logging.file.name=/var/log/restclient/asproxy.log
For more JVM command-line options, see the documentation.
Building a Docker image
- Clone the Aerospike REST Gateway
- Install Docker
- From the root directory run
docker build -t aerospike-rest-gateway .
3 - Configuration
REST server configuration
The REST gateway is a Spring Boot application and the container can be configured using, for example, path arguments at startup.
By default, the server will start at port
8080 and will have no prefix other than the version, so the base URL would be
https://localhost:8080/v1/. If, for example, your application used port
5150 and had the basename
party that could be configured at startup using the command
java -jar /path/to/jar --server.servlet.context-path=/party --server.port=5150
There are a large number of properties that may be set. For the common set (where you might change the log level for example) see here and for the server properties (where you might [as in the above example] change the port number) see here.
Aerospike server configuration
By default, the REST Gateway looks for an Aerospike Server available at
localhost:3000 . The following environment variables allow specification of a different host/port.
server.portChange the port the REST Gateway is listening on (default: 8080)
aerospike.restclient.hostnameThe IP address or Hostname of a seed node in the cluster (default:
localhost) Note: If TLS is being utilized,
aerospike.restclient.hostlistshould be used instead of this variable.
aerospike.restclient.portThe port to communicate with the Aerospike cluster over. (default:
aerospike.restclient.hostlistA comma separated list of cluster hostnames, (optional TLS names) and ports. If this is specified, it overrides the previous two environment variables. The format is described below:
The string format is : hostname1[:tlsname1][:port1],...
* Hostname may also be an IP address in the following formats.
* IPv4: xxx.xxx.xxx.xxx
* IPv6: [xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx:xxxx]
* IPv6: [xxxx::xxxx]
* IPv6 addresses must be enclosed by brackets.
* tlsname and port are optional.
java -jar as-rest-client-*.jar --aerospike.restclient.hostname=172.17.0.3 --server.port=9876
The REST Gateway also allows authentication to an Aerospike Enterprise edition server with security enabled. The following environment variables are used to find authentication information.
aerospike.restclient.clientpolicy.userThis is the name of a user registered with the Aerospike database. This variable is only needed when the Aerospike cluster is running with security enabled.
aerospike.restclient.clientpolicy.passwordThis is the password for the previously specified user. This variable is only needed when the Aerospike cluster is running with security enabled.
aerospike.restclient.clientpolicy.authModeThis is the authentication mode. Use it when user/password is defined. Supported modes are INTERNAL, EXTERNAL and EXTERNAL_INSECURE. Default is INTERNAL.
To utilize the multi-tenancy capability within the REST Gateway, send Aerospike login credentials using the Basic access authentication.
Set custom multi-user authentication configuration variables if needed:
aerospike.restclient.requireAuthenticationSet this boolean flag to true to require the Basic Authentication on each request.
aerospike.restclient.pool.sizeRepresents the max size of the authenticated clients LRU cache (default value: 16). Please note that an oversized client cache will consume a lot of resources and affect the performance.
Beginning with version
1.1.0 the Aerospike REST Gateway supports TLS communication between the client and the Aerospike Server. (This feature requires an Enterprise Edition Aerospike Server).
If utilizing TLS, the
aerospike.restclient.hostlist variable should be set to include appropriate TLS Names for each of the Aerospike Nodes. For example:
localhost:cluster-tls-name:4333 The following environment variables allow configuration of this connection:
aerospike.restclient.ssl.enabledboolean, set to
trueto enable a TLS connection with the Aerospike Server. If no other SSL environment variables are provided, the REST gateway will attempt to establish a secure connection utilizing the default Java SSL trust and keystore settings. Default:
aerospike.restclient.ssl.keystorepathThe path to a Java KeyStore to be used to interact with the Aerospike Server. If omitted the default Java KeyStore location and password will be used.
aerospike.restclient.ssl.keystorepasswordThe password to the keystore. If a keystore path is specified, this must be specified as well.
aerospike.restclient.ssl.keypasswordThe password for the key to be used when communicating with Aerospike. If omitted, and
aerospike.restclient.ssl.keystorepasswordis provided, the value of
aerospike.restclient.ssl.keystorepasswordwill be used as the key password.
aerospike.restclient.ssl.truststorepathThe path to a Java TrustStore to be used to interact with the Aerospike Server. If omitted the default Java TrustStore location and password will be used.
aerospike.restclient.ssl.truststorepasswordThe password for the truststore. May be omitted if the TrustStore is not password protected.
aerospike.restclient.ssl.forloginonlyBoolean indicating that SSL should only be used for the initial login connection to Aerospike. Default:
aerospike.restclient.ssl.allowedciphersAn optional comma separated list of ciphers that are permitted to be used in communication with Aerospike. Available cipher names can be obtained by
aerospike.restclient.ssl.allowedprotocolsAn optional comma separated list of protocols that are permitted to be used in communication with Aerospike. Available values can be aquired using
SSLSocket.getSupportedProtocols(). By Default only