For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Close upstream TCP connections that stay idle longer than the configured idle timeout.

Customize the default idle timeout of 1 hour (3600s).

About idle timeouts

By default, Envoy terminates the connection to a downstream or upstream service after one hour if there are no active streams. You can customize this idle timeout with a ListenerPolicy. The policy updates the common_http_protocol_options setting in Envoy.

Note that the idle timeout configures the timeout for the entire connection from a downstream service to the gateway proxy, and to the upstream service. If you want to set a timeout for a single stream, configure the idle stream timeout instead.

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.

   Cloud Provider LoadBalancerPort-forward for local testing

   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 idle timeouts

1. Create a ListenerPolicy with your idle timeout configuration. In this example, you apply an idle timeout of 30 seconds.

   kubectl apply -f- <<EOF
   apiVersion: gateway.kgateway.dev/v1alpha1
   kind: ListenerPolicy
   metadata:
     name: idle-time
     namespace: kgateway-system
   spec:
     targetRefs:
     - group: gateway.networking.k8s.io
       kind: Gateway
       name: http
     default:
       httpSettings:
         idleTimeout: "30s"
   EOF

2. Verify that the gateway proxy is configured with the idle timeout.

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

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

   2. Query the config dump and find the http_connection_manager configuration. Verify that the timeout policy is set as you configured it.

      curl -s 127.0.0.1:19000/config_dump | jq '.configs[]
      | select(."@type" == "type.googleapis.com/envoy.admin.v3.ListenersConfigDump")
      | .dynamic_listeners[].active_state.listener.filter_chains[].filters[]
      | select(.name == "envoy.filters.network.http_connection_manager")'

      Example output:

      {
        "name": "envoy.filters.network.http_connection_manager",
        "typed_config": {
            "@type": "type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager",
            "stat_prefix": "http",
            "rds": {
            "config_source": {
                "ads": {},
                "resource_api_version": "V3"
            },
            "route_config_name": "listener~8080"
            },
            "http_filters": [
            {
                "name": "envoy.filters.http.router",
                "typed_config": {
                "@type": "type.googleapis.com/envoy.extensions.filters.http.router.v3.Router"
                }
            }
            ],
            "use_remote_address": true,
            "normalize_path": true,
            "merge_slashes": true,
            "common_http_protocol_options": {
            "idle_timeout": "30s"
            }
        }
      }
      

Cleanup

kubectl delete listenerpolicy idle-time -n kgateway-system