Installing Aerospike Connect -- ESP Outbound
Connector version 2.0.0 or later
Starting with connector version 2.0.0
, there is a single installer that handles both XDR connector 5.0 wire protocol and HTTP.
- aerospike-esp-outbound-[version].[package] for server 5.0 and later
- aerospike/aerospike-esp-outbound:[version]
Version prior to 2.0.0
The communication protocol between Aerospike Database and the outbound connectors, including ESP, changed for server 5.0 and later. Different ESP outbound installers and container images are used for server 5.0 and later.
- aerospike-esp-outbound-[version].[package] for server 5.0 and later
- aerospike-esp-outbound-http-[version].[package] for prior to server 5.0
- aerospike/aerospike-esp-outbound:[version]
- aerospike/aerospike-esp-outbound-http:[version]
Prerequisites
Aerospike Server change notification configuration
Streaming from Aerospike requires you to configure your Aerospike database to send change notifications. For the steps, see Configuring Change Notification for Use with Connectors.
Procedures
You can deploy the ESP outbound connector in three environments:
Deploying in Docker
Prerequisite
Download and install Docker from here.
Procedure
Pull the image for the ESP outbound connector from Docker Hub.
You can pull the image by running this command:
docker pull aerospike/aerospike-esp-outbound:2.0.0
Create the configuration file aerospike-esp-outbound.yml
.
You can create this file anywhere in your system. When you run a Docker container in the next step, it will mount the file into the container's file system.
For descriptions of the configuration properties and a sample configuration file, see "Configuring the ESP outbound connector".
Run the container.
Use the following command to mount the configuration file in the container.
docker run \
-v <path to local aerospike-esp-outbound.yml>:/etc/aerospike-esp-outbound/aerospike-esp-outbound.yml \
aerospike/aerospike-esp-outbound:2.0.0
<path to local aerospike-esp-outbound.yml>
: The path (including the name) of the configuration file in your local filesystem.
Deploying in Kubernetes
Procedure
Configure the ESP outbound connector and apply the configuration with a Kubernetes ConfigMap.
This step involves creating a folder, creating and adding files to this folder, and pointing to this folder when you create a ConfigMap.
Create a folder
The path and name of the directory do not matter.
Example
mkdir aerospike-esp-outbound
Copy TLS truststore and keystore files, if you have any, into this directory.
If you plan to use TLS to connect to the destinations of the messages sent by the ESP outbound connector (load balancers or connector instances), copy truststore and keystore files for those connections into this folder, so that the Kubernetes container has access to them.
Create a configuration file named aerospike-esp-outbound.yml
in this directory.
For descriptions of the configuration properties and a sample configuration file, see Configuring the ESP outbound connector".
Create the ConfigMap.
kubectl -n <k8s namespace> create configmap aerospike-esp-outbound-config \
--from-file=<path-and-name-of-directory> --dry-run=client -o yaml | kubectl apply -f -
<k8s namespace>
: The name of the Kubernetes namespace in which to create the ConfigMap.<path-and-name-of-directory>
: The path and name of the directory that contains the configuration file.
Result
If the command runs successfully, it displays a message that it created the ConfigMap:
W0512 09:21:00.039900 12016 helpers.go:557] --dry-run is deprecated and can be replaced with --dry-run=client.
configmap/aerospike-esp-outbound-config created
Deploy the ESP outbound connector in a container.
These steps explain how to run the ESP outbound connector in its own pod. However, you can run the ESP outbound connector as a sidecar to the main container of an Aerospike database being run by the Aerospike Kubernetes Operator.
Create a Kubernetes deployment file.
Here is a sample Kubernetes deployment file named aerospike-esp-outbound-deployment.yml
. It deploys of two instances of ESP outbound connector as separate pods. You can run more than one instance of the ESP outbound connector in case one fails, the other continues receiving CN messages from your Aerospike cluster.
apiVersion: apps/v1
kind: Deployment
metadata:
name: aerospike-esp-outbound
namespace: aerospike
spec:
replicas: 2
selector:
matchLabels:
app: aerospike-esp-outbound
template:
metadata:
labels:
app: aerospike-esp-outbound
spec:
volumes:
- name: aerospike-esp-outbound-config
configMap:
name: aerospike-esp-outbound-config
containers:
- name: aerospike-esp-outbound
image: aerospike/aerospike-esp-outbound:2.0.0
volumeMounts:
- mountPath: /etc/aerospike-esp-outbound
name: aerospike-esp-outbound-config
Deploy the ESP outbound connector.
Deploy the ESP outbound connector by running this command:
kubectl apply -f aerospike-esp-outbound-deployment.yml
Sample output:
deployment.apps/aerospike-esp-outbound created
Installing on Linux
Prerequisites
Supported operating systems
The connector is supported on the following operating systems:
- RHEL / CentOS 7+
- Ubuntu 18.04+
- Ubuntu 20.04+
- Ubuntu 22.04+
- Debian 9
- Debian 10
- Debian 11
Java Runtime Environment
This connector is a Java web-application that requires Java 8 or later. If you plan to use TLS v1.3, then you must use Java 11 or later. Both Oracle and OpenJDK Java Runtime Environments are supported.
Support for Java 8 will be dropped in future releases.
Java 17 is supported since ESP version 1.1.0 and later.
The following steps apply to installing both the Debian (*.deb) and RHEL (*.rpm) packages. Significant differences in the steps are noted.
Install Java 8 or later version
The Aerospike Connect for ESP Outbound package does not include a Java runtime environment. Most supported platforms provide official JDK 8 packages. For platforms that do not, Oracle's JDK 8 builds can be obtained from jdk.java.net/8/.
RHEL, CentOS, etc.
sudo yum install java-1.8.0-openjdk
Debian, Ubuntu, etc.
sudo apt-get install openjdk-8-jre
Install connector package
Version 2.0.0 or later
Starting with connector version 2.0.0
, there is a single installer that handles both XDR connector 5.0 wire protocol and HTTP.
Go to the Aerospike Enterprise downloads
site to download the connector package for your platform and install it.
Remember to set the protocol
based on the change notification source. See protocol for details
Version prior to 2.0.0
Go to the Aerospike Enterprise downloads
site to download the connector package for your platform. Otherwise, use the esp-outbound-http
for the Aerospike
Enterprise version < 5.0 and the esp-outbound
.
RHEL, CentOS, etc.
Version 2.0.0 or later
sudo rpm -i aerospike-esp-outbound-2.0.0-1.noarch.rpm
Version prior to 2.0.0
// With Aerospike 5.0 and later
sudo rpm -i aerospike-esp-outbound-1.1.0-1.noarch.rpm
// With Aerospike prior to 5.0
sudo rpm -i aerospike-esp-outbound-http-1.1.0-1.noarch.rpm
Debian, Ubuntu, etc.
Version 2.0.0 or later
$ sudo dpkg -i aerospike-esp-outbound-2.0.0.all.deb
Version prior to 2.0.0
// With Aerospike 5.0 and later
$ sudo dpkg -i aerospike-esp-outbound-1.1.0.all.deb
// With Aerospike prior to 5.0
$ sudo dpkg -i aerospike-esp-outbound-http-1.1.0.all.deb
Verify/update connector configuration
The configuration file for the connector is in /etc/aerospike-esp-outbound/
.
For details on how to configure the ESP outbound connector and enable
TLS, etc., see the Configuration Guide.
Start the connector
The connector package includes a Systemd service definition. The installation procedure creates an aerospike-esp-outbound service.
Enable the connector to start on system startup or reboot.
Version 2.0.0 or later
$ sudo systemctl enable aerospike-esp-outbound
Version prior to 2.0.0
// With Aerospike 5.0 and later
$ sudo systemctl enable aerospike-esp-outbound
// With Aerospike prior to server 5.0
$ sudo systemctl enable aerospike-esp-outbound-http
To start the connector service run.
Version 2.0.0 or later
$ sudo systemctl start aerospike-esp-outbound
Version prior to 2.0.0
// With server 5.0 and later
$ sudo systemctl start aerospike-esp-outbound
// With Aerospike prior to server 5.0
$ sudo systemctl start aerospike-esp-outbound-http