knot.healthcheck

The knot.healthcheck library provides functions for space health monitoring. It is only available in agent-side health check scripts. The check functions (http_head, tcp_port, program) return True or False so you can combine them, then call check_result() to report the final status and exit.

Template health checks can also use the Agent type. Agent health checks do not run a script; the server watches for the space agent to stop transmitting state. If auto-restart is enabled and the agent stops transmitting, Knot marks the space unhealthy and starts a restart cycle for local-container and Nomad spaces. Automatic failed-node migration (restarting the space on a different live node) requires Knot Pro Pro .

Execution Environment

Functions

Optional arguments can be passed positionally or by keyword, e.g. hc.http_head(url, timeout=5) or hc.http_head(url, True, 5).

Usage

import knot.healthcheck as hc

# Simple HTTP check
hc.check_result(hc.http_head("http://localhost:8080/health"))

# Simple TCP check
hc.check_result(hc.tcp_port(8080))

# Combine multiple checks
ok = hc.http_head("http://localhost:8080/health") and hc.tcp_port(6379)
hc.check_result(ok)

# Custom logic, with per-check timeouts
ok = hc.tcp_port(5432, timeout=2) and hc.program("pg_isready -q", timeout=5)
hc.check_result(ok)

# HTTPS endpoint with a self-signed certificate
hc.check_result(hc.http_head("https://localhost:8443/health", skip_ssl_verify=True, timeout=5))

Function Details

http_head(url, skip_ssl_verify=False, timeout=10)

Perform an HTTP HEAD request. Returns True if the response status code is 200, False for any other status or connection error.

Parameters:

• url (string): The URL to check
• skip_ssl_verify (bool, optional): Skip TLS certificate verification (default: False)
• timeout (int, optional): Request timeout in seconds (default: 10)

Returns: bool — True if healthy

tcp_port(port, timeout=10)

Attempt a TCP connection to 127.0.0.1 on the given port. Returns True if the connection succeeds.

Parameters:

• port (int): The port number to check
• timeout (int, optional): Connection timeout in seconds (default: 10)

Returns: bool — True if healthy

program(command, timeout=10)

Run a program. Returns True if it exits with code 0, False for any non-zero exit code, timeout or error.

The command is not run through a shell: it is split on whitespace into the program and its arguments, so quoting, pipes, redirects, &&, globs and environment variable expansion are not supported. To use shell features, call the shell explicitly with a script file (e.g. program("/bin/sh /opt/check.sh")) or write a custom check.

Parameters:

• command (string): The program and its arguments, separated by whitespace
• timeout (int, optional): Execution timeout in seconds (default: 10)

Returns: bool — True if healthy

check_result(healthy)

Report the final health check result and exit the script immediately.

Parameters:

• healthy (bool): True for healthy, False for unhealthy

How Health Check Scripts Run

When a template configures a script-backed health check type (HTTP, TCP, or Program), the agent automatically generates and runs a script using these functions, passing the template’s timeout (and, for HTTP, its skip-TLS-verification setting) as keyword arguments. For the custom health check type, you write a script that imports knot.healthcheck directly, combines check functions as needed, and calls check_result() with the final result. The Agent health check type is handled by the server and does not use this library.

Health check scripts run inside the space under the agent and share the full Space environment with every other agent-side script — the standard and extended scriptling libraries plus knot.* libraries. They have no knot.apiclient transport, so the API libraries are not usable there.