Azure Cache for Redis
Compatible with the azure-mgmt-redis SDK, the az redis CLI, Terraform's azurerm_redis_cache,
and any ARM-speaking client for the management plane: plus any standard Redis client
(redis-py, StackExchange.Redis, Jedis, redis-cli, …) for the data plane.
Real sidecar (default). With
mocked=false(the default), each cache is backed by a real container (valkey/valkey:8-alpine: a drop-in, RESP-compatible Redis fork) that clients connect to with the Redis protocol. Unit-test profiles forcemocked=true(management plane only, no Docker).
Features
- Lifecycle: CreateOrUpdate, Get, Delete, Patch (tags / config), List (by subscription and by resource group)
- Access keys:
listKeysandregenerateKey; the create response embedsproperties.accessKeys - Real data plane: a Redis container per cache; the primary access key is the Redis password
(
--requirepass), and both the primary and secondary key authenticate via a Redis ACL on thedefaultuser - TLS on the SSL port (opt-in): with
FLOCI_AZ_SERVICES_REDIS_TLS_ENABLED=true, each cache also serves TLS onsslPort, so the connection strings Azure tooling builds ({hostName}:{sslPort},password=...,ssl=True, as azurerm'sprimary_connection_string) connect as they are. See TLS - Async provisioning: non-mocked caches start as
provisioningState=Creatingand flip toSucceededonce the container answersPING; mocked caches returnSucceededimmediately
Endpoints
All management operations use ARM paths:
PUT /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Cache/redis/{name}
GET /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Cache/redis/{name}
PATCH /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Cache/redis/{name}
DELETE /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Cache/redis/{name}
POST .../redis/{name}/listKeys
POST .../redis/{name}/regenerateKey # body: {"keyType":"Primary"|"Secondary"}
GET /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Cache/redis
GET /subscriptions/{sub}/providers/Microsoft.Cache/redis
POST /subscriptions/{sub}/providers/Microsoft.Cache/checkNameAvailability # body: {"name", "type"}
A cache name is a global DNS name: the first subscription to create it owns it in its cloud, and another
subscription's create is 409 NameNotAvailable until the owner deletes it. checkNameAvailability answers 200
with no body for a free name and the same 409 NameNotAvailable for a taken one; Azure's answer for a taken name
is not recorded, so that one is an emulator choice.
Quickstart
1: Create a cache
curl -s -X PUT \
"http://localhost:4577/subscriptions/my-sub/resourceGroups/my-rg/providers/Microsoft.Cache/redis/my-cache?api-version=2024-11-01" \
-H "Content-Type: application/json" \
-d '{
"location": "eastus",
"properties": {
"sku": {"name": "Basic", "family": "C", "capacity": 0},
"enableNonSslPort": true,
"minimumTlsVersion": "1.2"
}
}'
The response contains the connection details and keys:
{
"name": "my-cache",
"type": "Microsoft.Cache/Redis",
"properties": {
"provisioningState": "Succeeded",
"hostName": "localhost",
"port": 6379,
"sslPort": 6380,
"accessKeys": {"primaryKey": "…", "secondaryKey": "…"}
}
}
With floci-az running on the host, port is the host port published for the container's 6379,
taken from the configured range; the values above are what a cache reports when floci-az itself
runs in Docker. sslPort is 6380 unless TLS is enabled.
2: Connect with a Redis client
import redis
client = redis.Redis(host="localhost", port=6379, password="<primaryKey>")
client.set("greeting", "hello")
print(client.get("greeting")) # b'hello'
3: Rotate a key
curl -s -X POST \
"http://localhost:4577/subscriptions/my-sub/resourceGroups/my-rg/providers/Microsoft.Cache/redis/my-cache/regenerateKey?api-version=2024-11-01" \
-H "Content-Type: application/json" -d '{"keyType":"Primary"}'
In non-mocked mode the new key is applied to the running container immediately (no restart).
TLS
TLS is opt-in. By default a cache serves plain RESP on port only, and sslPort is reported as
6380 but not served. Enable it with:
or floci-az.services.redis.tls-enabled: true in application.yml. Each cache then also serves
TLS on the container's 6380, and:
- Two host ports per cache. The TLS port is published on a second host port from the same
range as the plain one (
base-porttomax-port), andsslPortreports it (the container port6380when floci-az runs in Docker). The default range of 21 ports fits 10 caches instead of 21; widen it withFLOCI_AZ_SERVICES_REDIS_MAX_PORTif you need more. enableNonSslPortdefaults tofalse, the Azure default, when a create omits it. Without TLS it defaults totrue, since the plain port is then the only one served. The plain port is served either way.
Connect over TLS on sslPort, as Azure clients do by default:
import redis
client = redis.Redis(host="localhost", port=<sslPort>, password="<primaryKey>",
ssl=True, ssl_ca_certs="floci-az-redis-ca.crt")
print(client.ping()) # True
redis-cli -h localhost -p <sslPort> -a "<primaryKey>" --tls --cacert floci-az-redis-ca.crt ping # PONG
The SSL port is trusted the same way as floci-az's own HTTPS endpoint:
-
floci-az TLS on (
FLOCI_AZ_TLS_ENABLED=true): the cache's certificate is issued by the CA thatGET /_floci/tls-certserves, for the cache's Azure host name ({name}.redis.cache.windows.net, or{name}.redis.cache.usgovcloudapi.netinAzureUSGovernment),localhost,127.0.0.1andhost.docker.internal. Trust that CA once and both the HTTPS endpoint and every cache verify:Issuing those certificates needs the CA's private key, which floci-az keeps next to the CA (
tls/floci-az-selfsigned-ca.keyunder the persistent path, owner-only). The CA's name constraints limit it to the names floci-az serves, which is why the certificate names Azure's host name and not the container's. With a CA of your own (FLOCI_AZ_TLS_CA_CERT_PATHandFLOCI_AZ_TLS_CA_KEY_PATH, see Use a CA you already trust), the cache certificates are issued from that CA instead. With a certificate of your own (FLOCI_AZ_TLS_CERT_PATHandFLOCI_AZ_TLS_KEY_PATH) the caches serve it unchanged, and with a CA written by an older floci-az, which kept no key, they serve the emulator's own certificate until the CA is next replaced. -
floci-az TLS off (the default): floci-az generates a CA in memory when it starts and issues each cache's certificate from it. Nothing is written to disk, and the CA changes on every restart. Copy it out of any cache container:
Or skip verification in the client (
ssl_cert_reqs="none"in redis-py), which is whatredis-cli --tls --insecuredoes.
minimumTlsVersion is accepted and echoed but not enforced; the container accepts TLS 1.2 and 1.3.
Configuration
floci-az:
services:
redis:
enabled: true
mocked: false # false (default) = real cache container per cache. true = no Docker, management plane only
default-image: "valkey/valkey:8-alpine"
base-port: 6379 # host port range start for cache containers
max-port: 6399 # host port range end
max-memory: "256mb" # per-instance maxmemory
tls-enabled: false # true = also serve TLS on sslPort (a second host port per cache)
| Env var | Default | Description |
|---|---|---|
FLOCI_AZ_SERVICES_REDIS_ENABLED |
true |
Enable/disable the service |
FLOCI_AZ_SERVICES_REDIS_MOCKED |
false |
Mocked mode (management plane only, no Docker) |
FLOCI_AZ_SERVICES_REDIS_DEFAULT_IMAGE |
valkey/valkey:8-alpine |
Cache container image (RESP-compatible) |
FLOCI_AZ_SERVICES_REDIS_BASE_PORT |
6379 |
Host port range start (each cache takes one port, two with TLS enabled) |
FLOCI_AZ_SERVICES_REDIS_MAX_PORT |
6399 |
Host port range end |
FLOCI_AZ_SERVICES_REDIS_MAX_MEMORY |
256mb |
Per-instance maxmemory |
FLOCI_AZ_SERVICES_REDIS_TLS_ENABLED |
false |
Serve TLS on sslPort (see TLS) |
Notes & limitations
- Endpoint resolution.
hostNamereturns a host clients can actually reach:localhostnatively, the Docker daemon's address in published mode, and Azure's own host name in the cache's cloud ({name}.redis.cache.windows.net,{name}.redis.cache.usgovcloudapi.netinAzureUSGovernment) when floci-az itself runs in Docker on a user-defined network, where the cache container answers to that name as a network alias. Cache names are unique per cloud, so two clouds' caches of one name never share an alias. WithFLOCI_AZ_DOCKER_RESOURCE_NAMESPACEset, the namespace goes between the name and the suffix ({name}.{namespace}.redis.cache.windows.net), so two emulator instances sharing a Docker network never answer to the same name. On the default bridge, which resolves no names, it stays the container name, and so it does inAzureChinaCloud, whose Redis suffix the cloud catalog does not record yet; there the cache certificate names onlylocalhost,127.0.0.1andhost.docker.internal.portis the host port allocated from the range for the container's6379(the container port itself when floci-az runs in Docker). - SSL port only with TLS enabled. By default
sslPort(6380) is reported for API fidelity but nothing serves it: connect over the non-SSL port, or enable TLS. - The plain port is always served.
enableNonSslPortis stored and reported, but the plain port stays open either way so existing plain-text clients keep working. - Single node. Clustering (
shardCount), geo-replication, private endpoints, firewall rules, and patch schedules are accepted on the management plane but not enforced. - Mocked mode returns
hostName=localhostwith no backing container: useful for provisioning tests, but data-plane connections will fail.