Skip to content

docs: add valkey support for memory db and elasticache services #143

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 31, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 39 additions & 5 deletions src/content/docs/aws/services/elasticache.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
title: "ElastiCache"
tags: ["Base"]
description: Get started with AWS ElastiCache on LocalStack
description: Get started with Amazon ElastiCache on LocalStack
persistence: supported
---

Expand All @@ -12,12 +12,13 @@ import FeatureCoverage from "../../../../components/feature-coverage/FeatureCove
Amazon ElastiCache is a managed in-memory caching service provided by Amazon Web Services (AWS).
It facilitates the deployment and operation of in-memory caches within the AWS cloud environment.
ElastiCache is designed to improve application performance and scalability by alleviating the workload on backend databases.
It supports popular open-source caching engines like Redis and Memcached (LocalStack currently supports Redis),
providing a means to efficiently store and retrieve frequently accessed data with minimal latency.

Amazon ElastiCache supports popular open-source caching engines like Redis, Valkey, and Memcached.
LocalStack currently supports Redis and Valkey, enabling developers to simulate ElastiCache behavior locally for efficient, low-latency data caching.

LocalStack supports ElastiCache via the Pro offering, allowing you to use the ElastiCache APIs in your local environment.
The supported APIs are available on our [API Coverage section](#api-coverage),
which provides information on the extent of ElastiCache integration with LocalStack.

The supported APIs are available on our [API Coverage section](#api-coverage), which provides information on the extent of ElastiCache integration with LocalStack.

## Getting started

Expand Down Expand Up @@ -115,6 +116,39 @@ Another reason you might want to use the container mode is to check the logs of

To do this, you can set the `REDIS_CONTAINER_MODE` configuration variable to `1`.

## Valkey Engine

LocalStack offers the additional option to use Valkey as an alternative to Redis in Amazon ElastiCache.

To enable full Valkey emulation:

1. Start LocalStack with Valkey support enabled by setting the environment variable, `REDIS_CONTAINER_MODE=1`
2. Create a cluster with the Valkey engine by including the `--engine valkey` flag in your API call:

```bash
awslocal elasticache create-replication-group \
--replication-group-id my-valkey-group \
--replication-group-description "Valkey test group" \
--engine valkey \
--cache-node-type cache.t4g.small \
--num-node-groups 1 \
--replicas-per-node-group 1 \
--automatic-failover-enabled
```

Valkey support includes:

- The ability to specify `valkey` as the engine when creating Amazon ElastiCache replication groups.

- Automatic mapping of each engine to a default supported version (Redis `7.2.10`, Valkey `7.2.10`), ensuring DockerHub compatibility.

- Support for the `Engine` and `EngineVersion` fields in the `CreateReplicationGroup` API, which now recognize and handle `valkey`.


::: note
A Valkey replication group can only be started when [container mode](/aws/services/elasticache/#container-mode) is enabled.
:::

## Resource browser

The LocalStack Web Application provides a Resource Browser for managing ElastiCache resources.
Expand Down
38 changes: 35 additions & 3 deletions src/content/docs/aws/services/memorydb.mdx
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: "MemoryDB for Redis"
title: "MemoryDB"
tags: ["Ultimate"]
description: Get started with MemoryDB on LocalStack
---
Expand All @@ -8,8 +8,9 @@ import FeatureCoverage from "../../../../components/feature-coverage/FeatureCove

## Introduction

MemoryDB is a fully managed, Redis-compatible, in-memory database tailored for workloads demanding ultra-fast, primary database functionality.
It streamlines the deployment and management of in-memory databases within the AWS cloud environment, acting as a replacement for using a cache in front of a database for improved durability and performance.
Amazon MemoryDB is a fully managed, in-memory database service designed for ultra-fast, primary database use cases. Compatible with both Valkey and Redis OSS, it improves performance and durability.

Built for the AWS cloud environment, MemoryDB simplifies the deployment and operation of in-memory databases, acting as a replacement for using a cache in front of a database.

LocalStack provides support for the main MemoryDB APIs surrounding cluster creation, allowing developers to utilize the MemoryDB functionalities in their local development environment.
The supported APIs are available on our [API Coverage section](#api-coverage), which provides information on the extent of MemoryDB's integration with LocalStack.
Expand Down Expand Up @@ -72,9 +73,40 @@ This approach directs LocalStack to launch Redis instances in distinct container
Additionally, container mode is beneficial for independently examining the logs of each Redis instance.
To activate this, set the `REDIS_CONTAINER_MODE` configuration variable to `1`.


## Valkey Engine

LocalStack offers the additional option to use Valkey as an alternative to Redis in Amazon MemoryDB.

To enable full Valkey emulation:

1. Start LocalStack with Valkey support enabled by setting the environment variable, `REDIS_CONTAINER_MODE=1`
2. Create a cluster with the Valkey engine by including the `--engine valkey` flag in your API call:

```bash
awslocal memorydb create-cluster \
--cluster-name my-valkey-cluster \
--node-type db.t4g.small \
--acl-name open-access \
--engine valkey
```

Valkey support includes:

- The ability to specify `valkey` as the engine when creating Amazon MemoryDB clusters.

- Automatic mapping of each engine to a default supported version (Redis `7.2.10`, Valkey `7.2.10`), ensuring DockerHub compatibility.

- Support for the `Engine` and `EngineVersion` fields in the `CreateCluster` API, which now recognize and handle `valkey`.

::: note
A Valkey cluster can only be started when [container mode](/aws/services/memorydb/#container-mode) is enabled.
:::

## Current Limitations

LocalStack's emulation support for MemoryDB primarily focuses on the creation and termination of Redis servers in cluster mode.

Essential resources for running a cluster, such as parameter groups, security groups, and subnet groups, are mocked but have no effect on the Redis servers' operation.

LocalStack currently doesn't support MemoryDB snapshots, failovers, users/passwords, service updates, replication scaling, SSL, migrations, service integration (like CloudWatch/Kinesis log delivery, SNS notifications) or tests.
Expand Down