Skip to content

ElastiCache

Protocol: Query (XML) for management API + Redis RESP protocol for data plane Management Endpoint: POST http://localhost:4566/ Data Endpoint: localhost:<proxy-port> (TCP)

Floci manages real Valkey/Redis Docker containers and proxies TCP connections to them. This means any Redis client works — including IAM authentication.

Encrypted cache connections

Redis/Valkey replication groups with transit encryption enabled take TLS at the advertised proxy endpoint. This includes groups using an AUTH token or IAM authentication, and a group remains encrypted when its last user group is removed. With TransitEncryptionMode set to preferred, the endpoint takes both TLS and unencrypted connections so clients can move to TLS; any other encrypted group takes TLS only. A modify that moves a preferred group to required closes its open unencrypted connections, as AWS does, and its TLS connections carry on. AWS adds new TLS endpoints while a group is preferred; Floci serves both kinds on the one endpoint. Serverless Redis/Valkey endpoints take TLS only. Unencrypted caches and Memcached retain their existing transport.

The cache listener uses a server certificate issued by Floci's shared local CA, including the default Floci endpoint names, IPv4 and IPv6 loopback, host.docker.internal, the floci.base-url host, and the configured Floci and cluster-announce hostnames. The listener renews its leaf certificate a minute before it expires, never past the CA's own expiry, while retaining the same trusted CA. Trust {persistent-path}/tls/floci-root-ca.crt or the CA from GET /_floci/ca.pem. The main HTTP listener's TLS setting does not disable cache transit encryption.

valkey-cli --tls --cacert ./floci-root-ca.crt -h localhost -p "$CACHE_PORT" \
  --user "$CACHE_USER" --askpass PING

TLS terminates in Floci's cache proxy; the Docker backend hop retains its existing transport. This does not add Memcached transit encryption.

User access strings

For Redis/Valkey replication groups, cluster-mode groups included, and serverless caches, the auth proxy applies each associated user's AccessString to a private backend ACL identity. Valkey enforces command, key and Pub/Sub channel permissions. Authenticating a subscribe-only user does not grant SET or FLUSHALL. The backend default account is disabled once RBAC is used, so another AUTH or HELLO AUTH cannot regain its unrestricted permissions.

Backend passwords are generated in memory separately from frontend passwords and IAM tokens. Even +@all users cannot manage ACLs or backend configuration, load modules, reconfigure replication, shut down the engine, or observe administrative commands through MONITOR or SLOWLOG. SYNC and PSYNC are also denied: replication streams can expose keys outside a user's permitted key patterns. SAVE, BGSAVE, BGREWRITEAOF, and MIGRATE are denied as well, preventing backend persistence operations and outbound key migrations. These restrictions protect private backend credentials and key boundaries. AWS lists these among its restricted cache commands.

In a cluster-mode group, each node has a proxy of its own, which applies the access string on that node when the user signs in there. A client that follows a MOVED redirect signs in to the other node's proxy, as it does on AWS. Sessions on a cluster node also cannot run the CLUSTER subcommands ElastiCache restricts, which change the cluster's topology, slots or failover state: ADDSLOTS, ADDSLOTSRANGE, BUMPEPOCH, DELSLOTS, DELSLOTSRANGE, FAILOVER, FLUSHSLOTS, FORGET, LINKS, MEET, REPLICATE, RESET, SAVECONFIG, SET-CONFIG-EPOCH and SETSLOT. Before the first node disables its default account, Floci gives every node a private replication user and sets masteruser and masterauth to it, so replication keeps authenticating. A cluster-mode group nobody signs in to with a user never gets that password, which its unrestricted sessions could otherwise read with CONFIG GET masterauth.

