Deployments · Health checks

Health checks

The probe ComputeSphere uses to decide whether each new spherelet is ready to serve traffic. Until enough checks pass, the rollout holds — your old spherelets keep serving requests, and a broken deploy can't take production down.

How it fits the rollout

Every deployment goes through the five-phase lifecycle. The fourth phase is the health check. New spherelets must respond successfully on your configured path or port a configurable number of times before traffic shifts to them. If they don't, the rollout aborts and the old spherelets keep serving traffic.

You don't need a health check enabled for a service to deploy — but without one, the rollout assumes the spherelet is healthy the moment the process is running. Most services need at least an HTTP probe.

Configure one

The simplest HTTP probe — hits /healthz on the service's port.

$ csph services set-health --path /healthz

Tune the timing for a slow-starting service:

$ csph services set-health --path /healthz --initial-delay 30 --interval 10 --failure-threshold 3 --timeout 5

For services that don't expose HTTP — a worker process, a database proxy, an event consumer — use a TCP probe instead.

$ csph services set-health --tcp --port 5432

Disable health checks (not recommended for production):

$ csph services set-health --off

Field reference

Field	Default	What it controls
Type	HTTP	HTTP checks a path. TCP opens a connection to the port and considers any successful connect a pass.
Path (HTTP only)	/healthz	The endpoint to probe. Your service should return HTTP 200 when healthy, anything else when not.
Port	Service port	The port to probe. Defaults to whatever your service listens on.
Initial delay	10 s	How long to wait after the spherelet starts before the first probe. Set this above your worst cold-start time.
Interval	10 s	Seconds between probes once the initial delay passes.
Timeout	3 s	How long to wait for each probe to respond before counting it as a fail.
Failure threshold	3	Consecutive failures before the spherelet is marked unhealthy. The rollout aborts when no new spherelets are healthy.

A working example

A minimal Express endpoint that returns OK once the database is reachable:

import express from "express";
import { pool } from "./db.js";

const app = express();

app.get("/healthz", async (_req, res) => {
  try {
    await pool.query("SELECT 1");
    res.status(200).send("ok");
  } catch {
    res.status(503).send("not ready");
  }
});

app.listen(process.env.PORT ?? 8080);

The point of a health check isn't "is the process alive" — Linux already tells the platform that. It's "is this spherelet ready to take real traffic?" If your service needs a database, a cache, or a downstream API to function, the health check should confirm those work too.

Next

• Lifecycle — how health checks gate traffic during rollout and rollback
• Networking — control who can reach your service once it's healthy
• Environment variables — configure your service before the health check runs