NGINX Plus Image and JWT Requirement

Overview

NGINX Gateway Fabric with NGINX Plus requires a valid JSON Web Token (JWT) to download the container image from the F5 registry. From version 1.5.0, this JWT token is also required to run NGINX Plus.

This requirement is part of F5’s broader licensing program and aligns with industry best practices. The JWT will streamline subscription renewals and usage reporting, helping you manage your NGINX Plus subscription more efficiently. The telemetry data we collect helps us improve our products and services to better meet your needs.

The JWT is required for validating your subscription and reporting telemetry data. For environments connected to the internet, telemetry is automatically sent to F5’s licensing endpoint. In offline environments, telemetry is routed through NGINX Instance Manager. Usage is reported every hour and on startup whenever NGINX is reloaded.

Set up the JWT

The JWT needs to be configured before deploying NGINX Gateway Fabric. The JWT will be stored in two Kubernetes Secrets: one for downloading the NGINX Plus container image, and the other for running NGINX Plus.

Note:

For security, follow these practices with JSON Web Tokens (JWTs), passwords, and shell history:

1. JWTs: JWTs are sensitive information. Store them securely. Delete them after use to prevent unauthorized access.

2. Shell history: Commands that include JWTs or passwords are recorded in the history of your shell, in plain text. Clear your shell history after running such commands. For example, if you use bash, you can delete commands in your ~/.bash_history file. Alternatively, you can run the history -c command to erase your shell history.

Follow these practices to help ensure the security of your system and data.

Download the JWT from MyF5

1. Log in to MyF5.
2. Go to My Products & Plans > Subscriptions to see your active subscriptions.
3. Find your NGINX products or services subscription, and select the Subscription ID for details.
4. Download the JSON Web Token (JWT) from the subscription page.

Note:
The Connectivity Stack for Kubernetes JWT does not work with NGINX Plus reporting. A regular NGINX Plus instance JWT must be used.

Docker Registry Secret

Note:
If you would rather pull the NGINX Plus image and push to a private registry, you can skip this specific step and instead follow this step.

If the nginx-gateway namespace does not yet exist, create it:

kubectl create namespace nginx-gateway

Create a Kubernetes docker-registry secret type using the contents of the JWT as the username and none for password (as the password is not used). The name of the docker server is private-registry.nginx.com.

kubectl create secret docker-registry nginx-plus-registry-secret --docker-server=private-registry.nginx.com --docker-username=<JWT Token> --docker-password=none -n nginx-gateway

It is important that the --docker-username=<JWT Token> contains the contents of the token and is not pointing to the token itself. When you copy the contents of the JWT, ensure there are no additional characters such as extra whitespaces. This can invalidate the token, causing 401 errors when trying to authenticate to the registry.

Provide the name of this Secret when installing NGINX Gateway Fabric:

• Helm
• Manifests

NGINX Plus Secret

Place the JWT in a file called license.jwt. Create a Kubernetes Secret using the contents of the JWT file.

kubectl create secret generic nplus-license --from-file license.jwt -n nginx-gateway

You can now delete the license.jwt file.

If you need to update the JWT at any time, update the license.jwt field in the Secret using kubectl edit and apply the changes.

If using a name other than the default nplus-license, provide the name of this Secret when installing NGINX Gateway Fabric:

• Helm
• Manifests

- name: nginx-plus-license
  secret:
    secretName: nplus-license

- mountPath: /etc/nginx/license.jwt
  name: nginx-plus-license
  subPath: license.jwt

Reporting to NGINX Instance Manager

If you are deploying NGINX Gateway Fabric in an environment where you need to report to NGINX Instance Manager instead of the default licensing endpoint, a few extra steps may be required.

First, you must specify the endpoint of your NGINX Instance Manager:

• Helm
• Manifests

usage_report endpoint=<your-endpoint>;

CA and Client certificate/key

To configure a CA cert and/or client certificate and key, a few extra steps are needed.

First, you need to create two Secrets in the nginx-gateway namespace. The CA must live under the key ca.crt:

kubectl -n nginx-gateway create secret generic nim-ca --from-file ca.crt

The client cert and key must be added to a TLS Secret:

