# ElastiCache

Source: /aws/services/elasticache/

## Introduction

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.

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.

## Getting started

This guide is designed for users new to ElastiCache and assumes basic knowledge of the AWS CLI and our [`lstk aws`](/aws/developer-tools/running-localstack/lstk/cloud-and-iac-commands/#aws) command.

### Single cache cluster

After starting LocalStack for AWS, you can create a cluster with the following command.

```bash
lstk aws elasticache create-cache-cluster \
  --cache-cluster-id my-redis-cluster \
  --cache-node-type cache.t2.micro \
  --engine redis \
  --num-cache-nodes 1
```

Wait for it to be available, then you can use the cluster endpoint for Redis operations.

```bash
lstk aws elasticache describe-cache-clusters --show-cache-node-info --query "CacheClusters[0].CacheNodes[0].Endpoint"
```

```bash title="Output"
{
  "Address": "localhost.localstack.cloud",
  "Port": 4510
}
```

The cache cluster uses a random port of the [external service port range](/aws/customization/networking/external-port-range/).
Use this port number to connect to the Redis instance like so:

```bash
redis-cli -p 4510 ping
PONG
redis-cli -p 4510 set foo bar
OK
redis-cli -p 4510 get foo
"bar"
```

### Replication groups in non-cluster mode

```bash
lstk aws elasticache create-replication-group \
  --replication-group-id my-redis-replication-group \
  --replication-group-description 'my replication group' \
  --engine redis \
  --cache-node-type cache.t2.micro \
  --num-cache-clusters 3
```

Wait for it to be available.
When running the following command, you should see one node group when running:

```bash
lstk aws elasticache describe-replication-groups --replication-group-id my-redis-replication-group
```

To retrieve the primary endpoint:

```bash
lstk aws elasticache describe-replication-groups --replication-group-id my-redis-replication-group \
  --query "ReplicationGroups[0].NodeGroups[0].PrimaryEndpoint"
```

### Replication groups in cluster mode

The cluster mode is enabled by using `--num-node-groups` and `--replicas-per-node-group`:

```bash
lstk aws elasticache create-replication-group \
  --engine redis \
  --replication-group-id my-clustered-redis-replication-group \
  --replication-group-description 'my clustered replication group' \
  --cache-node-type cache.t2.micro \
  --num-node-groups 2 \
  --replicas-per-node-group 2
```

Note that the group nodes do not have a primary endpoint.
Instead they have a `ConfigurationEndpoint`, which you can connect to using `redis-cli -c` where `-c` is for cluster mode.

```bash
lstk aws elasticache describe-replication-groups --replication-group-id my-clustered-redis-replication-group \
    --query "ReplicationGroups[0].ConfigurationEndpoint"
```

## Container mode

In order to start Redis clusters of a specific version, you need to use the container mode for Redis-based services.
This instructs LocalStack to start Redis instances in a separate container using the specified image tag.
Another reason you might want to use the container mode is to check the logs of every Redis instance separately.

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
  lstk aws 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.
You can access the Resource Browser by opening the LocalStack Web Application in your browser and navigating to the Resources section, then clicking on ElastiCache.

In the ElastiCache resource browser you can:

* List and remove existing cache clusters
  ![List existing cache clusters](/images/aws/elasticache-resource-browser-list.png)
* View details of cache clusters
  ![View details of cache clusters](/images/aws/elasticache-resource-browser-show.png)
* Create new cache clusters
  ![Create a ElastiCache cluster in the resource browser](/images/aws/elasticache-resource-browser-create.png)

## Current Limitations

LocalStack currently supports Redis single-node and cluster mode, but not memcached.
Moreover, LocalStack emulation support for ElastiCache is mostly centered around starting/stopping Redis servers.

Resources necessary to operate a cluster, like parameter groups, security groups, subnets groups, etc. are mocked, but have no effect on the functioning of the Redis servers.

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

## API Coverage


### ElastiCache API coverage

Source service: `elasticache`. 35 of 75 tracked operations are implemented.

Service documentation: /aws/services/elasticache/
License availability: available starting with the Base plan. See /aws/licensing/ for current plan details.

| Operation | Status |
| --- | --- |
| AddTagsToResource | Implemented |
| AuthorizeCacheSecurityGroupIngress | Not implemented |
| BatchApplyUpdateAction | Not implemented |
| BatchStopUpdateAction | Not implemented |
| CompleteMigration | Not implemented |
| CopyServerlessCacheSnapshot | Not implemented |
| CopySnapshot | Not implemented |
| CreateCacheCluster | Implemented |
| CreateCacheParameterGroup | Implemented |
| CreateCacheSecurityGroup | Implemented |
| CreateCacheSubnetGroup | Implemented |
| CreateGlobalReplicationGroup | Not implemented |
| CreateReplicationGroup | Implemented |
| CreateServerlessCache | Implemented |
| CreateServerlessCacheSnapshot | Not implemented |
| CreateSnapshot | Not implemented |
| CreateUser | Implemented |
| CreateUserGroup | Implemented |
| DecreaseNodeGroupsInGlobalReplicationGroup | Not implemented |
| DecreaseReplicaCount | Not implemented |
| DeleteCacheCluster | Implemented |
| DeleteCacheParameterGroup | Implemented |
| DeleteCacheSecurityGroup | Implemented |
| DeleteCacheSubnetGroup | Implemented |
| DeleteGlobalReplicationGroup | Not implemented |
| DeleteReplicationGroup | Implemented |
| DeleteServerlessCache | Implemented |
| DeleteServerlessCacheSnapshot | Not implemented |
| DeleteSnapshot | Not implemented |
| DeleteUser | Implemented |
| DeleteUserGroup | Implemented |
| DescribeCacheClusters | Implemented |
| DescribeCacheEngineVersions | Not implemented |
| DescribeCacheParameterGroups | Implemented |
| DescribeCacheParameters | Implemented |
| DescribeCacheSecurityGroups | Implemented |
| DescribeCacheSubnetGroups | Implemented |
| DescribeEngineDefaultParameters | Not implemented |
| DescribeEvents | Not implemented |
| DescribeGlobalReplicationGroups | Not implemented |
| DescribeReplicationGroups | Implemented |
| DescribeReservedCacheNodes | Not implemented |
| DescribeReservedCacheNodesOfferings | Not implemented |
| DescribeServerlessCacheSnapshots | Not implemented |
| DescribeServerlessCaches | Implemented |
| DescribeServiceUpdates | Not implemented |
| DescribeSnapshots | Not implemented |
| DescribeUpdateActions | Not implemented |
| DescribeUserGroups | Implemented |
| DescribeUsers | Implemented |
| DisassociateGlobalReplicationGroup | Not implemented |
| ExportServerlessCacheSnapshot | Not implemented |
| FailoverGlobalReplicationGroup | Not implemented |
| IncreaseNodeGroupsInGlobalReplicationGroup | Not implemented |
| IncreaseReplicaCount | Not implemented |
| ListAllowedNodeTypeModifications | Not implemented |
| ListTagsForResource | Implemented |
| ModifyCacheCluster | Implemented |
| ModifyCacheParameterGroup | Implemented |
| ModifyCacheSubnetGroup | Implemented |
| ModifyGlobalReplicationGroup | Not implemented |
| ModifyReplicationGroup | Implemented |
| ModifyReplicationGroupShardConfiguration | Not implemented |
| ModifyServerlessCache | Implemented |
| ModifyUser | Implemented |
| ModifyUserGroup | Implemented |
| PurchaseReservedCacheNodesOffering | Not implemented |
| RebalanceSlotsInGlobalReplicationGroup | Not implemented |
| RebootCacheCluster | Not implemented |
| RemoveTagsFromResource | Implemented |
| ResetCacheParameterGroup | Not implemented |
| RevokeCacheSecurityGroupIngress | Not implemented |
| StartMigration | Not implemented |
| TestFailover | Not implemented |
| TestMigration | Not implemented |