ModifyUser with AccessString or AppendAccessString is installed on the backend at once for every replication group, every node of a cluster-mode group and every serverless cache that holds the user, so it applies to connections that are already open. A change that cannot be installed, such as one with a selector, is logged and the open sessions keep their old permissions until the user authenticates again. Other changes, such as adding a user to a group or associating a user group with a cache, are installed on the next successful authentication; reconnect to apply them promptly. Revoked members' existing sessions are not proactively disconnected by this change. ACL selectors are rejected before backend changes: a selector can grant permissions independently of the root rules used to protect private backend credentials. Read-only ACL commands are also unavailable through these sessions.

Signing in again

A connection can send AUTH, or HELLO with AUTH, again after it has signed in, to refresh an IAM token or to switch to another user. The proxy checks those credentials as it does at sign-in, for caches with users and for caches with an AUTH token. Accepted credentials switch the connection to that user and its access string. Refused credentials get WRONGPASS and leave the connection signed in as before, as Valkey does. An AUTH or HELLO over 64 KiB, too large to check, is refused the same way. The client's password or token never reaches the backend: the proxy relays the command with the backend user's private credentials instead. A cache without authentication relays these commands to the engine as sent.

Supported Management Actions

Action Description
ValidateIamAuthToken Validate an IAM auth token (data-plane auth)
CreateReplicationGroup Start a new Redis/Valkey cluster; AtRestEncryptionEnabled, KmsKeyId (resolved to the key ARN), SnapshotRetentionLimit, SnapshotWindow, Tags and UserGroupIds are kept and returned, with the group ARN. UserGroupIds needs TransitEncryptionEnabled or an AuthToken
DescribeReplicationGroups List clusters and their connection info
ModifyReplicationGroup Modify SnapshotRetentionLimit and SnapshotWindow, and the associated user groups (UserGroupIdsToAdd, UserGroupIdsToRemove, RemoveUserGroups). A cache with user groups no longer takes its AUTH token, AuthTokenUpdateStrategy=DELETE removes the token when adding a user group, and removing the last user group leaves the cache without access control. Changing the AUTH token (ROTATE, SET) is not supported
IncreaseReplicaCount Raise a cluster-mode-disabled group's replicas to NewReplicaCount (up to 5), with ApplyImmediately=true. See Replicas and failover
DecreaseReplicaCount Lower a cluster-mode-disabled group's replicas to NewReplicaCount, with ApplyImmediately=true; ReplicasToRemove is not supported
TestFailover Promote the next member of node group 0001 of a cluster-mode-disabled group with automatic failover enabled
DeleteReplicationGroup Stop and remove a cluster
CreateUser Create a user with password, no-password-required or IAM authentication, set through AuthenticationMode or the top-level Passwords and NoPasswordRequired
DescribeUsers List ElastiCache users
ModifyUser Change a user's passwords and authentication mode, replace its access string with AccessString or add to it with AppendAccessString
DeleteUser Remove an ElastiCache user
CreateUserGroup Create a user group; a redis group must contain a user named default, a valkey group need not
DescribeUserGroups List user groups with their users and the replication groups and serverless caches using them
ModifyUserGroup Add or remove users, or change the engine; membership changes apply to authentication at once
DeleteUserGroup Remove a user group that no replication group or serverless cache uses
CreateCacheCluster Start a Memcached cluster, or a single-node Redis/Valkey one (NumCacheNodes must be 1)
CreateServerlessCache Create a local Valkey, Redis or Memcached runtime with serverless metadata
DescribeServerlessCaches List serverless caches, settings and endpoints
ModifyServerlessCache Update metadata and user-group association while retaining cache data
DeleteServerlessCache Delete serverless metadata and its backing runtime
DescribeCacheClusters List cache clusters: Memcached, single-node Redis/Valkey, and replication group members
DeleteCacheCluster Stop and remove a cache cluster
CreateCacheSubnetGroup Create a cache subnet group
DescribeCacheSubnetGroups List cache subnet groups
ModifyCacheSubnetGroup Replace a group's description or subnets
DeleteCacheSubnetGroup Delete a cache subnet group
CreateCacheParameterGroup Create a cache parameter group
DescribeCacheParameterGroups List parameter groups, including the AWS defaults
ModifyCacheParameterGroup Set parameters on a group
DescribeCacheParameters List the parameters set on a group
DeleteCacheParameterGroup Delete a cache parameter group
AddTagsToResource -
RemoveTagsFromResource -
ListTagsForResource Read stored tags for supported ElastiCache resource ARNs
CreateSnapshot Take a manual snapshot of a cluster-mode-disabled replication group, named by ReplicationGroupId or by one of its CacheClusterIds: the RDB file of its backend, available as soon as the call returns. See Snapshots
DescribeSnapshots List manual snapshots matching every one of SnapshotName, ReplicationGroupId, CacheClusterId and SnapshotSource, paged by MaxRecords and Marker
DeleteSnapshot Delete a snapshot and its RDB archive

