From 1bdf50ef2d86c5444a4fed6c1c76be0056be53e2 Mon Sep 17 00:00:00 2001 From: Venktesh Date: Tue, 9 Sep 2025 16:52:27 +0100 Subject: [PATCH 1/4] add documentation for statefulset --- .../includes/nic/configuration/security.md | 8 ++++-- .../nic/installation/manifests/statefulset.md | 25 +++++++++++++++++++ .../configmap-resource.md | 2 +- .../installing-nic/installation-with-helm.md | 14 ++++++++--- .../installation-with-manifests.md | 11 +++++--- .../app-protect-dos/installation.md | 6 ++++- .../app-protect-waf-v5/installation.md | 19 ++++++++++---- .../app-protect-waf/installation.md | 12 +++++++-- .../integrations/nic-n1-console.md | 4 +-- .../nic/logging-and-monitoring/prometheus.md | 2 +- .../logging-and-monitoring/service-insight.md | 2 +- content/nic/overview/product-telemetry.md | 2 +- .../troubleshooting/troubleshoot-common.md | 2 +- .../tutorials/oidc-custom-configuration.md | 18 ++++++++----- 14 files changed, 97 insertions(+), 30 deletions(-) create mode 100644 content/includes/nic/installation/manifests/statefulset.md diff --git a/content/includes/nic/configuration/security.md b/content/includes/nic/configuration/security.md index 7267eaa01..e9948fb93 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 # not required for statefulset +# emptyDir: {} # not required for statefulset # - 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/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/configmap-resource.md b/content/nic/configuration/global-configuration/configmap-resource.md index 715861b6b..fec4b25a2 100644 --- a/content/nic/configuration/global-configuration/configmap-resource.md +++ b/content/nic/configuration/global-configuration/configmap-resource.md @@ -199,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/nic/installation/installing-nic/installation-with-helm.md b/content/nic/installation/installing-nic/installation-with-helm.md index 8ac6f4d51..7066cd161 100644 --- a/content/nic/installation/installing-nic/installation-with-helm.md +++ b/content/nic/installation/installing-nic/installation-with-helm.md @@ -301,9 +301,9 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont {{}} |Parameter | Description | Default | | --- | --- | --- | -| **controller.name** | The name of the Ingress Controller daemonset or deployment. | Autogenerated | -| **controller.kind** | The kind of the Ingress Controller installation - deployment or daemonset. | deployment | -| **controller.annotations** | Allows for setting of `annotations` for deployment or daemonset. | {} | +| **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 | @@ -454,7 +454,13 @@ The following tables lists the configurable parameters of the NGINX Ingress Cont | **controller.podDisruptionBudget.annotations** | The annotations of the 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 2f44611f6..5dea64247 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 75a4439ae..2ec5e089f 100644 --- a/content/nic/installation/integrations/app-protect-dos/installation.md +++ b/content/nic/installation/integrations/app-protect-dos/installation.md @@ -172,6 +172,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 @@ -210,7 +214,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 2cdc5964c..872844aad 100644 --- a/content/nic/installation/integrations/app-protect-waf-v5/installation.md +++ b/content/nic/installation/integrations/app-protect-waf-v5/installation.md @@ -135,7 +135,7 @@ docker push /waf-enforcer: ## Deploy NGINX Ingress Controller {#deploy-ingress-controller} -{{< 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`. {{< /important >}} @@ -236,8 +236,8 @@ volumes: emptyDir: {} - name: nginx-log emptyDir: {} - - emptyDir: {} - name: app-protect-bd-config + - name: app-protect-bd-config + emptyDir: {} - emptyDir: {} name: app-protect-config - emptyDir: {} @@ -294,6 +294,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. --- @@ -380,7 +381,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: @@ -467,6 +468,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" >}} @@ -475,13 +480,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 ed7732450..c6ac072df 100644 --- a/content/nic/installation/integrations/app-protect-waf/installation.md +++ b/content/nic/installation/integrations/app-protect-waf/installation.md @@ -162,7 +162,7 @@ kubectl apply -f config/crd/bases/appprotect.f5.com_apusersigs.yaml {{< include "/nic/installation/deploy-controller.md" >}} -{{< 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. +{{< 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`. {{< /note >}} @@ -187,6 +187,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" >}} @@ -195,13 +199,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/installation/integrations/nic-n1-console.md b/content/nic/installation/integrations/nic-n1-console.md index 8602062a0..5b09063d9 100644 --- a/content/nic/installation/integrations/nic-n1-console.md +++ b/content/nic/installation/integrations/nic-n1-console.md @@ -33,7 +33,7 @@ Follow the [Installation with Helm]({{< ref "/nic/installation/installing-nic/in {{%tab name="Manifests"%}} -Add the following flag to the deployment/daemonset file of NGINX Ingress Controller: +Add the following flag to the deployment/daemonset/statefulset file of NGINX Ingress Controller: ```yaml args: @@ -79,7 +79,7 @@ data: Make sure you set the namespace in the nginx-agent-config to the same namespace as NGINX Ingress Controller. -Mount the ConfigMap to the deployment/daemonset file of NGINX Ingress Controller: +Mount the ConfigMap to the deployment/daemonset/statefulset file of NGINX Ingress Controller: ```yaml volumeMounts: diff --git a/content/nic/logging-and-monitoring/prometheus.md b/content/nic/logging-and-monitoring/prometheus.md index 17f32abe5..9c2a46731 100644 --- a/content/nic/logging-and-monitoring/prometheus.md +++ b/content/nic/logging-and-monitoring/prometheus.md @@ -12,7 +12,7 @@ NGINX Ingress Controller exposes metrics in the [Prometheus](https://prometheus. ## Enabling Metrics ### 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 b2908d27c..e585e4d6c 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 29f1ad409..d76b1e6a8 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. diff --git a/content/nic/troubleshooting/troubleshoot-common.md b/content/nic/troubleshooting/troubleshoot-common.md index 4207917a9..748ad0acf 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 a38143ad4..264fd61e6 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: From 43a88074ebd377ce637e8d2e5f061ec260e6b4d6 Mon Sep 17 00:00:00 2001 From: Venktesh Date: Wed, 10 Sep 2025 12:47:11 +0100 Subject: [PATCH 2/4] address review comments --- .../global-configuration/configmap-resource.md | 2 +- .../includes/nic/installation/deploy-controller.md | 1 + .../global-configuration/configmap-resource.md | 2 -- .../integrations/app-protect-waf-v5/installation.md | 12 ++++++------ .../integrations/app-protect-waf/installation.md | 2 +- 5 files changed, 9 insertions(+), 10 deletions(-) diff --git a/content/includes/nic/configuration/global-configuration/configmap-resource.md b/content/includes/nic/configuration/global-configuration/configmap-resource.md index 2e681b3a0..b4c8ad7e3 100644 --- a/content/includes/nic/configuration/global-configuration/configmap-resource.md +++ b/content/includes/nic/configuration/global-configuration/configmap-resource.md @@ -199,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/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/nic/configuration/global-configuration/configmap-resource.md b/content/nic/configuration/global-configuration/configmap-resource.md index f9abcedb5..9161896f8 100644 --- a/content/nic/configuration/global-configuration/configmap-resource.md +++ b/content/nic/configuration/global-configuration/configmap-resource.md @@ -170,7 +170,6 @@ If you encounter the error `error [emerg] 13#13: "zone_sync" directive is duplic {{< /call-out >}} -{{}} |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`, `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* | @@ -178,7 +177,6 @@ If you encounter the error `error [emerg] 13#13: "zone_sync" directive is duplic |*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` | |*zone-sync-resolver-valid* | Configures an [NGINX time](https://nginx.org/en/docs/syntax.html) that the optional [resolver](https://nginx.org/en/docs/http/ngx_http_core_module.html#resolver) directive for zone-sync will override the TTL value of responses from nameservers with. NGINX Plus & `zone-sync` Required | `5s` | -{{}} ### Snippets and custom templates 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 4c8b2d6f7..8c42f681a 100644 --- a/content/nic/installation/integrations/app-protect-waf-v5/installation.md +++ b/content/nic/installation/integrations/app-protect-waf-v5/installation.md @@ -227,18 +227,18 @@ Create required volumes: volumes: - name: nginx-etc emptyDir: {} - - name: nginx-cache - emptyDir: {} + - name: nginx-cache # not required for statefulset + emptyDir: {} # not required for statefulset - name: nginx-lib emptyDir: {} - name: nginx-log emptyDir: {} - name: app-protect-bd-config emptyDir: {} - - emptyDir: {} - name: app-protect-config - - emptyDir: {} - name: app-protect-bundles + - name: app-protect-config + emptyDir: {} + - name: app-protect-bundles + emptyDir: {} ``` Set `controller.securityContext.readOnlyRootFilesystem` to `true`. diff --git a/content/nic/installation/integrations/app-protect-waf/installation.md b/content/nic/installation/integrations/app-protect-waf/installation.md index b8a74b499..f6625e7f3 100644 --- a/content/nic/installation/integrations/app-protect-waf/installation.md +++ b/content/nic/installation/integrations/app-protect-waf/installation.md @@ -183,7 +183,7 @@ volumeMounts: ... ``` -{< call-out "note" >}} +{{< 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 >}} From 4e3d3aca442de47020a78656d85c71be125cac52 Mon Sep 17 00:00:00 2001 From: Venktesh Date: Wed, 10 Sep 2025 14:14:56 +0100 Subject: [PATCH 3/4] add call-out note --- content/nic/configuration/policy-resource.md | 4 ++-- .../installation/integrations/app-protect-waf/installation.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/nic/configuration/policy-resource.md b/content/nic/configuration/policy-resource.md index a09322da5..5edf8b2d0 100644 --- a/content/nic/configuration/policy-resource.md +++ b/content/nic/configuration/policy-resource.md @@ -770,11 +770,11 @@ cache: overrideUpstreamCache: true ``` -{{< note >}} +{{< 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. -{{< /note >}} +{{< /call-out >}} {{% table %}} |Field | Description | Type | Required | diff --git a/content/nic/installation/integrations/app-protect-waf/installation.md b/content/nic/installation/integrations/app-protect-waf/installation.md index f6625e7f3..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" >}} -{{< 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. +{{< 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 >}} From 7b04f43d2e9723ff4086684b7e60ff11eea215ac Mon Sep 17 00:00:00 2001 From: Venktesh Date: Wed, 10 Sep 2025 14:19:14 +0100 Subject: [PATCH 4/4] update security doc --- content/nic/configuration/security.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/content/nic/configuration/security.md b/content/nic/configuration/security.md index ad561cb21..d65fe24be 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 # not required for statefulset +# emptyDir: {} # not required for statefulset # - 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 ```