diff --git a/content/nginx-one-console/k8s/add-nic.md b/content/nginx-one-console/k8s/add-nic.md index fe94eb8b0c..a78a658508 100644 --- a/content/nginx-one-console/k8s/add-nic.md +++ b/content/nginx-one-console/k8s/add-nic.md @@ -13,12 +13,13 @@ Once connected, you'll see a **read-only** configuration of NGINX Ingress Contro - Read-only configuration file - Unmanaged SSL/TLS certificates for Control Planes +- F5 WAF for NGINX security events (when using a WAF-enabled image) ## Before you begin If you do not already have a [data plane key]({{< ref "/nginx-one-console/connect-instances/create-manage-data-plane-keys.md" >}}), you can create one. Pay attention to the expiration date of that key. Any instance that's connected to a data plane key that's expired or revoked will stop working. -You can create a data plane key through the NGINX One Console. Once loggged in, select **Manage > Control Planes > Add Control Plane**, and follow the steps shown. +You can create a data plane key through the NGINX One Console. Once logged in, select **Manage > Control Planes > Add Control Plane**, and follow the steps shown. Before connecting NGINX Ingress Controller to NGINX One Console, you need to create a Kubernetes Secret with the data plane key. Use the following command: @@ -28,14 +29,27 @@ kubectl create secret generic dataplane-key \ -n ``` -When you create a Kubernetes Secret, use the same namespace where NGINX Ingress Controller is running. -If you use [`-watch-namespace`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#watch-namespace-string" >}}) or [`watch-secret-namespace`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#watch-secret-namespace-string" >}}) arguments with NGINX Ingress Controller, +When you create a Kubernetes Secret, use the same namespace where NGINX Ingress Controller is running. +If you use [`-watch-namespace`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#watch-namespace-string" >}}) or [`watch-secret-namespace`]({{< ref "/nic/configuration/global-configuration/command-line-arguments.md#watch-secret-namespace-string" >}}) arguments with NGINX Ingress Controller, you need to add the dataplane key secret to the watched namespaces. This secret will take approximately 60 - 90 seconds to reload on the pod. {{< call-out "note" >}} -You can also create a data plane key through the NGINX One Console. Once loggged in, select **Manage > Control Planes > Add Control Plane**, and follow the steps shown. +You can also create a data plane key through the NGINX One Console. Once logged in, select **Manage > Control Planes > Add Control Plane**, and follow the steps shown. {{< /call-out >}} +### Choosing the right image + +Starting with NGINX Ingress Controller 5.5.0, images with F5 WAF for NGINX and NGINX Agent 3 are available using the `-agent` suffix. The image you need depends on your deployment: + +| Deployment type | Image variant | +|---|---| +| NGINX (open source) | Default image (no special variant needed) | +| NGINX Plus | `nginx-plus-ingress` | +| NGINX Plus with F5 WAF for NGINX v4 | Use an image with the `-nap-agent` suffix (for example, `debian-plus-nap-agent`) | +| NGINX Plus with F5 WAF for NGINX v5 | Use an image with the `-nap-v5-agent` suffix (for example, `debian-plus-nap-v5-agent`) | + +See the [Technical specifications]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}) for the full list of image variants available for each platform. + ## Deploy NGINX Ingress Controller with NGINX Agent {{}} @@ -63,6 +77,20 @@ Upgrade or install NGINX Ingress Controller with the following command to config --set nginxAgent.endpointHost=agent.connect.nginx.com ``` +- For NGINX Plus with F5 WAF for NGINX v4: + + ```shell + helm upgrade --install my-release oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} \ + --set controller.image.repository=myregistry.example.com/nginx-plus-ingress \ + --set controller.nginxplus=true \ + --set controller.appprotect.enable=true \ + --set nginxAgent.enable=true \ + --set nginxAgent.dataplaneKeySecretName= \ + --set nginxAgent.endpointHost=agent.connect.nginx.com + ``` + +- For NGINX Plus with F5 WAF for NGINX v5, set `controller.appprotect.v5=true` and configure the enforcer and config manager images. See the [F5 WAF for NGINX v5 installation guide]({{< ref "/nic/integrations/app-protect-waf-v5/installation.md" >}}) for the additional Helm values required. + The `dataplaneKeySecretName` is used to authenticate the agent with NGINX One Console. See the [NGINX One Console Docs]({{< ref "/nginx-one-console/connect-instances/create-manage-data-plane-keys.md" >}}) for instructions on how to generate your dataplane key from the NGINX One Console. @@ -80,6 +108,10 @@ args: Create a `ConfigMap` with an `nginx-agent.conf` file: +{{}} + +{{%tab name="Without F5 WAF for NGINX"%}} + ```yaml kind: ConfigMap apiVersion: v1 @@ -93,17 +125,17 @@ data: level: info # set log path. if empty, don't log to file. path: "" - + allowed_directories: - /etc/nginx - /usr/lib/nginx/modules - + features: - certificates - connection - metrics - file-watcher - + ## command server settings command: server: @@ -117,25 +149,84 @@ data: collector: log: path: "stdout" -``` +``` + +{{%/tab%}} + +{{%tab name="With F5 WAF for NGINX"%}} + +```yaml +kind: ConfigMap +apiVersion: v1 +metadata: + name: nginx-agent-config + namespace: +data: + nginx-agent.conf: |- + log: + # set log level (error, info, debug; default "info") + level: info + # set log path. if empty, don't log to file. + path: "" -Make sure to set the namespace in the nginx-agent.config to the same namespace as NGINX Ingress Controller. + allowed_directories: + - /etc/nginx + - /usr/lib/nginx/modules + - /etc/app_protect + + features: + - certificates + - connection + - metrics + - file-watcher + - logs-nap + + ## command server settings + command: + server: + host: agent.connect.nginx.com + port: 443 + auth: + tokenpath: "/etc/nginx-agent/secrets/dataplane.key" + tls: + skip_verify: false + + collector: + log: + path: "stdout" +``` + +The `logs-nap` feature enables NGINX Agent to collect F5 WAF for NGINX security events. The `/etc/app_protect` entry in `allowed_directories` is required for WAF-enabled deployments. + +{{%/tab%}} + +{{}} + +Make sure to set the namespace in the ConfigMap to the same namespace as NGINX Ingress Controller. Mount the ConfigMap to the Deployment/DaemonSet file of NGINX Ingress Controller: ```yaml volumeMounts: +- name: agent-etc + mountPath: /etc/nginx-agent - name: nginx-agent-config mountPath: /etc/nginx-agent/nginx-agent.conf subPath: nginx-agent.conf - name: dataplane-key mountPath: /etc/nginx-agent/secrets +- name: agent-dynamic + mountPath: /var/lib/nginx-agent volumes: - name: nginx-agent-config configMap: name: nginx-agent-config +- name: agent-etc + emptyDir: {} - name: dataplane-key secret: secretName: "" +- name: agent-dynamic + emptyDir: {} ``` Follow the [Installation with Manifests]({{< ref "/nic/install/manifests.md" >}}) instructions to deploy NGINX Ingress Controller. @@ -143,9 +234,15 @@ Follow the [Installation with Manifests]({{< ref "/nic/install/manifests.md" >}} {{%/tab%}} {{}} +## Configure F5 WAF for NGINX security monitoring {#configure-waf-security-monitoring} + +When deploying NGINX Ingress Controller with F5 WAF for NGINX, you can forward WAF security events to NGINX One Console for centralized security monitoring. + +For full setup instructions, including WAF policy configuration and examples, see [Connect F5 WAF for NGINX to NGINX Security Monitoring]({{< ref "/nic/tutorials/security-monitoring.md" >}}). + ## Verify a connection to NGINX One Console -After deploying NGINX Ingress Controller with NGINX Agent, you can verify the connection to NGINX One Console. +After deploying NGINX Ingress Controller with NGINX Agent, you can verify the connection to NGINX One Console. Log in to your F5 Distributed Cloud Console account. Select **NGINX One > Visit Service**. In the dashboard, go to **Manage > Instances**. You should see your instances listed by name. The instance name matches both the hostname and the pod name. ## Troubleshooting @@ -157,9 +254,12 @@ Check the NGINX Agent version: ```shell kubectl exec -it -n -- nginx-agent -v ``` - -If nginx-agent version is v3, continue with the following steps. -Otherwise, make sure you are using an image that does not include F5 WAF for NGINX. + +Verify that the output shows `nginx-agent version v3.x.x`. If the agent version is v2, you are using an image that includes NGINX Agent 2 instead of NGINX Agent 3. Use an image variant with the `-agent` suffix (available starting with NGINX Ingress Controller 5.5.0): + +- For NGINX Plus without WAF: use the standard NGINX Plus image +- For F5 WAF for NGINX v4: use an image with the `-nap-agent` suffix (for example, `debian-plus-nap-agent`) +- For F5 WAF for NGINX v5: use an image with the `-nap-v5-agent` suffix (for example, `debian-plus-nap-v5-agent`) Check the NGINX Agent configuration: @@ -167,6 +267,8 @@ Check the NGINX Agent configuration: kubectl exec -it -n -- cat /etc/nginx-agent/nginx-agent.conf ``` +If using F5 WAF for NGINX, verify that `logs-nap` is listed under `features` and `/etc/app_protect` is listed under `allowed_directories`. + Check NGINX Agent logs: ```shell @@ -175,7 +277,7 @@ kubectl exec -it -n -- nginx-agent Select the instance associated with your deployment of NGINX Ingress Controller. Under the **Details** tab, you'll see information associated with: -- Unmanaged SSL/TLS certificates for Control Planes -- Configuration recommendations +- Unmanaged SSL/TLS certificates for Control Planes +- Configuration recommendations Under the **Configuration** tab, you'll see a **read-only** view of the configuration files. diff --git a/content/nic/install/images/registry-download.md b/content/nic/install/images/registry-download.md index e844c2f708..2f1290b1bb 100644 --- a/content/nic/install/images/registry-download.md +++ b/content/nic/install/images/registry-download.md @@ -51,6 +51,12 @@ Replace `` with the specific version you need, for example, `{{< ni docker pull private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress: ``` +- For NGINX Plus Ingress Controller with F5 WAF for NGINX and NGINX Agent 3 (required for NGINX One Console, available starting with NGINX Ingress Controller 5.5.0), run: + + ```shell + docker pull private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:-agent + ``` + - For NGINX Plus Ingress Controller with F5 WAF for NGINX v5, run: ```shell @@ -65,6 +71,20 @@ Replace `` with the specific version you need, for example, `{{< ni docker pull private-registry.nginx.com/nap/waf-enforcer: ``` +- For NGINX Plus Ingress Controller with F5 WAF for NGINX v5 and NGINX Agent 3 (required for NGINX One Console, available starting with NGINX Ingress Controller 5.5.0), run: + + ```shell + docker pull private-registry.nginx.com/nginx-ic-nap-v5/nginx-plus-ingress:-agent + ``` + + ```shell + docker pull private-registry.nginx.com/nap/waf-config-mgr: + ``` + + ```shell + docker pull private-registry.nginx.com/nap/waf-enforcer: + ``` + - For NGINX Plus Ingress Controller with F5 DoS for NGINX, run: ```shell @@ -106,8 +126,33 @@ curl https://private-registry.nginx.com/v2/nginx-ic-nap/nginx-plus-ingress/tags/ "name": "nginx-ic-nap/nginx-plus-ingress", "tags": [ "{{< nic-version >}}-alpine-fips", + "{{< nic-version >}}-alpine-fips-agent", "{{< nic-version >}}-ubi", - "{{< nic-version >}}" + "{{< nic-version >}}-ubi-agent", + "{{< nic-version >}}-ubi8", + "{{< nic-version >}}-ubi8-agent", + "{{< nic-version >}}", + "{{< nic-version >}}-agent" + ] +} +``` + +```shell +curl https://private-registry.nginx.com/v2/nginx-ic-nap-v5/nginx-plus-ingress/tags/list --key --cert +``` + +```json +{ + "name": "nginx-ic-nap-v5/nginx-plus-ingress", + "tags": [ + "{{< nic-version >}}-alpine-fips", + "{{< nic-version >}}-alpine-fips-agent", + "{{< nic-version >}}-ubi", + "{{< nic-version >}}-ubi-agent", + "{{< nic-version >}}-ubi8", + "{{< nic-version >}}-ubi8-agent", + "{{< nic-version >}}", + "{{< nic-version >}}-agent" ] } ``` @@ -145,18 +190,42 @@ After pulling the image, tag it and upload it to your private registry. docker push /nginx-ic/nginx-plus-ingress: ``` - - For NGINX Controller with F5 WAF for NGINX, run: + - For NGINX Plus Ingress Controller with F5 WAF for NGINX, run: ```shell docker tag private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress: /nginx-ic-nap/nginx-plus-ingress: docker push /nginx-ic-nap/nginx-plus-ingress: ``` - - For NGINX Controller with F5 WAF for NGINX v5, run: + - For NGINX Plus Ingress Controller with F5 WAF for NGINX and NGINX Agent 3, run: ```shell - docker tag private-registry.nginx.com/nginx-ic-nap-v5/nginx-plus-ingress: /nginx-ic-nap/nginx-plus-ingress: - docker push /nginx-ic-nap/nginx-plus-ingress: + docker tag private-registry.nginx.com/nginx-ic-nap/nginx-plus-ingress:-agent /nginx-ic-nap/nginx-plus-ingress:-agent + docker push /nginx-ic-nap/nginx-plus-ingress:-agent + ``` + + - For NGINX Plus Ingress Controller with F5 WAF for NGINX v5, run: + + ```shell + docker tag private-registry.nginx.com/nginx-ic-nap-v5/nginx-plus-ingress: /nginx-ic-nap-v5/nginx-plus-ingress: + docker push /nginx-ic-nap-v5/nginx-plus-ingress: + ``` + + ```shell + docker tag private-registry.nginx.com/nap/waf-config-mgr: /nap/waf-config-mgr: + docker push /nap/waf-config-mgr: + ``` + + ```shell + docker tag private-registry.nginx.com/nap/waf-enforcer: /nap/waf-enforcer: + docker push /nap/waf-enforcer: + ``` + + - For NGINX Plus Ingress Controller with F5 WAF for NGINX v5 and NGINX Agent 3, run: + + ```shell + docker tag private-registry.nginx.com/nginx-ic-nap-v5/nginx-plus-ingress:-agent /nginx-ic-nap-v5/nginx-plus-ingress:-agent + docker push /nginx-ic-nap-v5/nginx-plus-ingress:-agent ``` ```shell @@ -169,7 +238,7 @@ After pulling the image, tag it and upload it to your private registry. docker push /nap/waf-enforcer: ``` - - For NGINX Controller with F5 DoS for NGINX, run: + - For NGINX Plus Ingress Controller with F5 DoS for NGINX, run: ```shell docker tag private-registry.nginx.com/nginx-ic-dos/nginx-plus-ingress: /nginx-ic-dos/nginx-plus-ingress: diff --git a/content/nic/technical-specifications.md b/content/nic/technical-specifications.md index 60e3c5ab2c..2d1b006036 100644 --- a/content/nic/technical-specifications.md +++ b/content/nic/technical-specifications.md @@ -50,15 +50,25 @@ NGINX Plus images are available through the F5 Container registry `private-regis |Alpine-based image | ``alpine:3.22`` | NJS (NGINX JavaScript)
OpenTelemetry | `nginx-ic/nginx-plus-ingress:{{< nic-version >}}-alpine` | arm64
amd64 | |Alpine-based image with FIPS inside | ``alpine:3.22`` | NJS (NGINX JavaScript)
OpenTelemetry
FIPS module and OpenSSL configuration | `nginx-ic/nginx-plus-ingress:{{< nic-version >}}-alpine-fips` | arm64
amd64 | |Alpine-based image with F5 WAF for NGINX & FIPS inside | ``alpine:3.22`` | F5 WAF for NGINX
NJS (NGINX JavaScript)
OpenTelemetry
FIPS module and OpenSSL configuration | `nginx-ic-nap/nginx-plus-ingress:{{< nic-version >}}-alpine-fips` | amd64 | +|Alpine-based image with F5 WAF for NGINX & FIPS inside and NGINX Agent 3 | ``alpine:3.22`` | F5 WAF for NGINX
NJS (NGINX JavaScript)
OpenTelemetry
FIPS module and OpenSSL configuration
NGINX Agent 3 | `nginx-ic-nap/nginx-plus-ingress:{{< nic-version >}}-alpine-fips-agent` | amd64 | |Alpine-based image with F5 WAF for NGINX v5 & FIPS inside | ``alpine:3.22`` | F5 WAF for NGINX v5
NJS (NGINX JavaScript)
OpenTelemetry
FIPS module and OpenSSL configuration | `nginx-ic-nap-v5/nginx-plus-ingress:{{< nic-version >}}-alpine-fips` | amd64 | +|Alpine-based image with F5 WAF for NGINX v5 & FIPS inside and NGINX Agent 3 | ``alpine:3.22`` | F5 WAF for NGINX v5
NJS (NGINX JavaScript)
OpenTelemetry
FIPS module and OpenSSL configuration
NGINX Agent 3 | `nginx-ic-nap-v5/nginx-plus-ingress:{{< nic-version >}}-alpine-fips-agent` | amd64 | |Debian-based image | ``debian:12-slim`` | NJS (NGINX JavaScript)
OpenTelemetry | `nginx-ic/nginx-plus-ingress:{{< nic-version >}}` | arm64
amd64 | |Debian-based image with F5 WAF for NGINX | ``debian:12-slim`` | F5 WAF for NGINX
NJS (NGINX JavaScript)
OpenTelemetry | `nginx-ic-nap/nginx-plus-ingress:{{< nic-version >}}` | amd64 | +|Debian-based image with F5 WAF for NGINX and NGINX Agent 3 | ``debian:12-slim`` | F5 WAF for NGINX
NJS (NGINX JavaScript)
OpenTelemetry
NGINX Agent 3 | `nginx-ic-nap/nginx-plus-ingress:{{< nic-version >}}-agent` | amd64 | |Debian-based image with F5 WAF for NGINX v5 | ``debian:12-slim`` | F5 WAF for NGINX v5
NJS (NGINX JavaScript)
OpenTelemetry | `nginx-ic-nap-v5/nginx-plus-ingress:{{< nic-version >}}` | amd64 | +|Debian-based image with F5 WAF for NGINX v5 and NGINX Agent 3 | ``debian:12-slim`` | F5 WAF for NGINX v5
NJS (NGINX JavaScript)
OpenTelemetry
NGINX Agent 3 | `nginx-ic-nap-v5/nginx-plus-ingress:{{< nic-version >}}-agent` | amd64 | |Debian-based image with F5 DoS for NGINX | ``debian:12-slim`` | F5 DoS for NGINX
NJS (NGINX JavaScript)
OpenTelemetry | `nginx-ic-dos/nginx-plus-ingress:{{< nic-version >}}` | amd64 | |Debian-based image with F5 WAF for NGINX and DoS | ``debian:12-slim`` | F5 WAF for NGINX and DoS
NJS (NGINX JavaScript)
OpenTelemetry | `nginx-ic-nap-dos/nginx-plus-ingress:{{< nic-version >}}` | amd64 | |Ubi-based image | ``redhat/ubi9-minimal`` | NJS (NGINX JavaScript)
OpenTelemetry | `nginx-ic/nginx-plus-ingress:{{< nic-version >}}-ubi` | arm64
amd64 | |Ubi-based image with F5 WAF for NGINX | ``redhat/ubi9`` | F5 WAF for NGINX
NJS (NGINX JavaScript)
OpenTelemetry | `nginx-ic-nap/nginx-plus-ingress:{{< nic-version >}}-ubi` | amd64 | +|Ubi-based image with F5 WAF for NGINX and NGINX Agent 3 | ``redhat/ubi9`` | F5 WAF for NGINX
NJS (NGINX JavaScript)
OpenTelemetry
NGINX Agent 3 | `nginx-ic-nap/nginx-plus-ingress:{{< nic-version >}}-ubi-agent` | amd64 | +|Ubi8-based image with F5 WAF for NGINX | ``redhat/ubi8`` | F5 WAF for NGINX
NJS (NGINX JavaScript)
OpenTelemetry | `nginx-ic-nap/nginx-plus-ingress:{{< nic-version >}}-ubi8` | amd64 | +|Ubi8-based image with F5 WAF for NGINX and NGINX Agent 3 | ``redhat/ubi8`` | F5 WAF for NGINX
NJS (NGINX JavaScript)
OpenTelemetry
NGINX Agent 3 | `nginx-ic-nap/nginx-plus-ingress:{{< nic-version >}}-ubi8-agent` | amd64 | |Ubi-based image with F5 WAF for NGINX v5 | ``redhat/ubi9`` | F5 WAF for NGINX v5
NJS (NGINX JavaScript)
OpenTelemetry | `nginx-ic-nap-v5/nginx-plus-ingress:{{< nic-version >}}-ubi` | amd64 | +|Ubi-based image with F5 WAF for NGINX v5 and NGINX Agent 3 | ``redhat/ubi9`` | F5 WAF for NGINX v5
NJS (NGINX JavaScript)
OpenTelemetry
NGINX Agent 3 | `nginx-ic-nap-v5/nginx-plus-ingress:{{< nic-version >}}-ubi-agent` | amd64 | +|Ubi8-based image with F5 WAF for NGINX v5 | ``redhat/ubi8`` | F5 WAF for NGINX v5
NJS (NGINX JavaScript)
OpenTelemetry | `nginx-ic-nap-v5/nginx-plus-ingress:{{< nic-version >}}-ubi8` | amd64 | +|Ubi8-based image with F5 WAF for NGINX v5 and NGINX Agent 3 | ``redhat/ubi8`` | F5 WAF for NGINX v5
NJS (NGINX JavaScript)
OpenTelemetry
NGINX Agent 3 | `nginx-ic-nap-v5/nginx-plus-ingress:{{< nic-version >}}-ubi8-agent` | amd64 | |Ubi-based image with F5 DoS for NGINX | ``redhat/ubi8`` | F5 DoS for NGINX
NJS (NGINX JavaScript)
OpenTelemetry | `nginx-ic-dos/nginx-plus-ingress:{{< nic-version >}}-ubi` | amd64 | |Ubi-based image with F5 WAF for NGINX and DoS | ``redhat/ubi8`` | F5 WAF for NGINX and DoS
NJS (NGINX JavaScript)
OpenTelemetry | `nginx-ic-nap-dos/nginx-plus-ingress:{{< nic-version >}}-ubi` | amd64 | diff --git a/content/nic/tutorials/security-monitoring.md b/content/nic/tutorials/security-monitoring.md index dc4275f935..28f88e5255 100644 --- a/content/nic/tutorials/security-monitoring.md +++ b/content/nic/tutorials/security-monitoring.md @@ -9,17 +9,24 @@ nd-docs: DOCS-1856 This document explains how to use NGINX Ingress Controller to configure NGINX Agent for sending F5 WAF for NGINX metrics to NGINX Security Monitoring. +You can send security metrics to either: + +- **NGINX Instance Manager** using NGINX Agent 2 +- **NGINX One Console** using NGINX Agent 3 (available starting with NGINX Ingress Controller 5.5.0, using images with the `-agent` suffix) + +{{}} + +{{%tab name="NGINX Instance Manager"%}} + ## Before you begin This guide assumes that you have an installation of NGINX Instance Manager with NGINX Security Monitoring which is reachable from the Kubernetes cluster on which NGINX Ingress Controller is deployed. -If you use custom container images, NGINX Agent must be installed along with F5 WAF for NGINX. See the [Dockerfile](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/build/Dockerfile) for examples of how to install NGINX Agent or the [NGINX Agent installation documentation]({{< ref "/agent/installation-upgrade/" >}}) for more information. +NGINX Ingress Controller images that include F5 WAF for NGINX also include NGINX Agent 2. See the [Technical specifications]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}) for the full list of available image variants. -## Deploying NGINX Ingress Controller with NGINX Agent configuration +## Deploy NGINX Ingress Controller with NGINX Agent -{{}} - -{{%tab name="Using Helm"%}} +### Using Helm 1. Add the below arguments to the `values.yaml` file: @@ -32,11 +39,9 @@ If you use custom container images, NGINX Agent must be installed along with F5 2. Follow the [Installation with Helm]({{< ref "/nic/install/helm.md" >}}) instructions to deploy NGINX Ingress Controller with custom resources enabled, and optionally set other `nginxAgent.*` values if required. -{{%/tab%}} - -{{%tab name="Using Manifests"%}} +### Using Manifests -1. Add the below argument to the manifest file of NGINX Ingress Controller: +1. Add the below arguments to the `args` section of your NGINX Ingress Controller Deployment, DaemonSet, or StatefulSet: ```yaml args: @@ -85,7 +90,7 @@ If you use custom container images, NGINX Agent must be installed along with F5 {{< call-out "note" >}} The `features` list must not contain `nginx-config-async` or `nginx-ssl-config` as these features can cause conflicts with NGINX Ingress Controller.{{< /call-out >}} -3. Make sure that the ConfigMap is mounted to the NGINX Ingress Controller pod at `/etc/nginx-agent/nginx-agent.conf` and the dynamic agent config is mounted at `/var/lib/nginx-agent` by adding the following volumes and volumeMounts to the NGINX Ingress Controller deployment manifest: +3. Mount the ConfigMap to the NGINX Ingress Controller pod at `/etc/nginx-agent/nginx-agent.conf` and the dynamic agent config at `/var/lib/nginx-agent` by adding the following to your Deployment, DaemonSet, or StatefulSet: ```yaml volumes: @@ -107,17 +112,267 @@ If you use custom container images, NGINX Agent must be installed along with F5 4. Follow the [Installation with Manifests]({{< ref "/nic/install/manifests.md" >}}) instructions to deploy NGINX Ingress Controller with custom resources enabled. +Once installed, the pods will be visible in the NGINX Instance Manager Instances dashboard. + {{%/tab%}} -{{}} +{{%tab name="NGINX One Console"%}} + +## Before you begin + +This guide assumes that you have an NGINX One Console account with access to create data plane keys. + +- Create a [data plane key]({{< ref "/nginx-one-console/connect-instances/create-manage-data-plane-keys.md" >}}) from NGINX One Console. Pay attention to the expiration date of that key. +- Create a Kubernetes Secret with the data plane key in the same namespace where NGINX Ingress Controller will be deployed: + + ```shell + kubectl create secret generic dataplane-key \ + --from-literal=dataplane.key= \ + -n + ``` + +- Use an image variant with the `-agent` suffix, available starting with NGINX Ingress Controller 5.5.0 (for example, `debian-plus-nap-agent` for F5 WAF for NGINX v4, or `debian-plus-nap-v5-agent` for v5). Images without the `-agent` suffix include NGINX Agent 2 and are not compatible with NGINX One Console. See the [Technical specifications]({{< ref "/nic/technical-specifications.md#images-with-nginx-plus" >}}) for the full list of available image variants. + +## Deploy NGINX Ingress Controller with NGINX Agent + +### Using Helm + +1. Add the below arguments to the `values.yaml` file: + + ```yaml + nginxAgent: + enable: true + dataplaneKeySecretName: "" + endpointHost: "agent.connect.nginx.com" + endpointPort: 443 + ``` + +2. Follow the [Installation with Helm]({{< ref "/nic/install/helm.md" >}}) instructions to deploy NGINX Ingress Controller with custom resources enabled. + +See the [Connect NGINX Ingress Controller to NGINX One Console]({{< ref "/nginx-one-console/k8s/add-nic.md" >}}) guide for more details on connecting to NGINX One Console. + +### Using Manifests + +1. Add the below argument to the `args` section of your NGINX Ingress Controller Deployment, DaemonSet, or StatefulSet: + + ```yaml + args: + - -agent=true + ``` -Once NGINX Ingress Controller is installed the pods will be visible in the NGINX Instance Monitoring Instances dashboard. +2. Create a Kubernetes Secret with the data plane key if you have not already done so: + + ```shell + kubectl create secret generic dataplane-key \ + --from-literal=dataplane.key= \ + -n + ``` + +3. Create a ConfigMap with an `nginx-agent.conf` file: + + ```yaml + kind: ConfigMap + apiVersion: v1 + metadata: + name: nginx-agent-config + namespace: + data: + nginx-agent.conf: |- + log: + level: info + path: "" + + allowed_directories: + - /etc/nginx + - /usr/lib/nginx/modules + - /etc/app_protect + + features: + - certificates + - connection + - metrics + - file-watcher + - logs-nap + + command: + server: + host: agent.connect.nginx.com + port: 443 + auth: + tokenpath: "/etc/nginx-agent/secrets/dataplane.key" + tls: + skip_verify: false + + collector: + log: + path: "stdout" + ``` + + The `logs-nap` feature enables NGINX Agent to collect F5 WAF for NGINX security events. The `/etc/app_protect` entry in `allowed_directories` is required for WAF-enabled deployments. + +4. Mount the ConfigMap and the data plane key Secret to the NGINX Ingress Controller pod: + + ```yaml + volumes: + - name: agent-conf + configMap: + name: nginx-agent-config + - name: agent-etc + emptyDir: {} + - name: dataplane-key + secret: + secretName: "" + - name: agent-dynamic + emptyDir: {} + ``` + + ```yaml + volumeMounts: + - name: agent-etc + mountPath: /etc/nginx-agent + - name: agent-conf + mountPath: /etc/nginx-agent/nginx-agent.conf + subPath: nginx-agent.conf + - name: dataplane-key + mountPath: /etc/nginx-agent/secrets + - name: agent-dynamic + mountPath: /var/lib/nginx-agent + ``` + +5. Follow the [Installation with Manifests]({{< ref "/nic/install/manifests.md" >}}) instructions to deploy NGINX Ingress Controller with custom resources enabled. + +Once installed, the pods will be visible in NGINX One Console. See [Verify a connection to NGINX One Console]({{< ref "/nginx-one-console/k8s/add-nic.md#verify-a-connection-to-nginx-one-console" >}}) for details. + +{{%/tab%}} + +{{}} ## Configuring F5 WAF for NGINX to send metrics to NGINX Agent -NGINX Agent runs a syslog listener which F5 WAF for NGINX can be configured to send logs to, which will then allow NGINX Agent to send metrics to NGINX Security Monitoring. The following examples show how to configure F5 WAF for NGINX to log to NGINX Agent. +NGINX Agent runs a syslog listener which F5 WAF for NGINX can be configured to send logs to, which will then allow NGINX Agent to send metrics to NGINX Security Monitoring. This applies to both NGINX Instance Manager (NGINX Agent 2) and NGINX One Console (NGINX Agent 3) deployments. When using NGINX Agent 3, the `logs-nap` feature handles syslog collection automatically. + +Configure the WAF Policy `logDest` to send logs to the NGINX Agent syslog listener at `syslog:server=127.0.0.1:1514`. + +For F5 WAF for NGINX v4, see the [VirtualServer example](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/security-monitoring) and [Ingress example](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/security-monitoring) in the repository. Do not modify the APLogConf in these examples, as NGINX Agent expects a specific log format. + +For F5 WAF for NGINX v5, see the [VirtualServer example](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/security-monitoring-v5) and [Ingress example](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/security-monitoring-v5) in the repository. Policy and log configurations are compiled into bundles (`.tgz` files) instead of using APPolicy and APLogConf custom resources. The log bundle must be compiled from a log profile that matches the format required by NGINX Security Monitoring. See the [F5 WAF for NGINX v5 configuration guide]({{< ref "/nic/integrations/app-protect-waf-v5/configuration.md" >}}) for details on compiling policy and log bundles. + +When using NGINX One Console, you can create and manage WAF policies under **WAF > Policies**. Once you have a policy, compile it into a `.tgz` bundle using the waf-compiler image and copy it to the pod at `/etc/app_protect/bundles/`. See [Compile WAF Policy from JSON to Bundle]({{< ref "/nic/install/waf-helm.md#compile-waf-policy-from-json-to-bundle" >}}) for the compilation steps. + +For the required log bundle, the `secops_dashboard` log profile is available to download directly from **WAF > Log Profiles** in NGINX One Console — no compilation needed. See [Set up security monitoring](https://docs.nginx.com/nginx-one-console/waf-integration/waf-security-dashboard/set-up-security-monitoring/) in the NGINX One Console documentation for details. + +## Upgrading from NGINX Instance Manager to NGINX One Console + +If you have an existing deployment using NGINX Instance Manager (NGINX Agent 2) and want to migrate to NGINX One Console (NGINX Agent 3, available starting with NGINX Ingress Controller 5.5.0), follow these steps: + +1. **Obtain a data plane key** from NGINX One Console. See [Create and manage data plane keys]({{< ref "/nginx-one-console/connect-instances/create-manage-data-plane-keys.md" >}}). + +2. **Create the data plane key Secret** in the same namespace as your NGINX Ingress Controller deployment: + + ```shell + kubectl create secret generic dataplane-key \ + --from-literal=dataplane.key= \ + -n + ``` + +3. **Update your deployment** to use NGINX Agent 3: + +{{}} + +{{%tab name="Using Helm"%}} + +Update your `values.yaml` to replace the NGINX Instance Manager configuration with NGINX One Console configuration: + +```yaml +# Remove these values: +# nginxAgent: +# instanceManager: +# host: "nim.example.com" +# syslog: ... +# napMonitoring: ... + +# Add NGINX One Console configuration: +nginxAgent: + enable: true + dataplaneKeySecretName: "dataplane-key" + endpointHost: "agent.connect.nginx.com" + endpointPort: 443 +``` + +Run the upgrade: + +```shell +helm upgrade oci://ghcr.io/nginx/charts/nginx-ingress --version {{< nic-helm-version >}} \ + -f values.yaml \ + -n +``` + +{{%/tab%}} + +{{%tab name="Using Manifests"%}} + +1. Update the container image in your Deployment or DaemonSet to an image variant with the `-agent` suffix, available starting with NGINX Ingress Controller 5.5.0 (for example, `debian-plus-nap-agent` for WAF v4, or `debian-plus-nap-v5-agent` for WAF v5). + +2. Update the container args to remove `-agent-instance-group`: + + ```yaml + args: + - -agent=true + # Remove: - -agent-instance-group= + ``` + +3. Replace the `nginx-agent.conf` ConfigMap with the NGINX Agent 3 configuration shown in the [Using NGINX One Console - Using Manifests](#using-nginx-one-console) section above. + +4. Update volumes and volumeMounts: + + Remove the NGINX Instance Manager TLS volume and mount: + + ```yaml + # Remove: + # - name: nginx-agent-tls + # projected: + # sources: + # - secret: + # name: + # - secret: + # name: + ``` + + Add the data plane key volume and mount: + + ```yaml + volumes: + - name: dataplane-key + secret: + secretName: "dataplane-key" + + volumeMounts: + - name: dataplane-key + mountPath: /etc/nginx-agent/secrets + ``` + +5. Apply the updated manifests: + + ```shell + kubectl apply -f .yaml + ``` + +{{%/tab%}} -- [Custom Resources example](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/custom-resources/security-monitoring) -- [Ingress Resources example](https://github.com/nginx/kubernetes-ingress/tree/v{{< nic-version >}}/examples/ingress-resources/security-monitoring) +{{}} + +4. **Verify the upgrade** by checking the agent version and connection: + + ```shell + kubectl exec -it -n -- nginx-agent -v + ``` + + The output should show `nginx-agent version v3.x.x`. Check the NGINX One Console dashboard under **Manage > Instances** to confirm your instances appear. + +5. **Clean up** old NGINX Instance Manager TLS secrets if they are no longer needed: + + ```shell + kubectl delete secret -n + ``` -{{< call-out "note" >}} Modifying the APLogConf in the examples may result in the Security Monitoring integration not working, as NGINX Agent expects a specific log format.{{< /call-out >}} +{{< call-out "note" >}} Your F5 WAF for NGINX Policy resources (APPolicy, APLogConf, or compiled bundles for v5) do not need to change during this migration. The WAF configuration and the `logDest` syslog destination (`syslog:server=127.0.0.1:1514`) remain the same.{{< /call-out >}}