Serverless caches and user groups

CreateServerlessCache, DescribeServerlessCaches, ModifyServerlessCache and DeleteServerlessCache use the native AWS Query protocol. Valkey and Redis caches reuse the existing single-node Valkey container and shared proxy port range. Memcached caches reuse the existing Memcached container runtime. Their internal backing clusters are hidden from ordinary cluster management APIs. Endpoint and ReaderEndpoint identify the same local runtime.

Every account has a built-in user with id and name default (no password, on ~* +@all) that cannot be modified or deleted; a custom user named default can take its place in a group. User groups support create, describe, modify and delete. Redis groups require a default user; Valkey groups can be empty and accept authenticated Redis or Valkey users. Caches read the current group membership and user credentials on each authentication. An attached empty group still requires authentication and grants no access. Removing UserGroupId through RemoveUserGroup allows anonymous connections. Attached groups cannot be deleted until their cache association is removed. IAM authentication validates tokens against the public serverless cache name.

Descriptions, security groups, usage limits, snapshot schedules and user-group associations can be modified without recreating the runtime or dropping cached values. Supplied subnets, security groups and KMS keys must exist in the caller's account and region; network resources must belong to one VPC. Names, settings, tags, owner account and runtime identity use the existing ElastiCache storage mode. Restart recovery reserves proxy ports and restores authentication and endpoints; the cache keyspace itself comes back empty, as for the other local cache runtimes.

Tags on a serverless cache are set at creation and are not editable afterwards, because AddTagsToResource and RemoveTagsFromResource are not implemented for ElastiCache.

Local serverless caches have fixed capacity and plaintext TCP endpoints. Usage limits, subnet and security-group placement, KMS encryption and snapshot schedules are metadata; they do not enable autoscaling, VPC networking, encryption or snapshot storage. Snapshot restore and final snapshots are rejected explicitly. Engine/version transitions are rejected; supported major versions are Valkey 8, Redis 7 and Memcached 1.6. With Docker unavailable, metadata operations still work and connections require a reachable Docker daemon and a runtime restart. Serverless snapshot APIs and serverless pagination are not implemented.

Single-node Redis/Valkey clusters

CreateCacheCluster serves three engines. Engine=memcached starts a Memcached container and reports its node-discovery ConfigurationEndpoint. Engine=redis or Engine=valkey starts a single-node cluster with no replication group: the same Valkey container and auth proxy a cluster-mode-disabled replication group gets, on a port from the same proxy range, which defaults to 6379. AWS allows only one node in that shape, so NumCacheNodes greater than 1 is refused with InvalidParameterValue, as it is on a live account.

This is the call aws_elasticache_cluster with engine = "redis" emits, which is why it is not interchangeable with CreateReplicationGroup: a single-node cluster created this way never appears in DescribeReplicationGroups. Following AWS, it carries no ConfigurationEndpoint either, and reports its node's address under CacheNodes when the request sets ShowCacheNodeInfo. These clusters are re-provisioned after a Floci restart, the same as replication groups and Memcached clusters.

An id is taken across all three at once: a standalone cache cluster, a Memcached cluster and a replication group cannot share one. Two of them would have DescribeCacheClusters report the same id twice, and for a cache cluster against a replication group it is worse, since Floci names both their containers valkey-<id> and keys both their proxies by it. Whichever create arrives second is refused, whether it is CreateCacheCluster or CreateReplicationGroup, rather than allowed to remove the first's container.

