Valkey#
Lagoon valkey
image Dockerfile, based on official valkey/valkey:alpine
image.
This Dockerfile is intended to be used to set up a standalone Valkey ephemeral server by default.
Info
Valkey is a community-led successor to Redis It's intended to be backwards compatible, but any integration should always be tested prior to first use.
Supported versions#
- 8 Dockerfile -
uselagoon/valkey-8
Usage#
There are 2 different flavors of Valkey: Ephemeral and Persistent.
Ephemeral#
The ephemeral flavor is intended to be used as an in-memory cache for applications and will not retain data across container restarts.
When being used as an in-memory (RAM) cache, the first thing you might want to tune if you have large caches is to adapt the MAXMEMORY
variable. This variable controls the maximum amount of memory (RAM) which valkey will use to store cached items.
Persistent#
The persistent Valkey flavor will persist data across container restarts and can be used for queues or application data that will need persistence.
We don't typically suggest using a persistent Valkey for in-memory cache scenarios as this might have unintended side-effects on your application while a Valkey container is restarting and loading data from disk.
Lagoon adaptions#
This image is prepared to be used on Lagoon. There are therefore some things already done:
- Folder permissions are automatically adapted with
fix-permissions
so this image will work with a random user. - The files within
/etc/valkey/*
are templated usingenvplate
via a container-entrypoint.
Included valkey.conf
configuration file#
The image ships a default Valkey configuration file, optimized to work on Lagoon.
Environment Variables#
Some options are configurable via environment variables.
Environment Variable | Default | Description |
---|---|---|
DATABASES | -1 | Default number of databases created at startup. |
LOGLEVEL | notice | Define the level of logs. |
MAXMEMORY | 100mb | Maximum amount of memory. |
MAXMEMORYPOLICY | allkeys-lru | The policy to use when evicting keys if Valkey reaches its maximum memory usage. |
VALKEY_FLAVOR | ephemeral | The Valkey configuration flavor to load. Can be ephemeral or persistent . |
VALKEY_PASSWORD | disabled | Enables authentication feature. |
Custom configuration#
By building on the base image you can include custom configuration. See https://github.com/valkey-io/valkey/blob/8.1/valkey.conf for full documentation of the Valkey configuration file.
Persistent storage#
The Lagoon valkey
image will check which flavor of Valkey to use by inspecting the VALKEY_FLAVOR
env var. When set to persistent
, the persistent configuration will be loaded.
Troubleshooting#
The Lagoon Valkey images all come pre-loaded with the valkey-cli
command, which allows for querying the Valkey service for information and setting config values dynamically. To use this utility, you can simply SSH into your Valkey pod by using the instructions here with valkey
as the pod
value then run it from the terminal once you've connected.
Maximum Memory Policy#
By default, the Lagoon valkey
images are set to use the allkeys-lru
policy. This policy will alow ANY keys stored in Valkey to be evicted if/when the Valkey service hits its maxmemory
limit according to when the key was least recently used.
For typical installations, this is the ideal configuration, as Drupal may not set a TTL
value for each key cached in Valkey. If the maxmemory-policy
is set to something like volatile-lru
and Drupal doesn't provide these TTL
tags, this would result in the Valkey container filling up, being totally unable to evict ANY keys, and ceasing to accept new cache keys at all.
More information on Valkey' maxmemory policies can be found in Valkey' official documentation.
Proceed with Caution
Changing this setting can lead to Valkey becoming completely full and cause outages as a result.
Tuning Valkey' maxmemory
value#
Finding the optimal amount of memory to give Valkey can be quite the difficult task. Before attempting to tune your Valkey cache's memory size, it is prudent to let it run normally for as long as practical, with at least a day of typical usage being the ideal minimum timeframe.
There are a few high level things you can look at when tuning these memory values:
- The first thing to check is the percentage of memory in use by Valkey currently.
- If this percentage is less than
50%
, you might consider lowering themaxmemory
value by 25%. - If this percentage is between
50%
and75%
, things are running just fine. - If this value is greater than
75%
, then it's worth looking at other variables to see ifmaxmemory
needs to be increased.
- If this percentage is less than
- If you find that your Valkey' memory usage percentage is high, the next thing to look at is the number of key evictions.
- A large number of key evictions and a memory usage greater than
95%
is a fairly good indicator that your valkey needs a highermaxmemory
setting. - If the number of key evictions doesn't seem high and typical response times are reasonable, this is simply indicative of Valkey doing its job and managing its allocated memory as expected.
- A large number of key evictions and a memory usage greater than
Example commands#
The following commands can be used to view information about the Valkey service:
- View all info about the Valkey service:
valkey-cli info
- View service memory information:
valkey-cli info memory
- View service keyspace information:
valkey-cli info keyspace
- View service statistics:
valkey-cli info stats
It is also possible to set values for the Valkey service dynamically without a restart of the Valkey service. It is important to note that these dynamically set values will not persist if the pod is restarted (which can happen as a result of a deployment, maintenance, or even just being shuffled from one node to another).
- Set
maxmemory
config value dynamically to500mb
:config set maxmemory 500mb
- Set
maxmemory-policy
config value dynamically tovolatile-lru
:config set maxmemory-policy volatile-lru
