Redis Proxy (proto)
This extension has the qualified name envoy.filters.network.redis_proxy
Note
This extension is not hardened and should only be used in deployments where both the downstream and upstream are trusted.
Tip
This extension extends and can be used with the following extension category:
This extension must be configured with one of the following type URLs:
Redis Proxy configuration overview.
extensions.filters.network.redis_proxy.v3.RedisProxy
[extensions.filters.network.redis_proxy.v3.RedisProxy proto]
{
"stat_prefix": ...,
"settings": {...},
"latency_in_micros": ...,
"prefix_routes": {...},
"downstream_auth_password": {...},
"downstream_auth_passwords": [],
"faults": [],
"downstream_auth_username": {...},
"external_auth_provider": {...}
}
- stat_prefix
(string, REQUIRED) The prefix to use when emitting statistics.
- settings
(extensions.filters.network.redis_proxy.v3.RedisProxy.ConnPoolSettings, REQUIRED) Network settings for the connection pool to the upstream clusters.
- latency_in_micros
(bool) Indicates that latency stat should be computed in microseconds. By default it is computed in milliseconds. This does not apply to upstream command stats currently.
- prefix_routes
(extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes) List of unique prefixes used to separate keys from different workloads to different clusters. Envoy will always favor the longest match first in case of overlap. A catch-all cluster can be used to forward commands when there is no match. Time complexity of the lookups are in O(min(longest key prefix, key length)).
Example:
prefix_routes: routes: - prefix: "ab" cluster: "cluster_a" - prefix: "abc" cluster: "cluster_b"
When using the above routes, the following prefixes would be sent to:
get abc:users
would retrieve the key ‘abc:users’ from cluster_b.get ab:users
would retrieve the key ‘ab:users’ from cluster_a.get z:users
would return a NoUpstreamHost error. A catch-all route would have retrieved the key from that cluster instead.
See the configuration section of the architecture overview for recommendations on configuring the backing clusters.
- downstream_auth_password
(config.core.v3.DataSource) Authenticate Redis client connections locally by forcing downstream clients to issue a Redis AUTH command with this password before enabling any other command. If an AUTH command’s password matches this password, an “OK” response will be returned to the client. If the AUTH command password does not match this password, then an “ERR invalid password” error will be returned. If any other command is received before AUTH when this password is set, then a “NOAUTH Authentication required.” error response will be sent to the client. If an AUTH command is received when the password is not set, then an “ERR Client sent AUTH, but no password is set” error will be returned.
Attention
This field is deprecated. Use downstream_auth_passwords.
- downstream_auth_passwords
(repeated config.core.v3.DataSource) Authenticate Redis client connections locally by forcing downstream clients to issue a Redis AUTH command with one of these passwords before enabling any other command. If an AUTH command’s password matches one of these passwords, an “OK” response will be returned to the client. If the AUTH command password does not match, then an “ERR invalid password” error will be returned. If any other command is received before AUTH when the password(s) are set, then a “NOAUTH Authentication required.” error response will be sent to the client. If an AUTH command is received when the password is not set, then an “ERR Client sent AUTH, but no password is set” error will be returned.
- faults
(repeated extensions.filters.network.redis_proxy.v3.RedisProxy.RedisFault) List of faults to inject. Faults currently come in two flavors: - Delay, which delays a request. - Error, which responds to a request with an error. Errors can also have delays attached.
Example:
faults: - fault_type: ERROR fault_enabled: default_value: numerator: 10 denominator: HUNDRED runtime_key: "bogus_key" commands: - GET - fault_type: DELAY fault_enabled: default_value: numerator: 10 denominator: HUNDRED runtime_key: "bogus_key" delay: 2s
See the fault injection section for more information on how to configure this.
- downstream_auth_username
(config.core.v3.DataSource) If a username is provided an ACL style AUTH command will be required with a username and password. Authenticate Redis client connections locally by forcing downstream clients to issue a Redis AUTH command with this username and the
downstream_auth_password
before enabling any other command. If an AUTH command’s username and password matches this username and thedownstream_auth_password
, an “OK” response will be returned to the client. If the AUTH command username or password does not match this username or thedownstream_auth_password
, then an “WRONGPASS invalid username-password pair” error will be returned. If any other command is received before AUTH when this password is set, then a “NOAUTH Authentication required.” error response will be sent to the client. If an AUTH command is received when the password is not set, then an “ERR Client sent AUTH, but no ACL is set” error will be returned.
- external_auth_provider
(extensions.filters.network.redis_proxy.v3.RedisExternalAuthProvider) External authentication configuration. If set, instead of validating username and password against
downstream_auth_username
anddownstream_auth_password
, the filter will call an external gRPC service to authenticate the client. A typical usage of this feature is for situations where the password is a one-time token that needs to be validated against a remote service, like a sidecar. Expiration is also supported, which will disable any further commands from the client after the expiration time, unless a new AUTH command is received and the external auth service returns a new expiration time. If the external auth service returns an error, authentication is considered failed. If this setting is set together withdownstream_auth_username
anddownstream_auth_password
, the external auth service will be source of truth, but those fields will still be used for downstream authentication to the cluster. The API is defined by RedisProxyExternalAuthRequest.
extensions.filters.network.redis_proxy.v3.RedisProxy.ConnPoolSettings
[extensions.filters.network.redis_proxy.v3.RedisProxy.ConnPoolSettings proto]
Redis connection pool settings.
{
"op_timeout": {...},
"enable_hashtagging": ...,
"enable_redirection": ...,
"dns_cache_config": {...},
"max_buffer_size_before_flush": ...,
"buffer_flush_timeout": {...},
"max_upstream_unknown_connections": {...},
"enable_command_stats": ...,
"read_policy": ...,
"connection_rate_limit": {...}
}
- op_timeout
(Duration, REQUIRED) Per-operation timeout in milliseconds. The timer starts when the first command of a pipeline is written to the backend connection. Each response received from Redis resets the timer since it signifies that the next command is being processed by the backend. The only exception to this behavior is when a connection to a backend is not yet established. In that case, the connect timeout on the cluster will govern the timeout until the connection is ready.
- enable_hashtagging
(bool) Use hash tagging on every redis key to guarantee that keys with the same hash tag will be forwarded to the same upstream. The hash key used for determining the upstream in a consistent hash ring configuration will be computed from the hash tagged key instead of the whole key. The algorithm used to compute the hash tag is identical to the redis-cluster implementation.
Examples:
‘{user1000}.following’ and ‘{user1000}.followers’ will be sent to the same upstream
‘{user1000}.following’ and ‘{user1001}.following’ might be sent to the same upstream
- enable_redirection
(bool) Accept moved and ask redirection errors from upstream redis servers, and retry commands to the specified target server. The target server does not need to be known to the cluster manager. If the command cannot be redirected, then the original error is passed downstream unchanged. By default, this support is not enabled.
- dns_cache_config
(extensions.common.dynamic_forward_proxy.v3.DnsCacheConfig) If
enable_redirection
is set to true this option configures the DNS cache that the connection pool will use to resolve hostnames that are returned with MOVED and ASK responses. If no configuration is provided, DNS lookups will not be performed (and thus the MOVED/ASK errors will be propagated verbatim to the user).
- max_buffer_size_before_flush
(uint32) Maximum size of encoded request buffer before flush is triggered and encoded requests are sent upstream. If this is unset, the buffer flushes whenever it receives data and performs no batching. This feature makes it possible for multiple clients to send requests to Envoy and have them batched- for example if one is running several worker processes, each with its own Redis connection. There is no benefit to using this with a single downstream process. Recommended size (if enabled) is 1024 bytes.
- buffer_flush_timeout
(Duration) The encoded request buffer is flushed N milliseconds after the first request has been encoded, unless the buffer size has already exceeded
max_buffer_size_before_flush
. Ifmax_buffer_size_before_flush
is not set, this flush timer is not used. Otherwise, the timer should be set according to the number of clients, overall request rate and desired maximum latency for a single command. For example, if there are many requests being batched together at a high rate, the buffer will likely be filled before the timer fires. Alternatively, if the request rate is lower the buffer will not be filled as often before the timer fires. Ifmax_buffer_size_before_flush
is set, butbuffer_flush_timeout
is not, the latter defaults to 3ms.
- max_upstream_unknown_connections
(UInt32Value)
max_upstream_unknown_connections
controls how many upstream connections to unknown hosts can be created at any given time by any given worker thread (seeenable_redirection
for more details). If the host is unknown and a connection cannot be created due to enforcing this limit, then redirection will fail and the original redirection error will be passed downstream unchanged. This limit defaults to 100.
- enable_command_stats
(bool) Enable per-command statistics per upstream cluster, in addition to the filter level aggregate count. These commands are measured in microseconds.
- read_policy
(extensions.filters.network.redis_proxy.v3.RedisProxy.ConnPoolSettings.ReadPolicy) Read policy. The default is to read from the primary.
- connection_rate_limit
(extensions.filters.network.redis_proxy.v3.RedisProxy.ConnectionRateLimit) Ops or connection timeout triggers reconnection to redis server which could result in reconnection storm to busy redis server. This config is a protection to rate limit reconnection rate. If not set, there will be no rate limiting on the reconnection.
Enum extensions.filters.network.redis_proxy.v3.RedisProxy.ConnPoolSettings.ReadPolicy
[extensions.filters.network.redis_proxy.v3.RedisProxy.ConnPoolSettings.ReadPolicy proto]
ReadPolicy controls how Envoy routes read commands to Redis nodes. This is currently supported for Redis Cluster. All ReadPolicy settings except MASTER may return stale data because replication is asynchronous and requires some delay. You need to ensure that your application can tolerate stale data.
- MASTER
(DEFAULT) Default mode. Read from the current primary node.
- PREFER_MASTER
Read from the primary, but if it is unavailable, read from replica nodes.
- REPLICA
Read from replica nodes. If multiple replica nodes are present within a shard, a random node is selected. Healthy nodes have precedent over unhealthy nodes.
- PREFER_REPLICA
Read from the replica nodes (similar to REPLICA), but if all replicas are unavailable (not present or unhealthy), read from the primary.
- ANY
Read from any node of the cluster. A random node is selected among the primary and replicas, healthy nodes have precedent over unhealthy nodes.
extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes
[extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes proto]
{
"routes": [],
"case_insensitive": ...,
"catch_all_route": {...}
}
- routes
(repeated extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route) List of prefix routes.
- case_insensitive
(bool) Indicates that prefix matching should be case insensitive.
- catch_all_route
(extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route) Optional catch-all route to forward commands that doesn’t match any of the routes. The catch-all route becomes required when no routes are specified.
extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route
[extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route proto]
{
"prefix": ...,
"remove_prefix": ...,
"cluster": ...,
"request_mirror_policy": [],
"key_formatter": ...,
"read_command_policy": {...}
}
- prefix
(string) String prefix that must match the beginning of the keys. Envoy will always favor the longest match.
- remove_prefix
(bool) Indicates if the prefix needs to be removed from the key when forwarded.
- cluster
(string, REQUIRED) Upstream cluster to forward the command to.
- request_mirror_policy
(repeated extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route.RequestMirrorPolicy) Indicates that the route has a request mirroring policy.
- key_formatter
(string) Indicates how redis key should be formatted. To substitute redis key into the formatting expression, use %KEY% as a string replacement command.
- read_command_policy
(extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route.ReadCommandPolicy) Indicates that the route has a read command policy
extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route.RequestMirrorPolicy
[extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route.RequestMirrorPolicy proto]
The router is capable of shadowing traffic from one cluster to another. The current implementation is “fire and forget,” meaning Envoy will not wait for the shadow cluster to respond before returning the response from the primary cluster. All normal statistics are collected for the shadow cluster making this feature useful for testing.
{
"cluster": ...,
"runtime_fraction": {...},
"exclude_read_commands": ...
}
- cluster
(string, REQUIRED) Specifies the cluster that requests will be mirrored to. The cluster must exist in the cluster manager configuration.
- runtime_fraction
(config.core.v3.RuntimeFractionalPercent) If not specified or the runtime key is not present, all requests to the target cluster will be mirrored.
If specified, Envoy will lookup the runtime key to get the percentage of requests to the mirror.
- exclude_read_commands
(bool) Set this to TRUE to only mirror write commands, this is effectively replicating the writes in a “fire and forget” manner.
extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route.ReadCommandPolicy
[extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route.ReadCommandPolicy proto]
ReadCommandPolicy specifies that Envoy should route read commands to another cluster.
{
"cluster": ...
}
- cluster
(string, REQUIRED)
extensions.filters.network.redis_proxy.v3.RedisProxy.RedisFault
[extensions.filters.network.redis_proxy.v3.RedisProxy.RedisFault proto]
RedisFault defines faults used for fault injection.
{
"fault_type": ...,
"fault_enabled": {...},
"delay": {...},
"commands": []
}
- fault_type
(extensions.filters.network.redis_proxy.v3.RedisProxy.RedisFault.RedisFaultType) Fault type.
- fault_enabled
(config.core.v3.RuntimeFractionalPercent, REQUIRED) Percentage of requests fault applies to.
- delay
(Duration) Delay for all faults. If not set, defaults to zero
- commands
(repeated string) Commands fault is restricted to, if any. If not set, fault applies to all commands other than auth and ping (due to special handling of those commands in Envoy).
Enum extensions.filters.network.redis_proxy.v3.RedisProxy.RedisFault.RedisFaultType
[extensions.filters.network.redis_proxy.v3.RedisProxy.RedisFault.RedisFaultType proto]
- DELAY
(DEFAULT) Delays requests. This is the base fault; other faults can have delays added.
- ERROR
Returns errors on requests.
extensions.filters.network.redis_proxy.v3.RedisProxy.ConnectionRateLimit
[extensions.filters.network.redis_proxy.v3.RedisProxy.ConnectionRateLimit proto]
Configuration to limit reconnection rate to redis server to protect redis server from client reconnection storm.
{
"connection_rate_limit_per_sec": ...
}
- connection_rate_limit_per_sec
(uint32) Reconnection rate per sec. Rate limiting is implemented with TokenBucket.
extensions.filters.network.redis_proxy.v3.RedisProtocolOptions
[extensions.filters.network.redis_proxy.v3.RedisProtocolOptions proto]
RedisProtocolOptions specifies Redis upstream protocol options. This object is used in
typed_extension_protocol_options,
keyed by the name envoy.filters.network.redis_proxy
.
{
"auth_password": {...},
"auth_username": {...}
}
- auth_password
(config.core.v3.DataSource) Upstream server password as defined by the
requirepass
directive https://redis.io/topics/config in the server’s configuration file.
- auth_username
(config.core.v3.DataSource) Upstream server username as defined by the
user
directive https://redis.io/topics/acl in the server’s configuration file.
extensions.filters.network.redis_proxy.v3.RedisExternalAuthProvider
[extensions.filters.network.redis_proxy.v3.RedisExternalAuthProvider proto]
RedisExternalAuthProvider specifies a gRPC service that can be used to authenticate Redis clients. This service will be called every time an AUTH command is received from a client. If the service returns an error, authentication is considered failed. If the service returns a success, the client is considered authenticated. The service can also return an expiration timestamp, which will be used to disable any further commands from the client after it passes, unless a new AUTH command is received and the external auth service returns a new expiration timestamp.
{
"grpc_service": {...},
"enable_auth_expiration": ...
}
- grpc_service
(config.core.v3.GrpcService) External auth gRPC service configuration. It will be called every time an AUTH command is received from a client.
- enable_auth_expiration
(bool) If set to true, the filter will expect an expiration timestamp in the response from the external auth service. This timestamp will be used to disable any further commands from the client after the expiration time, unless a new AUTH command is received and the external auth service returns a new expiration timestamp.