CacheSubnetGroupName must name a subnet group that exists, as on AWS, on the Engine=redis and Engine=valkey paths. Engine=memcached drops the parameter: it is neither checked nor echoed back. (CreateReplicationGroup does not check it either, so a replication group can still be created against a name nothing resolves.)

Each record re-reserves its proxy port as it is restored, before Floci serves anything, so a create is never handed a port a surviving cluster or replication group still advertises.

Port, when two caches ask for the same one

On AWS, Port belongs to a cache's own endpoint. 6379 is the Redis default, so nearly every ElastiCache cluster uses it and they coexist: each cache gets a DNS name of its own, and the port never has to tell them apart. Floci puts every cache's proxy on one host, where a TCP port is exclusive and the port is the only thing that does tell them apart.

This section is about Engine=redis and Engine=valkey, the engines Floci fronts with an auth proxy. Engine=memcached never reaches any of it: CreateCacheCluster routes that engine to a path the Port is not passed to, so a pinned port is silently ignored and the cluster reports the Docker-published port it is actually on. The safety property below holds there for a different reason, not because the rules do.

So a Port you pass is honored when it is free and inside FLOCI_SERVICES_ELASTICACHE_PROXY_BASE_PORT/_MAX_PORT, and otherwise the cache is served on another port from that range, which is the port its endpoint then reports. A create is never refused for a port that is merely taken: refusing the second cache on 6379 breaks any module standing up two Redis clusters, and any suite running one per test in parallel.

The port a cache reports is always the port it is actually on. If you pinned one Floci could not give you, the endpoint reports the substitute rather than the port you asked for, and the create logs a warning saying which and why. That is a visible difference: terraform treats the port as replacement-forcing, so a pinned port that was unavailable shows up as a diff on the next plan. It is deliberately preferred to the alternative, where a cache reports the port you pinned while listening somewhere else, because that endpoint names a different cache's listener and a client following it reads the wrong cache's data with no error.

The only port rejection left is a range check: Port must be between 1150 and 65535. That bound is the one RdsService.reserveProxyPort applies to the same argument, not a measurement of ElastiCache's own limit, which nothing here establishes. It is strictly more permissive than the proxy-range check it replaced, so the direction it could be wrong in is accepting a port AWS would refuse, never refusing one AWS accepts.

