Kong（V1.0.2） Health Checks and Circuit Breakers Reference

介绍

您可以让Kong代理的API使用ring-balancer，通过添加包含一个或多个目标实体的 upstream 实体进行配置，每个 target指向不同的IP地址(或主机名)和端口。ring-balancer将在各种目标之间负载，并基于上游对目标执行健康检查，使它们无论是否响应都是健康的或不健康的。然后，ring-balancer 只会将流量路由到健康的目标。

Kong有两种健康检查方法，可分别或同时使用:

• active checks主动检查，其中定期请求目标中的特定HTTP或HTTPS端点，并根据其响应确定目标的健康状态;
• passive checks被动检查(也称为断路器)，Kong在其中分析正在代理的流量，并根据目标的行为响应请求来确定目标的健康状况。

健康与不健康目标

健康检查功能的目标是为给定的Kong节点动态地将目标标记为健康或不健康。没有集群范围内的健康信息同步:每个Kong节点分别决定其目标的健康。这是可取的,因为某个Kong节点可以连接到一个目标,但另一个Kong节点未必能连接该目标:第一个节点将考虑它健康,而另一个将其标记为不健康的，将请求路由到其他目标（健康）。

主动探测(在主动健康检查上)或代理请求(在被动健康检查上)都会生成用于确定目标是否健康的数据。请求可能会产生TCP错误、超时或HTTP状态代码。基于此信息，健康检查器更新一系列内部计数器:

• 如果返回的状态码是配置为“健康”的状态码，将增加目标的“success”计数器，并清除其所有其他计数器;
• 如果连接失败，则增加目标的“TCP failure”计数器，清除“success”计数器;
• 如果超时，将增加目标的“超时”计数器，清除“成功”计数器;
• 如果返回的状态代码被配置为“不健康”，它将增加目标的“HTTP故障”计数器，并清除“成功”计数器。

如果任何“TCP失败”、“HTTP失败”或“超时”计数器达到其配置的阈值，目标将被标记为不健康。

如果“成功”计数器达到其配置的阈值，则将目标标记为健康。

HTTP状态码为“健康”或“不健康”的列表，并且每个计数器的独立阈值可以在每个上游的基础上进行配置。下面，我们有一个上游实体的配置示例，展示了用于配置健康检查的各种字段的默认值。每个字段的描述包含在Admin API 参考文档中。

{
    "name": "service.v1.xyz",
    "healthchecks": {
        "active": {
            "concurrency": 10,
            "healthy": {
                "http_statuses": [ 200, 302 ],
                "interval": 0,
                "successes": 0
            },
            "http_path": "/",
            "timeout": 1,
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [ 429, 404, 500, 501,
                                   502, 503, 504, 505 ],
                "interval": 0,
                "tcp_failures": 0,
                "timeouts": 0
            }
        },
        "passive": {
            "healthy": {
                "http_statuses": [ 200, 201, 202, 203,
                                   204, 205, 206, 207,
                                   208, 226, 300, 301,
                                   302, 303, 304, 305,
                                   306, 307, 308 ],
                "successes": 0
            },
            "unhealthy": {
                "http_failures": 0,
                "http_statuses": [ 429, 500, 503 ],
                "tcp_failures": 0,
                "timeouts": 0
            }
        }
    },
    "slots": 10
}

如果上游的所有目标都不健康，Kong将返回503 Service Unavailable。

注意:

1. 健康检查仅对活动目标进行操作，不修改Kong数据库中目标的活动状态。
2. 不健康的目标不会从负载均衡器中删除，因此在使用哈希算法时不会对均衡器布局产生任何影响(它们将被跳过)。
3. DNS caveats and balancer caveats也适用于健康检查。如果对目标使用主机名，那么请确保DNS服务器始终返回名称的完整IP地址集，并且不限制响应。如果不这样做，可能会导致不执行健康检查。

Types of health checks

Active health checks

正如其名称所暗示的那样，主动健康检查会主动探测其健康的目标。当上游实体中启用活动健康状态检查时，Kong将定期向上游每个目标的配置路径发出HTTP或HTTPS请求。这允许Kong根据探测结果probe results自动启用和禁用均衡器中的目标。

活动健康检查的周期可以针对目标的健康或不健康情况单独配置。如果任意一个的间隔值设置为0，则在相应的场景中禁用检查。当两者都为零时，活动健康检查将完全禁用。

注意:活动健康检查目前只支持HTTP/HTTPS目标。它们不适用于将协议属性设置为“tcp”或“tls”的服务的上行流。

Passive health checks (circuit breakers)

被动健康检查，也称为断路器，是根据Kong代理的请求(HTTP/HTTPS/TCP)执行的检查，不生成额外的流量。当目标变得无响应时，被动健康检查器将检测到该情况并将该目标标记为不健康。戒指均衡器将开始跳过这个目标，所以不会有更多的流量被路由到它。

一旦目标的问题得到解决，并准备再次接收流量，Kong管理员可以通过Admin API 端点手动通知健康检查程序应该再次启用目标，如下：

curl -i -X POST http://localhost:8001/upstreams/my_upstream/targets/10.1.2.3:1234/healthy
HTTP/1.1 204 No Content

此命令将广播一个集群范围的消息，以便将“健康”状态传播到整个Kong集群。这将导致Kong节点重置在Kong节点的所有worker中运行的health checkers的健康计数器，从而允许ring-balancer再次将流量路由到目标。

