Health Checks

By default, Koyeb automatically performs TCP health checks on your service deployment's exposed ports to ensure maximum availability and determine your deployment healthiness. The TCP probe performed by default checks a connection can be made and gracefully terminated on the deployment exposed ports.

These default health checks run on a repeating basis and are used at different stages of the deployment:

At Startup: To determine when your deployment is ready to accept traffic
Liveness: To determine when one or more of your deployment instances become unresponsive and need to be restarted

To start receiving traffic, all health checks must pass for all ports exposed on your service deployment. If one or all health checks fail for fifteen minutes, your service deployment will have the Error status. In that case, the previous Healthy deployment will continue to receive traffic until a new deployment reaches the Healthy status. If no previous deployment was successfully promoted, your service will not receive traffic.

Depending on the application you deploy, you may need more control over defining the health status of your service deployments. Koyeb allows you to override and define your own health check for each exposed port.

This documentation explains how to:

Customize health checks
- Configure a TCP health check
- Configure a HTTP health check
Monitor health checks

Customize health checks

Koyeb allows you to configure HTTP and TCP probes. Note that we plan to support more probes in the future like gRPC, QUIC, and more.

Configure a TCP health check

As previously mentioned, by default, Koyeb automatically performs a TCP health check on your service deployment exposed ports. Depending on your needs, you can override a part or all values of the default health check:

Grace period: The initial period to wait before performing the first health check. The minimum and default value is 5 seconds. The value can't exceed 300 seconds.
Interval: The interval in seconds between two health checks. The default value is 60 seconds. The minimum value is 30 seconds. The value can't exceed 300 seconds.
Restart limit: The number of consecutive failures before attempting to restart the instance. The default value is 3. The minimum value is 1. The value can't exceed 10 attempts.
Timeout: The time to wait in seconds before considering the check as a failure. The default value is 5 seconds. The minimum value is 1 second. The value can't exceed 600 seconds.

To customize the TCP health check using the Koyeb control panel, proceed as follows:

Go to the Koyeb control panel and select the service you want to configure the health check
On the Settings tab, click on the Advanced button and go to the Exposing your service section
For each port defined, you see a human-readable description of the health check that will be performed on the port. Click Customize health check to override the default health check
A dialog box opens with the health check configuration. You can override each value you want to customize and click the Save button
To apply the changes, click the Apply button to redeploy your service

Your health checks will be active when your new deployment is live.

Configure a HTTP health check

If you are deploying an HTTP server, like an API or a web application, we recommend you define custom HTTP health checks on relevant ports to indicate how Koyeb should determine the health of your service deployment. An HTTP probe allows you to check the status at the application level by sending an HTTP request to a specific path and expecting a specific HTTP status code in return.

For your health check to be considered successful, the path defined in the health check must return a 2xx or 3xx HTTP status code. Any other status code will be considered a failure.

By defining a custom HTTP health check, you can customize the following values:

Path: The path to perform the HTTP health check.
Method: The HTTP method to use to perform the health check. The default value is GET. You can change the method by one of the following GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, or TRACE.
Headers: A list of key/value pairs of HTTP headers to be sent to the server.
Grace period: The initial period to wait before performing the first health check. The minimum and default value is 5 seconds. The value can't exceed 300 seconds.
Interval: The interval in seconds between two health checks. The default value is 60 seconds. The minimum value is 30 seconds. The value can't exceed 300 seconds.
Restart limit: The number of consecutive failures before attempting to restart the instance. The default value is 3. The minimum value is 1. The value can't exceed 10.
Timeout: The time to wait in seconds before considering the check as a failure. The default value is 5 seconds. The minimum value is 1 second. The value can't exceed 600 seconds.

To customize and create an HTTP health check using the Koyeb control panel, proceed as follows:

Go to the Koyeb control panel and select the service you want to configure the health check
On the Settings tab, click on the Advanced button and go to the Exposing your service section
For each port defined, you see a human-readable description of the health check that will be performed on the port. Click Customize health check to override the default health check
A dialog box opens with the health check configuration
Change the protocol from TCP to HTTP
Set the path to perform the health check
Override each value you want to customize and click the Save button
To apply the changes, click the Apply button to redeploy your service

Your health checks will be active when your new deployment is live.

Monitor health checks

You can monitor the status of the health checks performed on your service deployments by looking at:

In addition to these statuses, a message is displayed to provide more details about the current state of the deployment and its instances.

Error messages

When your deployment failed and has the Error status, you can know if the error is due to a health check failure if the following message appears: Health checks failed to pass on all instances. Please check instances messages for more information.

In the case your deployment has the Unhealthy, Degraded, or Error status, you can click on the Instances tab to get more information and visualize if this status is related to a health check failure by looking at the status and message of the instances. For example, if an HTTP health check fails to pass on port 8080 you will see the following message on your deployment instances: HTTP health check on port 8080 failed.