feat(balancer) use lua-resty-dns-client healthThreshold attrib

[locao]

• added new field threshold to healthchecks in upstreams entities.
• added new query parameter balancer_health for the endpoint /upstreams/:upstream_id/health. When balancer_health=1, the endpoint returns the balancer health, instead of the targets' health.

[Tieske]

instead of the query argument, cannot we add the balancer health in the top elelements of the response as shown here: https://docs.konghq.com/1.4.x/admin-api/#show-upstream-health-for-node

{
    "total": 2,
    "node_id": "cbb297c0-14a9-46bc-ad91-1d0ef9b42df9",
    "status": "HEALTHY",                                        --------> this one added
    "data": [
        {
            "created_at": 1485524883980,
            "id": "18c0ad90-f942-4098-88db-bbee3e43b27f",
            "health": "HEALTHY",
            "target": "127.0.0.1:20000",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 100
        },
        {
            "created_at": 1485524914883,
            "id": "6c6f34eb-e6c3-4c1f-ac58-4060e5bca890",
            "health": "UNHEALTHY",
            "target": "127.0.0.1:20002",
            "upstream_id": "07131005-ba30-4204-a29f-0927d53257b4",
            "weight": 200
        }
    ]
}

[hishamhm]

instead of the query argument, cannot we add the balancer health in the top elelements

@Tieske I discussed this with @locao and I suggested the query argument as a way to add the feature without incurring in a breaking change for the format (and subsequent adjustments to any tooling built around Kong's health info, etc.) and we agreed this was a good way to go.

The rationale was that the configuration and behavior of healthchecks are already pretty complicated as is, and given that the default for health_threshold is 0, most users shouldn't need to deal with three nested levels of health status variables (your JSON example above didn't include the addresses nested array)

[hishamhm]

@locao Missing autodoc data for field upstreams.healthchecks.threshold ;)

[hishamhm]

@locao I noticed a small detail before hitting merge: the query-arg for the endpoint needs to be documented in the Admin API autodocs as well (grep for request_query in autodoc/data/admin-api.lua for example on documenting query args — or see #5210 😁 )

[locao]

@locao the query-arg for the endpoint needs to be documented in the Admin API autodocs as well

Good catch @hishamhm, thank you! Docs updated

changes addressed