Health Checks

By default, Koyeb automatically performs TCP health checks on your Service's exposed ports to ensure maximum availability and determine your Deployment healthiness. The TCP probe performed by default checks that a connection can be made and gracefully terminated on the Deployment's 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. If one or more health checks fail, the Deployment register an 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 checks for your Services. Koyeb allows you to override and define your own health check for each exposed port.

Customize health checks

Koyeb allows you to configure HTTP and TCP probes.

Configure a TCP health check

By default, Koyeb automatically performs a TCP health check on the exposed ports of your Service's Deployments. Depending on your needs, you can override some or all of the default health check values:

Grace period: The initial period to wait before performing the first health check. The minimum and default value is 5 seconds. The value cannot 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 cannot 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 cannot 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 cannot exceed 600 seconds.

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

Go to the Koyeb control panel (opens in a new tab) and select the Service you want to configure the health check for.
On the Settings tab, expand on the Health checks section.
For each port defined, you see a human-readable description of the health check that will be performed on the port. You can override each value you want to customize.
To apply the changes, click the Deploy button to redeploy your Service.

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

Configure an HTTP health check

If you are deploying an HTTP server, like an API or a web application, we recommend that you define custom HTTP health checks on the relevant ports. This tells the platform how to determine the health of your 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.

The path defined in the health check must return a 2xx or 3xx HTTP status code for the health check to be considered successful. 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 cannot 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 cannot 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 cannot 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 cannot 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 (opens in a new tab) and select the Service you want to configure the health check for.
On the Settings tab, expand the Health checks 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.
Change the protocol from TCP to HTTP.
Set the path to perform the health check.
To apply the changes, click the Deploy 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

If your Deployment fails and has the Error status, the following message indicates that the error is due to a health check failure: Health checks failed to pass on all Instances. Please check Instances messages for more information.

If your Deployment has an Unhealthy, Degraded, or Error status, you can click on the Instances tab to get more information and check 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.

Read the troubleshooting Deployments page to learn how to troubleshoot unhealthy Instances.

Troubleshooting Tips High Availability