For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
HTTP connection settings
Verified : Automated tests passed for: Kubernetes resources: The Kubernetes resources on this page were checked against their API schemas. End-to-end run: Every step ran in a fresh test environment and the results were checked.Configure and manage HTTP connections to an upstream service.
You can use an AgentgatewayPolicy to apply HTTP connection settings to the agentgateway proxy. These settings include the maximum buffer size, HTTP/1.1 idle timeouts and header limits, and HTTP/2 flow control and keepalive. Some settings apply only to HTTP/1.1 or only to HTTP/2, as noted in each section.
Before you begin
- Set up an agentgateway proxy.
- Install the httpbin sample app.
Maximum buffer size
Fine-tune connection speeds for read and write operations by setting a connection buffer limit (maxBufferSize). You can use this setting for both HTTP/1 and HTTP/2 connections.
HTTP/1.1 settings
Use these settings to control header limits and idle connection behavior for HTTP/1.1 connections.
Idle timeouts
Set an idle timeout for HTTP/1 traffic to terminate the connection to a downstream or upstream service if there are no active streams.
Max headers
Set the maximum number of headers allowed in HTTP/1.1 requests.
Create an AgentgatewayPolicy that applies the HTTP/1.1 connection configuration to the proxy.
kubectl apply -f- <<EOF apiVersion: agentgateway.dev/v1alpha1 kind: AgentgatewayPolicy metadata: name: http1 namespace: agentgateway-system spec: targetRefs: - kind: Gateway name: agentgateway-proxy group: gateway.networking.k8s.io frontend: http: http1MaxHeaders: 15 EOFSetting Description http1MaxHeadersThe maximum number of headers allowed in HTTP/1.1 requests. Requests that exceed the limit receive a 431 response. Port-forward the gateway proxy on port 15000.
kubectl port-forward deployment/agentgateway-proxy -n agentgateway-system 15000Get the config dump and verify that the policy is set as you configured it.
Example
jqcommand:curl -s http://localhost:15000/config_dump | jq '[.policies[] | select(.policy.frontend != null and .policy.frontend.hTTP != null and .policy.frontend.hTTP.http1IdleTimeout != null)] | .[0]'Example output:
http://localhost:15000/config_dump1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29{ "key": "frontend/agentgateway-system/http1:frontend-http:agentgateway-system/agentgateway-proxy", "name": { "kind": "AgentgatewayPolicy", "name": "http1", "namespace": "agentgateway-system" }, "target": { "gateway": { "gatewayName": "agentgateway-proxy", "gatewayNamespace": "agentgateway-system", "listenerName": null } }, "policy": { "frontend": { "hTTP": { "maxBufferSize": null, "http1MaxHeaders": 15, "http1IdleTimeout": null, "http2WindowSize": null, "http2ConnectionWindowSize": null, "http2FrameSize": null, "http2KeepaliveInterval": null, "http2KeepaliveTimeout": null } } } }Optional: Clean up and remove the AgentgatewayPolicy.
kubectl delete AgentgatewayPolicy http1 -n agentgateway-systemHTTP/2 settings
Use these settings to tune HTTP/2 flow control, which governs how much data can be in-flight at the stream and connection levels.
Flow control
Create an AgentgatewayPolicy that applies HTTP/2 flow control configuration to the proxy.
kubectl apply -f- <<EOF apiVersion: agentgateway.dev/v1alpha1 kind: AgentgatewayPolicy metadata: name: http2-flow namespace: agentgateway-system spec: targetRefs: - kind: Gateway name: agentgateway-proxy group: gateway.networking.k8s.io frontend: http: http2WindowSize: 1048576 http2ConnectionWindowSize: 4194304 http2FrameSize: 65536 EOFSetting Description http2WindowSizeControls how many bytes can be in-flight on a single HTTP/2 stream before the sender must wait for a WINDOW_UPDATEacknowledgment. Setting this to 1 means the client can only send 1 byte at a time per stream, essentially halting all throughput. The default is 65,535 bytes (64KB).http2ConnectionWindowSizeThe initial window size for connection-level flow control for received data. This settings controls the total bytes in-flight across all streams on a single connection combined. http2FrameSizeThe maximum size of a single HTTP/2 DATA frame the gateway accepts. The HTTP/2 protocol minimum (and default) is 16,384 bytes. 17000 is a modest bump above that default, allowing slightly larger frames and potentially fewer round-trips for larger payloads. Port-forward the gateway proxy on port 15000.
kubectl port-forward deployment/agentgateway-proxy -n agentgateway-system 15000Get the config dump and verify that the policy is set as you configured it.
Example
jqcommand:curl -s http://localhost:15000/config_dump | jq '[.policies[] | select(.policy.frontend != null and .policy.frontend.hTTP != null and .policy.frontend.hTTP.http2WindowSize != null)] | .[0]'Example output:
http://localhost:15000/config_dump1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29{ "key": "frontend/agentgateway-system/http2-flow:frontend-http:agentgateway-system/agentgateway-proxy", "name": { "kind": "AgentgatewayPolicy", "name": "http2-flow", "namespace": "agentgateway-system" }, "target": { "gateway": { "gatewayName": "agentgateway-proxy", "gatewayNamespace": "agentgateway-system", "listenerName": null } }, "policy": { "frontend": { "hTTP": { "maxBufferSize": null, "http1MaxHeaders": null, "http1IdleTimeout": null, "http2WindowSize": 1048576, "http2ConnectionWindowSize": 4194304, "http2FrameSize": 65536, "http2KeepaliveInterval": null, "http2KeepaliveTimeout": null } } } }Optional: Clean up and remove the AgentgatewayPolicy.
kubectl delete AgentgatewayPolicy http2-flow -n agentgateway-systemKeepalive
Manage idle and stale connections with HTTP/2 keepalive.
Backend connections
The frontend settings on this page tune the connections that clients open to the gateway. To tune the connections that the gateway opens to a destination, set the backend section of an AgentgatewayPolicy instead.
Important
The backend.tcp fields existed in earlier versions, but the controller did not translate them, so a policy that set them had no effect. Version 1.5 implements them. Review any policy that already sets backend.tcp, because the values now apply to real traffic.
Create an AgentgatewayPolicy that tunes the connection to the httpbin backend.
kubectl apply -f- <<EOF apiVersion: agentgateway.dev/v1alpha1 kind: AgentgatewayPolicy metadata: name: httpbin-connection namespace: httpbin spec: targetRefs: - group: gateway.networking.k8s.io kind: HTTPRoute name: httpbin backend: tcp: connectTimeout: 3s keepalive: time: 60s interval: 30s retries: 5 http: requestTimeout: 30s EOFSetting Description tcp.connectTimeoutDeadline for establishing a connection to the destination. The value must be at least 100ms. The default is11s.tcp.keepalive.timeHow long a connection stays idle before agentgateway starts to send keepalive probes. The default is 180s.tcp.keepalive.intervalTime between keepalive probes. The default is 180s.tcp.keepalive.retriesMaximum number of keepalive probes to send before agentgateway drops the connection. The default is 9.http.requestTimeoutDeadline for receiving a response from the backend. Policy merging replaces the more general
backend.tcpblock with the more specific one. For example, an HTTPRoute policy that sets onlybackend.tcp.keepalivedoes not inheritconnectTimeoutfrom a policy that targets the Service. The connection attempt then uses the defaultconnectTimeoutof11s.Port-forward the proxy admin port and verify the settings in the proxy configuration.
kubectl port-forward deployment/agentgateway-proxy -n agentgateway-system 15000 & sleep 2 curl -s http://localhost:15000/config_dump | jq '[.policies[] | select(.policy.backend != null and .policy.backend.tcp != null)] | .[0]'Optional: Clean up the AgentgatewayPolicy.
kubectl delete AgentgatewayPolicy httpbin-connection -n httpbin
This example targets the httpbin HTTPRoute. To set the same deadlines on a Kubernetes Service instead, so that they apply independently of the routes that reach it, see Backend timeouts.
Note
Of the connection settings on this page, a backend policy sets the tcp and http fields only. The handshakeTimeout, http1IdleTimeout, http2KeepaliveInterval, http2KeepaliveTimeout, and maxConnectionDuration settings belong to the frontend section, and apply to incoming connections. A backend policy sets other fields as well, such as tls and health; for the full list, see Policy sections. For more information about where each policy section attaches, see Targeting and merging.
Connection limits
Cap the number of requests and connections that clients can open to the gateway proxy at the same time. Over a limit, the proxy rejects new work immediately and does not queue it. As a result, a traffic spike or a client that opens many connections cannot exhaust the proxy’s memory and file descriptors.
You set both limits in the frontend section of an AgentgatewayPolicy that targets a Gateway. Each limit counts separately for each port of the Gateway and for each proxy replica. By default, both limits are unset, so the number of requests and connections is not limited.
| Setting | What the limit counts | What happens over the limit |
|---|---|---|
frontend.http.maxConcurrentRequests | In-flight HTTP requests, including HTTP/1 requests and HTTP/2 streams. The minimum value is 1. | The proxy returns a 503 response with the body request limit exceeded, and increments the agentgateway_requests_shed_total metric. |
frontend.tcp.maxConnections | Active client connections. The minimum value is 1. | The proxy closes the new connection without a response, and increments the agentgateway_downstream_connections_shed_total metric. |
Create an AgentgatewayPolicy that allows 2 in-flight requests on the Gateway.
kubectl apply -f- <<EOF apiVersion: agentgateway.dev/v1alpha1 kind: AgentgatewayPolicy metadata: name: connection-limits namespace: agentgateway-system spec: targetRefs: - group: gateway.networking.k8s.io kind: Gateway name: agentgateway-proxy frontend: http: maxConcurrentRequests: 2 EOFSend 3 requests at the same time to the httpbin
/delay/3endpoint, which responds after 3 seconds. The first 2 requests take all the request slots, so the proxy rejects the third request immediately with a503response.for i in 1 2 3; do curl -s -o /dev/null -w "request $i: %{http_code}\n" http://$INGRESS_GW_ADDRESS:80/delay/3 -H "host: www.example.com:80" & sleep 0.2 done; waitExample output:
request 3: 503 request 1: 200 request 2: 200Update the AgentgatewayPolicy so that it sets a connection limit of 1 and no request limit. With 1 connection slot, you can test the connection limit with 2 requests.
kubectl apply -f- <<EOF apiVersion: agentgateway.dev/v1alpha1 kind: AgentgatewayPolicy metadata: name: connection-limits namespace: agentgateway-system spec: targetRefs: - group: gateway.networking.k8s.io kind: Gateway name: agentgateway-proxy frontend: tcp: maxConnections: 1 EOFOpen a connection with a slow request, and then open a second connection. The first connection takes the only connection slot, so the proxy closes the second connection without a response. Curl reports
Connection reset by peer, orEmpty reply from serverthrough a port-forward.curl -s -o /dev/null -w "connection 1: %{http_code}\n" http://$INGRESS_GW_ADDRESS:80/delay/3 -H "host: www.example.com:80" & sleep 0.5 curl -sS -o /dev/null -w "connection 2: %{http_code}\n" http://$INGRESS_GW_ADDRESS:80/headers -H "host: www.example.com:80" waitExample output:
curl: (56) Recv failure: Connection reset by peer connection 2: 000 connection 1: 200Check the metrics that count the rejected requests and connections. The
bindlabel names the port and the Gateway.kubectl port-forward deployment/agentgateway-proxy -n agentgateway-system 15020 & PF_PID=$! sleep 2 curl -s localhost:15020/metrics | grep -E '^agentgateway_(requests|downstream_connections)_shed' kill $PF_PIDExample output:
agentgateway_downstream_connections_shed_total{bind="80/agentgateway-system/agentgateway-proxy"} 1 agentgateway_requests_shed_total{bind="80/agentgateway-system/agentgateway-proxy"} 1Optional: Delete the AgentgatewayPolicy.
kubectl delete AgentgatewayPolicy connection-limits -n agentgateway-system