kubectl -n nginx-gateway create secret tls nim-client --cert /path/to/cert --key /path/to/key

• Helm
• Manifests

- name: nginx-plus-usage-certs
  projected:
    sources:
    - secret:
        name: nim-ca
    - secret:
        name: nim-client

- mountPath: /etc/nginx/certs-bootstrap/
  name: nginx-plus-usage-certs

ssl_trusted_certificate /etc/nginx/certs-bootstrap/ca.crt;
ssl_certificate        /etc/nginx/certs-bootstrap/tls.crt;
ssl_certificate_key    /etc/nginx/certs-bootstrap/tls.key;

Once these Secrets are created and configuration options are set, you can now install NGINX Gateway Fabric.

Installation flags to configure usage reporting

When installing NGINX Gateway Fabric, the following flags can be specified to configure usage reporting to fit your needs:

If using Helm, the nginx.usage values should be set as necessary:

• secretName should be the name of the JWT Secret you created. By default this field is set to nplus-license. This field is required.
• endpoint is the endpoint to send the telemetry data to. This is optional, and by default is product.connect.nginx.com.
• resolver is the nameserver used to resolve the NGINX Plus usage reporting endpoint. This is optional and used with NGINX Instance Manager.
• skipVerify disables client verification of the NGINX Plus usage reporting server certificate.
• caSecretName is the name of the Secret containing the NGINX Instance Manager CA certificate. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway).
• clientSSLSecretName is the name of the Secret containing the client certificate and key for authenticating with NGINX Instance Manager. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway).

If using manifests, the following command-line options should be set as necessary on the nginx-gateway container:

• --usage-report-secret should be the name of the JWT Secret you created. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway). By default this field is set to nplus-license. A volume mount for this Secret is required for installation.
• --usage-report-endpoint is the endpoint to send the telemetry data to. This is optional, and by default is product.connect.nginx.com. Requires extra configuration if specified.
• --usage-report-resolver is the nameserver used to resolve the NGINX Plus usage reporting endpoint. This is optional and used with NGINX Instance Manager.
• --usage-report-skip-verify disables client verification of the NGINX Plus usage reporting server certificate.
• --usage-report-ca-secret is the name of the Secret containing the NGINX Instance Manager CA certificate. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway). Requires extra configuration if specified.
• --usage-report-client-ssl-secret is the name of the Secret containing the client certificate and key for authenticating with NGINX Instance Manager. Must exist in the same namespace that the NGINX Gateway Fabric control plane is running in (default namespace: nginx-gateway). Requires extra configuration if specified.

What’s reported and how it’s protected

NGINX Plus reports the following data every hour by default:

• NGINX version and status: The version of NGINX Plus running on the instance.
• Instance UUID: A unique identifier for each NGINX Plus instance.
• Traffic data:
  • Bytes received from and sent to clients: HTTP and stream traffic volume between clients and NGINX Plus.
  • Bytes received from and sent to upstreams: HTTP and stream traffic volume between NGINX Plus and upstream servers.
  • Client connections: The number of accepted client connections (HTTP and stream traffic).
  • Requests handled: The total number of HTTP requests processed.
• NGINX uptime: The number of reloads and worker connections during uptime.
• Usage report timestamps: Start and end times for each usage report.
• Kubernetes node details: Information about Kubernetes nodes.

Security and privacy of reported data

All communication between your NGINX Plus instances, NGINX Instance Manager, and F5’s licensing endpoint (product.connect.nginx.com) is protected using SSL/TLS encryption.

Only operational metrics are reported — no personally identifiable information (PII) or sensitive customer data is transmitted.

Pull an image for local use

To pull an image for local use, use this command:

docker login private-registry.nginx.com --username=<JWT Token> --password=none

Replace the contents of <JWT Token> with the contents of the JWT token itself.

You can then pull the image:

docker pull private-registry.nginx.com/nginx-gateway-fabric/nginx-plus:1.4.0

Once you have successfully pulled the image, you can tag it as needed, then push it to a different container registry.

Alternative installation options

There are alternative ways to get an NGINX Plus image for NGINX Gateway Fabric:

• Build the Gateway Fabric image describes how to use the source code with an NGINX Plus subscription certificate and key to build an image.