Deploy a Single Node EloqKV Cluster Using Eloqctl
eloqctl
is a powerful tool designed for the operation and maintenance of EloqKV clusters. With Eloqctl, you can effortlessly manage daily database tasks, such as deploying, starting, stopping, upgrading, and decommissioning EloqKV clusters, as well as configuring cluster parameters.
eloqctl
supports the deployment of various cluster types, including EloqKV transactional clusters, EloqKV log clusters, persistent storage clusters like Cassandra, and associated monitoring systems. This document provides guidance on deploying EloqKV cluster on a single node.
1. Prerequisites
EloqKV is compatible with Red Hat 8/9 and Ubuntu 20.04, 22.04, and 24.04.
Please ensure you've reviewed the following documents:
2. Deploy eloqctl on the control machine
- Get your eloqctl installation script here:
- To install eloqctl, simply run the following command:
bash eloqctl_installer.sh
If the following message is displayed, you have successfully installed eloqctl
:
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 16.6M 100 16.6M 0 0 203M 0 --:--:-- --:--:-- --:--:-- 205M
/home/eloq/.bash_profile has been modified to add eloqctl to PATH
===============================================
To use it, open a new terminal or execute:
source /home/eloq/.bash_profile
===============================================
This command installs eloqctl in the $HOME/.eloqctl directory, where the cluster metadata and downloaded components are also stored.
Please run source $HOME/.bash_profile
to add $HOME/.eloqctl
to the PATH environment variable, so you can use eloqctl
directly.
Once installed, you can verify the eloqctl
version by running:
eloqctl --version
3. Initialize the cluster topology file
Example cluster topology files can be found in the .eloqctl/config/examples/
directory.
You can select either eloqkv_rocksdb.yaml
or eloqkv_cassandra.yaml
to set up your EloqKV cluster. For a detailed comparison between the RocksDB and Cassandra storage engines, please refer to the EloqKV Introduction. In the following example, we will demonstrate how to set up the cluster topology file using RocksDB.
# example yaml file
.eloqctl/config/examples/eloqkv_rocksdb.yaml
Open the configuration file by running vi eloqkv_rocksdb.yaml
to view its contents:
connection:
username: "${USER}"
auth_type: "keypair"
auth:
keypair: "/home/${USER}/.ssh/id_rsa"
deployment:
cluster_name: "eloqkv-cluster"
product: "EloqKV"
version: "latest"
install_dir: "/home/${USER}"
tx_service:
host: [127.0.0.1]
client_port: 6389
log_service:
nodes:
- host: 127.0.0.1
port: 9000
data_dir:
- "/home/${USER}/eloqkv-cluster/wal_eloqkv"
replica: 1
storage_service:
rocksdb: Local
monitor:
data_dir: ""
monograph_metrics:
path: "/mono_metrics"
port: 18081
prometheus:
download_url: "https://github.com/prometheus/prometheus/releases/download/v2.42.0/prometheus-2.42.0.linux-amd64.tar.gz"
port: 9500
host: 127.0.0.1
grafana:
download_url: "https://dl.grafana.com/oss/release/grafana-9.3.6.linux-amd64.tar.gz"
port: 3301
host: 127.0.0.1
node_exporter:
url: "https://github.com/prometheus/node_exporter/releases/download/v1.5.0/node_exporter-1.5.0.linux-amd64.tar.gz"
port: 9200
Next, we'll provide detailed explanations for each configuration option available in the YAML file.
The connection
section includes settings for connecting to EloqKV nodes from the control machine. If you followed the steps in the Prerequisite Document, you can leave the connection section unchanged.
The deployment
section covers the configurations for deploying cluster metadata as well as the three key components: the transaction cluster, log cluster, and persistent storage cluster.
-
cluster_name
:
Type:String
Default:'eloqkv-cluster'
The name of the cluster being deployed serves as an identifier for the cluster. Witheloqctl
, you can deploy and manage multiple clusters, each distinguished by its unique name. -
product
:
Type:String
Default:'EloqKV'
The product name being deployed should be set to'EloqKV'
for the current deployment. In the future,eloqctl
will support the deployment of different database products likeEloqSQL
etc.. -
version
:
Type:String
Default:'latest'
Specifies the version of EloqKV to be installed. Setting this to'latest'
ensures that the most recent version is used. -
install_dir
:
Type:String
Default:'/home/${USER}'
Specifies the directory where the product will be installed. The${USER}
placeholder dynamically references the current user's home directory. -
tx_service.host
:
Type:List of Strings
Default:[127.0.0.1]
The list of IP addresses for the transaction service hosts. The transaction service handles Redis client requests and is compatible with the Redis Protocol. Note that each IP address can only be listed once. -
tx_service.client_port
:
Type:Integer
Default:6389
Specifies the port on which the transaction service listens. Redis clients connect to this port, and all transaction service hosts will use the sameclient_port
. -
log_service.nodes
:
Type:Composite
Specify the log service hosts. You can configure anywhere from zero to multiple log service nodes. Setting this to zero indicates that the Write-Ahead Log (WAL) is coupled with the transaction service, in which case you should remove the log_service section entirely. If you specify a non-zero value, the log service is decoupled from the transaction service, running as a standalone process. This can be deployed in a separate cluster or within the same cluster as the transaction service, depending on your requirements. -
log_service.nodes.host
:
Type:String
Default:'127.0.0.1'
The IP address where each log service process is running. -
log_service.nodes.port
:
Type:Integer
Default:9000
The port on which each log service process listens. -
log_service.nodes.data_dir
:
Type:Strings
Default:['/home/${USER}/disk_wal_kv']
The directory where each log service process stores its WAL logs. You can specify a separate disk for the log service to improve write throughput. -
log_service.replica
:
Type:Integer
Default:1
The number of replicas for the log service. A value of 1 means there is only one replica. For high availability, set this to 3 or 5. Note that the number of log service nodes should be greater than the number of replicas.
The monitor
section contains configurations for deploying a Prometheus and Grafana-based monitoring system for EloqKV. Monitoring is optional; if you do not wish to include it, simply remove the monitor section. If you choose to enable monitoring, set the prometheus.host and grafana.host fields to specify the locations of Prometheus and Grafana, and leave the other fields unchanged. Note that Prometheus and Grafana cannot be shared with other software, so you must ensure that the ports used by Prometheus and Grafana are not occupied by other processes.
-
monitor.grafana.host
: Type:String
Default:'127.0.0.1'
The IP address where grafana service is running. -
monitor.grafana.port
: Type:Integer
Default:'3301'
The port on which grafana service listens. -
monitor.prometheus.host
: Type:String
Default:'127.0.0.1'
The IP address where prometheus service is running. -
monitor.prometheus.host
: Type:Integer
Default:'9500'
The port on which prometheus service listens.
4. Run the deployment command
After you modified the eloqkv_rocksdb.yaml
. Use the eloqctl launch
command to provision an EloqKV cluster
eloqctl launch ${HOME}/.eloqctl/config/examples/eloqkv_rocksdb.yaml
The command will install the EloqKV components in the specified cluster.
If you see the following message, the EloqKV cluster has been successfully provisioned:
Launch cluster finished, Enjoy!
Connect to server:
/home/eloq/eloqkv-cluster/EloqKV/bin/eloqkv-cli -h 127.0.0.1 -p 6389
Prometheus: http://127.0.0.1:9500
Grafana: http://127.0.0.1:3301
Feel free to use eloqkv-cli
or any other Redis client to connect to EloqKV and enjoy exploring its features.