SnapshotRetentionLimit, SnapshotWindow, PreferredMaintenanceWindow, PreferredAvailabilityZone, SecurityGroupIds, NetworkType, IpDiscovery and AtRestEncryptionEnabled (output-only on real AWS's CreateCacheCluster; accepted here leniently and echoed) are kept and echoed by DescribeCacheClusters, with the same defaults and the same validation the replication group applies, since every one is an optional aws_elasticache_cluster argument that would otherwise read back unset and leave a permanent plan diff. NotificationConfiguration and LogDeliveryConfigurations are not modelled: a request may send them, and the describe will not report them back.

Cluster Mode

SecurityGroupIds supplied to CreateReplicationGroup are stored with the group and returned on every member by DescribeCacheClusters as SecurityGroups memberships with Status=active. This includes shards and replicas in cluster mode. Groups without stored IDs return no memberships. ModifyReplicationGroup accepts SecurityGroupIds and replaces the whole stored list, on the group and every member; a modify that names none leaves the memberships untouched. The IDs are control-plane metadata, not network rules applied to the backing cache containers.

CreateReplicationGroup provisions a real sharded Valkey cluster when the request asks for one: NumNodeGroups greater than 1, a default.*.cluster.on parameter group, a custom parameter group with cluster-enabled set to yes, or ClusterMode=enabled.

Floci starts one --cluster-enabled container per node — NumNodeGroups × (1 + ReplicasPerNodeGroup) in total — forms the cluster (config epochs, MEET, slot assignment, replica attachment), and fronts each node with its own auth-proxy port from the proxy port range. Nodes announce Floci's configured hostname as their preferred endpoint (cluster-announce-hostname with cluster-preferred-endpoint-type hostname, plus cluster-announce-client-ipv4/ cluster-announce-port), so CLUSTER SLOTS, CLUSTER SHARDS and MOVED/ASK redirects hand clients the same name the ConfigurationEndpoint reports, while the cluster bus keeps using the container network. Any cluster-aware Redis/Valkey client works against the reported ConfigurationEndpoint.

Because clients must resolve the announced name to follow redirects, a FLOCI_HOSTNAME that only resolves inside Floci's Docker network (such as the Compose service name floci) breaks cluster-aware clients connecting from outside it. Set FLOCI_SERVICES_ELASTICACHE_CLUSTER_ANNOUNCE_HOSTNAME to a universally resolvable name in that case — the shipped docker-compose.yml uses localhost.floci.io, which public DNS resolves to 127.0.0.1 on the host (reaching the published proxy ports) while the Compose network alias and Floci's embedded DNS resolve it to the Floci container from inside Docker. Cluster-mode groups then announce that name and report it as their ConfigurationEndpoint.

With persistent, hybrid or wal storage, every replication group, standalone cache cluster and Memcached cluster is re-provisioned from its persisted record on startup: containers are restarted, cluster-mode groups are re-formed, and proxy ports are re-reserved. Caches restart empty, as on any Floci restart: only the topology is persisted, never the keyspace.

Ports are re-reserved and records marked creating before Floci reports ready; the container restarts and cluster formation run in the background so a slow Docker daemon cannot delay readiness, and each record flips to available once its data plane is back. A replication group whose data plane cannot be brought back is reported with status create-failed instead of available, and its member clusters answer DescribeCacheClusters with restore-failed (CacheClusterStatus has no create-failed value). A standalone cache cluster or Memcached cluster that cannot be brought back reports restore-failed directly.

Reporting a failed record as failed matters more than it looks. A record that is left unreconciled keeps its available status with nothing behind the endpoint, so the control plane answers healthy while every connection fails, and the proxy port it still advertises is free for the next create to take: the old endpoint then reaches an unrelated cache rather than failing cleanly.

A Memcached cluster's endpoint follows its new container. Outside Docker, Floci publishes the backend on a host port Docker picks per run, so a restored cluster's ConfigurationEndpoint port can differ from the one it had before the restart. Replication groups and standalone cache clusters keep their port: it is a proxy port Floci owns and re-reserves.

A delete that arrives while a record is still creating wins. The restore takes the same per-record monitor DeleteReplicationGroup and DeleteCacheCluster take, and skips its write-back when the record is gone, so a group or cluster deleted in the first seconds after boot stays deleted rather than coming back available. Any container the abandoned restore had already started is stopped.

DescribeReplicationGroups reports the topology honestly: ClusterEnabled, one NodeGroup per shard with its Slots, NodeGroupMembers, and MemberClusters. Each member also answers DescribeCacheClusters (as on AWS), which is what terraform-provider-aws reads node type, engine version and port from.

Cluster mode requires a Valkey 8.1+ image (the default valkey/valkey:8 qualifies) for cluster-announce-client-ipv4 support. Each node consumes one port from the proxy range, so size FLOCI_SERVICES_ELASTICACHE_PROXY_BASE_PORT/_MAX_PORT to the number of nodes you need.

aws elasticache create-replication-group \
  --replication-group-id my-sharded-cache \
  --replication-group-description "Sharded dev cache" \
  --engine valkey \
  --cache-parameter-group-name default.valkey8.cluster.on \
  --num-node-groups 2 \
  --replicas-per-node-group 1 \
  --endpoint-url $AWS_ENDPOINT_URL

aws elasticache describe-replication-groups \
  --replication-group-id my-sharded-cache \
  --query 'ReplicationGroups[0].ConfigurationEndpoint' \
  --endpoint-url $AWS_ENDPOINT_URL

redis-cli -c -h localhost -p <configuration-endpoint-port> set mykey "hello"

Cache Subnet Groups

A subnet group's VPC and each subnet's availability zone are read from the subnets themselves, as AWS reads them, so the subnets have to exist in the emulator's EC2 first. Subnets that are unknown, or that span more than one VPC, are refused the way AWS refuses them.

Cache Parameter Groups

The default.* groups AWS publishes are listed for every family it supports, and cannot be modified or deleted — AWS refuses those by the identifier rule, since a name it accepts cannot contain a dot.

floci does not carry AWS's per-family catalogue of parameter names, which runs to dozens per family. It therefore stores whatever parameters a caller sets and reports them with source user, rather than rejecting names a partial catalogue happens to be missing, which would refuse configurations AWS accepts. DescribeCacheParameters returns those parameters; a request for system or engine-default parameters returns none, and listings are unpaged.

A replication group that names a parameter group is refused with CacheParameterGroupNotFound when no such group exists, and a parameter group still referenced by a replication group cannot be deleted: DeleteCacheParameterGroup answers InvalidCacheParameterGroupState until that replication group is gone. The reference counts from the moment CreateReplicationGroup accepts the name, not from when the group is stored, so a delete that lands while that create is still provisioning its container is refused too.

Replicas and failover

The members of a cluster-mode-disabled replication group share one backend, so a replica is a member cache cluster the group reports (MemberClusters, NodeGroupMembers), not a second server. IncreaseReplicaCount and DecreaseReplicaCount change the members at once, so ApplyImmediately must be true (AWS does not support false either), between 0 and 5 replicas, and at least one while Multi-AZ is enabled. New members take the next numbers, and a decrease removes the highest-numbered replicas, never the primary. TestFailover with NodeGroupId 0001 makes the next member the primary and the old primary a replica, as each CurrentRole then reports; the data and the endpoints stay as they are. It needs automatic failover enabled and at least one replica. Cluster-mode-enabled groups are refused with InvalidParameterValue.

Snapshots

CreateSnapshot saves the backend's dataset (SAVE) and keeps the RDB file with the snapshot record, so the snapshot is available when the call returns; a SAVE the server refuses, as it does while another save runs, fails the call with InvalidReplicationGroupState. CreateReplicationGroup with SnapshotName starts a new cluster-mode-disabled group and loads that file into its backend before the group is listed or its endpoint accepts connections; a group the file could not be loaded into is rolled back like any failed create. A snapshot whose file is missing is refused with InvalidSnapshotState before any group is created. A group cannot be deleted or modified while its snapshot is being taken, and a CacheClusterId given with a ReplicationGroupId must be one of that group's members. CreateSnapshot keeps its Tags, which ListTagsForResource, AddTagsToResource and RemoveTagsFromResource read and change through the snapshot's ARN. DescribeSnapshots returns snapshots in name order, MaxRecords (20 to 50, default 50) at a time, with a Marker for the next page.

Snapshots outlive the group they were taken from, as on AWS. They are taken of cluster-mode-disabled replication groups only: a cluster-mode-enabled group, a standalone cache cluster or a group without a running backend is refused, as is seeding a cluster-mode-enabled group. Automatic snapshots, CopySnapshot and FinalSnapshotIdentifier are not modeled. To reload the dataset, the backend runs with --enable-debug-command local, which allows DEBUG only for connections from inside its own container; clients always connect through the proxy. With shell-less-backend the snapshot file is placed before the server starts instead, and DEBUG is not enabled.

Engine version and backend image

EngineVersion is control-plane metadata. For Redis/Valkey replication groups and standalone cache clusters, Floci starts the image configured by floci.services.elasticache.default-image (FLOCI_SERVICES_ELASTICACHE_DEFAULT_IMAGE), whose default is valkey/valkey:8. The requested version does not select the image. For example, a request with Engine=valkey and EngineVersion=7.2 can describe itself as 7.2 while HELLO 2 or INFO server reports the Valkey 8 version in that image. Redis compatibility version fields can differ from the native Valkey version.

To test with Valkey 7.2, configure the backend image before creating the cache:

FLOCI_SERVICES_ELASTICACHE_DEFAULT_IMAGE=valkey/valkey:7.2

This setting applies to every Redis/Valkey cache in that Floci process, including cluster-mode nodes. Restoring persisted runtimes after a Floci restart uses the current image setting too. Use separate Floci instances when tests require different backend versions, and select a patch tag or digest when an exact build is required. Changing EngineVersion alone does not upgrade or downgrade a running backend. Check INFO server (including valkey_version for Valkey) to verify the running build; describe responses report the stored request metadata.

Memcached uses the separate floci.services.elasticache.default-memcached-image (FLOCI_SERVICES_ELASTICACHE_DEFAULT_MEMCACHED_IMAGE) setting, default memcached:1.6.

Images with no shell or CLI

By default Floci starts the backend through the image's VALKEY_EXTRA_FLAGS hook and takes and restores snapshots with the valkey-cli or redis-cli inside the container, which only images built like valkey/valkey provide. An image that has no shell and no CLI, such as a distroless Redis-compatible image, needs the other path, which is selected by floci.services.elasticache.shell-less-backend (FLOCI_SERVICES_ELASTICACHE_SHELL_LESS_BACKEND). It is false by default and is never inferred from the image name, so which path runs is always the one you configured. MemoryDB is not affected by it.

With shell-less-backend set to true:

  • The server flags are passed as container arguments (--port 6379 --protected-mode no --loglevel verbose, plus the cluster-mode flags for a cluster-mode group) instead of the VALKEY_EXTRA_FLAGS environment variable. The image's own default arguments are replaced by these, and the image must accept them.
  • CreateSnapshot runs SAVE, reads CONFIG GET dir and CONFIG GET dbfilename over the RESP connection to the backend, and copies the file out of the container through the Docker archive API. No command is executed inside the container.
  • CreateReplicationGroup with SnapshotName places the snapshot file in the container's data directory (the image's working directory, which is where a server started without --dir keeps its data) before the server starts, so the server loads it itself. No DEBUG command is used and --enable-debug-command is not passed. If the file cannot be placed, or the server cannot start with it, the new group's container is removed and the create fails with InvalidSnapshotState; the group the snapshot came from and the snapshot are not touched.
  • floci.services.elasticache.shell-less-backend-dbfilename (FLOCI_SERVICES_ELASTICACHE_SHELL_LESS_BACKEND_DBFILENAME, default dump.rdb) names the file the server loads from its data directory at startup. A restore places the snapshot under this name, and a snapshot falls back to it when the server does not report dbfilename. Set it to the name your image's server uses.

