HTTP Header Max Size Adjustment
This guide provides detailed instructions on how to modify buffer and body size limits related to HTTP requests within the Kong Gateway and NGINX Ingress environments on Kubernetes. These configurations help prevent request failures caused by large headers or payloads.
Overviewβ
Kong uses an embedded NGINX engine for handling HTTP traffic. By default, NGINX applies conservative size limits for request headers and bodies. In production environments, especially when handling: Large request headers (e.g., JWT tokens, cookies, user-agent), large request bodies (e.g., file uploads), or high concurrency with request transformations,β¦
These limits must be increased to avoid errors such as:
- 400 Bad Request β Request Header or Cookie Too Large
- 413 Request Entity Too Large
This guide explains how to adjust these limits in three different ways:
- Via Kong Deployment or Kong Configuration JSON
- Via NGINX Ingress Controller ConfigMap
- Via Ingress Resource Annotations (per service)
Key Configuration Parameters (Detailed Breakdown)β
nginx_http_client_header_buffer_sizeβ
- Description: Sets the size of a single buffer used when reading client request headers.
- Default: 1k
- When to modify: If request headers like Authorization, Cookie, User-Agent become too long (e.g., SSO tokens or multi-cookie headers).
- Recommended: Increase to 4k or 8k to ensure stability.
- Caution: Setting it too large may increase memory usage under high concurrency.
nginx_http_large_client_header_buffersβ
- Description: Configures the number and size of buffers for large request headers (e.g., multi-recipient cookies).
- Default: 4 8k (4 buffers of 8k each)
- When to modify: If encountering 400 Bad Request β Request Header or Cookie Too Large.
- Recommended: Increase to 4 16k or 8 16k.
- Caution: Only expand when needed to avoid unnecessary memory overhead.
nginx_http_client_max_body_sizeβ
- Description: Defines the max size of the request body that Kong accepts based on Content-Length.
- Default: 0 (no limit)
- When to modify: To prevent oversized body payloads (e.g., large file uploads) from causing 413 errors.
- Recommended: Set according to expected usage, e.g., 10m, 50m.
- Caution: Requests exceeding this size will trigger a 413 response from Kong.
nginx_admin_client_max_body_sizeβ
- Description: Sets the max body size accepted by the Admin API.
- Default: 10m
- When to modify: When sending large config payloads to Admin API (e.g., batch route registration).
- Recommended: 20m to 50m if needed.
- Caution: Since the Admin API is sensitive, increasing this too much may introduce security risks.
nginx_http_client_body_buffer_sizeβ
- Description: Buffer size for reading request body into memory. If the body exceeds this size, itβs written to disk.
- Default: 8k
- When to modify: When using body manipulation plugins like request-transformer, rate-limiting, etc., to avoid writing to disk.
- Recommended: Match with client_max_body_size, e.g., 50m.
- Caution: Large values increase memory consumption (consider request concurrency when setting).
nginx_admin_client_body_buffer_sizeβ
- Description: Same as above, but for Admin API request bodies.
- Default: 10m
- Recommended: Expand based on Admin API workload.
Configuration Methodsβ
Method 1: Kong Deployment or APIM Console Configurationβ
Applies only to the internal NGINX running inside Kong Gateway pods.
Option A β Modify Kong Deployment Environment Variables4
- name: KONG_NGINX_HTTP_CLIENT_HEADER_BUFFER_SIZE
value: "4k"
- name: KONG_NGINX_HTTP_LARGE_CLIENT_HEADER_BUFFERS
value: "4 16k"
- name: KONG_NGINX_HTTP_CLIENT_MAX_BODY_SIZE
value: "50m"
- name: KONG_NGINX_ADMIN_CLIENT_MAX_BODY_SIZE
value: "20m"
- name: KONG_NGINX_HTTP_CLIENT_BODY_BUFFER_SIZE
value: "50m"
Option B β Modify via Kong Configuration JSON in APIM Console
{
"nginx_http_client_body_buffer_size": "8k",
"nginx_proxy_buffer_size": "16k",
"nginx_proxy_buffers": "10 16k",
"nginx_proxy_busy_buffers_size": "64k"
}
After changes, restart Kong pods:
kubectl rollout restart deployment kong -n <namespace>
Method 2: NGINX Ingress Controller ConfigMapβ
Applies to all traffic routed through the NGINX Ingress Controller.
Example:
apiVersion: v1
kind: ConfigMap
metadata:
name: nginx-configuration
namespace: ingress-nginx
data:
proxy-body-size: "50m"
client-header-buffer-size: "4k"
large-client-header-buffers: "4 16k"
client-body-buffer-size: "50m"
Restart the Ingress Controller after applying changes:
kubectl rollout restart deployment ingress-nginx-controller -n ingress-nginx
Method 3: Ingress Resource Annotationsβ
Applies only to a specific service via annotations in the Ingress manifest.
Example:
apiVersion: [networking.k8s.io/v1](http://networking.k8s.io/v1)
kind: Ingress
metadata:
name: my-ingress
namespace: your-namespace
annotations:
[nginx.ingress.kubernetes.io/proxy-body-size:](http://nginx.ingress.kubernetes.io/proxy-body-size:) "50m"
[nginx.ingress.kubernetes.io/client-body-buffer-size:](http://nginx.ingress.kubernetes.io/client-body-buffer-size:) "50m"
spec:
ingressClassName: nginx
rules:
- host: your.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: your-service
port:
number: 80
This is the most fine-grained control level and takes highest precedence over global settings.
Priority Order of Applicationβ
When multiple settings coexist, the system resolves them in the following order of precedence:
- Ingress Resource Annotations (specific service-level override)
- NGINX Ingress ConfigMap (applies globally to all Ingress resources)
- Kong Gateway Deployment / Kong Configuration (internal to Kong proxy only)
Summary Tableβ
Use Case | Relevant Parameters |
---|---|
Large headers | nginx_http_client_header_buffer_size, nginx_http_large_client_header_buffers |
Large body (client) | nginx_http_client_max_body_size, nginx_http_client_body_buffer_size |
Large body (Admin API) | nginx_admin_client_max_body_size, nginx_admin_client_body_buffer_size |
Ingress-wide limits | Use ConfigMap with proxy-body-size, client-body-buffer-size, etc. |
Per-service override | Use Ingress annotations (e.g., proxy-body-size, client-body-buffer-size) |