ConfigMap Resource

The ConfigMap resources allows you to customize or fine tune NGINX behavior.

The ConfigMap resources allows you to customize or fine tune NGINX behavior. For example, set the number of worker processes or customize the access log format.

Using ConfigMap

  1. Our installation instructions deploy an empty ConfigMap while the default installation manifests specify it in the command-line arguments of the Ingress Controller. However, if you customized the manifests, to use ConfigMap, make sure to specify the ConfigMap resource to use through the command-line arguments of the Ingress Controller.

  2. Create a ConfigMap file with the name nginx-config.yaml and set the values that make sense for your setup:

    kind: ConfigMap
apiVersion: v1
metadata:
  name: nginx-config
  namespace: nginx-ingress
data:
  proxy-connect-timeout: "10s"
  proxy-read-timeout: "10s"
  client-max-body-size: "2m"

    See the section Summary of ConfigMap Keys for the explanation of the available ConfigMap keys (such as proxy-connect-timeout in this example).

  3. Create a new (or update the existing) ConfigMap resource:

    kubectl apply -f nginx-config.yaml

    The NGINX configuration will be updated.

ConfigMap and Ingress Annotations

Annotations allow you to configure advanced NGINX features and customize or fine tune NGINX behavior.

The ConfigMap applies globally, meaning that it affects every Ingress resource. In contrast, annotations always apply to their Ingress resource. Annotations allow overriding some ConfigMap keys. For example, the nginx.org/proxy-connect-timeout annotations overrides the proxy-connect-timeout ConfigMap key.

See the doc about annotations.

ConfigMap and VirtualServer/VirtualServerRoute Resource

The ConfigMap affects every VirtualServer and VirtualServerRoute resources. However, the fields of those resources allow overriding some ConfigMap keys. For example, the connect-timeout field of the upstream overrides the proxy-connect-timeout ConfigMap key.

See the doc about VirtualServer and VirtualServerRoute resources.

Summary of ConfigMap Keys

ConfigMap Key Description Default Example
external-status-address Sets the address to be reported in the status of Ingress resources. Requires the -report-status command-line argument. Overrides the -external-service argument. N/A Report Ingress Status.

General Customization

ConfigMap Key Description Default Example
proxy-connect-timeout Sets the value of the proxy_connect_timeout and grpc_connect_timeout directive. 60s
proxy-read-timeout Sets the value of the proxy_read_timeout and grpc_read_timeout directive. 60s
proxy-send-timeout Sets the value of the proxy_send_timeout and grpc_send_timeout directive. 60s
client-max-body-size Sets the value of the client_max_body_size directive. 1m
proxy-buffering Enables or disables buffering of responses from the proxied server. True
proxy-buffers Sets the value of the proxy_buffers directive. Depends on the platform.
proxy-buffer-size Sets the value of the proxy_buffer_size and grpc_buffer_size directives. Depends on the platform.
proxy-max-temp-file-size Sets the value of the proxy_max_temp_file_size directive. 1024m
set-real-ip-from Sets the value of the set_real_ip_from directive. N/A
real-ip-header Sets the value of the real_ip_header directive. X-Real-IP
real-ip-recursive Enables or disables the real_ip_recursive directive. False
default-server-return Configures the return directive in the default server, which handles a client request if none of the hosts of Ingress or VirtualServer resources match. The default value configures NGINX to return a 404 error page. You can configure a fixed response or a redirect. For example, default-server-return: 302 https://nginx.org will redirect a client to https://nginx.org. 404
server-tokens Enables or disables the server_tokens directive. Additionally, with the NGINX Plus, you can specify a custom string value, including the empty string value, which disables the emission of the “Server” field. True
worker-processes Sets the value of the worker_processes directive. auto
worker-rlimit-nofile Sets the value of the worker_rlimit_nofile directive. N/A
worker-connections Sets the value of the worker_connections directive. 1024
worker-cpu-affinity Sets the value of the worker_cpu_affinity directive. N/A
worker-shutdown-timeout Sets the value of the worker_shutdown_timeout directive. N/A
server-names-hash-bucket-size Sets the value of the server_names_hash_bucket_size directive. 256
server-names-hash-max-size Sets the value of the server_names_hash_max_size directive. 1024
map-hash-bucket-size Sets the value of the map_hash_bucket_size directive. 256
map-hash-max-size Sets the value of the map_hash_max_size directive. 2048
resolver-addresses Sets the value of the resolver addresses. Note: If you use a DNS name (for example, kube-dns.kube-system.svc.cluster.local ) as a resolver address, NGINX Plus will resolve it using the system resolver during the start and on every configuration reload. If the name cannot be resolved or the DNS server doesn’t respond, NGINX Plus will fail to start or reload. To avoid this, we recommend using IP addresses as resolver addresses instead of DNS names. Supported in NGINX Plus only. N/A Support for Type ExternalName Services.
resolver-ipv6 Enables IPv6 resolution in the resolver. Supported in NGINX Plus only. True Support for Type ExternalName Services.
resolver-valid Sets the time NGINX caches the resolved DNS records. Supported in NGINX Plus only. TTL value of a DNS record Support for Type ExternalName Services.
resolver-timeout Sets the resolver_timeout for name resolution. Supported in NGINX Plus only. 30s Support for Type ExternalName Services.
keepalive-timeout Sets the value of the keepalive_timeout directive. 75s
keepalive-requests Sets the value of the keepalive_requests directive. 1000
variables-hash-bucket-size Sets the value of the variables_hash_bucket_size directive. 256
variables-hash-max-size Sets the value of the variables-hash-max-size directive. 1024

