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:

1. Via Kong Deployment or Kong Configuration JSON
2. Via NGINX Ingress Controller ConfigMap
3. 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:

1. Ingress Resource Annotations (specific service-level override)
2. NGINX Ingress ConfigMap (applies globally to all Ingress resources)
3. 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)