Buffering

Fine-tune connection speeds for read and write operations by setting a connection buffer limit.

About read and write buffer limits

By default, kgateway is set up with 1MiB of request read and write buffer for each gateway. For large requests that must be buffered and that exceed the default buffer limit, kgateway either disconnects the connection to the downstream service if headers were already sent, or returns a 413 HTTP response code. To make sure that large requests can be sent and received, you can specify the maximum number of bytes that can be buffered between the gateway and the downstream service. Alternatively, when using kgateway as an edge proxy, configuring the buffer limit can be important when dealing with untrusted downstreams. By setting the limit to a small number, such as 32KiB, you can better guard against potential attacks or misconfigured downstreams that could excessively use the proxy’s resources.

The connection buffer limit can be configured on the Gateway level.

Considerations when using httpbin

When you use the httpbin sample app, keep in mind that httpbin limits the maximum body size to 1 mebibyte (1Mi). If you send a request to httpbin with a body size that is larger than that, httpbin automatically rejects the request with a 400 HTTP response code.

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 buffer limits per gateway

Use an annotation to set a per-connection buffer limit on your Gateway, which applies the buffer limit to all routes served by the Gateway.

1. Create a TrafficPolicy called transformation-buffer-body that forces buffering by transforming the response from the httpbin sample app.

   kubectl apply -f- <<EOF
   apiVersion: gateway.kgateway.dev/v1alpha1
   kind: TrafficPolicy
   metadata:
     name: transformation-buffer-body
     namespace: httpbin
   spec:
     targetRefs:
     - group: gateway.networking.k8s.io
       kind: HTTPRoute
       name: httpbin
     transformation:
       response:
         body:
           parseAs: AsString
           value: '{{ body() }}'
   EOF

2. Annotate the http Gateway resource to set a buffer limit of 1 kilobytes.

   kubectl apply -f- <<EOF
   kind: Gateway
   apiVersion: gateway.networking.k8s.io/v1
   metadata:
     name: http
     namespace: kgateway-system
     annotations:
       kgateway.dev/per-connection-buffer-limit: '1Ki'
   spec:
     gatewayClassName: kgateway
     listeners:
     - protocol: HTTP
       port: 8080
       name: http
       allowedRoutes:
         namespaces:
           from: All
   EOF

3. To test the buffer limit, create a payload in a temp file that exceeds the 1Ki buffer limit.

   dd if=/dev/zero bs=2048 count=1 | base64 -w 0 > /tmp/large_payload_2k.txt

4. Send a request to the /anything httpbin path with the large payload. Verify that the request fails with a connection error or timeout, indicating that the buffer limit was exceeded.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -vik -X POST http://$INGRESS_GW_ADDRESS:8080/anything \
   -H "host: www.example.com:8080" \
   -H "Content-Type: text/plain" \
   -d "{\"payload\": \"$(< /tmp/large_payload_2k.txt)\"}"

   curl -vik -X POST http://localhost:8080/anything \
   -H "host: www.example.com:8080" \
   -H "Content-Type: text/plain" \
   -d "{\"payload\": \"$(< /tmp/large_payload_2k.txt)\"}"

   Example output:

   * upload completely sent off: 2747 bytes
   < HTTP/1.1 413 Payload Too Large
   HTTP/1.1 413 Payload Too Large
   < access-control-allow-credentials: true
   access-control-allow-credentials: true
   < access-control-allow-origin: *
   access-control-allow-origin: *
   < x-envoy-upstream-service-time: 1
   x-envoy-upstream-service-time: 1
   < content-length: 17
   content-length: 17
   < server: envoy
   server: envoy

5. Test the buffer limit again by sending a request with a small payload, "hello world". This request succeeds with a normal response from httpbin because the payload size is within the 1Ki limit.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -vik -X POST http://$INGRESS_GW_ADDRESS:8080/anything \
      -H "host: www.example.com:8080" \
      -H "Content-Type: application/json" \
      -d "{\"payload\":  \"hello world\"}" 

   curl -vik -X POST http://localhost:8080/anything \
      -H "host: www.example.com:8080" \
      -H "Content-Type: application/json" \
      -d "{\"payload\":  \"hello world\"}" 

   Example output:

   * upload completely sent off: 27 bytes
   < HTTP/1.1 200 OK
   HTTP/1.1 200 OK
   ...
     "url": "http://www.example.com:8080/anything",
     "data": "{\"payload\":  \"hello world\"}",
     "files": null,
     "form": null,
     "json": {
       "payload": "hello world"
     }
   }

Cleanup

1. Delete the TrafficPolicy resources.

   kubectl delete TrafficPolicy transformation-buffer-body -n httpbin 

2. Remove the buffer limit annotation from the http Gateway resource.

   kubectl apply -f- <<EOF
   kind: Gateway
   apiVersion: gateway.networking.k8s.io/v1
   metadata:
     name: http
     namespace: kgateway-system
   spec:
     gatewayClassName: kgateway
     listeners:
     - protocol: HTTP
       port: 8080
       name: http
       allowedRoutes:
         namespaces:
           from: All
   EOF