diff --git a/content/includes/nic/configuration/global-configuration/configmap-resource.md b/content/includes/nic/configuration/global-configuration/configmap-resource.md index ab77c60c9..b4c8ad7e3 100644 --- a/content/includes/nic/configuration/global-configuration/configmap-resource.md +++ b/content/includes/nic/configuration/global-configuration/configmap-resource.md @@ -80,6 +80,7 @@ For more information, view the [VirtualServer and VirtualServerRoute resources]( |*proxy-buffering* | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | *True* | | |*proxy-buffers* | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | |*proxy-buffer-size* | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | +|*proxy-busy-buffers-size* | Sets the value of the [proxy_busy_buffers_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) directive. | Depends on the platform. | | |*proxy-max-temp-file-size* | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | *1024m* | | |*set-real-ip-from* | Sets the value of the [set_real_ip_from](https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive. | N/A | | |*real-ip-header* | Sets the value of the [real_ip_header](https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header) directive. | *X-Real-IP* | | @@ -198,7 +199,7 @@ If you encounter the error `error [emerg] 13#13: "zone_sync" directive is duplic {{}} |ConfigMap Key | Description | Default | Example | | ---| ---| ---| --- | -|*zone-sync* | Enables zone synchronization between NGINX Ingress Controller Pods. This autogenerates a [zone_sync_server](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync_server) and a headless service using the `ReplicaSet` or `DaemonSet` name. Please note that this headless service will be automatically cleaned up when uninstalling via Helm or by removing the value from the ConfigMap. The headless service will need to be manually removed if the `controller.customConfigMap` value is set via Helm or the deployment is uninstalled via Manifests. Each Ingress Controller manages its own headless service. NGINX Plus Required. | *False* | | +|*zone-sync* | Enables zone synchronization between NGINX Ingress Controller Pods. This autogenerates a [zone_sync_server](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync_server) and a headless service using the `ReplicaSet`, `DaemonSet` or `StatefulSet` name. Please note that this headless service will be automatically cleaned up when uninstalling via Helm or by removing the value from the ConfigMap. The headless service will need to be manually removed if the `controller.customConfigMap` value is set via Helm or the deployment is uninstalled via Manifests. Each Ingress Controller manages its own headless service. NGINX Plus Required. | *False* | | |*zone-sync-port* | Specifies the optional port on which NGINX Ingress Controller listens for zone sync traffic. NGINX Plus & `zone-sync` Required. | *12345* | | |*zone-sync-resolver-addresses* | Configures optional addresses used in the [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive for zone-sync. This field takes a comma separated list of addresses. NGINX Plus & `zone-sync` Required | `kube-dns.kube-system.svc.cluster.local` | | |*zone-sync-resolver-ipv6* | Configures whether the optional [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive for zone-sync will look up IPv6 addresses. NGINX Plus & `zone-sync` Required | `true` | | diff --git a/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md b/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md index 1690f3a0b..11ccf7099 100644 --- a/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md +++ b/content/includes/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -108,6 +108,7 @@ The table below summarizes the available annotations. | *nginx.org/proxy-buffering* | *proxy-buffering* | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | *True* | | | *nginx.org/proxy-buffers* | *proxy-buffers* | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | | *nginx.org/proxy-buffer-size* | *proxy-buffer-size* | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | +| *nginx.org/proxy-busy-buffers-size* | *proxy-busy-buffers-size* | Sets the value of the [proxy_busy_buffers_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) directive. | Depends on the platform. | | | *nginx.org/proxy-max-temp-file-size* | *proxy-max-temp-file-size* | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | *1024m* | | | *nginx.org/server-tokens* | *server-tokens* | Enables or disables the [server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#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* | | | *nginx.org/path-regex* | N/A | Enables regular expression modifiers for Ingress path parameter. This translates to the NGINX [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive. You can specify one of these values: "case_sensitive", "case_insensitive", or "exact". The annotation is applied to the entire Ingress resource and its paths. While using Master and Minion Ingresses i.e. Mergeable Ingresses, this annotation can be specified on Minion types. The `path-regex` annotation specified on Master is ignored, and has no effect on paths defined on Minions. | N/A | [path-regex](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/path-regex) | diff --git a/content/includes/nic/configuration/security.md b/content/includes/nic/configuration/security.md index 4ade6e0cf..3d73fbf0d 100644 --- a/content/includes/nic/configuration/security.md +++ b/content/includes/nic/configuration/security.md @@ -53,10 +53,12 @@ The block below shows the code you will look for: # volumes: # - name: nginx-etc # emptyDir: {} -# - name: nginx-cache -# emptyDir: {} +# - name: nginx-cache # do not set this value in statefulset if volumeclaimtemplate is set +# emptyDir: {} # do not set this value in statefulset if volumeclaimtemplate is set # - name: nginx-lib # emptyDir: {} +# - name: nginx-lib-state +# emptyDir: {} # - name: nginx-log # emptyDir: {} . @@ -73,6 +75,8 @@ The block below shows the code you will look for: # name: nginx-cache # - mountPath: /var/lib/nginx # name: nginx-lib +# - mountPath: /var/lib/nginx/state +# name: nginx-lib-state # - mountPath: /var/log/nginx # name: nginx-log ``` diff --git a/content/includes/nic/configuration/virtualserver-and-virtualserverroute-resources.md b/content/includes/nic/configuration/virtualserver-and-virtualserverroute-resources.md index 3f447ed18..2807c0440 100644 --- a/content/includes/nic/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/content/includes/nic/configuration/virtualserver-and-virtualserverroute-resources.md @@ -371,6 +371,7 @@ tls: |``buffering`` | Enables buffering of responses from the upstream server. See the [proxy_buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) directive. The default is set in the ``proxy-buffering`` ConfigMap key. | ``boolean`` | No | |``buffers`` | Configures the buffers used for reading a response from the upstream server for a single connection. | [buffers](#upstreambuffers) | No | |``buffer-size`` | Sets the size of the buffer used for reading the first part of a response received from the upstream server. See the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) directive. The default is set in the ``proxy-buffer-size`` ConfigMap key. | ``string`` | No | +|``busy-buffer-size`` | Sets the size of the buffer used for reading a response from the upstream server when the response is larger than the ``buffer-size``. See the [proxy_busy_buffers_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) directive. The default is set in the ``proxy-busy-buffers-size`` ConfigMap key. | ``string`` | No | |``ntlm`` | Allows proxying requests with NTLM Authentication. See the [ntlm](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#ntlm) directive. In order for NTLM authentication to work, it is necessary to enable keepalive connections to upstream servers using the ``keepalive`` field. Note: this feature is supported only in NGINX Plus.| ``boolean`` | No | |``type`` |The type of the upstream. Supported values are ``http`` and ``grpc``. The default is ``http``. For gRPC, it is necessary to enable HTTP/2 in the [ConfigMap](/nginx-ingress-controller/configuration/global-configuration/configmap-resource/#listeners) and configure TLS termination in the VirtualServer. | ``string`` | No | |``backup`` | The name of the backup service of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname). This will be used when the primary servers are unavailable. Note: The parameter cannot be used along with the ``random`` , ``hash`` or ``ip_hash`` load balancing methods. | ``string`` | No | diff --git a/content/includes/nic/installation/deploy-controller.md b/content/includes/nic/installation/deploy-controller.md index 7dcec97bd..489d80b7b 100644 --- a/content/includes/nic/installation/deploy-controller.md +++ b/content/includes/nic/installation/deploy-controller.md @@ -6,5 +6,6 @@ You have two options for deploying NGINX Ingress Controller: - **Deployment**. Choose this method for the flexibility to dynamically change the number of NGINX Ingress Controller replicas. - **DaemonSet**. Choose this method if you want NGINX Ingress Controller to run on all nodes or a subset of nodes. +- **StatefulSet**. Choose this method when you need stable, persistent storage and ordered deployment/scaling for your NGINX Ingress Controller pods. Before you start, update the [command-line arguments]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}) for the NGINX Ingress Controller container in the relevant manifest file to meet your specific requirements. diff --git a/content/includes/nic/installation/manifests/statefulset.md b/content/includes/nic/installation/manifests/statefulset.md new file mode 100644 index 000000000..9c7cac0ae --- /dev/null +++ b/content/includes/nic/installation/manifests/statefulset.md @@ -0,0 +1,25 @@ +--- +nd-docs: DOCS-000 +--- + +For additional context on managing containers using Kubernetes StatefulSets, refer to the official Kubernetes [StatefulSets](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) documentation. + +When you deploy NGINX Ingress Controller as a StatefulSet, Kubernetes creates pods with stable network identities and persistent storage. + +- For NGINX, run: + + ```shell + kubectl apply -f deployments/stateful-set/nginx-ingress.yaml + ``` + +- For NGINX Plus, run: + + ```shell + kubectl apply -f deployments/stateful-set/nginx-plus-ingress.yaml + ``` + + Update the `nginx-plus-ingress.yaml` file to include your chosen image from the F5 Container registry or your custom container image. + +{{< call-out "note" >}} +StatefulSets include persistent volume claims for nginx cache storage via `volumeClaimTemplates`. You may need to configure a StorageClass in your cluster or modify the volumeClaimTemplates section in the manifest to match your storage requirements. Other volumes (like those needed for App Protect modules) are configured in the regular `volumes` section, not in volumeClaimTemplates. +{{< /call-out >}} diff --git a/content/nic/configuration/global-configuration/command-line-arguments.md b/content/nic/configuration/global-configuration/command-line-arguments.md index 07f5d6f98..f59e990fc 100644 --- a/content/nic/configuration/global-configuration/command-line-arguments.md +++ b/content/nic/configuration/global-configuration/command-line-arguments.md @@ -658,6 +658,20 @@ The default value is `false`. --- +### -enable-directive-autoadjust + +Automatically adjusts NGINX buffer directives to prevent configuration errors. + +The default value is `false`. + +When enabled, the controller automatically adjusts `proxy_buffers`, `proxy_buffer_size`, and `proxy_busy_buffers_size` to ensure they work together properly and NGINX can start successfully. + +More explanation about this feature can be found in the guide [here](). + + + +--- + ### -enable-telemetry-reporting Enable gathering and reporting of software telemetry. diff --git a/content/nic/configuration/global-configuration/configmap-resource.md b/content/nic/configuration/global-configuration/configmap-resource.md index d854bebc6..9161896f8 100644 --- a/content/nic/configuration/global-configuration/configmap-resource.md +++ b/content/nic/configuration/global-configuration/configmap-resource.md @@ -75,6 +75,7 @@ For more information, view the [VirtualServer and VirtualServerRoute resources]( |*proxy-buffering* | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | *True* | | |*proxy-buffers* | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | |*proxy-buffer-size* | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | +|*proxy-busy-buffers-size* | Sets the value of the [proxy_busy_buffers_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) directive. | Depends on the platform. | | |*proxy-max-temp-file-size* | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | *1024m* | | |*set-real-ip-from* | Sets the value of the [set_real_ip_from](https://nginx.org/en/docs/http/ngx_http_realip_module.html#set_real_ip_from) directive. | N/A | | |*real-ip-header* | Sets the value of the [real_ip_header](https://nginx.org/en/docs/http/ngx_http_realip_module.html#real_ip_header) directive. | *X-Real-IP* | | @@ -171,7 +172,7 @@ If you encounter the error `error [emerg] 13#13: "zone_sync" directive is duplic |ConfigMap Key | Description | Default | | ---| ---| ---| -|*zone-sync* | Enables zone synchronization between NGINX Ingress Controller Pods. This autogenerates a [zone_sync_server](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync_server) and a headless service using the `ReplicaSet` or `DaemonSet` name. Please note that this headless service will be automatically cleaned up when uninstalling via Helm or by removing the value from the ConfigMap. The headless service will need to be manually removed if the `controller.customConfigMap` value is set via Helm or the deployment is uninstalled via Manifests. Each Ingress Controller manages its own headless service. NGINX Plus Required. | *False* | +|*zone-sync* | Enables zone synchronization between NGINX Ingress Controller Pods. This autogenerates a [zone_sync_server](https://nginx.org/en/docs/stream/ngx_stream_zone_sync_module.html#zone_sync_server) and a headless service using the `ReplicaSet`, `DaemonSet` or `StatefulSet` name. Please note that this headless service will be automatically cleaned up when uninstalling via Helm or by removing the value from the ConfigMap. The headless service will need to be manually removed if the `controller.customConfigMap` value is set via Helm or the deployment is uninstalled via Manifests. Each Ingress Controller manages its own headless service. NGINX Plus Required. | *False* | |*zone-sync-port* | Specifies the optional port on which NGINX Ingress Controller listens for zone sync traffic. NGINX Plus & `zone-sync` Required. | *12345* | |*zone-sync-resolver-addresses* | Configures optional addresses used in the [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive for zone-sync. This field takes a comma separated list of addresses. NGINX Plus & `zone-sync` Required | `kube-dns.kube-system.svc.cluster.local` | |*zone-sync-resolver-ipv6* | Configures whether the optional [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive for zone-sync will look up IPv6 addresses. NGINX Plus & `zone-sync` Required | `true` | diff --git a/content/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md b/content/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md index 7bbdb4685..f378fdddf 100644 --- a/content/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md +++ b/content/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md @@ -108,6 +108,7 @@ The table below summarizes the available annotations. | *nginx.org/proxy-buffering* | *proxy-buffering* | Enables or disables [buffering of responses](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) from the proxied server. | *True* | | | *nginx.org/proxy-buffers* | *proxy-buffers* | Sets the value of the [proxy_buffers](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) directive. | Depends on the platform. | | | *nginx.org/proxy-buffer-size* | *proxy-buffer-size* | Sets the value of the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) and [grpc_buffer_size](https://nginx.org/en/docs/http/ngx_http_grpc_module.html#grpc_buffer_size) directives. | Depends on the platform. | | +| *nginx.org/proxy-busy-buffers-size* | *proxy-busy-buffers-size* | Sets the value of the [proxy_busy_buffers_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) directive. | Depends on the platform. | | | *nginx.org/proxy-max-temp-file-size* | *proxy-max-temp-file-size* | Sets the value of the [proxy_max_temp_file_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_max_temp_file_size) directive. | *1024m* | | | *nginx.org/server-tokens* | *server-tokens* | Enables or disables the [server_tokens](https://nginx.org/en/docs/http/ngx_http_core_module.html#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* | | | *nginx.org/path-regex* | N/A | Enables regular expression modifiers for Ingress path parameter. This translates to the NGINX [location](https://nginx.org/en/docs/http/ngx_http_core_module.html#location) directive. You can specify one of these values: "case_sensitive", "case_insensitive", or "exact". The annotation is applied to the entire Ingress resource and its paths. While using Master and Minion Ingresses i.e. Mergeable Ingresses, this annotation can be specified on Minion types. The `path-regex` annotation specified on Master is ignored, and has no effect on paths defined on Minions. | N/A | [path-regex](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/path-regex) | diff --git a/content/nic/configuration/policy-resource.md b/content/nic/configuration/policy-resource.md index fd4fb4df8..5edf8b2d0 100644 --- a/content/nic/configuration/policy-resource.md +++ b/content/nic/configuration/policy-resource.md @@ -44,6 +44,8 @@ spec: |``ingressMTLS`` | The IngressMTLS policy configures client certificate verification. | [ingressMTLS](#ingressmtls) | No | |``egressMTLS`` | The EgressMTLS policy configures upstreams authentication and certificate verification. | [egressMTLS](#egressmtls) | No | |``waf`` | The WAF policy configures WAF and log configuration policies for [NGINX AppProtect]({{< ref "/nic/installation/integrations/app-protect-waf/configuration.md" >}}) | [WAF](#waf) | No | +|``cache`` | The cache policy configures proxy caching for serving cached content. | [cache](#cache) | No | + {{% /table %}} \* A policy must include exactly one policy. @@ -446,12 +448,14 @@ This feature is implemented using the NGINX Plus directive [auth_jwt_key_request {{< /call-out >}} {{% table %}} -|Field | Description | Type | Required | -| ---| ---| ---| --- | -|``jwksURI`` | The remote URI where the request will be sent to retrieve JSON Web Key set| ``string`` | Yes | -|``keyCache`` | Enables in-memory caching of JWKS (JSON Web Key Sets) that are obtained from the ``jwksURI`` and sets a valid time for expiration. To disable ``keyCache``, set value to ``0s``. | ``string`` | Yes | -|``realm`` | The realm of the JWT. | ``string`` | Yes | -|``token`` | The token specifies a variable that contains the JSON Web Token. By default the JWT is passed in the ``Authorization`` header as a Bearer Token. JWT may be also passed as a cookie or a part of a query string, for example: ``$cookie_auth_token``. Accepted variables are ``$http_``, ``$arg_``, ``$cookie_``. | ``string`` | No | +|Field | Description | Type | Required | Default | +| ---| ---| ---| --- | --- | +|``jwksURI`` | The remote URI where the request will be sent to retrieve JSON Web Key set| ``string`` | Yes | -- | +|``keyCache`` | Enables in-memory caching of JWKS (JSON Web Key Sets) that are obtained from the ``jwksURI`` and sets a valid time for expiration. | ``string`` | Yes | -- | +|``realm`` | The realm of the JWT. | ``string`` | Yes | -- | +|``token`` | The token specifies a variable that contains the JSON Web Token. By default the JWT is passed in the ``Authorization`` header as a Bearer Token. JWT may be also passed as a cookie or a part of a query string, for example: ``$cookie_auth_token``. Accepted variables are ``$http_``, ``$arg_``, ``$cookie_``. | ``string`` | No | -- | +|``sniEnabled`` | Enables SNI (Server Name Indication) for the JWT policy. This is useful when the remote server requires SNI to serve the correct certificate. | ``bool`` | No | `false` | +|``sniName`` | The SNI name to use when connecting to the remote server. If not set, the hostname from the ``jwksURI`` will be used. | ``string`` | No | -- | {{% /table %}} {{< call-out "note" >}} @@ -738,6 +742,57 @@ policies: In this example NGINX Ingress Controller will use the configuration from the first policy reference `oidc-policy-one`, and ignores `oidc-policy-two`. +### Cache + +The cache policy configures proxy caching, which improves performance by storing and serving cached responses to clients without having to proxy every request to upstream servers. + +For example, the following policy creates a cache zone named "my-cache" with 10MB memory allocation and caches all GET response codes for 30 seconds: + +```yaml +cache: + cacheZoneName: "mycache" + cacheZoneSize: "10m" + allowedCodes: ["any"] + allowedMethods: ["GET"] + time: "30s" +``` + +Here's an example with more specific configuration: + +```yaml +cache: + cacheZoneName: "mycache" + cacheZoneSize: "100m" + allowedCodes: [200, 301, 302] + allowedMethods: ["GET", "POST"] + time: "5m" + levels: "1:2" + overrideUpstreamCache: true +``` + +{{< call-out "note" >}} + +The feature is implemented using the NGINX [ngx_http_proxy_module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_cache_path) proxy_cache_path and related directives. + +{{< /call-out >}} + +{{% table %}} +|Field | Description | Type | Required | +| --- | ---| ---| --- | +| ``cacheZoneName`` | CacheZoneName defines the name of the cache zone. Must start with a lowercase letter,followed by alphanumeric characters or underscores, and end with an alphanumeric character. Single lowercase letters are also allowed. Examples: "cache", "my_cache", "cache1". | ``string`` | Yes | +|``cacheZoneSize`` | CacheZoneSize defines the size of the cache zone. Must be a number followed by a size unit: 'k' for kilobytes, 'm' for megabytes, or 'g' for gigabytes. Examples: "10m", "1g", "512k". | ``string`` | Yes | +|``allowedCodes`` | AllowedCodes defines which HTTP response codes should be cached. Accepts either: - The string "any" to cache all response codes (must be the only element) - A list of HTTP status codes as integers (100-599) Examples: ["any"], [200, 301, 404], [200]. Invalid: ["any", 200] (cannot mix "any" with specific codes). | ``[]IntOrString`` | No | +|``time`` | The default cache time for responses. Required when allowedCodes is specified. Must be a number followed by a time unit: 's' for seconds, 'm' for minutes, 'h' for hours, 'd' for days. Examples: "30s", "5m", "1h", "2d". | ``string`` | No | +|``allowedMethods`` | AllowedMethods defines which HTTP methods should be cached. Only "GET", "HEAD", and "POST" are supported by NGINX proxy_cache_methods directive. GET and HEAD are always cached by default even if not specified. Maximum of 3 items allowed. Examples: ["GET"], ["GET", "HEAD", "POST"]. Invalid methods: PUT, DELETE, PATCH, etc. | ``[]string`` | No | +|``levels`` | Levels defines the cache directory hierarchy levels for storing cached files. Must be in format "X:Y" or "X:Y:Z" where X, Y, Z are either 1 or 2. This controls the number of subdirectory levels and their name lengths. Examples: "1:2", "2:2", "1:2:2". Invalid: "3:1", "1:3", "1:2:3". | ``string`` | No | +|``overrideUpstreamCache`` | OverrideUpstreamCache controls whether to override upstream cache headers (using proxy_ignore_headers directive). When true, NGINX will ignore cache-related headers from upstream servers like Cache-Control, Expires etc, Default: false. | ``bool`` | No | +|``cachePurgeAllow`` | CachePurgeAllow defines IP addresses or CIDR blocks allowed to purge cache. This feature is only available in NGINX Plus. Examples: ["192.168.1.100", "10.0.0.0/8", "::1"]. | ``[]string`` | No | +{{% /table %}} + +#### Cache Merging Behavior + +A VirtualServer/VirtualServerRoute can reference multiple cache policies. However, only one can be applied: every subsequent reference will be ignored. + ## Using Policy You can use the usual `kubectl` commands to work with Policy resources, just as with built-in Kubernetes resources. diff --git a/content/nic/configuration/proxy-buffers-configuration.md b/content/nic/configuration/proxy-buffers-configuration.md new file mode 100644 index 000000000..bfb63511d --- /dev/null +++ b/content/nic/configuration/proxy-buffers-configuration.md @@ -0,0 +1,145 @@ +--- +title: Proxy Buffer Configuration Auto-Adjustment +toc: true +weight: 850 +nd-docs: DOCS-590 +--- + +This document explains how the `--enable-directive-autoadjust` option prevents NGINX configuration errors by automatically adjusting some HTTP proxy buffer directives. + +--- +## What it does + +The `--enable-directive-autoadjust` feature automatically fixes common proxy buffer configuration mistakes that would otherwise cause NGINX to fail with errors like: + +```text +[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:** +- [ConfigMap settings]({{< ref "/nic/configuration/global-configuration/configmap-resource.md#general-customization" >}}) +- [Ingress annotations]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations/#general-customization" >}}) +- [VirtualServer upstream buffer configurations]({{< ref "/nic/configuration/virtualserver-and-virtualserverroute-resources/#upstream" >}}) +--- + +## How to enable auto-adjustment +{{}} +{{% tab name="Manifests" %}} +Add the flag to the controller container: +```yaml + args: + - --enable-directive-autoadjust=true +``` +{{% /tab %}} +{{% tab name="Helm" %}} +Enable via the Helm chart values file: +```yaml +controller: + directiveAutoAdjust: "true" +``` +{{% /tab %}} +{{}} + +--- +## Examples + +### Example 1 + +**Input:** +```yaml +data: + proxy-buffer-size: "5m" + proxy-buffers: "8 1m" +``` + +{{}} + +{{% tab name="Before (Error)" %}} + +Before enabling `--enable-directive-autoadjust`, NGINX fails to start with configuration validation errors. + +```shell +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" +``` + +{{% /tab %}} + +{{% tab name="After (Fixed)" %}} + +With `--enable-directive-autoadjust`, the configuration is automatically adjusted: + +```nginx + proxy_buffers 8 1m; + proxy_buffer_size 5m; + proxy_busy_buffers_size 5m; +``` + +Logs: +```text +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 +``` + +{{% /tab %}} + +{{}} + +### Example 2 + +**Input:** +```yaml +data: + proxy-buffers: "1000000 1m" # Extremely high buffer count + proxy-buffer-size: "999m" # Very large buffer size + proxy-busy-buffers-size: "500m" +``` + +{{}} + +{{% tab name="Before (Error)" %}} + +```shell +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" +``` + +{{% /tab %}} + +{{% tab name="After (Fixed)" %}} + +With `--enable-directive-autoadjust`, sensible defaults are applied: + +```shell + proxy_buffers 1024 1m; + proxy_buffer_size 999m; + proxy_busy_buffers_size 999m; +``` + +Logs: +```shell +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 +``` + +{{% /tab %}} + +{{}} + +--- +## Monitoring and logging + +The controller outputs a log message whenever any of the proxy buffer directives are changed. Examples: + +```text +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: +```bash +kubectl logs -n | grep "Changes made to proxy values" +``` \ No newline at end of file diff --git a/content/nic/configuration/security.md b/content/nic/configuration/security.md index ad561cb21..e44d99e87 100644 --- a/content/nic/configuration/security.md +++ b/content/nic/configuration/security.md @@ -53,10 +53,12 @@ The block below shows the code you will look for: # volumes: # - name: nginx-etc # emptyDir: {} -# - name: nginx-cache -# emptyDir: {} +# - name: nginx-cache # do not set this value in statefulset if volumeclaimtemplate is set +# emptyDir: {} # do not set this value in statefulset if volumeclaimtemplate is set # - name: nginx-lib # emptyDir: {} +# - name: nginx-lib-state +# emptyDir: {} # - name: nginx-log # emptyDir: {} . @@ -73,6 +75,8 @@ The block below shows the code you will look for: # name: nginx-cache # - mountPath: /var/lib/nginx # name: nginx-lib +# - mountPath: /var/lib/nginx/state +# name: nginx-lib-state # - mountPath: /var/log/nginx # name: nginx-log ``` diff --git a/content/nic/configuration/virtualserver-and-virtualserverroute-resources.md b/content/nic/configuration/virtualserver-and-virtualserverroute-resources.md index 3a0a782e4..670599c36 100644 --- a/content/nic/configuration/virtualserver-and-virtualserverroute-resources.md +++ b/content/nic/configuration/virtualserver-and-virtualserverroute-resources.md @@ -356,6 +356,7 @@ tls: |``buffering`` | Enables buffering of responses from the upstream server. See the [proxy_buffering](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) directive. The default is set in the ``proxy-buffering`` ConfigMap key. | ``boolean`` | No | |``buffers`` | Configures the buffers used for reading a response from the upstream server for a single connection. | [buffers](#upstreambuffers) | No | |``buffer-size`` | Sets the size of the buffer used for reading the first part of a response received from the upstream server. See the [proxy_buffer_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) directive. The default is set in the ``proxy-buffer-size`` ConfigMap key. | ``string`` | No | +|``busy-buffers-size`` | Sets the size of the buffer used for reading a response from the upstream server when the response is larger than the ``buffer-size``. See the [proxy_busy_buffers_size](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) directive. The default is set in the ``proxy-busy-buffers-size`` ConfigMap key. | ``string`` | No | |``ntlm`` | Allows proxying requests with NTLM Authentication. See the [ntlm](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#ntlm) directive. In order for NTLM authentication to work, it is necessary to enable keepalive connections to upstream servers using the ``keepalive`` field. Note: this feature is supported only in NGINX Plus.| ``boolean`` | No | |``type`` |The type of the upstream. Supported values are ``http`` and ``grpc``. The default is ``http``. For gRPC, it is necessary to enable HTTP/2 in the [ConfigMap]({{< ref "/nic/configuration/global-configuration/configmap-resource.md#listeners" >}}) and configure TLS termination in the VirtualServer. | ``string`` | No | |``backup`` | The name of the backup service of type [ExternalName](https://kubernetes.io/docs/concepts/services-networking/service/#externalname). This will be used when the primary servers are unavailable. Note: The parameter cannot be used along with the ``random`` , ``hash`` or ``ip_hash`` load balancing methods. | ``string`` | No | diff --git a/content/nic/installation/ingress-nginx.md b/content/nic/installation/ingress-nginx.md index cdfed5470..7727c56e8 100644 --- a/content/nic/installation/ingress-nginx.md +++ b/content/nic/installation/ingress-nginx.md @@ -459,6 +459,7 @@ This table maps the Ingress-NGINX Controller annotations to NGINX Ingress Contro | [_nginx.ingress.kubernetes.io/proxy-buffering_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#proxy-buffering) | [_nginx.org/proxy-buffering_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_buffering_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffering) | | [_nginx.ingress.kubernetes.io/proxy-buffers-number_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#proxy-buffers-number) | [_nginx.org/proxy-buffers_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_buffers_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffers) | | [_nginx.ingress.kubernetes.io/proxy-buffer-size_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#proxy-buffer-size) | [_nginx.org/proxy-buffer-size_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_buffer_size_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_buffer_size) | +| [_nginx.ingress.kubernetes.io/proxy-busy-buffers-size_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#proxy-busy-buffers-size) | [_nginx.org/proxy-busy-buffers-size_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_busy_buffers_size_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_busy_buffers_size) | | [_nginx.ingress.kubernetes.io/proxy-connect-timeout_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#custom-timeouts) | [_nginx.org/proxy-connect-timeout_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_connect_timeout_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_connect_timeout) | | [_nginx.ingress.kubernetes.io/proxy-read-timeout_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#custom-timeouts) | [_nginx.org/proxy-read-timeout_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_read_timeout_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_read_timeout) | | [_nginx.ingress.kubernetes.io/proxy-send-timeout_](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#custom-timeouts) | [_nginx.org/proxy-send-timeout_]({{< ref "/nic/configuration/ingress-resources/advanced-configuration-with-annotations.md#general-customization" >}}) | [_proxy_send_timeout_](https://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_send_timeout) | diff --git a/content/nic/installation/installing-nic/installation-with-helm.md b/content/nic/installation/installing-nic/installation-with-helm.md index 3bdab4f57..6e4677e97 100644 --- a/content/nic/installation/installing-nic/installation-with-helm.md +++ b/content/nic/installation/installing-nic/installation-with-helm.md @@ -129,10 +129,10 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont {{< table >}} |Parameter | Description | Default | | --- | --- | --- | -| **controller.name** | The name of the NGINX Ingress Controller daemonset or deployment. | Autogenerated | -| **controller.kind** | The kind of the NGINX Ingress Controller installation - deployment or daemonset. | deployment | -| **controller.annotations** | Allows for setting of `annotations` for deployment or daemonset. | {} | -| **controller.nginxplus** | Deploys the NGINX Ingress Controller for NGINX Plus. | false | +| **controller.name** | The name of the Ingress Controller deployment, daemonset, or statefulset. | Autogenerated | +| **controller.kind** | The kind of the Ingress Controller installation - deployment, daemonset, or statefulset. | deployment | +| **controller.annotations** | Allows for setting of `annotations` for deployment, daemonset, or statefulset. | {} | +| **controller.nginxplus** | Deploys the Ingress Controller for NGINX Plus. | false | | **controller.mgmt.licenseTokenSecretName** | Configures the secret used in the [license_token](https://nginx.org/en/docs/ngx_mgmt_module.html#license_token) directive. This key assumes the secret is in the Namespace that NGINX Ingress Controller is deployed in. The secret must be of type `nginx.com/license` with the base64 encoded JWT in the `license.jwt` key. | license-token | | **controller.mgmt.enforceInitialReport** | Configures the [enforce_initial_report](https://nginx.org/en/docs/ngx_mgmt_module.html#enforce_initial_report) directive, which enables or disables the 180-day grace period for sending the initial usage report. | false | | **controller.mgmt.usageReport.endpoint** | Configures the endpoint of the [usage_report](https://nginx.org/en/docs/ngx_mgmt_module.html#usage_report) directive. This is used to configure the endpoint NGINX uses to send usage reports to NIM. | product.connect.nginx.com | @@ -152,6 +152,7 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont | **controller.nginxDebug** | Enables debugging for NGINX. Uses the `nginx-debug` binary. Requires `error-log-level: debug` in the ConfigMap via `controller.config.entries`. | false | | **controller.logLevel** | The log level of the NGINX Ingress Controller. | info | | **controller.logFormat** | The log format of the NGINX Ingress Controller. | glog | +| **controller.directiveAutoAdjust** | Automatically adjusts NGINX buffer directives to prevent configuration errors. | false | | **controller.image.digest** | The image digest of the NGINX Ingress Controller. | None | | **controller.image.repository** | The image repository of the NGINX Ingress Controller. | nginx/nginx-ingress | | **controller.image.tag** | The tag of the NGINX Ingress Controller image. | {{< nic-version >}} | @@ -260,6 +261,14 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont | **controller.readyStatus.enable** | Enables the readiness endpoint `"/nginx-ready"`. The endpoint returns a success code when NGINX has loaded all the config after the startup. This also configures a readiness probe for the NGINX Ingress Controller pods that uses the readiness endpoint. | true | | **controller.readyStatus.port** | The HTTP port for the readiness endpoint. | 8081 | | **controller.readyStatus.initialDelaySeconds** | The number of seconds after the NGINX Ingress Controller pod has started before readiness probes are initiated. | 0 | +| **controller.startupStatus.enable** | Enables the startup probe for the Ingress Controller. | false | +| **controller.startupStatus.port** | The port where the startup endpoint is exposed. This is a required field if `controller.startupStatus.enable` is set to true. | N/A | +| **controller.startupStatus.path** | The path to the startup endpoint. This is a required field if `controller.startupStatus.enable` is set to true. | N/A | +| **controller.startupStatus.initialDelaySeconds** | The number of seconds after the Ingress Controller pod has started before startup probes are initiated. | N/A | +| **controller.startupStatus.periodSeconds** | The number of seconds between each startup probe. | N/A | +| **controller.startupStatus.timeoutSeconds** | The number of seconds after which the startup probe times out. | N/A | +| **controller.startupStatus.successThreshold** | Minimum consecutive successes for the probe to be considered successful. | N/A | +| **controller.startupStatus.failureThreshold** | When a probe fails, Kubernetes will try failureThreshold times before giving up. | N/A | | **controller.enableLatencyMetrics** | Enable collection of latency metrics for upstreams. Requires `prometheus.create`. | false | | **controller.minReadySeconds** | Specifies the minimum number of seconds for which a newly created Pod should be ready without any of its containers crashing, for it to be considered available. [docs](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#min-ready-seconds) | 0 | | **controller.autoscaling.enabled** | Enables HorizontalPodAutoscaling. | false | @@ -273,7 +282,13 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont | **controller.podDisruptionBudget.annotations** | The annotations of the NGINX Ingress Controller pod disruption budget | {} | | **controller.podDisruptionBudget.minAvailable** | The number of Ingress Controller pods that should be available. This is a mutually exclusive setting with "maxUnavailable". | 0 | | **controller.podDisruptionBudget.maxUnavailable** | The number of Ingress Controller pods that can be unavailable. This is a mutually exclusive setting with "minAvailable". | 0 | -| **controller.strategy** | Specifies the strategy used to replace old Pods with new ones. Docs for [Deployment update strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy) and [Daemonset update strategy](https://kubernetes.io/docs/tasks/manage-daemon/update-daemon-set/#daemonset-update-strategy) | {} | +| **controller.strategy** | Specifies the strategy used to replace old Pods with new ones. Docs for [Deployment update strategy](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy), [Daemonset update strategy](https://kubernetes.io/docs/tasks/manage-daemon/update-daemon-set/#daemonset-update-strategy) and [StatefulSet update strategy](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#update-strategies) | {} | +| **controller.statefulset.podManagementPolicy** | Controls how pods are created during initial scale up, when replacing pods on nodes, or when scaling down. Available options: `OrderedReady` or `Parallel`. Only applies when `controller.kind` is set to `statefulset`. | `OrderedReady` | +| **controller.statefulset.persistentVolumeClaimRetentionPolicy.whenDeleted** | Controls the retention policy for PVCs when the StatefulSet is deleted. Available options: `Retain` or `Delete`. Only applies when `controller.kind` is set to `statefulset`. | `Retain` | +| **controller.statefulset.persistentVolumeClaimRetentionPolicy.whenScaled** | Controls the retention policy for PVCs when the StatefulSet is scaled down. Available options: `Retain` or `Delete`. Only applies when `controller.kind` is set to `statefulset`. | `Retain` | +| **controller.statefulset.nginxCachePVC.size** | The size of the persistent volume claim for NGINX cache storage. Only applies when `controller.kind` is set to `statefulset`. | `256Mi` | +| **controller.statefulset.nginxCachePVC.storageClass** | The storage class for the persistent volume claim. Only applies when `controller.kind` is set to `statefulset`. | `""` | +| **controller.statefulset.nginxCachePVC.accessModes** | The access modes for the persistent volume claim. Only applies when `controller.kind` is set to `statefulset`. | `["ReadWriteOnce"]` | | **controller.disableIPV6** | Disable IPV6 listeners explicitly for nodes that do not support the IPV6 stack. | false | | **controller.defaultHTTPListenerPort** | Sets the port for the HTTP `default_server` listener. | 80 | | **controller.defaultHTTPSListenerPort** | Sets the port for the HTTPS `default_server` listener. | 443 | diff --git a/content/nic/installation/installing-nic/installation-with-manifests.md b/content/nic/installation/installing-nic/installation-with-manifests.md index 8df8e0a53..dbbc84935 100644 --- a/content/nic/installation/installing-nic/installation-with-manifests.md +++ b/content/nic/installation/installing-nic/installation-with-manifests.md @@ -132,10 +132,11 @@ kubectl apply -f config/crd/bases/appprotectdos.f5.com_dosprotectedresources.yam ## Deploy NGINX Ingress Controller {#deploy-ingress-controller} -You have two options for deploying NGINX Ingress Controller: +You have three options for deploying NGINX Ingress Controller: - **Deployment**. Choose this method for the flexibility to dynamically change the number of NGINX Ingress Controller replicas. - **DaemonSet**. Choose this method if you want NGINX Ingress Controller to run on all nodes or a subset of nodes. +- **StatefulSet**. Choose this method when you need stable, persistent storage and ordered deployment/scaling for your NGINX Ingress Controller pods. Before you start, update the [command-line arguments]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}) for the NGINX Ingress Controller container in the relevant manifest file to meet your specific requirements. @@ -147,6 +148,10 @@ Before you start, update the [command-line arguments]({{< ref "/nic/configuratio {{< include "/nic/installation/manifests/daemonset.md" >}} +### Using a StatefulSet + +{{< include "/nic/installation/manifests/statefulset.md" >}} + --- ## Confirm NGINX Ingress Controller is running @@ -157,9 +162,9 @@ Before you start, update the [command-line arguments]({{< ref "/nic/configuratio ## How to access NGINX Ingress Controller -### Using a Deployment +### Using a Deployment or StatefulSet -For Deployments, you have two options for accessing NGINX Ingress Controller pods. +For Deployments and StatefulSets, you have two options for accessing NGINX Ingress Controller pods. #### Option 1: Create a NodePort service diff --git a/content/nic/installation/integrations/app-protect-dos/installation.md b/content/nic/installation/integrations/app-protect-dos/installation.md index c678dcf49..f090c6712 100644 --- a/content/nic/installation/integrations/app-protect-dos/installation.md +++ b/content/nic/installation/integrations/app-protect-dos/installation.md @@ -166,6 +166,10 @@ kubectl apply -f config/crd/bases/appprotectdos.f5.com_dosprotectedresources.yam {{< include "/nic/installation/manifests/daemonset.md" >}} +### Using a StatefulSet + +{{< include "/nic/installation/manifests/statefulset.md" >}} + --- ## Install the App Protect DoS Arbitrator @@ -204,7 +208,7 @@ Alternatively, you can install the App Protect DoS Arbitrator using the YAML man To enable the NGINX App Protect DoS Module: -- Add the `enable-app-protect-dos` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect-dos" >}}) to your Deployment or DaemonSet file. +- Add the `enable-app-protect-dos` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect-dos" >}}) to your Deployment, DaemonSet, or StatefulSet file. --- diff --git a/content/nic/installation/integrations/app-protect-waf-v5/installation.md b/content/nic/installation/integrations/app-protect-waf-v5/installation.md index 421dded1c..159923821 100644 --- a/content/nic/installation/integrations/app-protect-waf-v5/installation.md +++ b/content/nic/installation/integrations/app-protect-waf-v5/installation.md @@ -132,7 +132,7 @@ docker push /waf-enforcer: ## Deploy NGINX Ingress Controller {#deploy-ingress-controller} -{{< call-out "important" >}} NGINX Ingress Controller with the AppProtect WAF v5 module works only with policy bundles. You need to modify the Deployment or DaemonSet file to include volumes, volume mounts and two WAF 5 docker images: `waf-config-mgr` and `waf-enforcer`. +{{< important >}} NGINX Ingress Controller with the AppProtect WAF v5 module works only with policy bundles. You need to modify the Deployment, DaemonSet, or StatefulSet file to include volumes, volume mounts and two WAF 5 docker images: `waf-config-mgr` and `waf-enforcer`. NGINX Ingress Controller **requires** the volume mount path to be `/etc/app_protect/bundles`. {{< /call-out >}} @@ -227,18 +227,18 @@ Create required volumes: volumes: - name: nginx-etc emptyDir: {} - - name: nginx-cache - emptyDir: {} + - name: nginx-cache # do not set this value in statefulset if volumeclaimtemplate is set + emptyDir: {} # do not set this value in statefulset if volumeclaimtemplate is set - name: nginx-lib emptyDir: {} - name: nginx-log emptyDir: {} - - emptyDir: {} - name: app-protect-bd-config - - emptyDir: {} - name: app-protect-config - - emptyDir: {} - name: app-protect-bundles + - name: app-protect-bd-config + emptyDir: {} + - name: app-protect-config + emptyDir: {} + - name: app-protect-bundles + emptyDir: {} ``` Set `controller.securityContext.readOnlyRootFilesystem` to `true`. @@ -291,6 +291,7 @@ You have two options for deploying NGINX Ingress Controller: - **Deployment**. Choose this method for the flexibility to dynamically change the number of NGINX Ingress Controller replicas. - **DaemonSet**. Choose this method if you want NGINX Ingress Controller to run on all nodes or a subset of nodes. +- **StatefulSet**. Choose this method when you need stable, persistent storage and ordered deployment/scaling for your NGINX Ingress Controller pods. --- @@ -377,7 +378,7 @@ Add `waf-enforcer` image to the `containers` section: ... ``` -### Update NIC container in deployment or daemonset +### Update NIC container in deployment, daemonset, or statefulset Add `volumeMounts` as below: @@ -464,6 +465,10 @@ Add `readOnlyRootFilesystem` to the `waf-enforcer` container and set value to `t ... ``` +{{< call-out "note" >}} +**StatefulSet Volume Configuration**: When using StatefulSet deployments, the `nginx-cache` volume is automatically provided via `volumeClaimTemplates` for persistent storage. App Protect WAF v5 volumes (like app-protect-config, app-protect-bundles) are still configured as regular volumes in the `volumes` section. Use `emptyDir` for temporary data or PersistentVolumeClaims if you need persistence for App Protect configurations across pod restarts. +{{< /call-out >}} + ### Using a Deployment {{< include "/nic/installation/manifests/deployment.md" >}} @@ -472,13 +477,17 @@ Add `readOnlyRootFilesystem` to the `waf-enforcer` container and set value to `t {{< include "/nic/installation/manifests/daemonset.md" >}} +### Using a StatefulSet + +{{< include "/nic/installation/manifests/statefulset.md" >}} + --- ### Enable NGINX App Protect WAF module To enable the NGINX App Protect DoS Module: -- Add the `enable-app-protect` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect" >}}) to your Deployment or DaemonSet file. +- Add the `enable-app-protect` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect" >}}) to your Deployment, DaemonSet, or StatefulSet file. {{%/tab%}} diff --git a/content/nic/installation/integrations/app-protect-waf/installation.md b/content/nic/installation/integrations/app-protect-waf/installation.md index 0da5bc500..b5d8d3920 100644 --- a/content/nic/installation/integrations/app-protect-waf/installation.md +++ b/content/nic/installation/integrations/app-protect-waf/installation.md @@ -158,7 +158,7 @@ kubectl apply -f config/crd/bases/appprotect.f5.com_apusersigs.yaml {{< include "/nic/installation/deploy-controller.md" >}} -{{< call-out "note" >}} If you're using NGINX Ingress Controller with the AppProtect WAF module and policy bundles, you will need to modify the Deployment or DaemonSet file to include volumes and volume mounts. +{{< call-out "note" >}} If you're using NGINX Ingress Controller with the AppProtect WAF module and policy bundles, you will need to modify the Deployment, DaemonSet, or StatefulSet file to include volumes and volume mounts. NGINX Ingress Controller **requires** the volume mount path to be `/etc/nginx/waf/bundles`. {{< /call-out >}} @@ -183,6 +183,10 @@ volumeMounts: ... ``` +{{< call-out "note" >}} +**StatefulSet Volume Configuration**: When using StatefulSet deployments, the `nginx-cache` volume is automatically provided via `volumeClaimTemplates` for persistent storage. App Protect WAF v5 volumes (like app-protect-config, app-protect-bundles) are still configured as regular volumes in the `volumes` section. Use `emptyDir` for temporary data or PersistentVolumeClaims if you need persistence for App Protect configurations across pod restarts. +{{< /call-out >}} + ### Using a Deployment {{< include "/nic/installation/manifests/deployment.md" >}} @@ -191,13 +195,17 @@ volumeMounts: {{< include "/nic/installation/manifests/daemonset.md" >}} +### Using a StatefulSet + +{{< include "/nic/installation/manifests/statefulset.md" >}} + --- ## Enable NGINX App Protect WAF module To enable the NGINX App Protect DoS Module: -- Add the `enable-app-protect` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect" >}}) to your Deployment or DaemonSet file. +- Add the `enable-app-protect` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#cmdoption-enable-app-protect" >}}) to your Deployment, DaemonSet, or StatefulSet file. --- diff --git a/content/nic/logging-and-monitoring/prometheus.md b/content/nic/logging-and-monitoring/prometheus.md index 0bca69823..6ebbc749f 100644 --- a/content/nic/logging-and-monitoring/prometheus.md +++ b/content/nic/logging-and-monitoring/prometheus.md @@ -35,8 +35,7 @@ curl https://raw.githubusercontent.com/prometheus-operator/prometheus-operator/$ ``` ### Using Manifests - -If you're using *Kubernetes manifests* (Deployment or DaemonSet) to install the Ingress Controller, to enable Prometheus metrics: +If you're using *Kubernetes manifests* (Deployment, DaemonSet, or StatefulSet) to install the Ingress Controller, to enable Prometheus metrics: 1. Run the Ingress Controller with the `-enable-prometheus-metrics` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}). As a result, the Ingress Controller will expose NGINX or NGINX Plus metrics in the Prometheus format via the path `/metrics` on port `9113` (customizable via the `-prometheus-metrics-listen-port` command-line argument). 1. To enable TLS for the Prometheus endpoint, configure the `-prometheus-tls-secret` cli argument with the namespace and name of a TLS Secret. diff --git a/content/nic/logging-and-monitoring/service-insight.md b/content/nic/logging-and-monitoring/service-insight.md index 35b4c89a8..f33248bde 100644 --- a/content/nic/logging-and-monitoring/service-insight.md +++ b/content/nic/logging-and-monitoring/service-insight.md @@ -20,7 +20,7 @@ NGINX Plus determination of healthy can be tuned using advanced health checks, a ## Enabling Service Insight Endpoint -If you're using *Kubernetes manifests* (Deployment or DaemonSet) to install the Ingress Controller, to enable the Service Insight endpoint: +If you're using *Kubernetes manifests* (Deployment, DaemonSet, or StatefulSet) to install the Ingress Controller, to enable the Service Insight endpoint: 1. Run the Ingress Controller with the `-enable-service-insight` [command-line argument]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md" >}}). This will expose the Ingress Controller endpoint via paths `/probe/{hostname}` for Virtual Servers, and `/probe/ts/{service_name}` for Transport Servers on port `9114` (customizable with the `-service-insight-listen-port` command-line argument). The `service_name` parameter refers to the name of the deployed service (the service specified under `upstreams` in the transport server). 1. To enable TLS for the Service Insight endpoint, configure the `-service-insight-tls-secret` cli argument with the namespace and name of a TLS Secret. diff --git a/content/nic/overview/product-telemetry.md b/content/nic/overview/product-telemetry.md index 08196c4ca..ca9472af7 100644 --- a/content/nic/overview/product-telemetry.md +++ b/content/nic/overview/product-telemetry.md @@ -34,7 +34,7 @@ These are the data points collected and reported by NGINX Ingress Controller: - **VirtualServers** The number of VirtualServer resources managed by NGINX Ingress Controller. - **VirtualServerRoutes** The number of VirtualServerRoute resources managed by NGINX Ingress Controller. - **TransportServers** The number of TransportServer resources managed by NGINX Ingress Controller. -- **Replicas** Number of Deployment replicas, or Daemonset instances. +- **Replicas** Number of Deployment or StatefulSet replicas, or DaemonSet instances. - **Secrets** Number of Secret resources managed by NGINX Ingress Controller. - **ClusterIPServices** Number of ClusterIP Services managed by NGINX Ingress Controller. - **NodePortServices** Number of NodePort Services managed by NGINX Ingress Controller. @@ -54,6 +54,7 @@ These are the data points collected and reported by NGINX Ingress Controller: - **EgressMTLSPolicies** Number of EgressMTLS policies. - **OIDCPolicies** Number of OIDC policies. - **WAFPolicies** Number of WAF policies. +- **CachePolicies** Number of Cache policies. - **GlobalConfiguration** Represents the use of a GlobalConfiguration resource. - **AppProtectVersion** The AppProtect version - **IsPlus** Represents whether NGINX is Plus or OSS diff --git a/content/nic/releases.md b/content/nic/releases.md index 4821b26d8..0d8d717c9 100644 --- a/content/nic/releases.md +++ b/content/nic/releases.md @@ -5,6 +5,44 @@ toc: true nd-content-type: reference nd-product: NIC nd-docs: DOCS-616 +--- +## 5.2.0 + +15 Sept 2025 + +This Nginx Ingress Controller release focuses on enhancing performance, simplifying configurations, and improving security to better support modern application needs. Highlights of this release are: + +- NGINX Content Cache Using Policies which adds policy configuration that enables proxy caching. +- Support for Kubernetes `StatefulSet` object has been added which can also be use to provide persistent storage for cached content. +- Auto-Adjusting Incompatible Proxy Buffer Directive Values, we’ve added a new `--enable-directive-autoadjust` parameter. When enabled, this feature automatically resolves common proxy buffer configuration dependencies that could cause issues during NGINX reloads. +- Server Name Indication (SNI) Support in JWT Policies, users can now configure `sniName` and `sniEnabled` for scenarios where the remote server requires SNI to serve the correct certificate. + +### Features +- [8005](https://github.com/nginx/kubernetes-ingress/pull/8005) Add nginx content cache as NIC cache policy +- [8159](https://github.com/nginx/kubernetes-ingress/pull/8159) Statefulset support +- [8133](https://github.com/nginx/kubernetes-ingress/pull/8133) Add support for automatic adjustment of buffer related directives +- [8011](https://github.com/nginx/kubernetes-ingress/pull/8011) Allow startupprobe to be configured via helm +- [7993](https://github.com/nginx/kubernetes-ingress/pull/7993) Add sni to NIC jwt policy +- [8093](https://github.com/nginx/kubernetes-ingress/pull/8093) Add viol_bot_client and viol_geolocation violations support +- [8229](https://github.com/nginx/kubernetes-ingress/pull/8229) Add N+ license expiry to prometheus metrics +- [8142](https://github.com/nginx/kubernetes-ingress/pull/8142) Add globalconfigurationcustomname parameter +- [8195](https://github.com/nginx/kubernetes-ingress/pull/8195) Add support for fips 140-3 compliance + + + +### Dependencies +- [8208](https://github.com/nginx/kubernetes-ingress/pull/8208) Update Nginx agent to 3.3 +- [7959](https://github.com/nginx/kubernetes-ingress/pull/7959), [7983](https://github.com/nginx/kubernetes-ingress/pull/7983), [8037](https://github.com/nginx/kubernetes-ingress/pull/8037), [8057](https://github.com/nginx/kubernetes-ingress/pull/8057), [8083](https://github.com/nginx/kubernetes-ingress/pull/8083), [8096](https://github.com/nginx/kubernetes-ingress/pull/8096), [8126](https://github.com/nginx/kubernetes-ingress/pull/8126), [8143](https://github.com/nginx/kubernetes-ingress/pull/8143), [8183](https://github.com/nginx/kubernetes-ingress/pull/8183), [8186](https://github.com/nginx/kubernetes-ingress/pull/8186), [8200](https://github.com/nginx/kubernetes-ingress/pull/8200), [8231](https://github.com/nginx/kubernetes-ingress/pull/8231) Bump Go dependencies +- [7946](https://github.com/nginx/kubernetes-ingress/pull/7946), [7961](https://github.com/nginx/kubernetes-ingress/pull/7961), [7977](https://github.com/nginx/kubernetes-ingress/pull/7977), [7979](https://github.com/nginx/kubernetes-ingress/pull/7979), [7978](https://github.com/nginx/kubernetes-ingress/pull/7978), [7984](https://github.com/nginx/kubernetes-ingress/pull/7984), [7996](https://github.com/nginx/kubernetes-ingress/pull/7996), [8012](https://github.com/nginx/kubernetes-ingress/pull/8012), [8036](https://github.com/nginx/kubernetes-ingress/pull/8036), [8044](https://github.com/nginx/kubernetes-ingress/pull/8044), [8063](https://github.com/nginx/kubernetes-ingress/pull/8063), [8085](https://github.com/nginx/kubernetes-ingress/pull/8085), [8107](https://github.com/nginx/kubernetes-ingress/pull/8107), [8114](https://github.com/nginx/kubernetes-ingress/pull/8114), [8128](https://github.com/nginx/kubernetes-ingress/pull/8128), [8134](https://github.com/nginx/kubernetes-ingress/pull/8134), [8147](https://github.com/nginx/kubernetes-ingress/pull/8147), [8154](https://github.com/nginx/kubernetes-ingress/pull/8154), [8173](https://github.com/nginx/kubernetes-ingress/pull/8173), [8188](https://github.com/nginx/kubernetes-ingress/pull/8188), [8228](https://github.com/nginx/kubernetes-ingress/pull/8228), [8239](https://github.com/nginx/kubernetes-ingress/pull/8239), [8235](https://github.com/nginx/kubernetes-ingress/pull/8235), [8246](https://github.com/nginx/kubernetes-ingress/pull/8246) Bump Docker dependencies + +### Upgrade +- For NGINX, use the 5.2.0 images from our [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/tags?page=1&ordering=last_updated&name=5.2.0), [GitHub Container](https://github.com/nginx/kubernetes-ingress/pkgs/container/kubernetes-ingress), [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress) or [Quay.io](https://quay.io/repository/nginx/nginx-ingress). +- For NGINX Plus, use the 5.2.0 images from the F5 Container registry or build your own image using the 5.2.0 source code. +- For Helm, use version 2.3.0 of the chart. + +### Supported Platforms +We will provide technical support for NGINX Ingress Controller on any Kubernetes platform that is currently supported by its provider and that passes the Kubernetes conformance tests. This release was fully tested on the following Kubernetes versions: 1.26-1.34. + --- ## 5.1.1 @@ -2432,4 +2470,4 @@ Otherwise, the helm upgrade will not succeed. ## Previous Releases -To see the previous releases, see the [Releases page](https://github.com/nginx/kubernetes-ingress/releases) on the Ingress Controller GitHub repo. \ No newline at end of file +To see the previous releases, see the [Releases page](https://github.com/nginx/kubernetes-ingress/releases) on the Ingress Controller GitHub repo. diff --git a/content/nic/technical-specifications.md b/content/nic/technical-specifications.md index 869a87b3c..3a976b459 100644 --- a/content/nic/technical-specifications.md +++ b/content/nic/technical-specifications.md @@ -17,7 +17,8 @@ We test NGINX Ingress Controller on a range of Kubernetes platforms for each rel {{< table >}} | NIC version | Kubernetes versions tested | NIC Helm Chart version | NIC Operator version | NGINX / NGINX Plus version | End of Technical Support | | --- | --- | --- | --- | --- | --- | -| {{< nic-version >}} | 1.25 - 1.33 | {{< nic-helm-version >}} | {{< nic-operator-version >}} | 1.29.1 / R35 | - | +| {{< nic-version >}} | 1.26 - 1.34 | {{< nic-helm-version >}} | {{< nic-operator-version >}} | 1.29.1 / R35 | - | +| 5.1.1 | 1.25 - 1.33 | 2.2.2 | 3.2.3 | 1.29.1 / R35 | Aug 15, 2027 | | 5.0.0 | 1.25 - 1.32 | 2.1.0 | 3.1.0 | 1.27.4 / R34 | Apr 16, 2027 | | 4.0.1 | 1.25 - 1.32 | 2.0.1 | 3.0.1 | 1.27.4 / R33 P2 | Feb 7, 2027 | | 3.7.2 | 1.25 - 1.31 | 1.4.2 | 2.4.2 | 1.27.2 / R32 P1 | Nov 25, 2026 | @@ -25,7 +26,6 @@ We test NGINX Ingress Controller on a range of Kubernetes platforms for each rel | 3.5.2 | 1.23 - 1.30 | 1.2.2 | 2.2.2 | 1.27.0 / R32 | May 31, 2026 | | 3.4.3 | 1.23 - 1.29 | 1.1.3 | 2.1.2 | 1.25.4 / R31 P1 | Feb 19, 2026 | | 3.3.2 | 1.22 - 1.28 | 1.0.2 | 2.0.2 | 1.25.3 / R30 | Nov 1, 2025 | -| 3.2.1 | 1.22 - 1.27 | 0.18.1 | 1.5.1 | 1.25.2 / R30 | Aug 18, 2025 | {{< /table >}} ## Supported Docker images diff --git a/content/nic/troubleshooting/troubleshoot-common.md b/content/nic/troubleshooting/troubleshoot-common.md index 58f59e218..923b1c6ef 100644 --- a/content/nic/troubleshooting/troubleshoot-common.md +++ b/content/nic/troubleshooting/troubleshoot-common.md @@ -78,7 +78,7 @@ There are two places to configure more verbose logging for NGINX Ingress Control **Command line arguments** -When using `manifest` for deployment, use the command line argument `-nginx-debug` in your deployment or daemonset. +When using `manifest` for deployment, use the command line argument `-nginx-debug` in your deployment, daemonset, or statefulset. You can add the `-log-level` parameter to increase the verbosity of the NGINX Ingress Controller process. diff --git a/content/nic/tutorials/oidc-custom-configuration.md b/content/nic/tutorials/oidc-custom-configuration.md index f33ff8a08..c8281f468 100644 --- a/content/nic/tutorials/oidc-custom-configuration.md +++ b/content/nic/tutorials/oidc-custom-configuration.md @@ -111,7 +111,7 @@ This document will demonstrate how to add the `Volume` and `VolumeMount` using b ### Manifest -The below configuration shows where the `Volume` and `VolumeMount` can be added to your Deployment/Daemonset file. +The below configuration shows where the `Volume` and `VolumeMount` can be added to your Deployment, Daemonset, or StatefulSet file. The `VolumeMount` must be added the `spec.template.spec.containers` section. @@ -119,7 +119,7 @@ The `Volume` must be added the `spec.template.spec` section: ```yaml apiVersion: apps/v1 -kind: +kind: metadata: name: namespace: @@ -157,7 +157,7 @@ kubectl exec -it -n -- cat /etc/nginx/oid ### Helm Deployments using helm will need to edit their existing -Edit the NGINX Ingress Controller Deployment/Daemonset yaml to include a `Volume` and `VolumeMount`. +Edit the NGINX Ingress Controller Deployment/DaemonSet/StatefulSet yaml to include a `Volume` and `VolumeMount`. The `Volume` should be within the `spec.template.spec` section. @@ -169,15 +169,21 @@ For Deployments: kubectl edit deployments -n ``` -For Daemonsets: +For DaemonSets: ```shell kubectl edit daemonset -n ``` +For StatefulSets: + +```shell +kubectl edit statefulset -n +``` + ```yaml apiVersion: apps/v1 -kind: +kind: metadata: name: namespace: @@ -204,7 +210,7 @@ spec: readOnly: true ``` -Once the Deployment/Daemonset has been edited, save the file and exit. +Once the Deployment/DaemonSet/StatefulSet has been edited, save the file and exit. Confirm the `oidc.conf` file has been updated: diff --git a/layouts/shortcodes/nic-helm-version.html b/layouts/shortcodes/nic-helm-version.html index 7e541aec6..cc6612c36 100644 --- a/layouts/shortcodes/nic-helm-version.html +++ b/layouts/shortcodes/nic-helm-version.html @@ -1 +1 @@ -2.2.2 \ No newline at end of file +2.3.0 \ No newline at end of file diff --git a/layouts/shortcodes/nic-operator-version.html b/layouts/shortcodes/nic-operator-version.html index 06eda28ac..0fa4ae489 100644 --- a/layouts/shortcodes/nic-operator-version.html +++ b/layouts/shortcodes/nic-operator-version.html @@ -1 +1 @@ -3.2.3 \ No newline at end of file +3.3.0 \ No newline at end of file diff --git a/layouts/shortcodes/nic-version.html b/layouts/shortcodes/nic-version.html index 3bff05917..7cbea073b 100644 --- a/layouts/shortcodes/nic-version.html +++ b/layouts/shortcodes/nic-version.html @@ -1 +1 @@ -5.1.1 \ No newline at end of file +5.2.0 \ No newline at end of file