Logging

ConfigMap Key Description Default Example
error-log-level Sets the global error log level for NGINX. notice
access-log-off Disables the access log. False
default-server-access-log-off Disables the access log for the default server. If access log is disabled globally (access-log-off: "True"), then the default server access log is always disabled. False
log-format Sets the custom log format for HTTP and HTTPS traffic. For convenience, it is possible to define the log format across multiple lines (each line separated by \n). In that case, the Ingress Controller will replace every \n character with a space character. All ' characters must be escaped. See the template file for the access log. Custom Log Format.
log-format-escaping Sets the characters escaping for the variables of the log format. Supported values: json (JSON escaping), default (the default escaping) none (disables escaping). default
stream-log-format Sets the custom log format for TCP, UDP, and TLS Passthrough traffic. For convenience, it is possible to define the log format across multiple lines (each line separated by \n). In that case, the Ingress Controller will replace every \n character with a space character. All ' characters must be escaped. See the template file.
stream-log-format-escaping Sets the characters escaping for the variables of the stream log format. Supported values: json (JSON escaping), default (the default escaping) none (disables escaping). default

Request URI/Header Manipulation

ConfigMap Key Description Default Example
proxy-hide-headers Sets the value of one or more proxy_hide_header directives. Example: "nginx.org/proxy-hide-headers": "header-a,header-b" N/A
proxy-pass-headers Sets the value of one or more proxy_pass_header directives. Example: "nginx.org/proxy-pass-headers": "header-a,header-b" N/A

Auth and SSL/TLS

ConfigMap Key Description Default Example
redirect-to-https Sets the 301 redirect rule based on the value of the http_x_forwarded_proto header on the server block to force incoming traffic to be over HTTPS. Useful when terminating SSL in a load balancer in front of the Ingress Controller — see 115 False
ssl-redirect Sets an unconditional 301 redirect rule for all incoming HTTP traffic to force incoming traffic over HTTPS. True
hsts Enables HTTP Strict Transport Security (HSTS) : the HSTS header is added to the responses from backends. The preload directive is included in the header. False
hsts-max-age Sets the value of the max-age directive of the HSTS header. 2592000 (1 month)
hsts-include-subdomains Adds the includeSubDomains directive to the HSTS header. False
hsts-behind-proxy Enables HSTS based on the value of the http_x_forwarded_proto request header. Should only be used when TLS termination is configured in a load balancer (proxy) in front of the Ingress Controller. Note: to control redirection from HTTP to HTTPS configure the nginx.org/redirect-to-https annotation. False
ssl-protocols Sets the value of the ssl_protocols directive. TLSv1 TLSv1.1 TLSv1.2
ssl-prefer-server-ciphers Enables or disables the ssl_prefer_server_ciphers directive. False
ssl-ciphers Sets the value of the ssl_ciphers directive. HIGH:!aNULL:!MD5
ssl-dhparam-file Sets the content of the dhparam file. The controller will create the file and set the value of the ssl_dhparam directive with the path of the file. N/A

