Skip to main content
API7.ai Logo
Version: 3.9.x

Configure Readiness and Liveness Probes

API7 Gateway data plane (DP) nodes can expose built-in health endpoints on the status port, 7085 by default. You can use these endpoints in Kubernetes probes, load balancer health checks, or container-level checks to ensure traffic is sent only to healthy nodes.

Use this guide when you need to:

  • configure Kubernetes readiness and liveness probes
  • add health checks in non-Helm Kubernetes manifests
  • configure Docker or external load balancer checks for non-Kubernetes deployments

Health Check Endpoints​

When you configure the data plane status block, API7 Gateway provides health check endpoints on the status port (default 7085).

TypePathPurpose
Liveness/statusIndicates if the process has successfully started and is running.
Readiness/status/readyChecks worker synchronization and DP Manager availability for a connected gateway.

Use sync-aware readiness when you want to take a node out of rotation if it loses contact with DP Manager. When a node should serve cached configuration during an outage, check a published traffic port, or a path that still returns success from cached configuration. For nodes starting from fallback storage, see fallback recovery.

The status endpoints are controlled by the data plane status configuration:

config.yaml
apisix:
  status:
    ip: 0.0.0.0
    port: 7085

If you bind the status endpoint to 127.0.0.1, local container checks still work, but external load balancers will not be able to reach it.

Configure Probes in Kubernetes​

Helm values​

If you are deploying API7 Gateway via the api7/gateway Helm chart, enable the status endpoint and configure the probes in your values.yaml file.

values.yaml
api7ee:
  status_endpoint:
    enabled: true
    ip: 0.0.0.0
    port: 7085

gateway:
  livenessProbe:
    httpGet:
      path: /status
      port: 7085
    initialDelaySeconds: 10
    periodSeconds: 10
    timeoutSeconds: 5
    failureThreshold: 3
  readinessProbe:
    httpGet:
      path: /status/ready
      port: 7085
    initialDelaySeconds: 5
    periodSeconds: 10
    timeoutSeconds: 5
    failureThreshold: 3

The Helm chart exposes the underlying runtime apisix.status block through api7ee.status_endpoint, and the Kubernetes pod probes through gateway.livenessProbe and gateway.readinessProbe.

This example uses /status for process liveness and /status/ready for sync-aware readiness.

Non-Helm Kubernetes manifests​

If you deploy API7 Gateway with raw Deployment manifests instead of Helm, configure the probes directly on the gateway container:

deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api7-gateway
spec:
  template:
    spec:
      containers:
        - name: gateway
          image: api7/api7-ee-3-gateway:3.9.22
          ports:
            - containerPort: 9080
            - containerPort: 9443
            - containerPort: 7085
          livenessProbe:
            httpGet:
              path: /status
              port: 7085
            initialDelaySeconds: 10
            periodSeconds: 10
            timeoutSeconds: 5
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /status/ready
              port: 7085
            initialDelaySeconds: 5
            periodSeconds: 10
            timeoutSeconds: 5
            failureThreshold: 3

If you expose the gateway through a Kubernetes Service, do not send client traffic to port 7085; keep it for health checks and operational access only.

Configure Checks Outside Kubernetes​

Docker or container runtime checks​

If you run API7 Gateway directly with Docker, publish the status port and query the endpoints from the host:

curl -i "http://127.0.0.1:7085/status"
curl -i "http://127.0.0.1:7085/status/ready"

If port 7085 is not published to the host, expose it first so the health endpoints are reachable from outside the container.

The released gateway image does not include curl or wget. Keep the gateway image unchanged and run an external check in its network namespace instead:

docker run --rm --network container:<gateway-container> curlimages/curl:8.10.1 \
  -fsS "http://127.0.0.1:7085/status/ready"

For continuous checks, configure the host's service manager or external load balancer to request the published status endpoint. Do not install diagnostic packages in the gateway container.

External load balancer checks​

For VM, bare-metal, or Docker deployments behind a load balancer, configure health checks against the DP status API:

  • use http://<dp-host>:7085/status when you only need to verify that the process is running
  • use http://<dp-host>:7085/status/ready when you want to stop routing traffic to nodes that have lost control plane connectivity

When the load balancer should keep routing to nodes with cached configuration during an outage, check a published traffic port, or a path that still returns success from cached configuration.

TCP Socket Checks​

As an alternative to HTTP checks, you can use TCP socket checks on the proxy port (default 9080 for HTTP or 9443 for HTTPS). This is useful if you want to ensure the network stack is responding even if the status endpoint is unavailable.

deployment.yaml
readinessProbe:
  tcpSocket:
    port: 9080
  initialDelaySeconds: 5
  periodSeconds: 10

Expected Responses​

  • Success: A 200 OK response confirms that the specific check passed.
  • Readiness failure: A 503 Service Unavailable response from /status/ready indicates that a gateway worker is out of sync with the DP Manager configuration or that none of the configured DP Manager (etcd.host) endpoints are available. Inspect the response body and gateway logs to distinguish the cause.
  • Failure: Any other status code, connection refusal, or timeout indicates a health check failure.
  • Use /status for liveness checks.
  • Use /status/ready where traffic eligibility depends on synchronization with DP Manager.
  • Keep the status port reachable only by your orchestrator, load balancer, or operations network.
  • If you run outside Kubernetes, make sure your config.yaml exposes the status port on an address your health checker can reach.

Next Steps​