nginx · haywoodsh · Sep 9, 2025
@@ -0,0 +1,25 @@
+---
+nd-docs: ????
+---
+
+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" >}}
+StatefulSet deployments 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 >}}
@@ -76,6 +76,7 @@ The block below shows the code you will look for:
 #        - mountPath: /var/log/nginx
 #          name: nginx-log
 ```
+[//]: # (TODO: do we need to add anything about statefulsets?)
 
 - Add **waf-enforcer** and **waf-config-mgr** container sections
 - Add `readOnlyFilesystem: true` in both containers security context sections

@@ -129,9 +129,9 @@ 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.name** | The name of the NGINX Ingress Controller daemonset, deployment, or statefulset. | Autogenerated |
+| **controller.kind** | The kind of the NGINX Ingress Controller installation - deployment, daemonset, or statefulset. | deployment |
+| **controller.annotations** | Allows for setting of `annotations` for deployment, daemonset, or statefulset. | {} |
 | **controller.nginxplus** | Deploys the NGINX 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 |
@@ -273,7 +273,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 |

@@ -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
@@ -237,6 +242,15 @@ For more information about the _LoadBalancer_ service, refer to the [Kubernetes
 
 Connect to ports 80 and 443 using the IP address of any node in the cluster where NGINX Ingress Controller is running.
 
+### Using a StatefulSet
+
+[//]: # (TODO: add detail)
+For StatefulSets, you can use the same access methods as Deployments (NodePort or LoadBalancer services). StatefulSet pods have stable network identities, which can be useful for certain networking configurations.
+
+{{< call-out "note" >}}
+When using StatefulSets, each pod gets a stable  hostname following the pattern `<statefulset-name>-<ordinal>`. (index)? This can be useful for configurations that require predictable pod names.
+{{< /call-out >}}
+
 ---
 
 ## Uninstall NGINX Ingress Controller

@@ -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.
 
 ---
 

@@ -132,7 +132,7 @@ docker push <my-docker-registry>/waf-enforcer:<your-tag>
 
 ## 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`.
+{{< call-out "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 >}}
 
@@ -241,6 +241,7 @@ volumes:
     name: app-protect-bundles
 ```
 
+[//]: # (TODO: edit for statefulset)
 Set `controller.securityContext.readOnlyRootFilesystem` to `true`.
 
 Example Helm values:
@@ -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%}}
 

@@ -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. Other volumes like App Protect bundles should still be configured in the regular `volumes` section using PersistentVolumeClaims or other volume types as needed. The `volumeMounts` configuration in the container remains the same.
+{{< /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.
 
 ---
 

@@ -36,7 +36,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.

@@ -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.

@@ -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 replicas, DaemonSet instances, or StatefulSet replicas.
 - **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.