How to Add a Kubernetes startupProbe for a Slow-Starting Container

Why slow starters crash-loop

Kubernetes runs livenessProbe checks continuously. If you set failureThreshold: 3 and periodSeconds: 5, the container has 15 seconds to pass a liveness check - or Kubernetes kills it and restarts it.

A JVM service, a container that runs database migrations on boot, or anything that does heavy warm-up often takes 30-120 seconds before it can answer HTTP. The liveness probe declares it dead and kills it first. The pod enters a CrashLoopBackOff even though the app itself is perfectly healthy.

The fix: a startupProbe

startupProbe runs instead of livenessProbe until the probe succeeds once. After that first success, Kubernetes stops running the startup probe and switches to the liveness probe for ongoing health checks. This gives you:

• A long boot budget for slow starters (without loosening the liveness probe for the steady-state lifetime of the container)
• Clean separation of "did it finish starting?" from "is it still healthy?"

Add it to your Deployment manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
spec:
  replicas: 1
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
      - name: web
        image: my-app:latest
        ports:
        - containerPort: 80
        startupProbe:
          httpGet:
            path: /health
            port: 80
          failureThreshold: 30
          periodSeconds: 5
        livenessProbe:
          httpGet:
            path: /health
            port: 80
          periodSeconds: 10
          failureThreshold: 3

Apply and verify:

kubectl apply -f deployment.yaml
kubectl rollout status deployment/web
kubectl get deploy web -o yaml | grep -A6 startupProbe

Calculating the boot budget

The startup probe runs for up to failureThreshold x periodSeconds before giving up. With failureThreshold: 30 and periodSeconds: 5 that's 150 seconds of startup budget. Tune both numbers to match your app's worst-case boot time plus a comfortable margin.

Once the startup probe passes once, it is gone. The liveness probe takes over with its own (tighter) thresholds. This is the right pattern - you don't need to set a permissive initialDelaySeconds on the liveness probe or inflate its failureThreshold for the ongoing lifetime of the container.

Probe types

All three probe types (startupProbe, livenessProbe, readinessProbe) support the same check mechanisms - httpGet, tcpSocket, or exec. Use whatever your app already has a health endpoint for. A minimal /healthz that returns 200 as soon as the app is ready to serve traffic is the standard pattern.

When you need all three

• startupProbe - passes once the app has finished booting
• livenessProbe - restarts the container if it gets stuck (deadlock, OOM)
• readinessProbe - removes the pod from Service endpoints if it is temporarily overloaded or not ready for new traffic (does NOT restart it)