Proxy Buffer Configuration Auto-Adjustment

This document explains how the --with-directive-autoadjust option prevents NGINX configuration errors by automatically adjusting HTTP proxy buffer directives.

What it does

The --with-directive-autoadjust feature automatically fixes common proxy buffer configuration mistakes that would otherwise cause NGINX to fail with errors like:

[emerg] "proxy_busy_buffers_size" must be less than the size of all "proxy_buffers" minus one buffer

What gets fixed:

  • If you don’t specify proxy_buffers, it sets a sensible default of 8 4k
  • If your proxy_busy_buffers_size is too large, it reduces it to a safe value
  • If the number of proxy buffers is outside the valid range (minimum 2, maximum 1024), it gets clamped to those limits
  • Empty or invalid buffer settings get corrected automatically

Works with:

How to enable auto-adjustment

Add the flag to the controller container:

    args:
      - --with-directive-autoadjust=true

Enable via the Helm chart values file:

controller:
    directiveAutoAdjust: "true"

Examples

Example 1

Input:

data:
    proxy-buffer-size: "5m"
    proxy-buffers: "8 1m"

Before enabling --with-directive-autoadjust, NGINX fails to start with configuration validation errors.

stderr: "2025/08/26 14:29:49 [emerg] 196#196: "proxy_busy_buffers_size" must be less than the size of all "proxy_buffers" minus one buffer in /etc/nginx/nginx.conf:121"

With --with-directive-autoadjust, the configuration is automatically adjusted:

		proxy_buffers 8 1m;
		proxy_buffer_size 5m;
		proxy_busy_buffers_size 5m;

Logs:

I20250826 14:31:54.515490   1 configmaps.go:380] Changes made to proxy values: adjusted proxy_busy_buffers_size from  to 5m because it was too small

Example 2

Input:

data:
  proxy-buffers: "1000000 1m"   # Extremely high buffer count
  proxy-buffer-size: "999m"     # Very large buffer size
  proxy-busy-buffers-size: "500m"
stderr: "2025/08/26 14:34:46 [emerg] 47#47: "proxy_busy_buffers_size" must be equal to or greater than the maximum of the value of "proxy_buffer_size" and one of the "proxy_buffers" in /etc/nginx/nginx.conf:121\n"

With --with-directive-autoadjust, sensible defaults are applied:

		proxy_buffers 1024 1m;
		proxy_buffer_size 999m;
		proxy_busy_buffers_size 999m;

Logs:

I20250826 14:36:47.864375   1 configmaps.go:380] Changes made to proxy values: adjusted proxy_buffers number from 1000000 to 1024
I20250826 14:36:47.864389   1 configmaps.go:380] Changes made to proxy values: adjusted proxy_busy_buffers_size from 500m to 999m because it was too small

Monitoring and logging

The controller outputs a log message whenever any of the proxy buffer directives are changed. Examples:

I20250826 14:06:43.734757   1 annotations.go:341] Changes made to proxy values: adjusted proxy_buffer_size from 512k to 64k because it was too big for proxy_buffers (2 64k)
I20250826 14:06:43.734842   1 annotations.go:341] Changes made to proxy values: adjusted proxy_busy_buffers_size from  to 64k because it was too small

View adjustment logs:

kubectl logs <pod-name> -n <namespace> | grep "Changes made to proxy values"