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

Compress responses to clients and decompress encoded request bodies.

Use traffic.compression in an AgentgatewayPolicy for response compression and request decompression. You can configure either feature or both in the same policy.

About compression

Response compression reduces bandwidth for JSON, HTML, CSS, JavaScript, XML, plain text, and SVG responses. Clients must advertise a configured algorithm in the Accept-Encoding header to receive compressed responses.

The following limits apply:

• Responses must have a known length of at least 32 bytes. Streams without a known length, such as server-sent events, are not compressed.
• Responses that are already encoded, have a Content-Range header, or set Cache-Control: no-transform are not compressed. Responses with a 1xx, 204, or 304 status code are also excluded.
• Request decompression requires a single configured encoding in Content-Encoding. Unsupported or layered encodings, such as Content-Encoding: gzip, br, are forwarded unchanged.

Algorithm selection

The algorithm with the highest quality value (q) in Accept-Encoding wins. Ties follow the configured algorithm order. A * entry applies to algorithms that the client does not list by name. If identity has a higher quality value than every configured algorithm, the response stays uncompressed.

Headers and content types

Compressed responses set Content-Encoding, remove Content-Length and Accept-Ranges, and change strong ETag values to weak values, such as W/"abc". Eligible responses include Vary: accept-encoding even when sent uncompressed, so caches can distinguish responses by the client’s accepted encodings.

Eligible media types are application/javascript, application/json, application/xml, application/xhtml+xml, image/svg+xml, text/css, text/html, text/javascript, text/plain, and text/xml. Types with a +json or +xml suffix also qualify. Responses with other media types or without a Content-Type header are not compressed.

Decompressed requests have their Content-Encoding and Content-Length headers removed.

Policy order

Response compression runs after other response policies and the access log snapshot. Transformations and response body logs see the uncompressed body. The client’s Accept-Encoding is read before request header modifiers run, so removing that header before forwarding does not disable compression.

Request decompression runs after route-level authentication and authorization. These policies see encoded bodies, and denied requests are never decoded. Route-level rate limiting, external processing, and transformations see decoded bodies. Backend authorization also sees decoded bodies.

Policies in the PreRouting phase also see encoded request bodies.

Compression settings

The traffic.compression field takes a response block, a request block, or both.

Choose from Gzip, Brotli, Deflate, and Zstd. If you omit algorithms, the default is Gzip. Their HTTP encoding tokens are gzip, br, deflate, and zstd, respectively.

The following example compresses responses with Gzip or Brotli and decodes gzip request bodies.

traffic:
  compression:
    response:
      compress:
        algorithms:
        - Gzip
        - Brotli
    request:
      decompress: {}

For the full list of fields, see the API reference.

Before you begin

1. Set up an agentgateway proxy.
2. Install the httpbin sample app.

Compress responses and decompress requests

Use an AgentgatewayPolicy to configure compression for a Gateway, HTTPRoute, or route rule.

1. Create a policy that applies to the httpbin HTTPRoute. The policy compresses responses with Gzip, Brotli, or Zstd. The empty decompress block decodes request bodies that are encoded with the default algorithm, Gzip.

   kubectl apply -f- <<EOF
   apiVersion: agentgateway.dev/v1alpha1
   kind: AgentgatewayPolicy
   metadata:
     name: compression
     namespace: httpbin
   spec:
     targetRefs:
     - group: gateway.networking.k8s.io
       kind: HTTPRoute
       name: httpbin
     traffic:
       compression:
         response:
           compress:
             algorithms:
             - Gzip
             - Brotli
             - Zstd
         request:
           decompress: {}
   EOF

2. Send a request to the httpbin app and advertise support for gzip in the Accept-Encoding header. Verify that the response has the content-encoding: gzip and vary: accept-encoding headers.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -s -o /dev/null -D - http://$INGRESS_GW_ADDRESS:80/json \
     -H "host: www.example.com:80" \
     -H "Accept-Encoding: gzip"

   curl -s -o /dev/null -D - localhost:8080/json \
     -H "host: www.example.com" \
     -H "Accept-Encoding: gzip"

   Example output:

   HTTP/1.1 200 OK
   Access-Control-Allow-Credentials: true
   Access-Control-Allow-Origin: *
   Content-Type: application/json; encoding=utf-8
   content-encoding: gzip
   vary: accept-encoding
   transfer-encoding: chunked
   

3. Send the request without an Accept-Encoding header. The gateway proxy does not compress the response, so the response has a Content-Length header and no content-encoding header. The response still includes the vary: accept-encoding header.

   Cloud Provider LoadBalancerPort-forward for local testing

   curl -s -o /dev/null -D - http://$INGRESS_GW_ADDRESS:80/json \
     -H "host: www.example.com:80"

   curl -s -o /dev/null -D - localhost:8080/json \
     -H "host: www.example.com"

   Example output:

   HTTP/1.1 200 OK
   Access-Control-Allow-Credentials: true
   Access-Control-Allow-Origin: *
   Content-Type: application/json; encoding=utf-8
   Content-Length: 421
   vary: accept-encoding
   

4. Send a request body that is compressed with gzip to the httpbin /anything endpoint, which echoes the request back. The gateway proxy decodes the body, so httpbin receives the decoded JSON body. The data and json fields in the output show the decoded body.

   Cloud Provider LoadBalancerPort-forward for local testing

   echo '{"hello":"world"}' | gzip | curl -s http://$INGRESS_GW_ADDRESS:80/anything \
     -H "host: www.example.com:80" \
     -H "Content-Type: application/json" \
     -H "Content-Encoding: gzip" \
     --data-binary @-

   echo '{"hello":"world"}' | gzip | curl -s localhost:8080/anything \
     -H "host: www.example.com" \
     -H "Content-Type: application/json" \
     -H "Content-Encoding: gzip" \
     --data-binary @-

   Example output:

   {
     ...
     "data": "{\"hello\":\"world\"}\n",
     ...
     "json": {
       "hello": "world"
     }
   }
   

Cleanup

kubectl delete AgentgatewayPolicy compression -n httpbin