Databases AWS

Valkey on AWS User Guide

Last updated: 2026-05-25 | Product: Valkey on AWS

Overview

This image runs Valkey, the open source, BSD licensed, in memory key value store stewarded by the Linux Foundation. Valkey is a drop in replacement for the Redis API: the RESP protocol on port 6379, the same command surface, the same data structures, and the same client library compatibility. The current Valkey release available in the Ubuntu 24.04 archive is installed.

The image ships with no shared password. On the first boot of your instance a one shot service generates a fresh strong password, sets it as the requirepass on the running Valkey, and writes it to /root/valkey-credentials.txt, a file that only the root user can read. Authentication is enforced from the moment Valkey is reachable.

Valkey itself binds to the loopback address 127.0.0.1 on port 6379 on the instance, so the data port is never exposed to the public internet by accident. An nginx reverse proxy on port 80 serves a small Valkey identification page that doubles as a cloud network health check endpoint. You can connect to the data port from the instance itself with the bundled valkey-cli shell, or open the port to a private network by editing the Valkey configuration.

This is a headless image. Valkey has no web administration interface; you operate it over SSH with valkey-cli, covered below.

Prerequisites

Before you deploy this image you need:

An Amazon Web Services account where you can launch EC2 instances
IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
An EC2 key pair in the target Region for SSH access to the instance
A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and, if you want the identification page reachable, inbound port 80
The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Recommended instance type: m5.large (2 vCPU, 8 GB RAM) or larger. Valkey sizes its in memory dataset from available RAM; pick an instance size with enough memory for your working set plus headroom for replication and persistence.

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Valkey. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network. Optionally allow inbound port 80 from your monitoring network so the Valkey identification page is reachable. Do not open port 6379 to the public internet; restrict it to the address ranges of your application servers.

Select Launch instance. First boot initialisation, which generates the requirepass and applies it to Valkey, takes about a minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Valkey Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens inbound port 22 and (optionally) port 80.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --metadata-options HttpTokens=required \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":20,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=valkey-01}]'

The command prints a JSON document on success. Note the instance ID, then retrieve its public address once it is running with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Step 3: Connect over SSH

Connect over SSH with the key pair you selected and the public IP address from step 2. The SSH login user depends on the operating system of the AMI variant you launched:

AMI variant	SSH login user
Valkey 8 on Ubuntu 24.04	`ubuntu`

ssh <login-user>@<public-ip>

Wait until the instance has passed both EC2 status checks before connecting. The first boot service runs at boot, so Valkey is initialised and ready by the time you can log in.

Step 4: Retrieve the Generated requirepass

The first boot service generates a fresh requirepass for this instance and writes it, with the connection details, to /root/valkey-credentials.txt. The file is readable only by the root user. Display it from your SSH session:

sudo cat /root/valkey-credentials.txt

The file looks like this, with a unique password on your instance:

# Valkey — Per-Instance Credentials
# Generated on first boot by valkey-firstboot.service.

requirepass=<your generated password>
VALKEY_PASSWORD=<your generated password>
VALKEY_HOST=<your instance public IP>
LISTEN_ADDRESS=127.0.0.1
LISTEN_PORT=6379

The image ships with no default Valkey password, so the only way into the data port is the per instance value above.

Step 5: Confirm the Service and the Listener

Valkey runs under systemd as the valkey-server service and starts automatically on boot. Confirm it is active:

systemctl is-active valkey-server

The command prints active. Confirm the RESP listener is up. Valkey binds to 127.0.0.1 on port 6379 by default, so it is reachable from the instance itself:

ss -tln | grep 6379

You should see a listening socket on 127.0.0.1:6379.

The nginx identification page runs on port 80. Confirm it is reachable from the instance:

curl -s http://127.0.0.1/ | head -5

The page identifies the instance as a cloudimg Valkey AMI and is intended as a small, cloud network friendly health endpoint.

Step 6: Connect with valkey-cli

The valkey-cli shell ships in the image. Open an interactive session with the generated password. Replace <password> with the value from /root/valkey-credentials.txt:

valkey-cli -a '<password>' --no-auth-warning

You land in an interactive prompt:

127.0.0.1:6379>

Run a few commands to confirm the database is working:

PING
SET cloudimg:hello "Valkey on AWS"
GET cloudimg:hello
DEL cloudimg:hello
INFO server

PING returns PONG. SET returns OK. GET returns the value you just set. INFO server reports the running Valkey version and the operating system it is running on.

Exit the shell with quit.

Step 7: One Shot Commands from the Shell

You do not have to open an interactive session for every command. Pass -e to send a single command and exit. Replace <password> with the value from /root/valkey-credentials.txt:

valkey-cli -a '<password>' --no-auth-warning ping
valkey-cli -a '<password>' --no-auth-warning info server | head -20
valkey-cli -a '<password>' --no-auth-warning client list

ping returns PONG. info server returns version, build, mode, OS and uptime fields. client list shows the connections currently attached to Valkey.

Step 8: Open the Data Port to a Private Network

By default Valkey only accepts connections from the instance itself. To accept connections from other hosts on your private network, edit /etc/valkey/valkey.conf and replace bind 127.0.0.1 -::1 with the address you want Valkey to listen on, for example bind 0.0.0.0 -::*. Restart the service:

sudo systemctl restart valkey-server

In your security group, allow inbound TCP port 6379 only from the address ranges of your application servers. Never open 6379 to the public internet, even with requirepass set; rate limit and audit on the network instead.

Step 9: Persistence — RDB and AOF

Valkey writes periodic RDB snapshots to /var/lib/valkey/dump.rdb by default. RDB is the right choice for caches and ephemeral data. For write through durability also enable the append only file. Edit /etc/valkey/valkey.conf and set appendonly yes, then restart:

sudo systemctl restart valkey-server

The AOF lives under /var/lib/valkey/appendonlydir/. Both RDB and AOF are written into /var/lib/valkey/. Back up that directory with your normal backup tooling.

Step 10: Memory Cap and Eviction for Cache Workloads

By default Valkey has no memory cap and grows until the operating system runs out of RAM. For cache workloads, set an explicit memory cap and an eviction policy. Edit /etc/valkey/valkey.conf and add:

maxmemory 2gb
maxmemory-policy allkeys-lru

Restart the service. allkeys-lru evicts the least recently used key across the entire keyspace when the cap is reached and is the right policy for a general purpose cache.

Step 11: Connect from a Redis Client Library

Valkey implements the Redis API, so any Redis client library can talk to it without modification. The endpoint is the address and port you configured in step 8 and the password is the per instance value from /root/valkey-credentials.txt. As a smoke test from your laptop with the host added to the security group, run redis-cli or valkey-cli against the public IP with -h <public-ip> -a '<password>' --no-auth-warning ping.

Service Management

Day to day operations use the standard systemd commands:

sudo systemctl status valkey-server     # status + recent journal lines
sudo systemctl restart valkey-server    # apply config changes
sudo journalctl -u valkey-server -e     # follow the most recent log lines
sudo systemctl status nginx             # the identification page proxy

Valkey logs go to the systemd journal and to /var/log/valkey/valkey-server.log.

Updating Valkey

Valkey installs from the Ubuntu archive, so it tracks Ubuntu security updates. To apply security updates manually:

sudo apt-get update
sudo apt-get upgrade
sudo systemctl restart valkey-server

For major version upgrades, snapshot the data directory first, then upgrade as above.

Support

24/7 technical support is included. Contact cloudimg with the AWS instance ID and the Valkey version (valkey-server --version) to hand a question to a database engineer.