In the recent open-source data landscape, Valkey has emerged as a prominent player. Born as a Linux Foundation-backed, fully open-source fork of Redis (following Redis’s recent licensing changes), Valkey serves as a high-performance, in-memory key-value data store.
Whether Valkey is deployed as a primary database, an ephemeral cache, or a rapid message broker, a single node is rarely sufficient for production workloads, as it creates a single point of failure. Ensuring high availability and scaling out read operations requires replication.
This comprehensive guide explores how to configure a Primary-Replica (Master-Slave) replication topology in Valkey, detailing its underlying mechanics and the verification process.
Valkey’s replication is asynchronous and non-blocking. When a replica connects to a primary node, it initiates a synchronisation process.
Initially, the primary creates a snapshot of its entire dataset in memory (an RDB file) and sends it to the replica. Once this initial full sync is complete, the primary continuously streams a log of all new write operations to the replica. Because this happens asynchronously, the primary node does not wait for the replica to acknowledge writes, meaning applications experience zero latency penalty from the replication process.
Before diving into the configuration commands, it is important to understand the concrete benefits of this architecture:
The following components are required:
This tutorial uses the following hypothetical IP addresses:
By default, Valkey binds only to localhost (127.0.0.1), meaning it rejects connections from outside servers. This must be adjusted to allow replica connections.
2. Find the bind directive. Update it to listen on both localhost and the internal network IP. Note: While * can be used to listen on all interfaces, specifying the exact IP provides better security.
bind 127.0.0.1 172.31.32.27
While older versions of Redis used the requirepass directive, Valkey utilizes modern ACLs. Securing the default user and creating a dedicated, restricted user specifically for replication is highly recommended. This ensures the replica only has the permissions necessary to sync data. Add the following ACL rules:
|
1 2 3 4 5 |
# Secure the default user so unauthorized users cannot access the database user default on >amma@123 ~* &* +@all # Create a dedicated replication user with ONLY the permissions needed to sync user repl_user on >ReplPass@123 -@all +psync +replconf +ping +info |
|
1 |
sudo systemctl restart valkey |
Now, let’s move over to the Replica Node (172.31.37.55). There are two ways to configure a replica: dynamically via the CLI using the REPLICAOF command (which resets upon reboot) or permanently via the configuration file. For production, we will use the permanent method.
|
1 |
replicaof 172.31.32.27 6379 |
|
1 2 |
masteruser repl_user masterauth ReplPass@123 |
|
1 |
replica-read-only yes |
Restart the Valkey service on the replica:
|
1 |
sudo systemctl restart valkey |
The replica should now be connecting to the primary and synchronizing the dataset. Let’s verify the connection and test the data flow.
Log in to the Primary Node using the Valkey CLI.
Pro tip: The CLI generates a warning when passing a password with -a, as it appears in bash history. For production systems, consider utilizing the VALKEYCLI_AUTH environment variable instead. Note for Valkey 7.2.x users: As the first release following the Redis fork, the system still uses the legacy REDISCLI_AUTH environment variable name.
|
1 |
valkey-cli -a YourSuperSecurePassword |
Once inside the prompt, type the INFO replication command:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
root@ArunValkeyPrimary:/home/ubuntu# valkey-cli -a amma@123 127.0.0.1:6379> INFO replication # Replication role:master connected_slaves:1 slave0:ip=172.31.37.55,port=6379,state=online,offset=126,lag=1 master_failover_state:no-failover master_replid:7ef2ac2cc03b211c9571da0c0a53899327177349 master_replid2:0000000000000000000000000000000000000000 master_repl_offset:126 second_repl_offset:-1 repl_backlog_active:1 repl_backlog_size:1048576 repl_backlog_first_byte_offset:1 repl_backlog_histlen:126 127.0.0.1:6379> |
Warning: Using a password with ‘-a’ or ‘-u’ option on the command line interface may not be safe.
Key Metrics to Watch:
To double-check the data flow, set a key on the primary:
|
1 2 3 4 |
# On Primary (172.31.32.27) 127.0.0.1:6379> SET blog_status "Replication works!" OK 127.0.0.1:6379> |
Then, hop over to the Replica’s CLI and read the key:
|
1 2 3 4 |
# On Replica (172.31.37.55) 127.0.0.1:6379> GET blog_status "Replication works!" 127.0.0.1:6379> |
With just a few configuration changes, you’ve transformed a single-node Valkey setup into a scalable, production-ready replication topology. You now have data redundancy, improved read performance, and a solid foundation for growth.
But there’s one missing piece—automatic failover. If the primary node goes down, the replicas won’t take over automatically. That’s where the next evolution comes in.
In the upcoming guide, (Achieving High Availability with Valkey Sentinel) I will dive into Valkey Sentinel and show how to turn this replicated setup into a fully self-healing, highly available system.
