HTTP plugin
The HTTP plugin provides checks for HTTP services, and HTTP-based alerts.
Checks
http.get
check http.get "example" {
url = "https://www.example.com/"
content = "Example Domain"
content_expected = true
min_status_code = 200
max_status_code = 399
certificate_validity = 10d
network = "tcp6"
auth {
username = "acidburn"
password = "HackThePlanet"
}
}
Sends an HTTP GET request to the given URL.
The min_status_code and max_status_code parameter specify the allowed range for the
response's HTTP status code. These default to 100 and 399 (i.e., any non-error response).
If you wish to test a URL denies access to unauthenticated users, for example, you can use
min_status_code=401 max_status_code=403; to check for a single status code the two parameters
can be the same, e.g. min_status_code=418 max_status_code=418. Both must be between 100
and 599, and min_status_code must not be greater than max_status_code.
If the content parameter is specified then the response body is checked for the exact string.
By default the string must be present, and the check will fail if it is not. If content_expected
is set to false then the string must NOT be present, and the check will fail if it is.
If the certificate_validity parameter is specified, then the connection must have
been made over TLS, and the returned certificate must be valid for at least the given duration
from now. (An expired or untrusted certificate will cause a failure regardless of this setting.)
If the auth settings are provided, they will be sent in a Basic authentication header. Note
that basic authentication isn't encrypted, so shouldn't be used over an insecure connection.
By default, connections are made over TCP using IPv6 or IPv4 (whichever connects first). Set
network to "tcp4" or "tcp6" to only connect over IPv4 or IPv6, for example to check each
family of a dual-stack site separately. The check fails if the host has no address in that family.
Redirects are followed over the same family. If a proxy is configured, only the connection to the
proxy is limited.
http.healthcheck
check http.healthcheck "example" {
url = "https://www.example.com/health"
check_components = true
network = "tcp4"
auth {
username = "acidburn"
password = "HackThePlanet"
}
}
Retrieves the current status from a HTTP healthcheck endpoint. The endpoint is expected
to return JSON in a manner compatible with
draft-inadarei-api-health-check-04. The
check fails if the response isn't valid JSON, its status is missing or not recognised, or
it has a 4xx or 5xx HTTP status code (whatever its status says).
If the check_components setting is enabled, the state of each component/dependency
reported in the healthcheck response will also be verified. This means if the overall service
status is pass but a component is fail then the Goplum check will fail.
If the auth settings are provided, they will be sent in a Basic authentication header. Note
that basic authentication isn't encrypted, so shouldn't be used over an insecure connection.
The network setting limits connections to IPv4 or IPv6, as for http.get.
Alerts
http.webhook
alert http.webhook "example" {
url = "https://www.example.com/incoming"
headers = ["Authorization: Bearer token123"] # optional
secret = "my-secret-key" # optional
}
Sends alerts as a POST request to the given webhook URL with a JSON payload.
If the headers parameter is specified, each entry is sent as an additional HTTP header on the
request. Headers should be specified in "Name: Value" format. Multiple values for the same header
name can be provided by including multiple entries.
If the secret parameter is specified, an X-Goplum-Signature header is included with each request
containing a HMAC-SHA256 signature of the request body, prefixed with sha256=. This can be used
by the receiving endpoint to verify that the request was sent by Goplum.
The payload includes the check's configuration. Values that may contain secrets, such as passwords,
are replaced with "[redacted]". Passwords embedded in URLs (https://user:pass@host/) are
replaced with xxxxx.
{
"text": "Check 'example' is now failing (Bad status code: 503), was good.",
"name": "example",
"type": "http.get",
"config": {
"Url": "https://www.example.com/",
"Auth": {
"Username": "acidburn",
"Password": "[redacted]"
},
"Network": "tcp",
"Content": "Example Domain",
"ContentExpected": true,
"CertificateValidity": 864000000000000,
"MinStatusCode": 200,
"MaxStatusCode": 399
},
"last_result": {
"state": "failing",
"time": "2020-09-17T17:55:02.224973486+01:00",
"detail": "Bad status code: 503",
"facts": {
"chameth.com/goplum#check_time": 212264
}
},
"previous_state": "good",
"new_state": "failing",
"is_reminder": false,
"link": "https://wiki.example.com/runbooks/example"
}