kubernetes-health

A helper library for implementing Kubernetes heath checks and graceful HTTP shutdown in Node applications.

• Installation
• Usage
• API
• Examples
  • Standalone Health Server
  • Express
• License

Installation

Install using your preferred package manager:

$ yarn add kubernetes-health
$ pnpm add kubernetes-health
$ npm install kubernetes-health

Usage

kubernetes-health supports many different configuration options, can integrate with existing HTTP frameworks, can run tasks on termination, and and can gracefully handle in-flight HTTP requests. See below for more details.

To get started:

1. First, create a new Health instance to track your application health:

   import {Health} from 'kubernetes-health'
   
   const health = new Health()

2. Then once your application is ready to receive requests, mark its status as ready:

   health.markReady()

3. You will need to expose this health status to Kubernetes via an HTTP endpoint, the easiest way to do this is to start a standalone health server with startProbeServer():

   import {startProbeServer} from 'kubernetes-health'
   
   startProbeServer(health)

   This will serve the endpoints /healthz and /readyz on port 4000 (all configurable, see below). These endpoints can thus be referenced from the liveness, readiness, and startup probes.

API

Read the API documentation.

Examples

Standalone Health Server

To serve a standard Node http.Server for the liveness and readiness endpoints:

import {Health, startProbeServer} from 'kubernetes-health'
const health = new Health()

startProbeServer(health)

To create a new Node http.Server, but not automatically listen:

import {Health, createProbeServer} from 'kubernetes-health'
const health = new Health()

const server = createProbeServer(health)

Express

To mark the application as ready when the server is listening, and gracefully handle in-flight requests during termination:

import {Health, gracefulHttpTerminatorTask} from 'kubernetes-health'
import express from 'express'

const health = new Health()
const app = express()

// ...

const server = app.listen(3000, () => {
  health.markReady()
})

health.beforeTermination(gracefulHttpTerminatorTask(server))

To integrate the liveness and readiness endpoints into an existing Express application:

import {Health, createLivenessProbeListener, createReadinessProbeListener} from 'kubernetes-health'
import express from 'express'

const health = new Health()
const app = express()

app.get('/healthz', createLivenessProbeListener(health))
app.get('/readyz', createReadinessProbeListener(health))

License

MIT License, see LICENSE.