Apache Kvrocks on Ubuntu 24.04 on Azure User Guide

Overview

Apache Kvrocks is a distributed, persistent key-value store that is fully compatible with the Redis protocol but stores all of its data on disk through RocksDB instead of in RAM. That lets a single node serve working sets far larger than memory at low cost while keeping the Redis client, command and tooling ecosystem. The cloudimg image builds Apache Kvrocks 2.16.0 from the official Apache source release, runs it as a dedicated kvrocks system user, stores the RocksDB data directory on a dedicated Azure data disk, and rotates a unique password into the configuration on first boot. Backed by 24/7 cloudimg support.

What is included:

• Apache Kvrocks 2.16.0 built from the official Apache source release (Apache-2.0)
• The Redis-compatible client redis-cli (from redis-tools)
• A unique per-VM password generated on first boot (no shared default credential)
• RocksDB persistence on a dedicated 30 GiB Azure data disk at /var/lib/kvrocks
• Loopback-only listener on 6666 with requirepass authentication (not exposed publicly)
• 24/7 cloudimg support

This is a datastore product: Kvrocks listens on 127.0.0.1:6666 only. The port is not opened to the internet - connect locally on the VM or over an SSH tunnel.

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet + subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a good starting point. NSG inbound: allow 22/tcp from your management network. No inbound application ports are needed because Kvrocks is reached over the SSH tunnel.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Apache Kvrocks by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) only. Then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name kvrocks \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm Kvrocks is installed and running

kvrocks --version
systemctl is-active kvrocks

You should see Kvrocks 2.16.0 and active:

kvrocks version 2.16.0
active

Step 5 - Retrieve your per-VM password

Each VM generates its own unique Kvrocks password on first boot and writes it to a root-only credentials file:

sudo cat /root/kvrocks-credentials.txt

The file contains KVROCKS_PASSWORD, the connection string and the SSH-tunnel instructions. Store the password in your secrets manager. In the commands below, <KVROCKS_PASSWORD> stands for the value of KVROCKS_PASSWORD.

Step 6 - Authenticate with redis-cli

Kvrocks requires the password (requirepass) and listens on port 6666. Authenticate and run a PING:

redis-cli -p 6666 -a <KVROCKS_PASSWORD> --no-auth-warning ping

PONG

A wrong password is rejected with WRONGPASS, so the datastore is never open without the credential.

Step 7 - Store and retrieve data

Kvrocks speaks the Redis protocol, so every Redis command works unchanged. Set a string, read it back, increment a counter and push to a list:

redis-cli -p 6666 -a <KVROCKS_PASSWORD> --no-auth-warning set greeting "hello from Kvrocks"
redis-cli -p 6666 -a <KVROCKS_PASSWORD> --no-auth-warning get greeting
redis-cli -p 6666 -a <KVROCKS_PASSWORD> --no-auth-warning set counter 100
redis-cli -p 6666 -a <KVROCKS_PASSWORD> --no-auth-warning incr counter
redis-cli -p 6666 -a <KVROCKS_PASSWORD> --no-auth-warning rpush mylist a b c
redis-cli -p 6666 -a <KVROCKS_PASSWORD> --no-auth-warning lrange mylist 0 -1

OK
hello from Kvrocks
OK
101
3
a
b
c

Step 8 - Confirm RocksDB persistence

Kvrocks persists all data with RocksDB in the directory /var/lib/kvrocks on the dedicated data disk. Confirm the keyspace, the data directory and the server details:

redis-cli -p 6666 -a <KVROCKS_PASSWORD> --no-auth-warning info keyspace
redis-cli -p 6666 -a <KVROCKS_PASSWORD> --no-auth-warning config get dir
redis-cli -p 6666 -a <KVROCKS_PASSWORD> --no-auth-warning info server | grep -iE 'kvrocks_version|rocksdb_version'

# Keyspace
db0:keys=3,expires=0,avg_ttl=0,expired=0
used_disk_size:1705910272
dir
/var/lib/kvrocks
kvrocks_version:2.16.0
rocksdb_version:11.1.1

The data directory on the dedicated disk holds the RocksDB files, so the keyspace survives reboots. List the persisted RocksDB files:

sudo ls /var/lib/kvrocks

Step 9 - Connect remotely over an SSH tunnel

Kvrocks listens on 127.0.0.1:6666 only and is not exposed publicly - this is the secure default. To reach it from your workstation, open an SSH tunnel and point a local client at localhost:6666:

# On your workstation:
ssh -L 6666:127.0.0.1:6666 azureuser@<vm-public-ip>

# In another terminal, with a local redis-cli:
redis-cli -h 127.0.0.1 -p 6666 -a <KVROCKS_PASSWORD> --no-auth-warning ping

The authentication round-trip below proves the wall: the wrong password is rejected, the correct one is accepted.

For production remote access without a tunnel, bind Kvrocks to a private NIC and front it with TLS (for example via stunnel or a service mesh). Never expose 6666 to the internet without transport encryption.

Maintenance

• Persistence: the RocksDB data directory lives on the dedicated data disk at /var/lib/kvrocks, so the keyspace survives reboots and the volume is independently resizable.
• Password: change it by editing requirepass in /etc/kvrocks/kvrocks.conf and running sudo systemctl restart kvrocks.
• Tuning: edit /etc/kvrocks/kvrocks.conf (for example workers, maxclients, rocksdb.block_cache_size) and restart the service.
• Security patches: unattended-upgrades remains enabled so the OS continues to receive security updates automatically.
• Compatibility: Kvrocks is a Redis-protocol drop-in - existing Redis clients, libraries and tooling work unchanged against 6666.

Support

cloudimg provides 24/7 expert support for this image. Contact support@cloudimg.co.uk.

Apache Kvrocks and Apache are trademarks of the Apache Software Foundation. Redis is a trademark of Redis Ltd. This image is provided by cloudimg and is not affiliated with or endorsed by the Apache Software Foundation or Redis Ltd.