Envoy Redis 健康检查器（envoy.health_checkers.redis）配置与原理详解

Envoy Redis 健康检查器（envoy.health_checkers.redis）配置与原理详解

【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy

Envoy 提供了一套基于自定义健康检查（Custom Health Check）扩展机制的 Redis 上游健康检查器：envoy.health_checkers.redis。它以 Redis 协议（RESP）直接与上游 Redis 实例交互，通过发送PING期望得到PONG来判定主机存活，并可选地通过EXISTS <key>实现"维护模式"标记。本文以 官方文档 为骨架，结合仓库源码与测试，完整讲解该健康检查器的配置方式、工作流程、统计指标、AWS IAM 认证支持及底层实现原理。

一、什么是 Redis 健康检查器

Redis 健康检查器是 Envoy 中的一种自定义健康检查器（custom health checker），其扩展名称为envoy.health_checkers.redis。与 Envoy 内置的 HTTP、TCP 等健康检查不同，它针对 Redis 上游主机，按照 Redis 协议（RESP2）发送命令并解析响应。

其核心工作原理是：

• 向每个被检查的 Redis 上游主机发送一条 RedisPING命令，并期望收到PONG响应；
• 若上游 Redis 服务器返回任何非PONG的内容，则该次主动健康检查（active health check）立即判定为失败；
• 可选地，Envoy 可以对用户指定的 key 执行EXISTS命令。若该 key 不存在（返回 0），健康检查视为通过；若 key 存在，则判定为失败。

该设计在 api/envoy/extensions/health_checkers/redis/v3/redis.proto 中有明确描述：设置 key 后，Envoy 执行EXISTS <key>替代PING，Redis 返回 0（key 不存在）视为健康检查通过，返回非 0 视为失败。

二、典型配置示例

Redis 健康检查器通过标准健康检查配置中的custom_health_check字段挂载，示例配置如下：

custom_health_check: name: envoy.health_checkers.redis typed_config: "@type": type.googleapis.com/envoy.extensions.health_checkers.redis.v3.Redis key: foo

配置要点：

• name：固定为扩展名envoy.health_checkers.redis；
• typed_config."@type"：指向 v3 类型的envoy.extensions.health_checkers.redis.v3.Redis消息；
• key：可选字段。设置后，健康检查由PING模式切换为EXISTS <key>模式。

该配置挂在HealthCheck.CustomHealthCheck消息下（v3 API 参考envoy_v3_api_msg_config.core.v3.HealthCheck.CustomHealthCheck），并整体嵌套在集群的health_checks列表中，与其他健康检查参数（如timeout、interval、unhealthy_threshold等）共同生效。

从源码看，config.cc 中工厂方法createCustomHealthChecker通过utility.h中的getRedisHealthCheckConfig解析typed_config，然后构造RedisHealthChecker实例，最后通过REGISTER_FACTORY注册到自定义健康检查器工厂中。

三、两种工作模式与"维护模式"机制

3.1 默认模式：PING / PONG

未设置key时，健康检查器采用Ping模式：向上游发送PING，响应为简单字符串PONG即视为健康。

对应源码在 redis.cc：构造函数中根据key_是否为空决定type_为Type::Exists还是Type::Ping。请求构造见 HealthCheckRequest，它会生成一个仅含PING一个 Bulk String 元素的 RESP Array。

3.2 EXISTS 模式与维护标记

设置key后，健康检查器切换到Exists模式：向上游发送EXISTS <key>。响应处理逻辑在 onResponse：

• Ping模式：响应类型为SimpleString且内容为PONG→handleSuccess()；否则handleFailure(ACTIVE)；
• Exists模式：响应类型为Integer且值为0→handleSuccess()；否则递增exists_failure计数并handleFailure(ACTIVE)。

这带来一个非常有价值的运维场景：通过设置指定 key 将 Redis 实例标记为维护状态。具体做法是：

1. 在健康检查配置中指定key（例如foo）；
2. 正常运行时该 key 不存在（EXISTS返回 0），实例健康、流量正常；
3. 需要维护时，运维人员用任意客户端执行SET foo 1（或任意值），使EXISTS foo返回 1；
4. 健康检查随即失败，Envoy 将该主机从负载均衡中剔除，流量逐渐排空（drain）；
5. 维护完成后删除该 key，实例自动恢复健康、重新接收流量。

这种方式无需重启 Envoy、无需改动集群配置，即可优雅地让某个 Redis 实例下线维护。

3.3 超时、网络失败与重定向处理

源码中还对多种异常情况做了专门处理：

