diff --git a/docs/guides/agent/http-healthcheck.mdx b/docs/guides/agent/http-healthcheck.mdx new file mode 100644 index 00000000..07a114e6 --- /dev/null +++ b/docs/guides/agent/http-healthcheck.mdx @@ -0,0 +1,66 @@ +--- +title: HTTP Health Checks +sidebar_label: HTTP Health Checks +sidebar_position: 30 +--- + +As of `v1.0.7` the zrok Agent supports health checks for `proxy` backend shares. Backend health checks are not yet implemented for other backend modes. + +## Local Agent Health Checks + +With an Agent running in your environment, create a share: + +``` +$ zrok share public http://127.0.0.1:18080 +token:"8rvjpmeeyvwc" frontendEndpoints:"http://8rvjpmeeyvwc.zrok.example.com:8080" +``` + +Then the new `zrok agent share http-healthcheck` command can be used to validate that the Agent is able to communicate with the backend target: + +``` +$ zrok agent share http-healthcheck 8rvjpmeeyvwc GET / 200 +healthy +``` + +A non-existent endpoint will return a non-`200` response: +``` +$ zrok agent share http-healthcheck 8rvjpmeeyvwc GET /non-existent 200 +unhealthy; unexpected status code; got '202', want '200' +``` + +### Detecting Communications Errors + +This health check infrastructure will report any issue communicating with the underlying backend target, including low-level communication errors: + +``` +$ zrok share public http://127.1.1.1:9090 +token:"2bfvnne6kb3c" frontendEndpoints:"http://2bfvnne6kb3c.zrok.quigley.com:8080" + +$ zrok agent share http-healthcheck 2bfvnne6kb3c GET / 200 +unhealthy; failed to execute request: Get "http://127.1.1.1:9090/": dial tcp 127.1.1.1:9090: connect: connection refused +``` + +## Remoted Agent Health Checks + +When your Agent is remoted and accessible through the zrok API, you can use the `/agent/share/http-healthcheck` endpoint to remotely check your Agent's connectivity to the backend target: + +``` +$ curl -H "X-TOKEN: 5hLXj48Bmn11" -XPOST -H "Content-Type: application/zrok.v1+json" -d '{"envZId": "MxMbUXSANU", "shareToken": "8rvjpmeeyvwc", "httpVerb": "GET", "endpoint": "/", "expectedHttpResponse": 200}' http://localhost:18080/api/v1/agent/share/http-healthcheck | jq + % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 136 100 17 100 119 267 1870 --:--:-- --:--:-- --:--:-- 2158 +{ + "healthy": true +} +``` + +A non-existent health check URL will return a non-`200` response: +``` +$ curl -H "X-TOKEN: 5hLXj48Bmn11" -XPOST -H "Content-Type: application/zrok.v1+json" -d '{"envZId": "MxMbUXSANU", "shareToken": "8rvjpmeeyvwc", "httpVerb": "GET", "endpoint": "/non-existent", "expectedHttpResponse": 200}' http://localhost:18080/api/v1/agent/share/http-healthcheck | jq % Total % Received % Xferd Average Speed Time Time Time Current + Dload Upload Total Spent Left Speed +100 189 100 58 100 131 866 1956 --:--:-- --:--:-- --:--:-- 2863 +{ + "error": "unexpected status code; got '202', want '200'" +} +``` +