被动健康检查的优点是不会产生额外的流量，但是它们无法自动将目标再次标记为健康:“circuit is broken”，需要系统管理员重新启用目标。

Summary of pros and cons

• 主动健康检查可以自动重新启用ring-balancer中的目标，只要它再次健康。被动的健康检查不能。
• 被动健康检查不会给目标带来额外的流量。而主动健康检查会产生。
• 主动健康检查程序要求将目标中具有可靠状态响应的已知URL配置为探测端点(可以简单到“/”)。被动健康检查不需要这样的配置。
• 通过为主动健康检查器提供自定义探针端点，应用程序可以确定自己的健康指标，并生成供Kong使用的状态代码。即使目标继续为在被动健康检查器看来健康的流量提供服务，它也能够以失败状态响应主动探测，本质上是请求从接受新流量中解脱出来。

把这两种模式结合起来是可能的。例如，可以启用被动健康检查，仅根据其流量监视目标健康状况，并在目标不健康时才使用主动健康检查，以便自动重新启用它。

Enabling and disabling health checks启用和禁用健康检查

Enabling active health checks启用积极的健康检查

要启用活动健康检查，需要指定healthchecks.active下的配置项，该配置项在Upstream object中处于活动状态。您需要指定必要的信息，以便Kong能够对目标执行定期探测，以及如何解释结果信息。

你可以使用healthchecks.active.type属性以指定是执行HTTP还是HTTPS探测(将其设置为“HTTP”或“HTTPS”)，还可以通过简单的测试能否连接给定主机和端口的(将其设置为“tcp”)来指定。

要配置探测，您需要指定:

• healthchecks.active.http_path - 向目标发出HTTP GET请求时应该使用的路径。默认值是“/”。
• healthchecks.active.timeout -  探测的HTTP GET请求的连接超时限制。默认值是1秒。
• healthchecks.active.concurrency - 在活动健康检查中要并发检查的目标数量。

您还需要为运行探测的间隔指定正值:

• healthchecks.active.healthy.interval -对健康目标的活动健康检查之间的间隔(以秒为单位)。值为0表示不应该对健康目标执行主动探测。
• healthchecks.active.unhealthy.interval - 活动健康检查不健康目标之间的间隔(秒)。值为0表示不应该对不健康的目标执行活动探测。

这允许您调整活动健康检查的行为，无论您希望健康和不健康目标的探测以相同的间隔运行，还是希望一个比另一个更频繁。

如果使用HTTPS healthcheck，还可以指定以下字段:

• healthchecks.active.https_verify_certificate - 在使用HTTPS执行活动健康检查时，是否检查远程主机的SSL证书的有效性。
• healthchecks.active.https_sni - 使用HTTPS执行活动健康状态检查时用作SNI(服务器名标识)的主机名。当使用IPs配置目标时，这尤其有用，这样目标主机的证书就可以用适当的SNI进行验证。

注意，失败的TLS验证将增加“TCP失败”计数器;“HTTP失败”仅指HTTP状态代码，无论探测是通过HTTP还是HTTPS完成的。

最后，您需要配置Kong应该如何解释探测，方法是在health counters上设置各种阈值，一旦达到阈值将触发状态更改。反阈值字段为:

• healthchecks.active.healthy.successes - 活动探测(由healthcheck .active.health .http_statuses定义)中考虑目标是否健康的成功次数。
• healthchecks.active.unhealthy.tcp_failures - 活动探测中认为目标不健康的TCP失败或TLS验证失败的次数。
• healthchecks.active.unhealthy.timeouts - 活动探测中认为目标不健康的超时次数。
• healthchecks.active.unhealthy.http_failures - 活动探测(由healthcheck .active.unhealth .http_statuses定义)中考虑目标不健康的HTTP失败次数。

Enabling passive health checks

被动健康检查没有探测功能，因为它们通过分析来自目标流量来工作。这意味着，要启用被动检查，您只需要配置其计数器阈值:

• healthchecks.passive.healthy.successes - 代理流量中的成功次数(由healthcheck .passive.health .http_statuses定义)，以考虑目标的健康，如被动健康检查所观察到的。当启用被动检查时，这需要为正数，以便正常的流量重置不健康的计数器。
• healthchecks.passive.unhealthy.tcp_failures - 被动健康检查所观察到的，代理流量中认为目标不健康的TCP失败次数。
• healthchecks.passive.unhealthy.timeouts -通过被动健康检查观察到，代理通信流中认为目标不健康的超时次数。
• healthchecks.passive.unhealthy.http_failures -代理的流量(由healthchecks.passive.unhealthy.http_statuses定义)中HTTP失败的数量，以考虑目标不健康，如被动健康检查所观察到的。

Disabling health checks

在healthcheck配置中指定的所有计数器阈值和间隔中，将值设置为0意味着禁用该字段所表示的功能。将探测间隔设置为0将禁用探测。同样，您可以通过将某些类型的检查的计数器阈值设置为零来禁用它们。例如，要在执行healthcheck时不考虑超时，可以将两个超时字段(用于主动和被动检查)都设置为零。这为您提供了对健康检查器行为的细粒度控制。

总之，要完全禁用上游的活动健康检查，您需要将healthcheck .active.health .interval和healthcheck .active.unhealth .interval都设置为0。

要完全禁用被动健康检查，需要在healthcheck下设置所有计数器阈值。被动使其各种计数器为零。

healthcheck中的所有计数器阈值和间隔默认为零，这意味着在新创建的上行流中，默认情况下完全禁用健康检查。