본문으로 건너뛰기

HTTP Header Max Size Adjustment

이 가이드는 Kubernetes의 Kong Gateway 및 NGINX Ingress 환경 내에서 HTTP 요청과 관련된 버퍼 및 본문 크기 제한을 수정하는 방법에 대한 자세한 지침을 제공합니다. 이러한 구성은 큰 헤더나 페이로드로 인해 발생하는 요청 실패를 방지하는 데 도움이 됩니다.

개요​

Kong은 HTTP 트래픽 처리를 위해 내장된 NGINX 엔진을 사용합니다. 기본적으로 NGINX는 요청 헤더와 본문에 대해 보수적인 크기 제한을 적용합니다. 프로덕션 환경에서는 특히 다음과 같은 경우에: 큰 요청 헤더(예: JWT 토큰, 쿠키, 사용자 에이전트), 큰 요청 본문(예: 파일 업로드) 또는 요청 변환이 있는 높은 동시성 처리 시,…

이러한 제한은 다음과 같은 오류를 피하기 위해 증가해야 합니다:

  • 400 잘못된 요청 – 요청 헤더 또는 쿠키가 너무 큼
  • 413 요청 엔티티가 너무 큼

이 가이드는 이러한 제한을 조정하는 세 가지 방법을 설명합니다:

  1. Kong 배포 또는 Kong 구성 JSON을 통해
  2. NGINX Ingress 컨트롤러 ConfigMap을 통해
  3. Ingress 리소스 주석을 통해 (서비스별)

주요 구성 매개변수 (상세 분석)​

nginx_http_client_header_buffer_size​

  • 설명: 클라이언트 요청 헤더를 읽을 때 사용되는 단일 버퍼의 크기를 설정합니다.
  • 기본값: 1k
  • 수정 시기: Authorization, Cookie, User-Agent와 같은 요청 헤더가 너무 길어질 경우(예: SSO 토큰 또는 다중 쿠키 헤더).
  • 권장: 안정성을 보장하기 위해 4k 또는 8k로 증가시킵니다.
  • 주의: 너무 크게 설정하면 높은 동시성에서 메모리 사용량이 증가할 수 있습니다.

nginx_http_large_client_header_buffers​

  • 설명: 큰 요청 헤더(예: 다수 수신자 쿠키)에 대한 버퍼의 수와 크기를 구성합니다.
  • 기본값: 4 8k (8k 크기의 4개 버퍼)
  • 수정 시기: 400 잘못된 요청 – 요청 헤더 또는 쿠키가 너무 큼 오류가 발생할 경우.
  • 권장: 4 16k 또는 8 16k로 증가시킵니다.
  • 주의: 불필요한 메모리 오버헤드를 피하기 위해 필요할 때만 확장합니다.

nginx_http_client_max_body_size​

  • 설명: Kong이 Content-Length에 따라 수용하는 요청 본문의 최대 크기를 정의합니다.
  • 기본값: 0 (제한 없음)
  • 수정 시기: 과도한 본문 페이로드(예: 큰 파일 업로드)로 인해 413 오류가 발생하지 않도록 하기 위해.
  • 권장: 예상 사용량에 따라 설정, 예: 10m, 50m.
  • 주의: 이 크기를 초과하는 요청은 Kong에서 413 응답을 트리거합니다.

nginx_admin_client_max_body_size​

  • 설명: Admin API에서 수용하는 최대 본문 크기를 설정합니다.
  • 기본값: 10m
  • 수정 시기: Admin API에 큰 구성 페이로드를 보낼 때(예: 배치 경로 등록).
  • 권장: 필요 시 20m에서 50m로 설정합니다.
  • 주의: Admin API는 민감하므로 너무 많이 증가시키면 보안 위험이 발생할 수 있습니다.

nginx_http_client_body_buffer_size​

  • 설명: 요청 본문을 메모리로 읽기 위한 버퍼 크기입니다. 본문이 이 크기를 초과하면 디스크에 기록됩니다.
  • 기본값: 8k
  • 수정 시기: request-transformer, rate-limiting 등과 같은 본문 조작 플러그인을 사용할 때 디스크에 기록하지 않도록 하기 위해.
  • 권장: client_max_body_size와 일치시킵니다, 예: 50m.
  • 주의: 큰 값은 메모리 소비를 증가시킵니다(설정 시 요청 동시성을 고려).

nginx_admin_client_body_buffer_size​

  • 설명: 위와 동일하지만 Admin API 요청 본문에 대한 것입니다.
  • 기본값: 10m
  • 권장: Admin API 작업량에 따라 확장합니다.

구성 방법​

방법 1: Kong 배포 또는 APIM 콘솔 구성​

Kong Gateway 포드 내에서 실행되는 내부 NGINX에만 적용됩니다.

옵션 A – Kong 배포 환경 변수 수정

- 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"

옵션 B – APIM 콘솔에서 Kong 구성 JSON을 통해 수정

{
"nginx_http_client_body_buffer_size": "8k",
"nginx_proxy_buffer_size": "16k",
"nginx_proxy_buffers": "10 16k",
"nginx_proxy_busy_buffers_size": "64k"
}

변경 후 Kong 포드를 재시작합니다:

kubectl rollout restart deployment kong -n <namespace>

방법 2: NGINX Ingress 컨트롤러 ConfigMap​

NGINX Ingress 컨트롤러를 통해 라우팅되는 모든 트래픽에 적용됩니다.

예시:

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"

변경 사항을 적용한 후 Ingress 컨트롤러를 재시작합니다:

kubectl rollout restart deployment ingress-nginx-controller -n ingress-nginx

방법 3: Ingress 리소스 주석​

Ingress 매니페스트의 주석을 통해 특정 서비스에만 적용됩니다.

예시:

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

이것은 가장 세밀한 제어 수준이며 전역 설정보다 높은 우선 순위를 가집니다.

적용 우선 순위​

여러 설정이 공존할 때 시스템은 다음 우선 순위에 따라 이를 해결합니다:

  1. Ingress 리소스 주석 (특정 서비스 수준 오버라이드)
  2. NGINX Ingress ConfigMap (모든 Ingress 리소스에 전역적으로 적용)
  3. Kong Gateway 배포 / Kong 구성 (Kong 프록시 내부 전용)

요약 표​

Use CaseRelevant Parameters
큰 헤더nginx_http_client_header_buffer_size, nginx_http_large_client_header_buffers
큰 본문 (클라이언트)nginx_http_client_max_body_size, nginx_http_client_body_buffer_size
큰 본문 (Admin API)nginx_admin_client_max_body_size, nginx_admin_client_body_buffer_size
Ingress 전역 제한proxy-body-size, client-body-buffer-size가 포함된 ConfigMap 사용
서비스별 오버라이드Ingress 주석 사용 (예: proxy-body-size, client-body-buffer-size)