Documentation
Resiliency
TCP keepalive

TCP keepalive

Manage idle and stale connections with TCP keepalive.

⚠️
This feature is available in kgateway version 2.1.x or later. This feature is experimental in the upstream Kubernetes Gateway API and subject to change.

About TCP keepalive

With keepalive, the kernel sends probe packets with only an acknowledgement flag (ACK) to the TCP socket of the destination after the connection was idle for a specific amount of time. This way, the connection does not have to be re-established repeatedly, which could otherwise lead to latency spikes. If the destination returns the packet with an acknowledgement flag (ACK), the connection is determined to be alive. If not, the probe can fail a certain number of times before the connection is considered stale. Kgateway can then close the stale connection, which can help avoid longer timeouts and retries on broken or stale connections.

Before you begin

  1. Follow the Get started guide to install kgateway.

  2. Follow the Sample app guide to create a gateway proxy with an HTTP listener and deploy the httpbin sample app.

  3. 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  
    kubectl port-forward deployment/http -n kgateway-system 8080:8080

Set up TCP keepalive

  1. Create a BackendConfigPolicy that applies TCP keepalive settings to the httpbin service.

    kubectl apply -f- <<EOF
kind: BackendConfigPolicy
apiVersion: gateway.kgateway.dev/v1alpha1
metadata:
  name: httpbin-keepalive
  namespace: httpbin   
spec:
  targetRefs:
    - name: httpbin
      group: ""
      kind: Service
  tcpKeepalive:
    keepAliveProbes: 3
    keepAliveTime: 30s
    keepAliveInterval: 5s
EOF
    Setting Description
    keepAliveProbes The maximum number of keepalive probes to send without a response before a connection is considered stale.
    keepAliveTime The number of seconds a connection needs to be idle before keep-alive probes are sent.
    keepAliveInterval The number of seconds between keep-alive probes.

  2. Port-forward the gateway proxy on port 19000.

    kubectl port-forward deployment/http -n kgateway-system 19000

  3. Get the configuration of your gateway proxy as a config dump.

    curl -X POST 127.0.0.1:19000/config_dump\?include_eds > gateway-config.json

  4. Open the config dump and find the kube_httpbin_httpbin_8000 cluster. Verify that you see all the connection settings that you enabled in your BackendConfigPolicy.

    Example output

    ...
   "connect_timeout": "5s",
   "metadata": {},
   "upstream_connection_options": {
    "tcp_keepalive": {
     "keepalive_probes": 3,
     "keepalive_time": 30,
     "keepalive_interval": 5
    }
   }
  },
...

Cleanup

You can remove the resources that you created in this guide. 
kubectl delete backendconfigpolicy httpbin-keepalive -n httpbin
RetriesTimeouts