Skip to content


The tcp health check is used to open a TCP connection to the supplied host/port. No data is sent over the connection; the test is only to validate that the port can be connected to.

Configuration Keys

The following configuration options apply to the DNS health check method:

Key Type Default
port Integer undef
tcp_timeout Integer 5

Remote Check Options

As this is a remote check, the following additional options are supported:

Key Type Default
host String undef
address_family Optional String undef
all_valid Bool False

The host field contains the IP address or hostname that the health check should be executed against. If a hostname is supplied, each health check execution will perform a DNS resolution to ensure the current IP is used.

As the hostname may resolve to multiple addresses and/or address families (eg. IPv4 and IPv6) the address_family and all_valid options can be used to control what happens in those situations.


If specifying a host name instead of an IP address, temporary DNS resolution errors will cause the health check to fail. Specify an IP address to avoid this behaviour.

Address Family

The address_family key is used when host is set to a hostname. Should the hostname resolve to an IPv4 and IPv6 address you may want the check to only be sent to a single address family rather than both.

The values ipv4 or ipv6 are supported. If not defined there is no filtering for IPv4 or IPv6 addresses applied.

All Valid

The all_valid key is used when host is set to a hostname. If the hostname resolves to multiple IP addresses and all_valid is set to True, the health check will be executed against all IP addresses available. Should the health check to any IP address fail the service will be marked as down.

If set to the default False value a successful health check from any IP address is considered valid and the service will be marked up.


The port value defines which port the connection should be made to.

TCP Timeout

The tcp_timeout controls the timeout for opening the TCP connection.


An example TCP check:


# The list of health checks

  - name: Example TCP Check
    description: Ensure that the IP responds on port 80
      method: tcp
      port: 80
    nexthop: self