diff --git a/content/includes/nim/tech-specs/supported-distros.md b/content/includes/nim/tech-specs/supported-distros.md index dc57fda00..d86fcac41 100644 --- a/content/includes/nim/tech-specs/supported-distros.md +++ b/content/includes/nim/tech-specs/supported-distros.md @@ -14,10 +14,10 @@ The following table lists the Linux distributions supported by NGINX Instance Ma |-----------------|----------------------------------------|------------------|-----------------------------------------------------|----------------------------------------------------| | Debian | 11
12
13 | x86_64
x86_64
x86_64 | Supported
Supported
Supported | Supported
Supported
Supported | | Oracle Linux | 8.0 and later in the 8.x family | x86_64 | Supported | Supported | -| RHEL and Rocky | 8.0 and later in the 8.x family
9.0 and later in the 9.x family
10.0 and later in the 10.x family | x86_64
x86_64
x86_64 | Supported
Supported
Supported | Supported
Supported
Supported | -| Ubuntu | 22.04
24.04
26.04 | x86_64
x86_64
x86_64 | Supported
Supported on 2.18.0+ | Supported
Supported
Supported | +| RHEL | 8.0 and later in the 8.x family
9.0 and later in the 9.x family
10.0 and later in the 10.x family | x86_64
x86_64
x86_64 | Supported
Supported
Supported | Supported
Supported
Supported | +| Rocky Linux | 8.0 and later in the 8.x family
9.0 and later in the 9.x family
10.0 and later in the 10.x family | x86_64
x86_64
x86_64 | Supported (via RHEL compatibility packages)
Supported (via RHEL compatibility packages)
Supported (native packages on 2.23.0+) | Supported
Supported
Supported | +| Ubuntu | 22.04
24.04
26.04 LTS | x86_64
x86_64
x86_64 | Supported
Supported on 2.18.0+
Supported on 2.23.0+ | Supported
Supported
Supported | {{}} - diff --git a/content/ngf/overview/technical-specifications.md b/content/ngf/overview/technical-specifications.md index 6634e97af..d16983e1b 100644 --- a/content/ngf/overview/technical-specifications.md +++ b/content/ngf/overview/technical-specifications.md @@ -33,6 +33,9 @@ The following table lists the software versions NGINX Gateway Fabric supports. O | 1.3.0 | 1.1.0 | 1.25+ | 1.27.0 | R32 | --- | --- | | 1.2.0 | 1.0.0 | 1.23+ | 1.25.4 | R31 | --- | --- | +{{< call-out class="note" title="Note: NGINX Instance Manager integration" >}} +For version requirements to export F5 WAF for NGINX security events to NGINX Instance Manager, see [Export security logs to F5 NGINX Instance Manager]({{< ref "/ngf/waf-integration/policy-sources.md#export-security-logs-to-f5-nginx-instance-manager" >}}).{{< /call-out >}} + ### OpenShift Compatibility The following table lists the OpenShift versions and Operator versions compatible with NGINX Gateway Fabric. diff --git a/content/ngf/waf-integration/policy-sources.md b/content/ngf/waf-integration/policy-sources.md index 260cd3050..72d30b377 100644 --- a/content/ngf/waf-integration/policy-sources.md +++ b/content/ngf/waf-integration/policy-sources.md @@ -4,24 +4,24 @@ weight: 300 toc: true f5-content-type: how-to f5-product: NGINX Gateway Fabric -f5-description: Configure WAFPolicy to fetch compiled bundles from F5 NGINX Instance Manager, F5 NGINX One Console, an HTTP server, or Policy Lifecycle Management. +description: Configure WAFPolicy to fetch compiled bundles from F5 NGINX Instance Manager, F5 NGINX One Console, an HTTP server, or Policy Lifecycle Management. --- NGINX Gateway Fabric supports four policy source types for fetching compiled WAF bundles: F5 NGINX Instance Manager, F5 NGINX One Console, direct HTTP/HTTPS URLs, and Policy Lifecycle Management (PLM). For a quick start walkthrough using the HTTP source, see [Get started with F5 WAF for NGINX]({{< ref "/ngf/waf-integration/get-started-http.md" >}}). For a walkthrough using PLM, see [Get started with F5 WAF for NGINX using PLM]({{< ref "/ngf/waf-integration/get-started-plm.md" >}}). -Before configuring a policy source, make sure WAF is [enabled on the NginxProxy]({{< ref "/ngf/waf-integration/overview.md#enable-waf-on-the-nginxproxy" >}}), either per Gateway or globally through Helm values. +Before you configure a policy source, make sure F5 WAF is turned on for the NginxProxy — either per Gateway or globally through Helm values. For version requirements, see [Technical specifications]({{< ref "/ngf/overview/technical-specifications.md" >}}). -{{< call-out class="tip" >}} By default, NGINX Gateway Fabric retries transient fetch failures up to 3 times with exponential backoff, and each fetch attempt times out after 30 seconds. You can tune these using the `retryAttempts` and `timeout` fields on `policySource` or `logSource`. {{< /call-out >}} +{{< call-out class="tip" title="Tip: Fetch retry behavior" >}} By default, NGINX Gateway Fabric retries transient fetch failures up to 3 times with exponential backoff, and each fetch attempt times out after 30 seconds. You can tune these using the `retryAttempts` and `timeout` fields on `policySource` or `logSource`. {{< /call-out >}} --- -## NGINX Instance Manager +## F5 NGINX Instance Manager -Use this option when you manage WAF policies through NGINX Instance Manager. For details on creating and compiling policies in NGINX Instance Manager, see [How WAF policy management works]({{< ref "/nim/waf-integration/overview.md" >}}) and [Create a security policy bundle]({{< ref "/nim/waf-integration/policies-and-logs/bundles/create-bundle.md" >}}). +Use this option when you manage F5 WAF policies through F5 NGINX Instance Manager. For details on creating and compiling policies in NGINX Instance Manager, see [How WAF policy management works]({{< ref "/nim/waf-integration/overview.md" >}}) and [Create a security policy bundle]({{< ref "/nim/waf-integration/policies-and-logs/bundles/create-bundle.md" >}}). **Workflow:** -1. Author and compile a policy in NGINX Instance Manager using the NGINX Instance Manager console or API. Verify that compilation succeeded before proceeding. NGINX Gateway Fabric can't detect compilation failures in NGINX Instance Manager. +1. Author and compile a policy in NGINX Instance Manager using the NGINX Instance Manager console or API. Verify that compilation succeeded. NGINX Gateway Fabric can't detect compilation failures in NGINX Instance Manager. 2. Create a Secret with your NGINX Instance Manager credentials. 3. Create a `WAFPolicy` referencing the compiled policy by name. @@ -92,13 +92,13 @@ EOF Replace `https://nim.example.com` with your NGINX Instance Manager base URL, and `ngfBlocking` with your compiled policy name. -{{< call-out class="tip" >}} To skip TLS certificate verification when fetching bundles (for testing only - not recommended for production), uncomment 'insecureSkipVerify: true'. {{< /call-out >}} +{{< call-out class="tip" title="Tip: Testing with self-signed certificates" >}} To skip TLS certificate verification when fetching bundles, uncomment `insecureSkipVerify: true`. Don't use this in production. {{< /call-out >}} -{{< call-out class="tip" >}} To pin a specific policy version, use `policyUID` instead of `policyName`. Find the UID in the NGINX Instance Manager console or API. A pinned UID always resolves to the same compiled bundle, so polling should be disabled to avoid unnecessary network requests. {{< /call-out >}} +{{< call-out class="tip" title="Tip: Pin a policy version" >}} To pin a specific policy version, use `policyUID` instead of `policyName`. Find the UID in the NGINX Instance Manager console or API. A pinned UID always resolves to the same compiled bundle. Turn off polling to avoid unnecessary network requests. {{< /call-out >}} ### Apply a route-level override (optional) -To apply a different policy to a specific route (for example, a data-guard policy), create a route-level `WAFPolicy`: +To apply a different policy to a specific route, such as a data-guard policy, create a route-level `WAFPolicy`: ```yaml kubectl apply -f - <}}). + --- ## F5 NGINX One Console -Use this option when you manage WAF policies through F5 NGINX One Console. For details on creating and compiling policies in NGINX One Console, see [Manage policies]({{< ref "/nginx-one-console/waf-integration/policy/_index.md" >}}). +Use this option when you manage F5 WAF policies through F5 NGINX One Console. For details on creating and compiling policies in NGINX One Console, see [Manage policies]({{< ref "/nginx-one-console/waf-integration/policy/_index.md" >}}). **Workflow:** -1. Author and compile a policy in the NGINX One Console console or API. If no compiled bundle for a given policy exists yet, NGINX Gateway Fabric triggers compilation through the NGINX One Console API when it first reconciles the WAFPolicy and waits for it to complete. -2. Create a Secret with your NGINX One Console API token. -3. Create a `WAFPolicy` referencing the compiled policy. +1. Author and compile a policy in the NGINX One Console or API. +2. If no compiled bundle exists yet, NGINX Gateway Fabric triggers compilation through the NGINX One Console API. This happens the first time NGINX Gateway Fabric reconciles the `WAFPolicy` resource. NGINX Gateway Fabric waits for compilation to finish before continuing. +3. Create a Secret with your NGINX One Console API token. +4. Create a `WAFPolicy` referencing the compiled policy. ### Create the credentials Secret @@ -202,45 +205,112 @@ EOF Replace `` with your NGINX One Console tenant hostname. The `namespace` field refers to the NGINX One Console namespace where the policy resides. -{{< call-out class="tip" >}} To pin a specific policy version, set `policyVersionID`. A pinned version always resolves to the same compiled bundle, so polling should be disabled to avoid unnecessary network requests. If you use only `policyName` or `policyObjectID` without a version pin, the latest compiled bundle is fetched on each reconciliation or poll cycle. {{< /call-out >}} +{{< call-out class="tip" title="Tip: Pin a policy version" >}} To pin a specific policy version, set `policyVersionID`. A pinned version always resolves to the same compiled bundle. Turn off polling to avoid unnecessary network requests. If you use only `policyName` or `policyObjectID` without a version pin, NGINX Gateway Fabric fetches the latest compiled bundle on each reconciliation or poll cycle. {{< /call-out >}} --- ## HTTP/HTTPS server -Use this option when you compile WAF policies using the F5 WAF compiler CLI or a CI/CD pipeline and host the resulting bundle on an HTTP/HTTPS server. For details on using the compiler, see [Build and use the compiler tool]({{< ref "/waf/configure/compiler.md" >}}). +Use this option when you compile F5 WAF policies using the F5 WAF compiler CLI or a CI/CD pipeline and host the resulting bundle on an HTTP/HTTPS server. For details on using the compiler, see [Build and use the compiler tool]({{< ref "/waf/configure/compiler.md" >}}). For a complete walkthrough including policy compilation and a bundle server deployment, see [Get started with F5 WAF for NGINX]({{< ref "/ngf/waf-integration/get-started-http.md" >}}). -For production environments, you would typically host compiled bundles on an HTTPS server with authentication. See [Configure WAF settings]({{< ref "/ngf/waf-integration/configuration.md" >}}) for details on adding credentials, custom CA certificates, and checksum verification to your `policySource`. +In production environments, host compiled bundles on an HTTPS server with authentication. See [Configure WAF settings]({{< ref "/ngf/waf-integration/configuration.md" >}}) for details on adding credentials, custom CA certificates, and checksum verification to your `policySource`. --- ## Policy Lifecycle Management (PLM) -Use this option when you manage WAF policies as Kubernetes resources with Policy Lifecycle Management (PLM). With PLM, you define your security posture as `APPolicy` and `APLogConf` custom resources instead of `policySource`/`logSource`; the PLM controller compiles them automatically and stores the resulting bundles in in-cluster storage. NGINX Gateway Fabric fetches those bundles and deploys them to the data plane. Because PLM is event-driven, no per-`WAFPolicy` credentials Secret or polling configuration is needed. +Use this option when you manage F5 WAF policies as Kubernetes resources with Policy Lifecycle Management (PLM). With PLM, you define your security posture as `APPolicy` and `APLogConf` custom resources instead of `policySource`/`logSource`. The PLM controller compiles these resources automatically and stores the resulting bundles in in-cluster storage. NGINX Gateway Fabric fetches those bundles and deploys them to the data plane. Because PLM is event-driven, you don't need a per-`WAFPolicy` credentials Secret or polling configuration. + +For a comparison of PLM with the other source types, see [PLM]({{< ref "/ngf/waf-integration/overview.md#plm-policy-lifecycle-management" >}}). For a complete walkthrough, including PLM storage setup, defining `APPolicy`/`APLogConf` resources, and applying a `WAFPolicy`, see [Get started with F5 WAF for NGINX using PLM]({{< ref "/ngf/waf-integration/get-started-plm.md" >}}). + +--- + +## Policy deployment visibility + +NGINX Instance Manager and NGINX One Console don't show which F5 WAF policies are deployed to NGINX Gateway Fabric. Neither console shows which compiled bundle version NGINX Gateway Fabric has fetched. -For a comparison of PLM with the other source types, see [PLM (Policy Lifecycle Management)]({{< ref "/ngf/waf-integration/overview.md#plm-policy-lifecycle-management" >}}). For a complete walkthrough (including PLM storage setup, defining `APPolicy`/`APLogConf` resources, and applying a `WAFPolicy`), see [Get started with F5 WAF for NGINX using PLM]({{< ref "/ngf/waf-integration/get-started-plm.md" >}}). +This is intentional. NGINX Gateway Fabric pulls compiled bundles from the management plane and deploys them directly in Kubernetes using native manifests, not through NGINX Instance Manager or NGINX One Console. This design lets you create and compile policies, then make them available to NGINX Gateway Fabric through the API, without a console-managed deployment step. + +F5 plans to add policy association visibility for NGINX Instance Manager and NGINX One Console in a future release. In the meantime, use `kubectl describe wafpolicy ` to check deployment status. --- -## Management console visibility +## Security event monitoring + +### NGINX Instance Manager + +#### Connect NGINX Gateway Fabric to F5 NGINX Instance Manager + +Configure NGINX Gateway Fabric to connect to NGINX Instance Manager before continuing. Follow [Connect NGINX Gateway Fabric to NGINX Instance Manager]({{< ref "/nim/connect-kubernetes/connect-ngf.md" >}}). + +#### Export security logs to F5 NGINX Instance Manager + +The Security Monitoring dashboard in NGINX Instance Manager doesn't show which F5 WAF policies are deployed to NGINX Gateway Fabric data planes. You can still export F5 WAF security events to NGINX Instance Manager. Exporting these events gives your security operations team visibility into blocked attacks, violations, and traffic patterns directly in the dashboard. + +{{< call-out class="important" title="Important: Version requirement" >}} +This integration requires NGINX Instance Manager 2.23 or later. +{{< /call-out >}} + +To export these events, configure a `securityLogs` entry on the `WAFPolicy` resource. The entry sends events to the syslog listener that NGINX Agent runs inside the NGINX pod. NGINX Agent's built-in OpenTelemetry collector transforms the events and exports them to NGINX Instance Manager. + +```yaml +kubectl apply -f - <}}). NGINX Gateway Fabric handles this authentication internally. No separate credential is required for log export. -When using NGINX Instance Manager or NGINX One Console as your policy source, be aware that neither management console currently displays WAF policy deployments to NGINX Gateway Fabric, nor does it show which compiled bundle versions NGINX Gateway Fabric has fetched. +{{< call-out class="note" title="Note: Network requirements" >}} +- Port `1514` (local syslog): NGINX Agent listens on this port inside the NGINX pod. This traffic doesn't leave the pod. +- Port `4317` (gRPC): NGINX Agent uses this port to export events to NGINX Instance Manager. Make sure this port is reachable from your cluster. +{{< /call-out >}} -This is by design: NGINX Gateway Fabric pulls compiled bundles from the management plane using a pull model and deploys them directly in Kubernetes using native Kubernetes manifests, rather than through the NGINX Instance Manager or NGINX One Console console. This workflow means policies can be created, compiled, and made available to NGINX Gateway Fabric through an API without requiring console-managed deployment flows. +{{< call-out class="tip" title="Tip: Testing with self-signed certificates" >}} +To test with self-signed certificates, add `insecureSkipVerify: true` to `policySource` and `logSource`. Don't use this setting in production. See [Configure WAF settings]({{< ref "/ngf/waf-integration/configuration.md" >}}) for adding CA certificates and credentials. +{{< /call-out >}} -Policy association visibility for NGINX Instance Manager and NGINX One Console will be added in a future release. In the meantime, use `kubectl describe wafpolicy ` to check deployment status. +### NGINX One Console -### Connect NGINX Gateway Fabric to F5 NGINX One Console +#### Connect NGINX Gateway Fabric to F5 NGINX One Console -Make sure NGINX Gateway Fabric is configured to connect to NGINX One Console. Follow the guidance at [Connect NGINX Gateway Fabric with Helm]({{< ref "/nginx-one-console/k8s/add-ngf-helm.md" >}}) or [Connect NGINX Gateway Fabric with Manifests]({{< ref "/nginx-one-console/k8s/add-ngf-manifests.md" >}}) before continuing. +Configure NGINX Gateway Fabric to connect to NGINX One Console before continuing. Follow [Connect NGINX Gateway Fabric with Helm]({{< ref "/nginx-one-console/k8s/add-ngf-helm.md" >}}) or [Connect NGINX Gateway Fabric with Manifests]({{< ref "/nginx-one-console/k8s/add-ngf-manifests.md" >}}). -### Export security logs to F5 NGINX One Console +#### Export security logs to F5 NGINX One Console -Although the NGINX One Console console does not display which policies are deployed to NGINX Gateway Fabric data planes, you can export WAF security events to the NGINX One Console security dashboard. This gives your security operations team visibility into blocked attacks, violations, and traffic patterns directly in the console. +NGINX One Console doesn't show which F5 WAF policies are deployed to NGINX Gateway Fabric data planes. You can still export F5 WAF security events to the NGINX One Console security dashboard. Your security operations team can then view blocked attacks, violations, and traffic patterns directly in the console. -To set this up, configure a `securityLogs` entry that sends events to the built-in OpenTelemetry collector in NGINX Agent, which forwards them to NGINX One Console. Use a log profile compiled for the NGINX One Console security dashboard: +To export these events, configure a `securityLogs` entry that sends events to NGINX Agent's built-in OpenTelemetry collector, which forwards them to NGINX One Console. Use a log profile compiled for the NGINX One Console security dashboard: ```yaml kubectl apply -f - <}} The `profileName: "secops_dashboard"` log profile must exist in your NGINX One Console namespace. This profile is required for events to appear correctly in the NGINX One Console security dashboard. {{< /call-out >}} +{{< call-out class="note" title="Note: Log profile must exist in NGINX One Console" >}} The `profileName: "secops_dashboard"` log profile must exist in your NGINX One Console namespace. Events don't appear correctly in the NGINX One Console security dashboard without this profile. {{< /call-out >}} --- @@ -291,4 +361,5 @@ The `localhost:1514` syslog destination points to the OpenTelemetry collector re - [Get started with F5 WAF for NGINX using PLM]({{< ref "/ngf/waf-integration/get-started-plm.md" >}}) - [Configure WAF settings]({{< ref "/ngf/waf-integration/configuration.md" >}}) - [Troubleshoot WAFPolicy status]({{< ref "/ngf/waf-integration/troubleshooting.md" >}}) -- [WAFPolicy and NginxProxy API reference]({{< ref "/ngf/reference/api.md" >}}) +- [Technical specifications]({{< ref "/ngf/overview/technical-specifications.md" >}}) +- [WAFPolicy and NginxProxy API reference]({{< ref "/ngf/reference/api.md" >}}) \ No newline at end of file diff --git a/content/ngf/waf-integration/troubleshooting.md b/content/ngf/waf-integration/troubleshooting.md index 6fe3f2e48..94125dd97 100644 --- a/content/ngf/waf-integration/troubleshooting.md +++ b/content/ngf/waf-integration/troubleshooting.md @@ -106,6 +106,29 @@ To resolve the conflict, choose one of the following approaches: --- +### Security events aren't reaching NGINX Instance Manager + +F5 WAF for NGINX generates security events, but they don't appear in the NGINX Instance Manager Security Monitoring dashboard, even though the `WAFPolicy` resource shows `Programmed`. + +**How to identify the problem:** + +Check whether the event reached NGINX Agent inside the pod: + +```shell +kubectl exec -n -c nginx -- \ + tail -100 /var/log/nginx-agent/opentelemetry-collector-agent.log +``` + +If the event isn't in this log, F5 WAF for NGINX isn't reaching NGINX Agent. If the event is in the log but not in NGINX Instance Manager, the export from NGINX Agent is failing. + +**Resolution:** + +- **Event missing from the NGINX Agent log:** Confirm the `WAFPolicy` `securityLogs.destination.syslog.server` field is set to exactly `localhost:1514`. Any other value prevents the event from reaching NGINX Agent, which listens on `127.0.0.1:1514` inside the `nginx` container. +- **Event in the log but export fails:** Check the log for `Unauthenticated` errors. A JWT authentication failure between NGINX Agent and NGINX Instance Manager causes this error. This is the same NGINX Plus subscription JWT used to create the NGINX Plus Secret in [Connect NGINX Gateway Fabric to NGINX Instance Manager]({{< ref "/nim/connect-kubernetes/connect-ngf.md" >}}). If the JWT has expired or was revoked, download a new one from [MyF5](https://my.f5.com/manage/s/) and repeat the steps to recreate the Secret. NGINX Gateway Fabric doesn't pick up a rotated Secret automatically. Restart the Gateway pod after recreating it. +- **Export succeeds but NGINX Instance Manager shows nothing:** Confirm NGINX Instance Manager's embedded OpenTelemetry collector is running and reachable on port `4317`. See [Troubleshooting]({{< ref "/nim/security-monitoring/troubleshooting.md" >}}) for the NGINX Instance Manager–side checks. + +--- + ## See also - [F5 WAF for NGINX overview]({{< ref "/ngf/waf-integration/overview.md" >}}) diff --git a/content/nim/connect-kubernetes/_index.md b/content/nim/connect-kubernetes/_index.md new file mode 100644 index 000000000..84120bace --- /dev/null +++ b/content/nim/connect-kubernetes/_index.md @@ -0,0 +1,11 @@ +--- +title: Connect Kubernetes deployments +weight: 85 +url: /nginx-instance-manager/connect-kubernetes/ +f5-product: NGINX Instance Manager +f5-content-type: landing-page +description: "Connect Kubernetes-based NGINX deployments, such as NGINX Gateway Fabric, to F5 NGINX Instance Manager." +f5-summary: > + Connect Kubernetes-based NGINX deployments to F5 NGINX Instance Manager. + This section covers connecting NGINX Gateway Fabric for usage and licensing reporting. +--- \ No newline at end of file diff --git a/content/nim/connect-kubernetes/connect-ngf.md b/content/nim/connect-kubernetes/connect-ngf.md new file mode 100644 index 000000000..2b3d81c95 --- /dev/null +++ b/content/nim/connect-kubernetes/connect-ngf.md @@ -0,0 +1,75 @@ +--- +title: Connect NGINX Gateway Fabric to NGINX Instance Manager +weight: 100 +toc: true +f5-content-type: how-to +f5-product: NGINX Instance Manager +f5-docs: +description: "Connect NGINX Gateway Fabric to F5 NGINX Instance Manager to export F5 WAF security events to the Security Dashboard." +f5-summary: > + Connect NGINX Gateway Fabric to F5 NGINX Instance Manager to export F5 WAF security events to the Security Dashboard. + This page covers the NGINX Plus JWT, the NGINX Plus Secret, and the Helm values required to configure the connection. +--- + +## Overview + +Connect NGINX Gateway Fabric to NGINX Instance Manager to export F5 WAF security events to the Security Dashboard. + +This connection supports security event export only. F5 WAF policy fetching uses a separate credential flow. See [Configure policy sources]({{< ref "/ngf/waf-integration/policy-sources.md" >}}). + +--- + +## Before you begin + +Before you begin, verify that you have: + +- Administrator access to a Kubernetes cluster +- Helm and kubectl installed locally +- An NGINX Plus subscription + +--- + +## Download your NGINX Plus JWT + +{{< include "/ngf/installation/nginx-plus/download-jwt.md" >}} + +--- + +## Create the NGINX Plus Secret + +{{< include "/ngf/installation/nginx-plus/nginx-plus-secret.md" >}} + +This Secret is required to run NGINX Plus, with or without F5 WAF for NGINX. It also authenticates the connection from NGINX Gateway Fabric to NGINX Instance Manager. + +--- + +## Install Gateway API resources + +{{< include "/ngf/installation/install-gateway-api-resources.md" >}} + +--- + +## Install NGINX Gateway Fabric + +This integration requires NGINX Plus with F5 WAF for NGINX. Install NGINX Gateway Fabric using the following Helm command: + +```shell +helm install ngf oci://ghcr.io/nginx/charts/nginx-gateway-fabric \ + --set nginx.image.repository=private-registry.nginx.com/nginx-gateway-fabric/nginx-plus \ + --set nginx.plus=true \ + --set nginx.config.waf.enable=true \ + --set nginx.imagePullSecret=nginx-plus-registry-secret \ + --set nginx.usage.secretName=nplus-license \ + --set nginx.nginxInstanceManager.endpointHost= \ + -n nginx-gateway +``` + +Replace `` with your NGINX Instance Manager hostname. + +--- + +## See also + +- [Deploy a Gateway for data plane instances]({{< ref "/ngf/install/deploy-data-plane.md" >}}) +- [Configure policy sources]({{< ref "/ngf/waf-integration/policy-sources.md" >}}) +- [View NGINX Gateway Fabric security events]({{< ref "/nim/security-monitoring/ngf-security-events.md" >}}) \ No newline at end of file diff --git a/content/nim/fundamentals/tech-specs.md b/content/nim/fundamentals/tech-specs.md index 0172c4861..1c29b5a68 100644 --- a/content/nim/fundamentals/tech-specs.md +++ b/content/nim/fundamentals/tech-specs.md @@ -1,11 +1,11 @@ --- f5-docs: DOCS-805 -title: Technical Specifications +title: Technical specifications toc: true weight: 20 f5-content-type: reference f5-product: NGINX Instance Manager -description: "Technical specifications for F5 NGINX Instance Manager, including supported operating systems, Kubernetes distributions, NGINX versions, browsers, and hardware requirements." +description: "Technical specifications for F5 NGINX Instance Manager. Covers supported operating systems, Kubernetes distributions, NGINX versions, browsers, and hardware requirements." f5-summary: > Check the technical specifications for F5 NGINX Instance Manager before you install it. This reference lists supported operating systems, Kubernetes distributions, NGINX versions, browsers, and hardware requirements. @@ -13,7 +13,9 @@ f5-summary: > ## Overview -F5 NGINX Instance Manager provides centralized management for NGINX Open Source and NGINX Plus instances across various environments, including bare metal, containers, public clouds (AWS, Azure, Google Cloud), and virtual machines. It supports several Linux distributions, including Amazon Linux, CentOS, Debian, RHEL, and Ubuntu. This guide outlines the technical specifications, minimum requirements, and supported platforms for deploying NGINX Instance Manager, ensuring optimal performance in both small and large environments. +F5 NGINX Instance Manager provides centralized management for NGINX Open Source and NGINX Plus instances. Supported environments are bare metal, containers, public clouds, and virtual machines. Supported public clouds are AWS, Microsoft Azure, and Google Cloud Platform. NGINX Instance Manager supports several Linux distributions: Amazon Linux, CentOS, Debian, RHEL, and Ubuntu. + +This guide outlines the technical specifications, minimum requirements, and supported platforms for NGINX Instance Manager deployments. These specifications help you achieve optimal performance in small and large environments. ## Supported deployment environments {#supported-environments} @@ -24,17 +26,17 @@ You can deploy NGINX Instance Manager in the following environments: - **Public cloud**: AWS, Google Cloud Platform, Microsoft Azure - **Virtual machine** -## Supported Linux Distributions {#supported-distributions} +## Supported Linux distributions {#supported-distributions} {{< include "nim/tech-specs/supported-distros.md" >}} ## Supported NGINX Instance Manager versions {#supported-nginx-instance-manager-versions} -We recommend using the latest version of NGINX Instance Manager to take advantage of the newest features, improvements, and security fixes. +F5 recommends the latest version of NGINX Instance Manager. It includes the newest features, improvements, and security fixes. [Technical support](https://www.f5.com/support) is available for the current release and for any version released within two years of the current version's release date. -Use the table below to check the end-of-support (EoS) dates for recent versions. +The following table shows end-of-support (EoS) dates for recent versions. | NGINX Instance Manager | End of Support (EoS) | |------------------------|----------------------| @@ -48,19 +50,19 @@ Use the table below to check the end-of-support (EoS) dates for recent versions. | 2.16.x | April 18, 2026 | | 2.15.x | December 12, 2025 | -## Supported NGINX Versions {#nginx-versions} +## Supported NGINX versions {#nginx-versions} {{< include "nim/tech-specs/supported-nginx-versions.md" >}} -## Sizing recommendations for Managing NGINX Instances {#system-sizing} +## Sizing recommendations for managing NGINX instances {#system-sizing} -The following recommendations provide the minimum guidelines for NGINX Instance Manager. These guidelines ensure adequate performance, but for optimal results, we strongly recommend using solid-state drives (SSDs) for storage. If you set up [deployments with F5 WAF for NGINX](#system-sizing-app-protect), you may need additional memory and CPU. +The following recommendations are minimum guidelines for NGINX Instance Manager. For optimal results, F5 recommends solid-state drives (SSDs) for storage. If you set up [deployments with F5 WAF for NGINX](#system-sizing-app-protect), you may need additional memory and CPU. ### Standard NGINX configuration deployments -This section outlines the recommendations for NGINX Instance Manager deployments with data plane instances using standard configurations, without F5 WAF for NGINX. **Standard configurations** typically support up to **40 upstream servers** with associated location and server blocks, and up to **350 certificates**. This is ideal for medium-sized environments or applications with moderate traffic. +This section outlines recommendations for NGINX Instance Manager deployments with data plane instances that use standard configurations, without F5 WAF for NGINX. Standard configurations typically support up to 40 upstream servers with associated location and server blocks, and up to 350 certificates. This fits medium-sized environments or applications with moderate traffic. -We recommend using SSDs to enhance storage performance. +F5 recommends SSDs to improve storage performance. {{}} | Number of Data Plane Instances | CPU | Memory | Network | Storage | @@ -70,11 +72,11 @@ We recommend using SSDs to enhance storage performance. | 1000 | 4 vCPU | 8 GB RAM | 1 GbE NIC | 3 TB | {{
}} -These values represent the minimum resources needed for deployments that fall under standard configurations. +These values are the minimum resources for deployments under standard configurations. ### Large NGINX configuration deployments -For environments requiring more resources, **large configurations** are suitable. These configurations can support up to **300 upstream servers** and are designed for enterprise environments or applications handling high traffic and complex configurations, without F5 WAF for NGINX. +For environments that need more resources, large configurations are suitable. These configurations can support up to 300 upstream servers. They're designed for enterprise environments or applications that handle high traffic and complex configurations, without F5 WAF for NGINX. {{}} | Number of Data Plane Instances | CPU | Memory | Network | Storage | @@ -85,107 +87,127 @@ For environments requiring more resources, **large configurations** are suitable ### NGINX configuration deployments with F5 WAF for NGINX {#system-sizing-app-protect} -If using F5 WAF for NGINX features in NGINX Instance Manager, this requires additional CPU and Memory for policy compilation and security monitoring features. At a minimum, 8gb Memory and 4 CPUs are required for a standard F5 WAF for NGINX use case (under 20 NGINX Plus instances). The requirements are heavily dependent on the number of policies being managed, the frequency of updates and the number of events being that occur in the security monitoring feature. +If you use F5 WAF for NGINX features in NGINX Instance Manager, you need additional CPU and memory for policy compilation and security monitoring. A standard F5 WAF for NGINX use case (under 20 NGINX Plus instances) requires a minimum of 8 GB of memory and 4 CPUs. + +Requirements depend on the number of policies you manage, how often you update them, and how many events occur in the security monitoring feature. ### Lightweight mode {#lightweight-mode} -(New in 2.20.0) You can run NGINX Instance Manager without installing ClickHouse. This setup is useful if you don’t need monitoring data or prefer a simpler deployment. It reduces system requirements and removes the need to manage a metrics database. You can add ClickHouse later if your needs change. For instructions, see [Disable metrics collection]({{< ref "nim/system-configuration/configure-clickhouse.md#disable-metrics-collection" >}}). +(New in 2.20.0) You can run NGINX Instance Manager without ClickHouse. If you don't need monitoring data or want a simpler deployment, use this setup. It reduces system requirements and removes the need to manage a metrics database. If your needs change, you can add ClickHouse later. For instructions, see [Disable metrics collection]({{< ref "nim/system-configuration/configure-clickhouse.md#disable-metrics-collection" >}}). + +F5 tested Lightweight mode with ten managed NGINX instances and configuration publishing. Without F5 WAF for NGINX, it ran with as little as 1 CPU core and 1 GB of memory. With F5 WAF for NGINX enabled, NGINX Instance Manager needed 2 CPU cores and 4 GB of memory to compile policies. -In Lightweight mode, we tested NGINX Instance Manager with ten managed NGINX instances and configuration publishing. It ran with as little as 1 CPU core and 1 GB of memory (without App Protect). When App Protect was enabled, we needed 2 CPU cores and 4 GB of memory to compile policies. +These figures reflect the minimum tested configuration. If you experience performance issues, allocate more system resources. -These figures are guidelines only. They reflect the minimum tested configuration and may cause performance issues depending on your setup. For better performance, consider allocating more system resources. +{{< call-out class="note" title="Note: Raw usage record storage" >}} +These figures don't include storage or memory for raw usage records. If your NGINX Plus instances report usage data, see [Configure the retention window]({{< ref "nim/licensing-and-reporting/view-recent-usage.md#configure-the-retention-window" >}}) for sizing guidance based on your instance count and retention period. +{{< /call-out >}} ### License and usage reporting only {#reporting-sizing} -This section applies when you’ve set up NGINX Instance Manager to handle licensing and usage reporting only. In this setup, NGINX instances report license and usage data in an "unmanaged" way. Each instance sends periodic updates to NGINX Instance Manager for counting purposes only. +This section applies when you use NGINX Instance Manager only for licensing and usage reporting. In this setup, NGINX instances report license and usage data in an "unmanaged" way. Each instance sends periodic updates to NGINX Instance Manager for counting purposes only. For details on how to configure this setup, see [Prepare your environment for reporting]({{< ref "/solutions/about-subscription-licenses.md#set-up-environment" >}}). -When used only for licensing and usage reporting, NGINX Instance Manager has minimal system requirements. We recommend using [Lightweight mode](#lightweight-mode) in this case to avoid the ClickHouse dependency, especially if you don’t plan to use other features. +If you use NGINX Instance Manager only for licensing and usage reporting, it needs minimal CPU and network resources. Regardless of fleet size, this means 2 vCPU and a 1 GbE NIC. F5 recommends [Lightweight mode](#lightweight-mode) for this case, to avoid the ClickHouse dependency, especially if you don't plan to use other features. + +Memory and storage depend on your instance count and the retention period you configure for raw usage records, from 0 to 365 days (120-day default). The following table shows estimates at the default 120-day retention and the maximum 365-day (1-year) retention. These figures assume NGINX Plus's default cadence of one usage report per instance per hour. {{
}} -| Number of Data Plane Instances | CPU | Memory | Network | Storage | -|--------------------------------|--------|----------|-----------|---------| -| n/a | 2 vCPU | 4 GB RAM | 1 GbE NIC | 20 GB | +| Instances | 120-day storage | 120-day working memory | 1-year storage | 1-year working memory | +|-----------|------------------|--------------------------|------------------|--------------------------| +| 50 | ~0.13 GB | ~2.4 GB | ~0.4 GB | ~2.9 GB | +| 100 | ~0.26 GB | ~2.6 GB | ~0.8 GB | ~3.5 GB | +| 500 | ~1.3 GB | ~4.2 GB | ~4.0 GB | ~8.3 GB | +| 800 | ~2.1 GB | ~5.4 GB | ~6.3 GB | ~11.7 GB | +| 1,000 | ~2.6 GB | ~6.2 GB | ~7.9 GB | ~14.1 GB | {{
}} +{{< call-out class="note" title="Note: Tested range" >}} +NGINX Instance Manager's scale testing for 1-year retention covered up to 800 instances. The 1,000-instance figures in this table extrapolate beyond that tested point. +{{< /call-out >}} + +For retention periods between 120 days and 1 year, memory and storage scale roughly linearly with the number of days you configure. See [Estimate storage for extended retention]({{< ref "nim/licensing-and-reporting/view-recent-usage.md#estimate-storage-for-extended-retention" >}}) for host-sizing guidance and the per-record storage model behind these figures. + ### Sizing benchmarks for storage -The following benchmarks focus on **disk storage** requirements for NGINX Instance Manager. Storage needs depend on the **number of instances** and **data retention periods** (in days). The benchmarks are divided into three configuration sizes: +The following benchmarks focus on disk storage requirements for NGINX Instance Manager. Storage needs depend on the number of instances and data retention periods (in days). These benchmarks group into three configuration sizes: -- **Small configuration**: Typically supports about **15 servers**, **50 locations**, and **30 upstreams/backends**. Each instance generates **3,439 metrics per minute**. -- **Medium configuration**: Usually includes about **50 servers**, **200 locations**, and **200 upstreams/backends**. Each instance generates **16,766 metrics per minute**. -- **Generic Large configuration**: Handles up to **100 servers**, **1,000 locations**, and **900 upstreams/backends**. In **NGINX Plus**, each instance generates **59,484 metrics per minute**. +- **Small configuration**: Supports about 15 servers, 50 locations, and 30 upstreams or backends. Each instance generates 3,439 metrics per minute. +- **Medium configuration**: Includes about 50 servers, 200 locations, and 200 upstreams or backends. Each instance generates 16,766 metrics per minute. +- **Generic large configuration**: Handles up to 100 servers, 1,000 locations, and 900 upstreams or backends. In NGINX Plus, each instance generates 59,484 metrics per minute. #### Storage requirements for NGINX Plus -The table below provides storage estimates for **NGINX Plus** based on configuration size, number of instances, and a 14-day data retention period. Larger configurations and longer retention periods will require proportionally more storage. +The following table provides storage estimates for NGINX Plus, based on configuration size, instance count, and a 14-day data retention period. Larger configurations and longer retention periods will require proportionally more storage. {{}} -| Config Size | Instances | Retention (days) | Estimated Disk Usage (NGINX Plus) | -|------------------------|-----------|------------------|-----------------------------------| -| **Small Size** | 10 | 14 | 5 GiB | -| | 50 | 14 | 25 GiB | -| | 100 | 14 | 45 GiB | -| | 1000 | 14 | 450 GiB | -| **Medium Size** | 10 | 14 | 25 GiB | -| | 50 | 14 | 126 GiB | -| | 100 | 14 | 251 GiB | -| | 500 | 14 | 1.157 TiB | -| **Generic Large Size** | 10 | 14 | 100 GiB | -| | 50 | 14 | 426 GiB | -| | 100 | 14 | 850 GiB | -| | 250 | 14 | 2 TiB | +| Config size | Instances | Retention (days) | Estimated disk usage (NGINX Plus) | +|------------------------|-----------|-------------------|------------------------------------| +| **Small size** | 10 | 14 | 5 GiB | +| | 50 | 14 | 25 GiB | +| | 100 | 14 | 45 GiB | +| | 1000 | 14 | 450 GiB | +| **Medium size** | 10 | 14 | 25 GiB | +| | 50 | 14 | 126 GiB | +| | 100 | 14 | 251 GiB | +| | 500 | 14 | 1.157 TiB | +| **Generic large size** | 10 | 14 | 100 GiB | +| | 50 | 14 | 426 GiB | +| | 100 | 14 | 850 GiB | +| | 250 | 14 | 2 TiB | {{
}} -{{< call-out class="note" title="Note" >}}MiB (mebibyte), GiB (gibibyte), and TiB (tebibyte) are units of data storage. MiB equals 1,024^2 (2^20) bytes, GiB equals 1,024^3 (2^30) bytes, and TiB equals 1,024^4 (2^40) bytes. These are often used in computing to represent binary data storage capacities, as opposed to MB (megabyte), GB (gigabyte), and TB (terabyte), which use decimal units.{{< /call-out >}} +{{< call-out class="note" title="Note" >}} +MiB (mebibyte), GiB (gibibyte), and TiB (tebibyte) measure data storage in binary units: MiB equals 1,024² (2²⁰) bytes, GiB equals 1,024³ (2³⁰) bytes, and TiB equals 1,024⁴ (2⁴⁰) bytes. MB (megabyte), GB (gigabyte), and TB (terabyte) measure storage in decimal units instead. +{{< /call-out >}} -#### Storage requirements for NGINX OSS +#### Storage requirements for NGINX Open Source -**NGINX OSS** collects fewer metrics per instance compared to NGINX Plus. This is because NGINX OSS lacks the advanced features of NGINX Plus, such as the NGINX Plus API, which limits the amount of operational data collected and stored. For example, in the **Generic Large configuration**, NGINX OSS generates only **167 metrics per minute per instance**, compared to **59,484 metrics per minute** in NGINX Plus. +NGINX Open Source collects fewer metrics per instance than NGINX Plus. This is because NGINX Open Source lacks advanced features such as the NGINX Plus API, which limits the operational data it collects and stores. For example, in the generic large configuration, NGINX Open Source generates only 167 metrics per minute per instance, compared to 59,484 metrics per minute in NGINX Plus. -The table below shows the estimated storage requirements for **NGINX OSS**, based on the number of instances and a 14-day retention period. +The following table shows estimated storage requirements for NGINX Open Source, based on instance count and a 14-day retention period. {{}} -| Config Size | Instances | Retention (days) | Estimated Disk Usage (NGINX OSS) | -|------------------------|-----------|------------------|----------------------------------| -| **Generic Large Size** | 10 | 14 | 200 MiB | -| | 50 | 14 | 850 MiB | -| | 100 | 14 | 1.75 GiB | -| | 250 | 14 | 4 GiB | +| Config size | Instances | Retention (days) | Estimated disk usage (NGINX Open Source) | +|------------------------|-----------|-------------------|--------------------------------------------| +| **Generic large size** | 10 | 14 | 200 MiB | +| | 50 | 14 | 850 MiB | +| | 100 | 14 | 1.75 GiB | +| | 250 | 14 | 4 GiB | {{
}} -## Directory Requirements for NGINX Instance Manager +## Directory requirements for NGINX Instance Manager -Below are the directory requirements and storage recommendations for fresh, minimal, and moderate usage (<100 instances) of NGINX Instance Manager (NIM). +The following directory requirements and storage recommendations apply to fresh, minimal, and moderate NGINX Instance Manager deployments (under 100 instances). {{< call-out class="important" >}} -These recommendations apply if you are using NGINX Agent to connect NGINX instances to NIM for full management capabilities, including: +These recommendations apply if you use NGINX Agent to connect NGINX instances to NGINX Instance Manager for full management capabilities: -- Managing configurations -- Viewing metrics -- Applying WAF policies -- Managing certificates +- Manage configurations +- View metrics +- Apply F5 WAF for NGINX policies +- Manage certificates -If you're concerned solely on usage reporting, you do not need NGINX Agent. Required resources needed are significantly reduced. For usage reporting-only deployments, NIM receives and stores usage data sent directly from the instances. +If you're interested only in usage reporting, you don't need NGINX Agent. Usage reporting needs significantly fewer resources. For usage-reporting-only deployments, NGINX Instance Manager receives and stores usage data sent directly from the instances. {{< /call-out >}} {{}} -| Directory path | Content | Recommendation | -|------------------------|-------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| /usr/bin | Stores NIM binaries | 500MB | -| /var/lib/nms/dqlite | Stores DQLite database data | 2GiB without F5 WAF for NGINX; 5GiB with F5 WAF for NGINX enabled and large compiled bundles | -| /var/lib/nms/streaming | Stores NATS streaming messages | 500MiB | -| /var/lib/nms/secrets | Stores secrets for LLM license handshakes | 10MiB | -| /var/lib/nms/modules | Stores static content like manager.json | 100KiB (12KiB minimum) | -| /var/lib/clickhouse | Stores ClickHouse metrics data | recommend 2.5GB per instance (25GB for 10 instances, 250GB for 100 instances). This is only required if ClickHouse metrics are enabled | -| /var/log/nms | Stores logs for NIM with rotation enabled | recommended 50MiB per week if archived once a month | -| /etc/nms/ | Stores NIM configuration files | 50MiB | -| /etc/nginx | Stores NGINX configuration files | typical size is 10MiB-50MiB | +| Directory path | Content | Recommendation | +|------------------------|---------------------------------------------|-----------------------------------------------------------------------------------------------| +| /usr/bin | Stores NGINX Instance Manager binaries | 500 MB | +| /var/lib/nms/dqlite | Stores DQLite database data | 2 GiB without F5 WAF for NGINX. 5 GiB with F5 WAF for NGINX enabled and large compiled bundles. | +| /var/lib/nms/streaming | Stores NATS streaming messages | 500 MiB | +| /var/lib/nms/secrets | Stores secrets for LLM (Local License Manager) license handshakes | 10 MiB | +| /var/lib/nms/modules | Stores static content like manager.json | 100 KiB (12 KiB minimum) | +| /var/lib/clickhouse | Stores ClickHouse metrics data | Recommended: 2.5 GB per instance (25 GB for 10 instances, 250 GB for 100 instances). This applies only if you enable ClickHouse metrics. | +| /var/log/nms | Stores NGINX Instance Manager logs with rotation enabled | Recommended: 50 MiB per week if you archive logs once a month. | +| /etc/nms/ | Stores NGINX Instance Manager configuration files | 50 MiB | +| /etc/nginx | Stores NGINX configuration files | Typical size is 10-50 MiB. | {{
}} ## ClickHouse tuning {#clickhouse-tuning} @@ -196,13 +218,13 @@ The default ClickHouse configuration works efficiently with NGINX Instance Manag NGINX Instance Manager and NGINX Agent use the Unix domain socket by default and proxy through the gateway on port `443`. -To ensure smooth communication, make sure port 443 is open on any firewalls between NGINX Instance Manager, NGINX Agent, and other systems they need to communicate with. This allows secure HTTPS traffic to pass through. +Make sure port 443 is open on any firewalls between NGINX Instance Manager, NGINX Agent, and the systems they communicate with. Port 443 carries secure HTTPS traffic between these systems. ## Logging {#logging} -NGINX Instance Manager stores its log files in `/var/log/nms`. To prevent your system from running out of disk space as logs grow, we recommend either creating a separate partition for logs or enabling [log rotation](http://nginx.org/en/docs/control.html#logs). +NGINX Instance Manager stores its log files in `/var/log/nms`. As logs grow, your system can run out of disk space. To prevent this, create a separate log partition, or enable [log rotation](http://nginx.org/en/docs/control.html#logs). -## Supported Browsers {#supported-browsers} +## Supported browsers {#supported-browsers} The NGINX Instance Manager web interface works best on the latest versions of these browsers: @@ -219,4 +241,4 @@ The NGINX Instance Manager web interface works best on the latest versions of th ### Data plane requirements -- **Supported distributions**: The NGINX Agent can run on most environments. For the supported distributions, see the [NGINX Agent Technical Specs](https://docs.nginx.com/nginx-agent/technical-specifications/) guide. +- **Supported distributions**: NGINX Agent can run on most environments. For the supported distributions, see the [NGINX Agent technical specifications](https://docs.nginx.com/nginx-agent/technical-specifications/) guide. \ No newline at end of file diff --git a/content/nim/licensing-and-reporting/view-recent-usage.md b/content/nim/licensing-and-reporting/view-recent-usage.md new file mode 100644 index 000000000..3180ef2e5 --- /dev/null +++ b/content/nim/licensing-and-reporting/view-recent-usage.md @@ -0,0 +1,329 @@ +--- +title: View recent NGINX usage +description: "View raw, per-record NGINX usage telemetry in NGINX Instance Manager to verify billing data and support compliance audits." +weight: 350 +toc: true +f5-docs: +f5-personas: +- devops +- netops +- secops +- support +f5-content-type: how-to +f5-product: NGINX Instance Manager +f5-summary: > + View and export raw, unaggregated NGINX usage telemetry for NGINX Plus, NGINX Ingress Controller, and NGINX Gateway Fabric instances in NGINX Instance Manager. + Use this audit-grade record view to independently verify billing data and support compliance reviews, separately from the usage reports NGINX Instance Manager sends to F5. +--- + +## Overview + +The **Usage Overview** page shows the raw usage telemetry that F5 NGINX Instance Manager collects from your instances. This includes F5 NGINX Plus, F5 NGINX Ingress Controller, and F5 NGINX Gateway Fabric. NGINX Open Source instances don't appear in usage records. They don't include the `ngx_mgmt_module` that NGINX Plus uses to report usage. + +Each row is one telemetry record, exactly as your instance reported it. NGINX Instance Manager doesn't aggregate or transform records. Use this page to independently verify the data behind your F5 billing and to support compliance audits. + +NGINX Agent isn't required. Your instances send usage data directly to NGINX Instance Manager. + +### Instances and Clusters tabs + +The page has two tabs: + +- **Instances**: Shows records from standalone NGINX Plus instances that run on VMs or bare metal. +- **Clusters**: Shows records from NGINX deployments that run in Kubernetes. This includes records from NGINX Ingress Controller and NGINX Gateway Fabric. + +By default, the page shows the last 7 days of records, sorted by end time with the most recent first. NGINX Instance Manager keeps records for the last 120 days by default. You can change this retention period. See [Configure the retention window](#configure-the-retention-window). + +--- + +## Before you begin + +Before you view usage records, make sure you have: + +- **NGINX Plus R33 or later**: NGINX Plus R33 and later include the `ngx_mgmt_module` module. Earlier versions can't report usage to NGINX Instance Manager. +- **NGINX Plus configured to report usage**: Each NGINX Plus instance needs the `usage_report` directive set to your NGINX Instance Manager host. See [Configure NGINX Plus to report usage to NGINX Instance Manager]({{< ref "nim/licensing-and-reporting/report-usage-connected-deployment.md#configure-nginx-plus-to-report-usage-to-nginx-instance-manager" >}}). +- **The NGINX Plus Usage permission**: Your user account needs this role-based access control (RBAC) permission to view usage records in the dashboard or through the API. + +--- + +## View and filter usage records + +### View records in the dashboard + +To view raw usage records: + +1. Log in to NGINX Instance Manager (`https:///ui/`). +2. In the left navigation, select **Usage > Usage Overview**. +3. Select the **Instances** or **Clusters** tab. + +By default, the dashboard shows records from the last 7 days, sorted by end time with the most recent first. + +{{< call-out class="note" title="Note: Fields not shown in the table" >}} +The dashboard's summary table doesn't show every field from a usage record. For example, it doesn't show the reporting start time. Select a row to view the full record and see every field. +{{< /call-out >}} + +### View record details + +Select a row to open a side panel that shows all fields for that record. + +### Filter records + +Select **Add Filter** to narrow your results by: + +{{}} +| Filter | Description | +|---|---| +| Date range | Filters by reporting end time. Defaults to the last 7 days. Maximum range is 365 days. | +| NGINX Instance ID | Filters by a specific NGINX instance UUID. | +| Cluster ID | Filters by a Kubernetes cluster UUID. Available on the **Clusters** tab only. | +| Product type | Filters by product: NGINX Plus, NGINX Ingress Controller, NGINX Gateway Fabric, or Unspecified. Select multiple types. | +| Subscription token | Filters by JWT token ID (`jti`). | +{{
}} + +#### Find filter values + +If you don't already have the identifiers used in these filters: + +- **NGINX Instance ID**: NGINX Plus stores this in `/var/lib/nginx/nginx.id` on each instance. You can also find it in the **NGINX UID** column or in the detail panel. +- **Cluster ID**: Visible in the **K8s Cluster ID** column on the Clusters tab. NGINX Ingress Controller and NGINX Gateway Fabric generate this ID at installation and store it in the deployment's Kubernetes secret. +- **Subscription token (jti)**: A claim inside your subscription JWT (`license.jwt`). Paste the JWT contents into [jwt.io](https://jwt.io) and look for the `jti` field. You can also find it in the **JWT ID** column. + +### Export usage records to a file + +To export usage records for an offline review or compliance check: + +1. Apply the filters you need. +2. Select **Export CSV**. + +The exported file downloads in CSV (comma-separated values) format. It includes all records matching your current filters, with no rounding or aggregation. + +If the export is slow, apply additional filters to narrow the result set before you export. + +The following table lists which columns appear in each tab's CSV export. + +{{}} +| Field | Instances tab | Clusters tab | +|---|---|---| +| `nginx_uid` | Yes | Yes | +| `product_type` | Yes | Yes | +| `nginx_version` | Yes | Yes | +| `start_time` | Yes | Yes | +| `end_time` | Yes | Yes | +| `nap` | Yes | Yes | +| `jwt_token_id` | Yes | Yes | +| `jwt_expiration` | Yes | Yes | +| `jwt_order_type` | Yes | Yes | +| `workers` | Yes | Yes | +| `user_agent` | Yes | Yes | +| `uptime` | Yes | Yes | +| `reloads` | Yes | Yes | +| `installation_id` | No | Yes | +| `cluster_id` | No | Yes | +| `cluster_node_count` | No | Yes | +{{
}} + +{{< call-out class="note" title="Note: If your export is truncated" >}} +See [An exported file is truncated](#an-exported-file-is-truncated). +{{< /call-out >}} + +--- + +## Configure the retention window + +NGINX Instance Manager automatically removes usage records older than the configured retention period. A background job runs once at startup and then every 24 hours to purge expired records. + +{{}} +| Setting | Value | +|---|---| +| Default retention | 120 days | +| Allowed range | 0–365 days | +| Configuration key | `nginx_raw_usage_retention_days` (under `dpm:`) | +{{
}} + +To change the retention period: + +1. Open `/etc/nms/nms.conf` on the NGINX Instance Manager server. +2. Add or update the setting under the `dpm:` block: + + ```yaml + dpm: + nginx_raw_usage_retention_days: 180 + ``` + +3. Restart NGINX Instance Manager: + + ```shell + sudo systemctl restart nms + ``` + +A retention change takes effect after this restart. Because the purge job runs immediately on startup, it removes records outside the new window right away, not on the next scheduled 24-hour cycle. + +{{< call-out class="important" title="Important: Retention value limits" >}} +NGINX Instance Manager normalizes retention values on startup. It caps any value above 365 to 365. It ignores negative values and uses the default (120 days) instead. A value of 0 blocks local storage: NGINX Instance Manager doesn't write new records and purges existing records on the next run. This doesn't affect usage reporting to F5. +{{< /call-out >}} + +If NGINX Instance Manager clamps or rejects your configured value, it logs a `[RAW-USAGE]` warning so you know the configured value wasn't applied. + +### Estimate storage for extended retention + +Storage and memory scale with your instance count and configured retention period. Each usage record takes about 0.9 KB on disk. This estimate includes the database index. + +The following table shows estimated storage and working memory at two retention periods: the default 120 days, and the maximum 365 days (1 year). These figures assume the default NGINX Plus reporting cadence of one report per instance per hour. + +{{}} +| Instances | 120-day storage | 120-day working memory | 1-year storage | 1-year working memory | +|---|---|---|---|---| +| 50 | ~0.13 GB | ~2.4 GB | ~0.4 GB | ~2.9 GB | +| 100 | ~0.26 GB | ~2.6 GB | ~0.8 GB | ~3.5 GB | +| 500 | ~1.3 GB | ~4.2 GB | ~4.0 GB | ~8.3 GB | +| 800 | ~2.1 GB | ~5.4 GB | ~6.3 GB | ~11.7 GB | +| 1,000 | ~2.6 GB | ~6.2 GB | ~7.9 GB | ~14.1 GB | +{{
}} + +{{< call-out class="note" title="Note: Tested range" >}} +NGINX Instance Manager's scale testing for 1-year retention covered up to 800 instances. The 1,000-instance figures in this table extrapolate beyond that tested point. +{{< /call-out >}} + +For retention periods between 120 days and 1 year, storage and working memory scale roughly linearly with the number of days you configure. If you halve your retention period, you roughly halve both storage and memory. + +To size a host: + +- **Memory**: Provision enough RAM to cover the working memory estimate for your fleet size and retention period. Size by RAM, not by a specific vendor instance type. +- **Disk**: Budget headroom beyond the storage estimate for database indexes, snapshots, write-ahead logs, and NGINX Instance Manager's other services. For large fleets at extended retention, budget tens of GB of SSD storage. +- **Alternative to over-provisioning**: Lower `nginx_raw_usage_retention_days` rather than add more host resources. If you reduce retention, you shrink stored data and memory use proportionally. This doesn't affect usage reporting to F5. + +This sizing applies even in Lightweight mode. NGINX Instance Manager stores usage records independently of ClickHouse. As a result, instance count and retention affect your storage needs, even in deployments used only for licensing and usage reporting. + +--- + +## Validate a record from the command line + +Use the REST API to retrieve usage records and confirm the identifiers in a specific record. All endpoints are available at `/api/platform/v1/usage-records`. + +### Retrieve records for a specific instance or cluster + +Query by `nginxUid` to retrieve every record for a specific NGINX Plus instance: + +```shell +curl -k -u : \ + "https:///api/platform/v1/usage-records?deploymentType=vm&nginxUid=" +``` + +Query by `clusterId` to retrieve every record for a specific Kubernetes cluster: + +```shell +curl -k -u : \ + "https:///api/platform/v1/usage-records?deploymentType=cluster&clusterId=" +``` + +### What each identifier means + +{{}} +| Field | Description | Where it comes from | Applies to | +|---|---|---|---| +| `nginx_uid` | UUID that uniquely identifies the NGINX Plus instance. | Generated by NGINX Plus. | All records | +| `product_type` | Integration type: `NGINX_PLUS`, `NIC`, `NGF`, or `UNSPECIFIED`. | Reported by the instance. | All records | +| `jwt_token_id` | The `jti` claim of the F5 subscription token the instance uses for reporting. | Derived from the F5 subscription token. | Records with subscription metadata | +| `jwt_expiration` | Subscription end date from the F5 subscription token. | Derived from the F5 subscription token. | Records with subscription metadata | +| `cluster_id` | UUID of the Kubernetes cluster where the instance runs. | Provided by NGINX Ingress Controller or NGINX Gateway Fabric. | Kubernetes records | +| `installation_id` | UUID identifying an individual NGINX Ingress Controller or NGINX Gateway Fabric installation. | Provided by NGINX Ingress Controller or NGINX Gateway Fabric. | Kubernetes records | +| `cluster_node_count` | Number of nodes in the Kubernetes cluster. | Provided by NGINX Ingress Controller or NGINX Gateway Fabric. | Kubernetes records | +{{
}} + +NGINX Instance Manager stores and displays these values exactly as your instances report them. It doesn't generate or modify them. + +{{< call-out class="note" title="Note: To confirm an identifier on a running instance" >}} +This page shows you how to view identifiers as NGINX Instance Manager received them. To independently confirm a value like Cluster ID directly on a running Kubernetes deployment, see the NGINX Ingress Controller or NGINX Gateway Fabric documentation for that identifier. +{{< /call-out >}} + +--- + +## What's shown + +{{}} +| Field | Description | +|---|---| +| NGINX Instance ID | UUID that identifies the NGINX instance. | +| Product type | NGINX Plus, NGINX Ingress Controller, NGINX Gateway Fabric, or Unspecified. | +| NGINX version | The NGINX version string, for example `1.29.8`. | +| Reporting window | Start and end timestamps of the reporting period. | +| F5 WAF status | Whether F5 WAF for NGINX is active or inactive. | +| Subscription token | JWT token ID (`jti`) and expiration date. | +| Workers | Number of active NGINX worker processes. | +| Uptime | Seconds since the last NGINX restart. | +| Reloads | Number of configuration reloads during the reporting period. | +| Cluster ID | Kubernetes cluster identifier. Kubernetes deployments only. | +| Cluster node count | Number of nodes in the Kubernetes cluster. Kubernetes deployments only. | +{{
}} + +{{< call-out class="note" title="Note: No personally identifiable information" >}} +Usage records contain only UUIDs, timestamps, and numeric counters. They don't include hostnames, IP addresses, or other personally identifiable information. +{{< /call-out >}} + +--- + +## How this differs from usage reporting to F5 + +The **Usage Overview** page is a local, on-demand audit view. It's different from the usage reports NGINX Instance Manager automatically sends to F5 for billing. + +{{}} +| | **Usage Overview** page | Usage reporting to F5 | +|---|---|---| +| Purpose | Local audit and verification | Billing and entitlement | +| Data | Raw, per-record, unaggregated | Aggregated for submission | +| Retention | Configurable, 0–365 days (120 default) | Not applicable | +| Where to configure | This page | [Report usage data to F5 (connected)]({{< ref "nim/licensing-and-reporting/report-usage-connected-deployment.md" >}}) or [Report usage data to F5 (disconnected)]({{< ref "nim/licensing-and-reporting/report-usage-disconnected-deployment.md" >}}) | +{{
}} + +When you view or export records on this page, usage reporting to F5 doesn't change. The two pipelines operate independently. + +This page works the same way in connected and disconnected deployments. Your instances keep reporting locally, and existing records stay fully browsable, even without internet access. + +--- + +## Troubleshooting + +### No records appear in the dashboard + +**Symptom**: The usage dashboard shows no records. + +**Cause**: One of the following: + +- NGINX Plus isn't configured to report usage to NGINX Instance Manager. +- Your NGINX Plus version is earlier than R33. +- The date range filter is too narrow. +- Your account doesn't have the NGINX Plus Usage permission. + +**Fix**: Make sure the `usage_report` directive is set in the `mgmt` block of your NGINX Plus configuration. Make sure your NGINX Plus version is R33 or later. Expand the date range or reset it to the default (last 7 days). Make sure your RBAC role includes the NGINX Plus Usage permission. + +### An exported file is truncated + +**Symptom**: The exported CSV file appears incomplete. + +**Cause**: The CSV export streams data directly from the server. A dropped connection during the export leaves the file incomplete. + +**Fix**: Re-export the file. If your connection is slow or unreliable, use narrower date filters to reduce the export size. + +### A record's reporting window spans more than one hour + +**Symptom**: A record's reporting window is longer than expected, for example 09:00–11:00 instead of 09:00–10:00. + +**Cause**: A previous report failed. NGINX Plus combined the missed window with the next scheduled report. This is expected behavior. No usage data is lost. + +**Fix**: No action needed. NGINX Instance Manager retains both the extended record and any partially persisted original record. + +### Dashboard loads slowly with a large date range + +**Symptom**: The dashboard takes several seconds to load with a wide date range or no filters applied. + +**Cause**: Large date ranges return more records to retrieve and count, especially with thousands of instances. + +**Fix**: Narrow the date range or apply additional filters, such as instance, cluster, or product type. The default 7-day view typically loads within a few seconds. + +--- + +## References + +- [Report usage data to F5 (connected)]({{< ref "nim/licensing-and-reporting/report-usage-connected-deployment.md" >}}) +- [Report usage data to F5 (disconnected)]({{< ref "nim/licensing-and-reporting/report-usage-disconnected-deployment.md" >}}) +- [Change telemetry settings]({{< ref "nim/licensing-and-reporting/change-telemetry-settings.md" >}}) +- [System requirements for licensing and usage reporting only]({{< ref "nim/fundamentals/tech-specs.md#reporting-sizing" >}}) \ No newline at end of file diff --git a/content/nim/releases/2.23.0-release-notes.md b/content/nim/releases/2.23.0-release-notes.md new file mode 100644 index 000000000..7316bbb94 --- /dev/null +++ b/content/nim/releases/2.23.0-release-notes.md @@ -0,0 +1,52 @@ +--- +title: 2.23.0 release notes +weight: 956 +toc: true +f5content-type: reference +f5product: F5 NGINX Instance Manager +description: "Release notes for F5 NGINX Instance Manager, including new features, improvements, and bug fixes in each release." +f5-summary: > + Stay up to date with the latest features, improvements, and bug fixes in F5 NGINX Instance Manager. This document provides details about new features, known issues, and resolved problems for each version. +--- + +September 02, 2026 + +### Upgrade Paths {#2-23-0-upgrade-paths} + +NGINX Instance Manager 2.23.0 supports upgrades from these previous versions: + +- 2.20.0 - 2.22.2 + +If your NGINX Instance Manager version is older, you may need to upgrade to an intermediate version before upgrading to the target version. + +### What's new {#2-23-0-whats-new} + +This release includes the following updates: + +- {{% icon-feature %}} **Security monitoring for NGINX Gateway Fabric in NGINX Instance Manager** + + F5 NGINX Instance Manager now shows F5 WAF security events from NGINX Gateway Fabric deployments in the Security Dashboard, alongside F5 NGINX Ingress Controller events. NGINX Gateway Fabric's NGINX Agent v3 exports these events directly to NGINX Instance Manager, without requiring changes to Gateway API resources. This integration provides visibility only. NGINX Instance Manager can't manage NGINX Gateway Fabric instances, instance groups, or F5 WAF policy deployments. + + See [View NGINX Gateway Fabric security events]({{< ref "/nim/security-monitoring/ngf-security-events.md" >}}) to get started. + +- {{% icon-feature %}} **Support for Ubuntu 26.04 added** + + NGINX Instance Manager now supports Ubuntu 26.04 LTS (Resolute Racoon). + +- {{% icon-feature %}} **Rocky Linux 10 Support** + + F5 NGINX Instance Manager now includes native installation packages for Rocky Linux 10. Starting with version 2.21, Rocky Linux 10 used Red Hat Enterprise Linux 10 compatibility packages. This release adds native Rocky Linux 10 packages that F5 builds, packages, and validates. + +- {{% icon-feature %}} **New Usage Overview page for auditing raw NGINX usage data** + + NGINX Instance Manager 2.23.0 adds the **Usage Overview** page. This page gives you direct access to the raw, unaggregated usage records that NGINX Plus, NGINX Ingress Controller, and NGINX Gateway Fabric instances send, separately from the usage reports NGINX Instance Manager sends to F5. Filter, browse, and export records as a CSV file for offline audits and compliance reviews. You can configure retention from 120 days up to 1 year, and records never include hostnames, IP addresses, or other personally identifiable information. This page works in both connected and disconnected deployments. For details, see [View recent NGINX usage]({{< ref "/nim/licensing-and-reporting/view-recent-usage.md" >}}). + +### Resolved issues {#2-23-0-resolved-issues} + +This release fixes the following issues. Use your browser's search function to find the issue ID in the page. + +- {{% icon-resolved %}} Auto-downloaded WAF compiler v5.690.0 and later fails to compile policies (47651) + +### Known issues {#2-23-0-known-issues} + +You can find information about known issues in the [Known Issues]({{< ref "/nim/releases/known-issues.md" >}}) topic. diff --git a/content/nim/releases/known-issues.md b/content/nim/releases/known-issues.md index c0b29f9cc..b10a46d8b 100644 --- a/content/nim/releases/known-issues.md +++ b/content/nim/releases/known-issues.md @@ -136,6 +136,59 @@ How to re-enable mTLS for NGINX Agent and internal service connections: --- +### {{% icon-resolved %}} Auto-downloaded WAF compiler v5.690.0 and later fails to compile policies {#47651} + +| Issue ID | Status | +|----------------|--------| +| 47651 | Fixed in Instance Manager 2.23.0 | + +#### Description + +WAF compiler v5.690.0 and later can fail to compile policies on hosts where NGINX Instance Manager auto-downloaded it before you upgraded to NGINX Instance Manager 2.23.0. This release fixes the auto-download process, so new downloads no longer have this problem. + +You'll see an error like this in the NGINX Instance Manager web interface: + +```text +: failed building config payload: policy compilation failed for deployment due to integrations service error: compiler controller error: exit status 1 +``` + +The `nms.log` file also shows one of the following errors, depending on your operating system. + +**Debian or Ubuntu:** + +```text +/usr/bin/perl: symbol lookup error: /opt/nms-nap-compiler/app_protect-5.690.0/bin/../lib/perl/auto/F5/PatternMatching/PatternMatching.so: undefined symbol: _ZN3re23RE2C1ESt17basic_string_viewIcSt11char_traitsIcEERKNS0_7OptionsE +``` + +**RHEL:** + +```text +Can't load '/opt/nms-nap-compiler/app_protect-5.690.0/bin/../lib/perl/auto/F5/PatternMatching/PatternMatching.so' for module F5::PatternMatching: libre2.so.11: cannot open shared object file: No such file or directory at /usr/lib64/perl5/DynaLoader.pm +``` + +#### Workaround + +If NGINX Instance Manager auto-downloaded WAF compiler v5.690.0 or later on a host (not through `apt` or `yum`) before you upgraded to NGINX Instance Manager 2.23.0, do the following. + +1. Check the library filenames in your compiler's `lib` directory. The filenames in step 2 apply to compiler v5.690.0; later versions may bundle different library versions. + + ```shell + ls /opt/nms-nap-compiler/app_protect-/lib/ | grep -E 'libre2|libprotobuf' + ``` + +2. Replace `` with your installed compiler version and run the following command. If step 1 showed different filenames, edit the command to match before running it. + + ```shell + sudo bash -c ' + cd /opt/nms-nap-compiler/app_protect-/lib && \ + ln -sfn libre2.so.11.0.0 libre2.so.11 && \ + ln -sfn libprotobuf.so.3.21.12.0 libprotobuf.so.32 && \ + ln -sfn libprotobuf.so.32 libprotobuf.so + ' + ``` + +--- + ## 2.22.0 April 28, 2026 @@ -144,7 +197,7 @@ April 28, 2026 | Issue ID | Status | |----------------|--------| -| 47286 | Open | +| 47286 | Won't be resolved | #### Description @@ -156,7 +209,7 @@ Custom users can't perform any actions on the **Security Log Profiles** tab. | Issue ID | Status | |----------------|--------| -| 47287 | Open | +| 47287 | Won't be resolved | #### Description @@ -293,7 +346,7 @@ July 10, 2024 | Issue ID | Status | |----------------|--------| -| 45113 | Open | +| 45113 | Won't be resolved | #### Description @@ -309,7 +362,7 @@ Edit the "/etc/nginx-agent/nginx-agent.conf" file and configure "precompiled_pub | Issue ID | Status | |----------------|--------| -| 45131 | Open | +| 45131 | Won't be resolved | #### Description @@ -426,7 +479,7 @@ August 28, 2023 | Issue ID | Status | |----------------|--------| -| 43950 | Open | +| 43950 | Won't be resolved | #### Description diff --git a/content/nim/security-monitoring/ngf-security-events.md b/content/nim/security-monitoring/ngf-security-events.md new file mode 100644 index 000000000..f79c9316e --- /dev/null +++ b/content/nim/security-monitoring/ngf-security-events.md @@ -0,0 +1,56 @@ +--- +title: View NGINX Gateway Fabric security events +weight: 150 +toc: true +f5-content-type: concept +f5-product: NGINX Instance Manager +f5-docs: +description: "View F5 WAF security events from NGINX Gateway Fabric deployments in F5 NGINX Instance Manager's Security Dashboard." +f5-summary: > + View F5 WAF security events from NGINX Gateway Fabric deployments in F5 NGINX Instance Manager's Security Dashboard. + NGINX Gateway Fabric's NGINX Agent v3 exports security events directly to NGINX Instance Manager, giving you unified event visibility alongside F5 NGINX Ingress Controller. +--- + +## Overview + +F5 NGINX Instance Manager shows F5 WAF security events from NGINX Gateway Fabric deployments in the **Security Dashboard**. NGINX Gateway Fabric's NGINX Agent v3 includes a built-in OpenTelemetry collector that exports security events directly to NGINX Instance Manager. You don't need NGINX Agent v2 to see F5 WAF activity on your NGINX Gateway Fabric instances. + +You can view: + +- F5 WAF security violations +- Bot detection events +- Policy violations +- Attack patterns +- Security event history + +{{< call-out class="important" title="Important: Event visibility only" >}} +This integration covers security event visibility only. NGINX Instance Manager can't manage NGINX Gateway Fabric instances, instance groups, or F5 WAF policy deployments. F5 plans to add full NGINX Agent v3 support for these capabilities in a future release. +{{< /call-out >}} + +## Requirements + +- NGINX Instance Manager 2.23 or later +- NGINX Gateway Fabric running F5 WAF for NGINX with NGINX Agent v3, connected to NGINX Instance Manager. See [Connect NGINX Gateway Fabric to NGINX Instance Manager]({{< ref "/nim/connect-kubernetes/connect-ngf.md" >}}). +- Security Monitoring turned on in NGINX Instance Manager + +## Set up event export from NGINX Gateway Fabric + +NGINX Gateway Fabric generates and exports security events. NGINX Instance Manager doesn't pull or request them. Configure the export on the NGINX Gateway Fabric side. + +This integration doesn't require changes to Gateway API resources. + +See [Export security logs to F5 NGINX Instance Manager]({{< ref "/ngf/waf-integration/policy-sources.md#export-security-logs-to-f5-nginx-instance-manager" >}}). + +## View events in the dashboard + +Go to **WAF** > **Security Dashboard** in NGINX Instance Manager. The dashboard has four tabs: Main, Bots, Advanced, and Event Logs. These tabs cover aggregate attack statistics, bot activity, signature and threat detail, and individual events. + +Use **Event Logs** for individual event details, including source IP, URI, and Support ID. + +You can filter events across all four tabs by fields including instance, instance group, IP address, policy, signature, severity, and Support ID. + +## See also + +- [Export security logs to F5 NGINX Instance Manager]({{< ref "/ngf/waf-integration/policy-sources.md#export-security-logs-to-f5-nginx-instance-manager" >}}) +- [Add user access to Security Monitoring dashboards]({{< ref "/nim/security-monitoring/give-access-to-security-monitoring-dashboards.md" >}}) +- [Troubleshooting]({{< ref "/nim/security-monitoring/troubleshooting.md" >}}) \ No newline at end of file diff --git a/content/nim/security-monitoring/troubleshooting.md b/content/nim/security-monitoring/troubleshooting.md index 8ca527d98..6684c4b41 100644 --- a/content/nim/security-monitoring/troubleshooting.md +++ b/content/nim/security-monitoring/troubleshooting.md @@ -43,6 +43,37 @@ F5 WAF for NGINX supports logging to multiple destinations. You can send logs to --- +## NGINX Gateway Fabric security events don't appear in the dashboard + +### Description + +If NGINX Instance Manager doesn't receive security events from a NGINX Gateway Fabric deployment, the Security Monitoring dashboard shows no data for that deployment. + +### Resolution + +Check the following on NGINX Instance Manager, in order: + +1. Confirm the embedded OpenTelemetry collector is turned on. In `nms.conf`, verify `collector_config.enable` is set to `true`: + + ```yaml + collector_config: + enable: true + ``` + + If you change this setting, restart the service: + + ```shell + sudo systemctl restart nms + ``` + +2. Confirm NGINX Instance Manager is reachable from the Kubernetes cluster on port `4317` (gRPC). + +3. Confirm the log profile referenced in the `WAFPolicy` resource exists in NGINX Instance Manager and matches exactly. A mismatched or missing profile name causes events to arrive without expected fields, or not arrive at all. + +If these checks pass and events still don't appear, the problem is likely on the NGINX Gateway Fabric side. See [Security events aren't reaching NGINX Instance Manager]({{< ref "/ngf/waf-integration/troubleshooting.md#security-events-arent-reaching-nginx-instance-manager" >}}) and [Export security logs to F5 NGINX Instance Manager]({{< ref "/ngf/waf-integration/policy-sources.md#export-security-logs-to-f5-nginx-instance-manager" >}}). + +--- + ## How to get support {{< include "nim/support/how-to-get-support.md" >}}