An image used this way has to:

  • accept the server flags above as arguments, including the cluster-mode flags (--cluster-enabled, --cluster-announce-*) for a cluster-mode group;
  • answer SAVE, CONFIG GET dir and CONFIG GET dbfilename, write its snapshot to a file in its data directory and load a file of that name from there at startup (Floci checks dir, and dbfilename when the server reports one, after a restore);
  • support ACL users with access strings (ACL SETUSER, AUTH), because the proxy enforces user groups through the backend's ACL and passes the backend's -NOPERM replies on to the client. An image without ACL support works only for groups with no user group.

The backend's port is published the way it is for the default image, so the container is reached only through the proxy in the usual setup. A snapshot of a group that has user groups, taken once a user has connected, is refused because Floci's own connection to the backend is not authenticated; the default path has the same limit.

For example, with the KiviDB image, whose server keeps its snapshot as dump.kdb:

FLOCI_SERVICES_ELASTICACHE_DEFAULT_IMAGE=ghcr.io/kividbio/kividb:v1.2.2
FLOCI_SERVICES_ELASTICACHE_SHELL_LESS_BACKEND=true
FLOCI_SERVICES_ELASTICACHE_SHELL_LESS_BACKEND_DBFILENAME=dump.kdb

A snapshot is a file in the server's own format, so it restores into a backend of the same kind: do not restore a snapshot taken from one engine into another.

