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:
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 theVALKEY_EXTRA_FLAGSenvironment variable. The image's own default arguments are replaced by these, and the image must accept them. CreateSnapshotrunsSAVE, readsCONFIG GET dirandCONFIG GET dbfilenameover 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.CreateReplicationGroupwithSnapshotNameplaces the snapshot file in the container's data directory (the image's working directory, which is where a server started without--dirkeeps its data) before the server starts, so the server loads it itself. NoDEBUGcommand is used and--enable-debug-commandis 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 withInvalidSnapshotState; 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, defaultdump.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 reportdbfilename. 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 dirandCONFIG GET dbfilename, write its snapshot to a file in its data directory and load a file of that name from there at startup (Floci checksdir, anddbfilenamewhen 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-NOPERMreplies 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.