• 网络失败：onFailure()回调触发handleFailure(NETWORK)（见 redis.cc）；
• 超时：onTimeout()取消当前请求并关闭客户端连接（redis.cc）。底层RedisConfig::opTimeout()返回父级健康检查timeout的 2 倍，让健康检查基础设施统一控制超时（redis.h）；
• 重定向：onRedirection()将任何 Redis 服务器返回的重定向错误响应视为成功（redis.cc），这与RedisConfig::enableRedirection()返回true的设置一致——集群场景下 MOVED/ASK 重定向不代表主机不健康；
• 连接复用：健康检查会话按reuse_connection配置决定是否在响应后关闭客户端连接（redis.cc）；
• 读取策略：readPolicy()固定为Primary（主节点），避免从从节点读到过时数据（redis.h）。

四、统计指标

Redis 健康检查器在health_check.redis.*命名空间下输出统计指标，完整定义见 redis.h 中的ALL_REDIS_HEALTH_CHECKER_STATS宏，统计前缀在 redis.cc 中生成：

该计数器只在Exists模式下、且EXISTS返回非 0 值时递增（redis.cc）。运维上可以结合该指标监控"维护标记"是否被误设置，或观察排空进度。

五、AWS IAM 认证支持

Redis 健康检查器支持与redis_proxy过滤器相同方式的AWS IAM 认证，可用于连接 Amazon ElastiCache 与 Amazon MemoryDB 实例。详细配置说明参见 redis_proxy_filter.rst 中的 "AWS IAM Authentication" 一节。

在健康检查器的 proto 定义中，aws_iam字段类型直接复用了filters.network.redis_proxy.v3.AwsIam消息（见 redis.proto）。对应示例（以 redis_proxy 集群协议选项为例，字段结构相同）：

typed_extension_protocol_options: envoy.filters.network.redis_proxy: "@type": type.googleapis.com/envoy.extensions.filters.network.redis_proxy.v3.RedisProtocolOptions auth_username: inline_string: test aws_iam: region: ap-southeast-2 service_name: elasticache cache_name: testcache expiration_time: 900s

完整示例文件见 redis-aws-iam-auth.yaml。

配置要点（与 redis_proxy 过滤器一致）：

• region：可选，未指定时按 region provider chain 自动推断；
• cache_name：必填，设置为缓存名称，与auth_username一起参与 IAM 认证令牌计算；
• auth_password：AWS IAM 模式下不使用，密码由 Envoy 自动计算；
• service_name：elasticache（ElastiCache，valkey 或 Redis OSS 模式）或memorydb（MemoryDB），需与 IAM Policy 中允许的 Action（如memorydb:Connect）对应。

从源码看，config.cc 在配置中存在aws_iam时，会通过AwsIamAuthenticatorFactory::initAwsIamAuthenticator初始化认证器，并将其与aws_iam_config一并传给RedisHealthChecker。同时，健康检查器的认证用户名/密码取自集群的 Redis 协议选项配置（ProtocolOptionsConfigImpl::authUsername/authPassword，见 redis.cc）。

六、底层实现与测试验证

6.1 实现架构

整个实现位于source/extensions/health_checkers/redis/目录：

• redis.h：定义RedisHealthChecker类，继承自Upstream::HealthCheckerImplBase，内部含RedisActiveHealthCheckSession（每个被检查主机一个会话）、RedisConfig（Redis 客户端参数）与HealthCheckRequest（请求构造）；
• redis.cc：实现会话生命周期、定时器触发、请求/响应处理；
• config.cc：自定义健康检查器工厂与注册；
• utility.h：typed_config的解析与校验。

会话工作流程：

1. 到达健康检查间隔时，onInterval()创建（或复用）Redis 客户端，并依据type_发送EXISTS <key>或PING（redis.cc）；
2. 客户端收到响应后触发onResponse，按上述规则判定成功/失败；
3. 失败超过阈值后，主机从健康集合中剔除。

6.2 测试覆盖

仓库在 test/extensions/health_checkers/redis/redis_test.cc 中提供了完整的单元测试，覆盖 PING/PONG、EXISTS、超时、重定向、认证等场景，可以作为理解行为边界和二次开发的参考。

七、总结

Envoy 的 Redis 健康检查器是一个轻量、协议级、可扩展的主动健康检查方案：

• 通过custom_health_check与typed_config即插即用，无需额外编译扩展；
• PING/PONG保证最基本的存活探测；
• EXISTS <key>提供优雅的维护模式标记，让流量排空与实例下线完全可控；
• 支持集群重定向、超时控制、连接复用等健壮性细节；
• 与 redis_proxy 过滤器共享 AWS IAM 认证能力，无缝对接 ElastiCache / MemoryDB 托管服务；
• health_check.redis.exists_failure指标为维护状态的监控与排障提供依据。

相关配套文档入口见 health_checkers.rst（Redis 健康检查器总览目录），实际部署时可结合集群health_checks的通用参数（timeout、interval、healthy_threshold、unhealthy_threshold等）统一调优。

【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy