Managing health checks
The Appclacks CLI can be used to manage health checks
How health checks are executed
You can choose when you create an health check if it should be executed or not by the Appclacks cloud platform.
It’s possible to create health checks on Appclacks but to host yourself the prober executing the health check, or to execute it by both Appclacks and on your infrastructure. See the Appclacks on your private infrastructure guide for more information about self-hosting.
Health check types
Appclacks supports 5 healthchecks types (detailed options for each type are described at the end of this page):
HTTP(s)
: An HTTP request will be executed on the target. You can configure a lot of options about the health check request (method, path, headers, protocol, TLS configuration, body…) or the expected response (status code, body).TCP
: A TCP connection will be initiated with the target. You can also use this kind of health check to check that a TCP target is not responding, to be sure that a component is not exposed on the internet for example.TLS
: A TLS connection will be initiated by the target. If you host the prober yourself you can even configure which certificates to use for the connection.DNS
: A DNS resolution will be executed on a domain. You can use it to see if the resolution is working and to check the IP returned by it.Command
: An arbitrary shell command (with optional arguments) will be executed. The health check is considered failed if the command fails to execute. This health check type cannot be executed by the Appclacks cloud platform but can run in your private infrastructure.
Creating an health check
Use the appclacks healthcheck <type> create
command to create a health check, where <type>
is the health check type (http
, tcp
, tls
, dns
, command
).
In this example, we create an HTTP health check targeting appclacks.com
. You can see in the response (in json due to the --output
option) the default values for HTTP health checks.
$ appclacks healthcheck http create --name "hello" --target "appclacks.com" --output json
{"id":"caaa5899-26a7-4a91-a77a-86adc849d23e","name":"hello","type":"http","timeout":"5s","interval":"60s","created-at":"2022-12-04T21:47:03.592347391Z","enabled":true,"Definition":{"valid-status":[200],"target":"appclacks.com","method":"GET","port":443,"redirect":true,"protocol":"https"}}
The --disabled
flag controls whether or not the health check should be executed by the Appclacks cloud platform. If set, the health check enabled
field will be set to false and the health will not be executed by Appclacks. Disabling health checks can be useful if you self-host the Appclacks prober and want to execute these checks on your private infrastructure.
Use the --help
command to get details about health checks options, for example appclacks healthcheck http create --help
. The available options are also explained at the end of this page for each health check type.
Some health check types and parameters cannot be used for health checks running one Appclacks cloud platform:
command
health checks cannot be enabled on the Cloud platform.- TLS and HTTP health checks: the TLS configurations parameters (
key
,cert
,cacert
) cannot be used. - The local interface (
localhost
,127.0.0.1
…) cannot be used as a health check target.
Managing health checks
The appclacks healthcheck list
and appclacks healthcheck get --id <healthcheck_id>
(get
also supports --name <healthcheck_name>
) commands can be used to retrieve health checks information.
You can update an existing health check with the appclacks healthcheck <type> update
commands. All health checks fields which you want to configure should be specified, the update is a replace.
Health checks results
Each time a health check is executed by the Appclacks cloud platform, its result is stored and available through the Appclacks API.
The appclacks healthcheck result list
command retrieves health checks results. By default, all health check results from the last 5 minutes are retrieved. +
Health checks results are paginated and only 100 results are returned. The --page
option can be used to retrieve the next results from the list.
You can also configure which results you want to retrieve with the flags:
--healthcheck-id
: Get the results for a specific health check only.--start-date
: The start date (UTC) for retrieving results, in format2006-01-02T15:04:05
.--end-date
: The end date (UTC) for retrieving results, in the format2006-01-02T15:04:05
.--end-date
: The end date (UTC) for retrieving results, in the format2006-01-02T15:04:05
.--error
: Retrieve only failed health checks.--success
: Retrieve only successful health checks.
Health checks options reference
Common fields
These fields are available to all health checks:
name
: the health check name. It should be unique.description
: an optional health check description (optional)labels
: key/value pairs of strings, useful to add metadata to health checks (optional, exampleenvironment=production
)interval
: the health check execution interval (example:30s
for 30 seconds,1m
for one minute…).timeout
: the health check execution timeout (example:3s
for 3 seconds)enabled
: Enable or not the health check on the Appclacks cloud platform. Only enabled health checks are executed by Appclacks. Setting health checks can be useful if you only want to self-host the Appclacks prober.
HTTP
valid-status
: a list of HTTP status code to consider the health check successful (example:200
,201
).target
: the URL or IP address to target (example:api.appclacks.com
).method
: the HTTP method to use (example:GET
).port
: the port to target (example:443
).protocol
: the protocol to use (http
orhttps
)host
: override the HTTP Host header (optional, example:api.appclacks.com
).redirect
: follow redirect (optional, defaultfalse
).query
: HTTP query parameters to pass to the request (optional).body
: HTTP query to pass to the request (optional).body-regexp
: A list of regular expressions on which the HTTP response body will be matched. The health check is considered failed if the response body does not have the regular expressions (optional).headers
: extra HTTP headers to pass to the request (optional).key
: A path to a file containing a certificate private key for mTLS (optional).cert
: A path to a file containing a certificate public key for mTLS (optional).cacert
: A path to a file containing certificates authorities to trust (optional).server-name
: the server name identifier to use (optional).insecure
: enable insecure TLS (default tofalse
)
TCP
target
: the URL or IP address to target (example:api.appclacks.com
).port
: the port to target (example:443
).should-fail
: if set to true, the health check will be considered successful if the TCP connection fails (default tofalse
).
TLS
target
: the URL or IP address to target (example:api.appclacks.com
).port
: the port to target (example:443
).key
: A path to a file containing a certificate private key for mTLS (optional).cert
: A path to a file containing a certificate public key for mTLS (optional).cacert
: A path to a file containing certificates authorities to trust (optional).server-name
: the server name identifier to use (optional).insecure
: enable insecure TLS (default tofalse
)expiration-delay
: duration before alerting for the target certificat expiration date (optional, for example an expiration delay of48h
would make the health check fails if the certificate expires in less than 48 hours).
DNS
domain
: the domain to target (example:google.com
)expected-ips
: a list of IP ddresses (v4 or v6) that should be present in the DNS answer to consider the health checks successful (optional)
Command
command
: the command to execute (example:ls
)arguments
: the list of arguments to pass th the command (example:-l
).