Health checks

The cache health check endpoint is used to determine whether an application container is healthy, and allows the VIP edge load balancers to identify application containers that are extremely busy or non-responsive. If the health check request is not handled quickly, or if it returns a HTTP status code other than 200, the application container will be marked “unhealthy”. Unhealthy containers will not receive traffic for a short time until they have recovered.

• Applications with inconsistent or poor health checks can be unstable, can experience downtime, and can fail to deploy.
• The VIP Platform sends frequent health checks to all Node.js applications at this endpoint: /cache-healthcheck?
• The structure of this endpoint cannot be customized, and must include an empty query string (?) and lack a trailing slash.
• Because Node.js server implementations vary widely, VIP cannot implement this health check endpoint automatically. Therefore, as a requirement for running on the VIP platform, all Node.js applications must implement this endpoint using application code.
• Examples in the Node.js skeleton and Next.js boilerplate repositories show methods for implementing the health check endpoint in several popular Node.js frameworks.

Strategies for successful health checks

• First and final. Take a “first and final” approach when implementing the health check endpoint: It should be the first thing an application does when responding to a request, and the result should be final—that is, it should return a response immediately without giving other code an opportunity to modify it.
• Postpone heavy operations. Delay any intensive or asynchronous operations (like fetching data) until after the health check has been handled. Applications should provide a consistently quick response that is not dependent on any external systems.
• Postpone redirects. The health check should be handled before any redirects are implemented by an application. This prevents accidental matches that could cause the health check endpoint to respond with 3xx instead of 200. Be especially aware of any “trailing-slash redirects” implemented by an application or its underlying framework.
• Ignore the hostname. Only consider the path (/cache-healthcheck?) when identifying health check requests. Health checks are sent internally within VIP’s platform, so they do not use custom / mapped domains.
• Keep it short. Health checks are frequent and the response body is ignored, so short responses save time. Consider responding with “Ok” to allow quick, human validation.

Simulate a health check on a local machine

For a Node.js application that is running on a local machine, curl -I can be run against the application’s health check endpoint to check the status.

In this example, curl -I is run against an application running at http://localhost:3000:

$ curl -I "http://localhost:3000/cache-healthcheck?"
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: text/plain; charset=utf-8
Content-Length: 2

The HTTP status code 200 is returned in the command output, indicating that the application passes the health check. Any status code other than 200 indicates a failed health check.

Preflight checks

vip-go-preflight-checks npm package

For Node.js application code that is running on a local machine, a vip-go-preflight-checks npm package can conduct “preflight checks” to verify that the health check has been implemented correctly. This health check can be run without a user having access to the VIP Dashboard of the codebase’s application.

In the local machine’s terminal, navigate (cd) to the root of the Node.js project and run the command:

npx @automattic/vip-go-preflight-checks

VIP-CLI preflight validation

For Node.js application code that is running on a local machine, the VIP-CLI command vip validate preflight can conduct a full suite of preflight validation tests, including a test to verify that the health check has been implemented correctly. By targeting a specific application and environment in the command, the tests will run with settings that are identical to the targeted environment.

In this example command, preflight validation tests will run with settings that are identical to the develop environment of the “example-node-app” application, against a codebase on a user’s local machine found in the directory node-repo/:

vip @example-node-app.develop validate preflight --path=/Users/example-user/node-repo/