Configuration

Variable Default Description
FLOCI_SERVICES_ELASTICACHE_ENABLED true Enable or disable the service
FLOCI_SERVICES_ELASTICACHE_PROXY_BASE_PORT 6379 First host port in the ElastiCache proxy range
FLOCI_SERVICES_ELASTICACHE_PROXY_MAX_PORT 6399 Last host port in the ElastiCache proxy range
FLOCI_SERVICES_ELASTICACHE_DEFAULT_IMAGE valkey/valkey:8 Docker image for Redis/Valkey containers
FLOCI_SERVICES_ELASTICACHE_SHELL_LESS_BACKEND false Start and snapshot the backend for an image with no shell or CLI: see above
FLOCI_SERVICES_ELASTICACHE_SHELL_LESS_BACKEND_DBFILENAME dump.rdb Snapshot file name the server loads at startup, used with the setting above

Docker Compose

ElastiCache requires the Docker socket and port range exposure. For private registry authentication and other Docker settings see Docker Configuration.

services:
  floci:
    image: floci/floci:latest
    ports:
      - "4566:4566"
      - "6379-6399:6379-6399"   # ElastiCache proxy ports
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      FLOCI_SERVICES_DOCKER_NETWORK: my-project_default

Examples

export AWS_ENDPOINT_URL=http://localhost:4566

