Redis 代理 (proto)

此扩展的限定名称为 envoy.filters.network.redis_proxy

注意

此扩展未经过硬化，仅应在上下游都可信的部署中使用。

提示

此扩展扩展并可与以下扩展类别一起使用

envoy.filters.network

此扩展必须使用以下类型 URL 之一进行配置

type.googleapis.com/envoy.extensions.filters.network.redis_proxy.v3.RedisProxy

Redis 代理配置概述.

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) 发射统计信息时要使用的前缀。

settings: (extensions.filters.network.redis_proxy.v3.RedisProxy.ConnPoolSettings, REQUIRED) 与上游集群的连接池的网络设置。

latency_in_micros: (bool) 指示延迟统计信息应以微秒计算。默认情况下，它以毫秒计算。目前，这并不适用于上游命令统计信息。

prefix_routes

(extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes) 用于将来自不同工作负载的键与不同集群分开的唯一前缀列表。在出现重叠的情况下，Envoy 将始终优先考虑最长的匹配项。可以使用一个万能集群来转发没有匹配项的命令。查找的时间复杂度为 O(min(最长键前缀，键长度))。

示例

prefix_routes:
  routes:
    - prefix: "ab"
      cluster: "cluster_a"
    - prefix: "abc"
      cluster: "cluster_b"

使用上述路由时，以下前缀将发送到

get abc:users 将从 cluster_b 中检索键 'abc:users'。
get ab:users 将从 cluster_a 中检索键 'ab:users'。
get z:users 将返回 NoUpstreamHost 错误。一个万能路由将从该集群中检索键，而不是。

请参阅体系结构概述的配置部分，了解有关配置支持集群的建议。

downstream_auth_password: (config.core.v3.DataSource) 通过强制下游客户端在启用任何其他命令之前使用此密码发出 Redis AUTH 命令来在本地对 Redis 客户端连接进行身份验证。如果 AUTH 命令的密码与此密码匹配，则将向客户端返回“OK”响应。如果 AUTH 命令密码与此密码不匹配，则将返回“ERR invalid password”错误。如果在设置此密码时在 AUTH 之前收到任何其他命令，则将向客户端发送“NOAUTH Authentication required.”错误响应。如果在未设置密码时收到 AUTH 命令，则将返回“ERR Client sent AUTH, but no password is set”错误。

注意

此字段已弃用。使用 downstream_auth_passwords.

downstream_auth_passwords: (repeated config.core.v3.DataSource) 通过强制下游客户端在启用任何其他命令之前使用这些密码之一发出 Redis AUTH 命令来在本地对 Redis 客户端连接进行身份验证。如果 AUTH 命令的密码与这些密码之一匹配，则将向客户端返回“OK”响应。如果 AUTH 命令密码不匹配，则将返回“ERR invalid password”错误。如果在设置密码时在 AUTH 之前收到任何其他命令，则将向客户端发送“NOAUTH Authentication required.”错误响应。如果在未设置密码时收到 AUTH 命令，则将返回“ERR Client sent AUTH, but no password is set”错误。

faults

(repeated extensions.filters.network.redis_proxy.v3.RedisProxy.RedisFault) 要注入的故障列表。目前，故障有两种类型： - 延迟，它延迟请求。 - 错误，它以错误响应请求。错误也可以附加延迟。

示例

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

请参阅故障注入部分，了解有关如何配置此功能的更多信息。

downstream_auth_username: (config.core.v3.DataSource) 如果提供用户名，则需要使用用户名和密码进行 ACL 样式的 AUTH 命令。通过强制下游客户端在启用任何其他命令之前使用此用户名和 downstream_auth_password 发出 Redis AUTH 命令来在本地对 Redis 客户端连接进行身份验证。如果 AUTH 命令的用户名和密码与此用户名和 downstream_auth_password 匹配，则将向客户端返回“OK”响应。如果 AUTH 命令用户名或密码与此用户名或 downstream_auth_password 不匹配，则将返回“WRONGPASS invalid username-password pair”错误。如果在设置此密码时在 AUTH 之前收到任何其他命令，则将向客户端发送“NOAUTH Authentication required.”错误响应。如果在未设置密码时收到 AUTH 命令，则将返回“ERR Client sent AUTH, but no ACL is set”错误。

