Gateway health checks

Tip

If your load balancer prepends PROXY protocol headers to health check connections, such as an AWS NLB with proxy protocol v2 enabled, the Envoy readiness listener on port 8082 drops these connections by default. You can enable the PROXY protocol filter on the readiness listener so that health checks succeed. For more information, see Readiness listener PROXY protocol.

Enable a health check plugin on your gateway proxy to respond with common HTTP codes.

Kgateway includes an HTTP health checking plug-in that you can enable for a gateway proxy listener. This plug-in responds to health check requests directly with either a 200 OK or 503 Service Unavailable message, depending on the current draining state of Envoy.

Before you begin

Follow the Get started guide to install kgateway.
Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.

Get the external address of the gateway and save it in an environment variable.

export INGRESS_GW_ADDRESS=$(kubectl get svc -n kgateway-system http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
echo $INGRESS_GW_ADDRESS

Configure a health check on a gateway

Create a ListenerPolicy resource to configure a health check path for the HTTP or HTTPS listener on the gateway. You can define any path, such as /check/healthz.

kubectl apply -f- <<EOF
apiVersion: gateway.kgateway.dev/v1alpha1
kind: ListenerPolicy
metadata:
  name: healthcheck
  namespace: kgateway-system
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: http
  default:
    httpSettings:
      healthCheck:
        path: <path>
EOF

To test the health check, drain the Envoy connections by sending an HTTP POST request to the /healthcheck/fail endpoint of the Envoy admin port.
1. Port-forward the http deployment on port 19000.
  kubectl port-forward deploy/http -n kgateway-system 19000 &
2. Send an HTTP POST request to the /healthcheck/fail endpoint. This causes Envoy connections to begin draining.
  curl -X POST 127.0.0.1:19000/healthcheck/fail

Send a request to the health check path. Because Envoy is in a draining state, the 503 Service Unavailable message is returned.

curl -i $INGRESS_GW_ADDRESS:8080/<path>

Example output:

HTTP/1.1 503 Service Unavailable
x-envoy-upstream-healthchecked-cluster: http.kgateway-system
x-envoy-immediate-health-check-fail: true
date: Wed, 16 Jul 2025 16:35:12 GMT
server: envoy
connection: close
content-length: 0

After you finish testing, resume Envoy connections by sending an HTTP POST request to the /healthcheck/ok endpoint of the Envoy admin port.
```
curl -X POST 127.0.0.1:19000/healthcheck/ok
```

Send another request to the health check path. Because Envoy is operating normally, the 200 OK message is returned.

curl -i $INGRESS_GW_ADDRESS:8080/<path>

Example output:

HTTP/1.1 200 OK
x-envoy-upstream-healthchecked-cluster: http.kgateway-system
date: Wed, 16 Jul 2025 16:37:13 GMT
server: envoy
content-length: 0

Stop port-forwarding the http deployment.
```
lsof -ti:19000 | xargs kill -9
```

Cleanup

You can remove the resources that you created in this guide.

kubectl delete listenerpolicy healthcheck -n kgateway-system

Backend health checks

Was this page helpful?