ElastiCache Clusters

With Docker enabled, ElastiCache clusters run real cache servers. You can connect with redis-cli, any Redis client library, or Memcached clients.

Prerequisites

  • SIMFRA_DOCKER=true
  • Docker images are pulled automatically on first use

Supported Engines

Engine Default Image Default Port
redis redis:7 6379
valkey valkey/valkey:8 6379
memcached memcached:1.6 11211

Override images with SIMFRA_ELASTICACHE_IMAGE_REDIS, SIMFRA_ELASTICACHE_IMAGE_VALKEY, or SIMFRA_ELASTICACHE_IMAGE_MEMCACHED.

Creating a Cluster

Redis / Valkey

aws --endpoint-url http://localhost:4599 elasticache create-cache-cluster \
  --cache-cluster-id my-cache \
  --engine redis \
  --cache-node-type cache.t3.micro \
  --num-cache-nodes 1

Memcached

aws --endpoint-url http://localhost:4599 elasticache create-cache-cluster \
  --cache-cluster-id my-memcached \
  --engine memcached \
  --cache-node-type cache.t3.micro \
  --num-cache-nodes 1

The cluster starts in creating state and transitions to available once the container is running and the cache engine is ready.

Connecting to the Cache

ElastiCache clusters are always private - they do not publish ports to the host. This matches real AWS, where ElastiCache is only accessible from within the VPC.

From Lambda or ECS

Lambda functions and ECS tasks on the same VPC network can use the ElastiCache endpoint DNS name directly. Simfra DNS resolves it to the container IP:

import redis
r = redis.Redis(host='my-cache.abcdef.0001.use1.cache.simfra.dev', port=6379)
r.set('key', 'value')

Port Forwarding from Host

To connect from the host for debugging or development:

curl -X POST http://localhost:4599/_simfra/port-forwards \
  -d '{"targetArn":"arn:aws:elasticache:us-east-1:000000000000:cluster:my-cache","targetPort":6379}'

Response:

{
  "id": "pf-abc123",
  "localPort": 11800,
  "targetPort": 6379
}

Then connect:

redis-cli -h localhost -p 11800

To clean up:

curl -X DELETE http://localhost:4599/_simfra/port-forwards/pf-abc123

Replication Groups

For Redis/Valkey replication groups with multiple nodes:

aws --endpoint-url http://localhost:4599 elasticache create-replication-group \
  --replication-group-id my-repl-group \
  --replication-group-description "My replication group" \
  --engine redis \
  --cache-node-type cache.t3.micro \
  --num-cache-clusters 2

This creates a primary node and one replica, each backed by a separate Docker container. The primary endpoint and reader endpoint resolve to the appropriate containers.

AUTH Tokens

Redis/Valkey clusters support AUTH tokens for authentication:

aws --endpoint-url http://localhost:4599 elasticache create-cache-cluster \
  --cache-cluster-id my-secure-cache \
  --engine redis \
  --cache-node-type cache.t3.micro \
  --num-cache-nodes 1 \
  --auth-token my-secret-token \
  --transit-encryption-enabled

The AUTH token is passed to the Redis container. Clients must authenticate:

redis-cli -h localhost -p 11800 --pass my-secret-token

Serverless Caches

ElastiCache Serverless caches are also supported:

aws --endpoint-url http://localhost:4599 elasticache create-serverless-cache \
  --serverless-cache-name my-serverless \
  --engine redis

State Machine

Operation States
Create creating -> available
Delete deleting -> (removed)
Modify modifying -> available
Reboot rebooting -> available

Cross-Service Integration

  • Lambda and ECS containers access ElastiCache by endpoint DNS name within the VPC.
  • CloudWatch: clusters emit metrics (CurrConnections, BytesUsedForCache, etc.).
  • EventBridge: state changes emit events.
  • KMS: encryption at rest is validated when a KMS key is specified.

Next Steps