본문으로 건너뛰기

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 Bad Request – 요청 헤더 또는 쿠키가 너무 큽니다. 오류가 발생할 경우.
  • 권장 사항: 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 콘솔 구성​

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

옵션 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: "50m" spec: ingressClassName: nginx rules:

  • host: your.example.com http: paths:
    • path: / pathType: Prefix backend: service: name: your-service port: number: 80
이것은 가장 세밀한 제어 수준이며 전역 설정보다 높은 우선 순위를 가집니다.

![](/img/apim/advanced-guide/20fb7135-d33b-8028-bfbf-c290d6cef6c0.png)

### 애플리케이션의 우선 순위 \{#priority-order-of-application}


여러 설정이 공존할 때, 시스템은 다음과 같은 우선 순위로 이를 해결합니다:

1. 인그레스 리소스 주석 (특정 서비스 수준 재정의)
1. NGINX 인그레스 ConfigMap (모든 인그레스 리소스에 전역적으로 적용)
1. Kong 게이트웨이 배포 / Kong 구성 (Kong 프록시 내부 전용)
## 요약 표 \{#summary-table}

| <b>Use Case</b> | <b>Relevant Parameters</b> |
| --- | --- |
| 큰 헤더 | nginx_http_client_header_buffer_size, nginx_http_large_client_header_buffers |
| 큰 본문 (클라이언트) | nginx_http_client_max_body_size, nginx_http_client_body_buffer_size |
| 큰 본문 (관리 API) | nginx_admin_client_max_body_size, nginx_admin_client_body_buffer_size |
| 인그레스 전체 제한 | proxy-body-size, client-body-buffer-size 등을 사용하여 ConfigMap 사용 |
| 서비스별 재정의 | 인그레스 주석 사용 (예: proxy-body-size, client-body-buffer-size) |