Kubernetes Probes

Laravel Health provides dedicated endpoints for each Kubernetes probe type.

Probe Endpoints

Kubernetes Deployment YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
        - name: app
          livenessProbe:
            httpGet:
              path: /health
              port: 80
            initialDelaySeconds: 10
            periodSeconds: 15
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 80
            initialDelaySeconds: 5
            periodSeconds: 10
          startupProbe:
            httpGet:
              path: /health/startup
              port: 80
            failureThreshold: 30
            periodSeconds: 5

Probe Design

Understanding the difference between liveness and readiness is critical. Misconfigured probes are the most common cause of self-inflicted outages in Kubernetes.

Liveness — "Is the process stuck?" If this fails, Kubernetes restarts the container. Only check things intrinsic to the process itself. The default DatabaseCheck verifies the app can reach its primary datastore — that's usually sufficient.

Readiness — "Can this pod serve traffic?" If this fails, the pod is removed from the Service load balancer but keeps running. Include all dependencies the app needs to handle a request: database, cache, queue, external APIs.

Startup — "Has the app finished booting?" Runs once. Prevents premature liveness kills on slow-starting apps (e.g. large migration, cache warm-up). No checks by default.

Cascading Failures

A liveness check that depends on an external service can take down your entire application.

When Redis goes down and RedisCheck is on your liveness probe, Kubernetes restarts every pod. The pods come back, still can't reach Redis, get restarted again. Your app is now in a crash loop — not because it is broken, but because a dependency is temporarily unavailable.

The rule: liveness checks should only fail when the process itself is unhealthy and a restart would fix it. Dependency failures belong on readiness.

What goes where

Example: safe configuration

'checks' => [
    'liveness' => [
        DatabaseCheck::class,     // core dependency only
    ],
    'readiness' => [
        DatabaseCheck::class,
        CacheCheck::class,
        RedisCheck::class,
        QueueCheck::class,
        StorageCheck::class,
    ],
    'startup' => [
        EnvironmentCheck::class,  // validate env once at boot
    ],
],

If Redis goes down with this configuration: the readiness probe fails, Kubernetes stops sending traffic to the pod, but the pod stays alive and recovers automatically when Redis returns.

Authentication

The liveness endpoint is public by default (configured in security.public_endpoints). For token-protected probes, pass the token as a query parameter in your probe config:

readinessProbe:
  httpGet:
    path: /health/ready?token=your-secret-token
    port: 80

Related Documentation

• Endpoints Overview
• Health Checks
• Security