extern/zrok
1
1
Fork 0
mirror of https://github.com/openziti/zrok.git synced 2025-08-14 10:08:26 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs (#1002)

Browse Source
This commit is contained in:
Michael Quigley
2025-07-18 13:37:00 -04:00
parent a6f04bfb0c
commit e752b29bfa
1 changed files with 66 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

66
docs/guides/agent/http-healthcheck.mdx Normal file
View File

@ -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'"
}
```