Kubernetes Integration

Configure Kubernetes liveness and readiness probes with Connectum health checks, and report health status during graceful shutdown.

HTTP Probes

The HTTP probe examples below use HTTP/1.1. For a plaintext Connectum server, keep allowHTTP1: true (the default). A plaintext h2c server uses allowHTTP1: false; use the gRPC probes below for that configuration.

The built-in /healthz, /health, and /readyz endpoints report the same aggregate status. They do not maintain separate liveness and readiness states; use them only when the same dependency and service failures should affect both probes. See Health protocol for the status model.

apiVersion: v1
kind: Pod
spec:
  containers:
    - name: my-service
      image: my-service:latest
      ports:
        - containerPort: 5000
      livenessProbe:
        httpGet:
          path: /healthz
          port: 5000
        initialDelaySeconds: 5
        periodSeconds: 10
        failureThreshold: 3
      readinessProbe:
        httpGet:
          path: /readyz
          port: 5000
        initialDelaySeconds: 3
        periodSeconds: 5
        failureThreshold: 2

Requires httpEnabled: true in the Healthcheck protocol:

protocols: [Healthcheck({ httpEnabled: true })]

gRPC Probes (Kubernetes 1.27+)

Built-in gRPC probes are stable since Kubernetes 1.27. The following probes use a plaintext gRPC endpoint:

livenessProbe:
  grpc:
    port: 5000
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  grpc:
    port: 5000
    service: my.service.v1.MyService
  initialDelaySeconds: 3
  periodSeconds: 5

gRPC probes use the grpc.health.v1.Health/Check method directly -- no HTTP endpoint needed.

Configure a plaintext HTTP/2 transport with allowHTTP1: false and register Healthcheck() on the server. The default plaintext HTTP/1.1 transport cannot serve these gRPC probes. See Transport configuration.

Graceful Shutdown Integration

Report service status through lifecycle events:

import { createServer } from '@connectum/core';
import {
  Healthcheck,
  healthcheckManager,
  ServingStatus,
} from '@connectum/healthcheck';

const server = createServer({
  services: [routes],
  protocols: [Healthcheck({ httpEnabled: true })],
  shutdown: {
    autoShutdown: true,
    timeout: 25000,  // Connection drain only; budget hooks separately
  },
});

server.on('ready', () => {
  healthcheckManager.update(ServingStatus.SERVING);
});

// When shutdown begins, mark as NOT_SERVING
// Subsequent readiness probes observe NOT_SERVING
server.on('stopping', () => {
  healthcheckManager.update(ServingStatus.NOT_SERVING);
});

await server.start();

Pod Specification

apiVersion: v1
kind: Pod
spec:
  # Include preStop, connection drain, bounded hooks, and a safety margin.
  terminationGracePeriodSeconds: 45
  containers:
    - name: my-service
      image: my-service:latest
      ports:
        - containerPort: 5000
      readinessProbe:
        httpGet:
          path: /healthz
          port: 5000
        periodSeconds: 5
      lifecycle:
        preStop:
          exec:
            # Give load balancers time to remove this pod
            command: ["sleep", "5"]

Shutdown Timeline

The stopping handler marks health status NOT_SERVING. Pod termination and readiness updates are managed separately by Kubernetes. Leave enough grace time for preStop, request draining, and hooks; see the canonical graceful shutdown timeline for the complete sequence and timing boundaries.

Critical

terminationGracePeriodSeconds must cover more than shutdown.timeout: it also includes preStop and shutdown hooks. Use the budget described in the linked shutdown guide; otherwise Kubernetes may kill the process before cleanup finishes.

Related

• Health Checks Overview -- back to overview
• Protocol Details -- gRPC methods, HTTP endpoints, configuration
• Graceful Shutdown -- shutdown options, hooks, lifecycle events
• Kubernetes Deployment -- full deployment guide
• @connectum/healthcheck -- Package Guide