Redis

Envoy can act as a Redis proxy, partitioning commands among instances in a cluster. In this mode, the goals of Envoy are to maintain availability and partition tolerance over consistency. This is the key point when comparing Envoy to Redis Cluster. Envoy is designed as a best-effort cache, meaning that it will not try to reconcile inconsistent data or keep a globally consistent view of cluster membership.

The Redis project offers a thorough reference on partitioning as it relates to Redis. See “Partitioning: how to split data among multiple Redis instances”.

Features of Envoy Redis:

  • Redis protocol codec.
  • Hash-based partitioning.
  • Ketama distribution.
  • Detailed command statistics.
  • Active and passive healthchecking.

Planned future enhancements:

  • Additional timing stats.
  • Circuit breaking.
  • Request collapsing for fragmented commands.
  • Replication.
  • Built-in retry.
  • Tracing.
  • Hash tagging.

Configuration

For filter configuration details, see the Redis proxy filter configuration reference.

The corresponding cluster definition should be configured with ring hash load balancing.

If active health checking is desired, the cluster should be configured with a custom health check which configured as a Redis health checker.

If passive healthchecking is desired, also configure outlier detection.

For the purposes of passive healthchecking, connect timeouts, command timeouts, and connection close map to 5xx. All other responses from Redis are counted as a success.

Supported commands

At the protocol level, pipelines are supported. MULTI (transaction block) is not. Use pipelining wherever possible for the best performance.

At the command level, Envoy only supports commands that can be reliably hashed to a server. PING is the only exception, which Envoy responds to immediately with PONG. Arguments to PING are not allowed. All other supported commands must contain a key. Supported commands are functionally identical to the original Redis command except possibly in failure scenarios.

For details on each command’s usage see the official Redis command reference.

CommandGroup
PINGConnection
DELGeneric
DUMPGeneric
EXISTSGeneric
EXPIREGeneric
EXPIREATGeneric
PERSISTGeneric
PEXPIREGeneric
PEXPIREATGeneric
PTTLGeneric
RESTOREGeneric
TOUCHGeneric
TTLGeneric
TYPEGeneric
UNLINKGeneric
GEOADDGeo
GEODISTGeo
GEOHASHGeo
GEOPOSGeo
GEORADIUS_ROGeo
GEORADIUSBYMEMBER_ROGeo
HDELHash
HEXISTSHash
HGETHash
HGETALLHash
HINCRBYHash
HINCRBYFLOATHash
HKEYSHash
HLENHash
HMGETHash
HMSETHash
HSCANHash
HSETHash
HSETNXHash
HSTRLENHash
HVALSHash
LINDEXList
LINSERTList
LLENList
LPOPList
LPUSHList
LPUSHXList
LRANGEList
LREMList
LSETList
LTRIMList
RPOPList
RPUSHList
RPUSHXList
EVALScripting
EVALSHAScripting
SADDSet
SCARDSet
SISMEMBERSet
SMEMBERSSet
SPOPSet
SRANDMEMBERSet
SREMSet
SSCANSet
ZADDSorted Set
ZCARDSorted Set
ZCOUNTSorted Set
ZINCRBYSorted Set
ZLEXCOUNTSorted Set
ZRANGESorted Set
ZRANGEBYLEXSorted Set
ZRANGEBYSCORESorted Set
ZRANKSorted Set
ZREMSorted Set
ZREMRANGEBYLEXSorted Set
ZREMRANGEBYRANKSorted Set
ZREMRANGEBYSCORESorted Set
ZREVRANGESorted Set
ZREVRANGEBYLEXSorted Set
ZREVRANGEBYSCORESorted Set
ZREVRANKSorted Set
ZSCANSorted Set
ZSCORESorted Set
APPENDString
BITCOUNTString
BITFIELDString
BITPOSString
DECRString
DECRBYString
GETString
GETBITString
GETRANGEString
GETSETString
INCRString
INCRBYString
INCRBYFLOATString
MGETString
MSETString
PSETEXString
SETString
SETBITString
SETEXString
SETNXString
SETRANGEString
STRLENString

Failure modes

If Redis throws an error, we pass that error along as the response to the command. Envoy treats a response from Redis with the error datatype as a normal response and passes it through to the caller.

Envoy can also generate its own errors in response to the client.

ErrorMeaning
no upstream hostThe ring hash load balancer did not have a healthy host available at the ring position chosen for the key.
upstream failureThe backend did not respond within the timeout period or closed the connection.
invalid requestCommand was rejected by the first stage of the command splitter due to datatype or length.
unsupported commandThe command was not recognized by Envoy and therefore cannot be serviced because it cannot be hashed to a backend server.
finished with n errorsFragmented commands which sum the response (e.g. DEL) will return the total number of errors received if any were received.
upstream protocol errorA fragmented command received an unexpected datatype or a backend responded with a response that not conform to the Redis protocol.
wrong number of arguments for commandCertain commands check in Envoy that the number of arguments is correct.

In the case of MGET, each individual key that cannot be fetched will generate an error response. For example, if we fetch five keys and two of the keys’ backends time out, we would get an error response for each in place of the value.

  1. $ redis-cli MGET a b c d e
  2. 1) "alpha"
  3. 2) "bravo"
  4. 3) (error) upstream failure
  5. 4) (error) upstream failure
  6. 5) "echo"