external_auth_provider: (extensions.filters.network.redis_proxy.v3.RedisExternalAuthProvider) 外部身份验证配置。如果设置，则过滤器将调用外部 gRPC 服务来对客户端进行身份验证，而不是针对 downstream_auth_username 和 downstream_auth_password 验证用户名和密码。此功能的典型用法是针对密码是一次性令牌需要针对远程服务进行验证的情况，例如 sidecar。还支持过期，这将在过期时间后禁用来自客户端的任何进一步命令，除非收到新的 AUTH 命令并且外部身份验证服务返回新的过期时间。如果外部身份验证服务返回错误，则身份验证被视为失败。如果此设置与 downstream_auth_username 和 downstream_auth_password 一起设置，则外部身份验证服务将成为真实来源，但这些字段仍将用于对集群进行下游身份验证。该 API 由 RedisProxyExternalAuthRequest 定义。

extensions.filters.network.redis_proxy.v3.RedisProxy.ConnPoolSettings

[extensions.filters.network.redis_proxy.v3.RedisProxy.ConnPoolSettings proto]

Redis 连接池设置。

{
  "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) 以毫秒为单位的每个操作超时。计时器从将管道中的第一个命令写入后端连接时开始。从 Redis 收到的每个响应都将重置计时器，因为它表示下一个命令正在由后端处理。此行为的唯一例外是当尚未建立与后端的连接时。在这种情况下，集群上的连接超时将控制超时，直到连接准备就绪为止。

enable_hashtagging

(bool) 对每个 redis 键使用哈希标签，以确保具有相同哈希标签的键将转发到相同的上游。用于在一致哈希环配置中确定上游的哈希键将根据哈希标签键而不是整个键来计算。用于计算哈希标签的算法与 redis-cluster 实现相同。

示例

‘{user1000}.following’ 和 ‘{user1000}.followers’ 将发送到相同的上游
‘{user1000}.following’ 和 ‘{user1001}.following’ 可能发送到相同的上游

enable_redirection: (bool) 接受来自上游 redis 服务器的移动和请求重定向错误，并将命令重试到指定的目标服务器。目标服务器无需为集群管理器所知。如果无法重定向命令，则原始错误将原封不动地传递到下游。默认情况下，此支持未启用。

dns_cache_config: (extensions.common.dynamic_forward_proxy.v3.DnsCacheConfig) 如果 enable_redirection 设置为 true，则此选项将配置连接池将用来解析 MOVED 和 ASK 响应中返回的主机名的 DNS 缓存。如果未提供任何配置，则不会执行 DNS 查找（因此 MOVED/ASK 错误将原封不动地传播给用户）。

max_buffer_size_before_flush: (uint32) 在触发刷新并向上游发送编码请求之前，编码请求缓冲区的最大大小。如果未设置此值，则缓冲区在收到数据时就会刷新，并且不执行任何批处理。此功能使多个客户端可以将请求发送到 Envoy 并对其进行批处理——例如，如果运行多个工作进程，每个进程都有自己的 Redis 连接。对单个下游进程使用此功能没有任何好处。建议的大小（如果启用）为 1024 字节。

buffer_flush_timeout: (Duration) 在第一个请求被编码后，编码请求缓冲区将在 N 毫秒后刷新，除非缓冲区大小已经超过 max_buffer_size_before_flush。如果 max_buffer_size_before_flush 未设置，则不会使用此刷新计时器。否则，应根据客户端数量、总体请求速率和单个命令的预期最大延迟来设置计时器。例如，如果有很多请求以高速率一起进行批处理，则缓冲区很可能在计时器触发之前被填满。或者，如果请求速率较低，则缓冲区在计时器触发之前不会被填满。如果 max_buffer_size_before_flush 已设置，但 buffer_flush_timeout 未设置，则后者默认为 3 毫秒。

max_upstream_unknown_connections: (UInt32Value) max_upstream_unknown_connections 控制任何给定工作线程在任何给定时间可以创建到未知主机的上游连接数量（有关详细信息，请参见 enable_redirection）。如果主机未知，并且由于执行此限制而无法创建连接，则重定向将失败，并且原始重定向错误将向下游传递而不会更改。此限制默认为 100。

enable_command_stats: (bool) 除了过滤器级别的聚合计数之外，还为每个上游集群启用每个命令的统计信息。这些命令以微秒为单位测量。

read_policy: (extensions.filters.network.redis_proxy.v3.RedisProxy.ConnPoolSettings.ReadPolicy) 读取策略。默认值是从主节点读取。

connection_rate_limit: (extensions.filters.network.redis_proxy.v3.RedisProxy.ConnectionRateLimit) 操作或连接超时会触发重新连接到 Redis 服务器，这可能导致对繁忙的 Redis 服务器的重新连接风暴。此配置是一种保护措施，用于限制重新连接速率。如果未设置，则不会限制重新连接的速率。

枚举 extensions.filters.network.redis_proxy.v3.RedisProxy.ConnPoolSettings.ReadPolicy

[extensions.filters.network.redis_proxy.v3.RedisProxy.ConnPoolSettings.ReadPolicy proto]

ReadPolicy 控制 Envoy 如何将读取命令路由到 Redis 节点。这目前支持 Redis 集群。除了 MASTER 之外的所有 ReadPolicy 设置都可能返回陈旧数据，因为复制是异步的，并且需要一些延迟。您需要确保您的应用程序可以容忍陈旧数据。

MASTER: (DEFAULT) ⁣默认模式。从当前主节点读取。

PREFER_MASTER: ⁣从主节点读取，但如果主节点不可用，则从副本节点读取。

REPLICA: ⁣从副本节点读取。如果在一个分片中存在多个副本节点，则会随机选择一个节点。健康节点优先于不健康的节点。

PREFER_REPLICA: ⁣从副本节点读取（类似于 REPLICA），但如果所有副本都不可用（不存在或不健康），则从主节点读取。

ANY: ⁣从集群的任何节点读取。在主节点和副本节点之间随机选择一个节点，健康节点优先于不健康的节点。

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) 前缀路由列表。