Listeners

ConfigMap Key Description Default Example
http2 Enables HTTP/2 in servers with SSL enabled. False
proxy-protocol Enables PROXY Protocol for incoming connections. False Proxy Protocol.

Backend Services (Upstreams)

ConfigMap Key Description Default Example
lb-method Sets the load balancing method. To use the round-robin method, specify "round_robin". "random two least_conn"
max-fails Sets the value of the max_fails parameter of the server directive. 1
upstream-zone-size Sets the size of the shared memory zone for upstreams. For NGINX, the special value 0 disables the shared memory zones. For NGINX Plus, shared memory zones are required and cannot be disabled. The special value 0 will be ignored. 256k for NGINX, 512k for NGINX Plus
fail-timeout Sets the value of the fail_timeout parameter of the server directive. 10s
keepalive Sets the value of the keepalive directive. Note that proxy_set_header Connection ""; is added to the generated configuration when the value > 0. 0

Snippets and Custom Templates

ConfigMap Key Description Default Example
main-snippets Sets a custom snippet in main context. N/A
http-snippets Sets a custom snippet in http context. N/A
location-snippets Sets a custom snippet in location context. N/A
server-snippets Sets a custom snippet in server context. N/A
stream-snippets Sets a custom snippet in stream context. N/A Support for TCP/UDP Load Balancing.
main-template Sets the main NGINX configuration template. By default the template is read from the file in the container. Custom Templates.
ingress-template Sets the NGINX configuration template for an Ingress resource. By default the template is read from the file on the container. Custom Templates.
virtualserver-template Sets the NGINX configuration template for an VirtualServer resource. By default the template is read from the file on the container. Custom Templates.

Modules

ConfigMap Key Description Default Example
opentracing Enables OpenTracing globally (for all Ingress, VirtualServer and VirtualServerRoute resources). Note: requires the Ingress Controller image with OpenTracing module and a tracer. See the docs for more information. False
opentracing-tracer Sets the path to the vendor tracer binary plugin. N/A
opentracing-tracer-config Sets the tracer configuration in JSON format. N/A
app-protect-compressed-requests-action Sets the app_protect_compressed_requests_action global directive. drop
app-protect-cookie-seed Sets the app_protect_cookie_seed global directive. Random automatically generated string
app-protect-failure-mode-action Sets the app_protect_failure_mode_action global directive. pass
app-protect-cpu-thresholds Sets the app_protect_cpu_thresholds global directive. high=100 low=100
app-protect-physical-memory-util-thresholds Sets the app_protect_physical_memory_util_thresholds global directive. high=100 low=100
app-protect-reconnect-period-seconds Sets the app_protect_reconnect_period_seconds global directive. 5
app-protect-dos-log-format Sets the custom log format for Dos Access log traffic. For convenience, it is possible to define the log format across multiple lines (each line separated by \n). In that case, the Ingress Controller will replace every \n character with a space character. All ' characters must be escaped. , vs_name_al=$app_protect_dos_vs_name, ip=$remote_addr, tls_fp=$app_protect_dos_tls_fp, outcome=$app_protect_dos_outcome, reason=$app_protect_dos_outcome_reason, policy_name=$app_protect_dos_policy_name, dos_version=$app_protect_dos_version, ip_tls=$remote_addr:$app_protect_dos_tls_fp,
app-protect-dos-log-format-escaping Sets the characters escaping for the variables of the stream log format. Supported values: json (JSON escaping), default (the default escaping) none (disables escaping). default
app-protect-dos-arb-fqdn Sets the app-protect-dos-arb-fqdn directive. svc-appprotect-dos-arb