Kubernetes Integration

Configure Kubernetes liveness and readiness probes with Connectum health checks, and integrate with graceful shutdown for zero-downtime deployments.

HTTP Probes

HTTP probes are the simplest approach and work with all Kubernetes versions:

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.24+)

Kubernetes 1.24+ supports gRPC health probes natively:

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.

Graceful Shutdown Integration

Combine health checks with lifecycle events for zero-downtime deployments:

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,  // Less than Kubernetes terminationGracePeriodSeconds
  },
});

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

// When shutdown begins, mark as NOT_SERVING
// Kubernetes stops routing traffic to this pod
server.on('stopping', () => {
  healthcheckManager.update(ServingStatus.NOT_SERVING);
});

await server.start();

Pod Specification

apiVersion: v1
kind: Pod
spec:
  terminationGracePeriodSeconds: 30  # Must be > shutdown.timeout
  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

At shutdown, mark the service NOT_SERVING before Kubernetes removes the pod from endpoints, then leave enough grace time for request draining and hooks. See the canonical graceful shutdown timeline for the complete sequence and timing boundaries.

Critical

Always set shutdown.timeout to a value less than Kubernetes terminationGracePeriodSeconds. Otherwise, Kubernetes may SIGKILL the process before your shutdown hooks complete.

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