case_insensitive: (bool) 指示前缀匹配是否不区分大小写。

catch_all_route: (extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route) 可选的通用路由，用于转发与任何路由都不匹配的命令。当没有指定任何路由时，通用路由变为必需。

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) 必须与键开头匹配的字符串前缀。 Envoy 始终优先考虑最长的匹配。

remove_prefix: (bool) 指示转发时是否需要从键中删除前缀。

cluster: (string, REQUIRED) 要将命令转发到的上游集群。

request_mirror_policy: (repeated extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route.RequestMirrorPolicy) 指示路由具有请求镜像策略。

key_formatter: (string) 指示 Redis 键的格式。要将 Redis 键替换到格式化表达式中，请使用 %KEY% 作为字符串替换命令。

read_command_policy: (extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route.ReadCommandPolicy) 指示路由具有读取命令策略

extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route.RequestMirrorPolicy

[extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route.RequestMirrorPolicy proto]

路由器能够将来自一个集群的流量镜像到另一个集群。当前实现是“即发即弃”，这意味着 Envoy 不会等待镜像集群响应，然后才会返回来自主集群的响应。所有正常统计信息都会为镜像集群收集，这使得此功能可用于测试。

{
  "cluster": ...,
  "runtime_fraction": {...},
  "exclude_read_commands": ...
}

cluster: (string, REQUIRED) 指定将镜像请求到的集群。该集群必须存在于集群管理器配置中。

runtime_fraction

(config.core.v3.RuntimeFractionalPercent) 如果未指定或运行时键不存在，则将镜像到目标集群的所有请求。

如果指定，Envoy 将查找运行时键以获取要镜像的请求的百分比。

exclude_read_commands: (bool) 将此设置为 TRUE 仅镜像写入命令，这实际上是在以“即发即弃”方式复制写入操作。

extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route.ReadCommandPolicy

[extensions.filters.network.redis_proxy.v3.RedisProxy.PrefixRoutes.Route.ReadCommandPolicy proto]

ReadCommandPolicy 指定 Envoy 应将读取命令路由到另一个集群。

{
  "cluster": ...
}

cluster: (string, REQUIRED)

extensions.filters.network.redis_proxy.v3.RedisProxy.RedisFault

[extensions.filters.network.redis_proxy.v3.RedisProxy.RedisFault proto]

RedisFault 定义用于故障注入的故障。

{
  "fault_type": ...,
  "fault_enabled": {...},
  "delay": {...},
  "commands": []
}

fault_type: (extensions.filters.network.redis_proxy.v3.RedisProxy.RedisFault.RedisFaultType) 故障类型。

fault_enabled: (config.core.v3.RuntimeFractionalPercent, REQUIRED) 故障适用的请求百分比。

delay: (Duration) 所有故障的延迟。如果未设置，则默认为零

commands: (repeated string) 故障限制的命令（如果有）。如果未设置，则故障适用于除 auth 和 ping 之外的所有命令（由于 Envoy 中对这些命令的特殊处理）。

枚举 extensions.filters.network.redis_proxy.v3.RedisProxy.RedisFault.RedisFaultType

[extensions.filters.network.redis_proxy.v3.RedisProxy.RedisFault.RedisFaultType proto]

DELAY: (DEFAULT) ⁣延迟请求。这是基本故障；其他故障可以添加延迟。

ERROR: ⁣在请求上返回错误。

extensions.filters.network.redis_proxy.v3.RedisProxy.ConnectionRateLimit

[extensions.filters.network.redis_proxy.v3.RedisProxy.ConnectionRateLimit proto]

配置以限制对 Redis 服务器的重新连接速率，以保护 Redis 服务器免受客户端重新连接风暴的影响。

{
  "connection_rate_limit_per_sec": ...
}

connection_rate_limit_per_sec: (uint32) 每秒的重新连接速率。速率限制是使用 TokenBucket 实现的。

extensions.filters.network.redis_proxy.v3.RedisProtocolOptions

[extensions.filters.network.redis_proxy.v3.RedisProtocolOptions proto]

RedisProtocolOptions 指定 Redis 上游协议选项。此对象用于 typed_extension_protocol_options，以 envoy.filters.network.redis_proxy 作为键。

{
  "auth_password": {...},
  "auth_username": {...}
}

auth_password: (config.core.v3.DataSource) 由服务器配置文件中的 requirepass 指令定义的上游服务器密码 https://redis.ac.cn/topics/config。

auth_username: (config.core.v3.DataSource) 由服务器配置文件中的 user 指令定义的上游服务器用户名 https://redis.ac.cn/topics/acl。

extensions.filters.network.redis_proxy.v3.RedisExternalAuthProvider

[extensions.filters.network.redis_proxy.v3.RedisExternalAuthProvider proto]

RedisExternalAuthProvider 指定了一个 gRPC 服务，该服务可用于对 Redis 客户端进行身份验证。每次从客户端收到 AUTH 命令时，都会调用此服务。如果服务返回错误，则身份验证被视为失败。如果服务返回成功，则客户端被视为已通过身份验证。该服务还可以返回一个过期时间戳，该时间戳将用于在过期时间之后禁用来自客户端的任何进一步命令，除非收到新的 AUTH 命令并且外部身份验证服务返回新的过期时间戳。

{
  "grpc_service": {...},
  "enable_auth_expiration": ...
}

grpc_service: (config.core.v3.GrpcService) 外部身份验证 gRPC 服务配置。每次从客户端收到 AUTH 命令时，都会调用它。

enable_auth_expiration: (bool) 如果设置为 true，则过滤器将期望外部身份验证服务响应中包含过期时间戳。此时间戳将用于在过期时间之后禁用来自客户端的任何进一步命令，除非收到新的 AUTH 命令并且外部身份验证服务返回新的过期时间戳。