diff --git a/datacenter/dtr/2.2/guides/admin/configure/use-a-load-balancer.md b/datacenter/dtr/2.2/guides/admin/configure/use-a-load-balancer.md index 64770ae51e..dd02e338e4 100644 --- a/datacenter/dtr/2.2/guides/admin/configure/use-a-load-balancer.md +++ b/datacenter/dtr/2.2/guides/admin/configure/use-a-load-balancer.md @@ -24,18 +24,27 @@ Make sure you configure your load balancer to: * Load balance TCP traffic on ports 80 and 443 * Not terminate HTTPS connections -* Use the `/health` endpoint (note the lack of an `/api/v0/` in the path) on each -DTR replica, to check if the replica is healthy and if it should remain on the -load balancing pool or not +* Use the unauthenticated `/health` endpoint (note the lack of an `/api/v0/` in +the path) on each DTR replica, to check if the replica is healthy and if it +should remain in the load balancing pool or not ## Health check endpoints -The `/health` endpoint returns a JSON object for the replica being queried with -`"Healthy"` as one of the keys. Any response other than a 200 HTTP status code -and `"Healthy":true` means the replica is unsuitable for taking requests. If -the API server is still up, the returned JSON object will have an `"Error"` key -with more details. More specifically, these issues can be in any of these -services: +The `/health` endpoint returns a JSON object for the replica being queried of +the form: + +```json +{ + "Error": "error message", + "Health": true +} +``` + +A response of `"Healthy": true` means the replica is suitable for taking +requests. It is also sufficient to check whether the HTTP status code is 200. + +An unhealthy replica will return 503 as the status code and populate `"Error"` +with more details on any one of these services: * Storage container (registry) * Authorization (garant) @@ -43,16 +52,37 @@ services: * Content trust (notary) Note that this endpoint is for checking the health of a *single* replica. To get -the health of every replica in a cluster, querying each individual replica is +the health of every replica in a cluster, querying each replica individiually is the preferred way to do it in real time. -The `/api/v0/meta/cluster_status` endpoint returns a JSON object for the entire -cluster *as observed* by the replica being queried. Health status for the -replicas is available in the `"replica_health"` key. These statuses are taken -from a cache which is updated by each replica individually. +The `/api/v0/meta/cluster_status` +[endpoint](https://docs.docker.com/datacenter/dtr/2.2/reference/api/) +returns a JSON object for the entire cluster *as observed* by the replica being +queried, and it takes the form: -In addition, this endpoint returns a dump of the rethink system tables -which can be rather large (~45 KB) for a status endpoint. +```json +{ + "replica_health": { + "replica id": "OK", + "another replica id": "error message" + }, + "replica_timestamp": { + "replica id": "2006-01-02T15:04:05Z07:00", + "another replica id": "2006-01-02T15:04:05Z07:00" + }, + // other fields +} +} +``` + +Health statuses for the replicas is available in the `"replica_health"` object. +These statuses are taken from a cache which is last updated by each replica +individually at the time specified in the `"replica_timestamp"` object. + +The response also contains information about the internal DTR storage state, +which is around 45 KB of data. This, combined with the fact that the endpoint +requires admin credentials, means it is not particularly appropriate for load +balance checks. Use `/health` instead for those kinds of checks. ## Where to go next