# Create a replication group (starts a Valkey container)
aws elasticache create-replication-group \
  --replication-group-id my-cache \
  --replication-group-description "Dev cache" \
  --endpoint-url $AWS_ENDPOINT_URL

# Get the connection port
PORT=$(aws elasticache describe-replication-groups \
  --replication-group-id my-cache \
  --query 'ReplicationGroups[0].NodeGroups[0].PrimaryEndpoint.Port' \
  --output text \
  --endpoint-url $AWS_ENDPOINT_URL)

# Connect with redis-cli
redis-cli -h localhost -p $PORT ping

# Use from your application
redis-cli -h localhost -p $PORT set mykey "hello"
redis-cli -h localhost -p $PORT get mykey

# Delete the cluster
aws elasticache delete-replication-group \
  --replication-group-id my-cache \
  --endpoint-url $AWS_ENDPOINT_URL

IAM Authentication

Floci supports ElastiCache IAM auth token validation. Create a user with access strings and validate tokens the same way real ElastiCache RBAC works.

# Create an ElastiCache user
aws elasticache create-user \
  --user-id alice \
  --user-name alice \
  --engine redis \
  --access-string "on ~* +@all" \
  --no-no-password-required \
  --endpoint-url $AWS_ENDPOINT_URL

IAM connection lifetime and transactions

As on AWS, a connection signed in with an IAM token is closed 12 hours after it signed in. Sending AUTH or HELLO with a new token gives it another 12 hours, and signing in again as a user without IAM ends the limit.

IAM re-authentication is not supported inside MULTI/EXEC. An AUTH or HELLO for an IAM user inside a transaction is refused with ERR Command not allowed inside a transaction, and EXEC then aborts the transaction with EXECABORT. AWS does not document its reply, so this one is Floci's reading. An image older than Valkey 8 refuses it with ERR MULTI calls can not be nested instead, and runs the rest of the transaction. Another user's AUTH inside a transaction is queued and runs with EXEC, as in Valkey. It leaves the 12 hours as they were, since Floci cannot see whether EXEC runs it. Lua scripts cannot send AUTH or HELLO at all: the engine refuses both from a script.

Transit encryption mode metadata

An explicit TransitEncryptionMode (preferred or required) on a replication group is persisted and returned by create, modify and describe responses, including the member entries in DescribeCacheClusters. An unrelated modification preserves it. This is control-plane metadata; it does not establish data-plane TLS or plaintext rejection. Legacy records and requests that omit the mode do not acquire an invented value.