HTTP¶

The http health check allows you to perform HTTP/HTTPS requests to a web server. To verify the service is working correctly there are options to send POST data, validate the response code, testing the response content and validating the SSL.

Configuration Keys¶

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

Key	Type	Default
`url`	String	undef
`response`	Optional Pattern	undef
`expected_status`	Optional Integer	undef
`require_status`	Bool	`True`
`http_timeout`	Integer	`5`
`user_agent`	String	`ExaCheck HTTP Health Check [v<version>]`
`headers`	Optional Dict	undef
`verify_ssl`	Bool	`False`
`request_method`	String	`GET`
`data`	Optional Dict	undef
`http2`	Bool	`False`

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`

Host¶

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.

Warning

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.

URL¶

The full URL to request from the web server. The actual HTTP request is sent to the web server defined in the host variable with the host header in the HTTP request being set to the value from the URL.

HTTPS requests are configured to use SNI automatically if the URL to check is a hostname.

If basic authentication is required the username/password can be added to the URL (eg. http://user:password@example.com) or the headers option can be used.

Response¶

The response value may be set to a pattern to match the content returned from the web server. If not set (the default) no checks are performed on the actual content returned by the web server.

Expected Status¶

The expected_status code may be set to ensure that the web server responds with a specific HTTP status code. In some cases you may want to validate the web server responds with a specific status code (eg. 301) and not just a 200.

Require Status¶

When the require_status option is set to True (the default), the HTTP response code must indicate that the request was successful. If expected_status is set to a non-successful response code this setting is overridden.

HTTP Timeout¶

The http_timeout option determines how long the HTTP request is allowed to wait for a response.

User Agent¶

The default user agent header can be overridden by setting the user_agent value to a custom value.

Headers¶

If additional headers are required to be sent with the HTTP request a dict of the headers may be provided. As an example:

      headers:
        Example-Header: Example-Data
        Another-Header: More-Data

Verify SSL¶

Set verify_ssl to True to validate that the SSL certificate is trusted by the systems certificate store.

Request Method¶

By default the HTTP check will make a GET request to the web server. The request_method may be set to one of the following values:

GET
POST
PUT
DELETE
HEAD
OPTIONS

Data¶

If the request_method is set to a value that allows data to be included (eg. POST requests), a dict of data can be set. As an example:

      request_method: POST
      data:
        field1: example
        field2: another example

HTTP2¶

The http2 bool can be set to True to allow HTTP2 to be used (if supported by the server) for the request. If the server does not support HTTP2 the request will proceed as normal as a HTTP1 request.

Examples¶

Some examples of HTTP health checks:

BasicDNS NameBasic AuthenticationPOST Data

A basic configuration:

---

# The list of health checks
checks:

  - name: Example Basic HTTP Check
    description: Perform a HTTP request to the web server and verify a successful response code is received
    args:
      method: http
      host: 127.0.0.1
      url: https://example.com
    prefixes:
      - 192.0.2.255
    nexthop: self

A basic configuration using a hostname as the host to connect to:

---

# The list of health checks
checks:

  - name: Example Basic HTTP Check
    description: >
      Perform a HTTP request to example.com. The IPv4 address for example.com will be resolved.
      If there are multiple IP addresses available, a response from any is considered successful.
    args:
      method: http
      host: example.com
      url: https://example.com
      address_family: ipv4
      all_valid: false
    prefixes:
      - 192.0.2.255
    nexthop: self

A HTTP check that requires basic authentication:

---

# The list of health checks
checks:

  - name: Example HTTP Check with Authentication
    description: Perform a HTTP request which requires basic authentication
    args:
      method: http
      host: 127.0.0.1
      url: https://user:password@example.com
      verify_ssl: true
      expected_status: 200
    prefixes:
      - 2001:db8::ffff/128
    nexthop: self

A HTTP check which includes POST data:

---

# The list of health checks
checks:

  - name: Example HTTP Check with POST data
    description: Send a HTTP POST request to a web server
    args:
      method: http
      host: 192.0.2.50
      url: https://www.example.com/submit.php
      verify_ssl: true
      request_method: POST
      data:
        field1: First field of data
        field2: Another field of data
    prefixes:
      - 192.0.2.240/32
      - 192.0.2.0/29
    nexthop: 192.0.2.50