Improve load balancer docs

Author: whoshuu

datacenter/dtr/2.2/guides/admin/configure/use-a-load-balancer.md

@@ -24,35 +24,65 @@ 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)
 * Metadata persistence (rethinkdb)
 * 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.
-
-In addition, this endpoint returns a dump of the rethink system tables
-which can be rather large (~45 KB) for a status endpoint.
+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:
+
+```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