R33 pre-release guidance for automatic upgrades

NGINX R33: Immediate action required for automatic upgrades
NGINX Plus R33 requires a valid JSON Web Token (JWT) to start and accept new connections.
If automatic upgrades are enabled, apply the JWT and configure your network now to avoid downtime when R33 is released.

What to know before upgrading to NGINX Plus R33

What’s new

Starting with NGINX Plus R33, expected in Q4 of 2024, all NGINX Plus instances will require a valid JSON Web Token (JWT). The JWT is tied to your subscription, not individual instances, and is used to validate your subscription and report telemetry data. In internet-connected environments, telemetry is sent to F5’s licensing endpoint. In offline environments, telemetry is routed through NGINX Instance Manager.

This change is part of F5’s broader licensing program, designed to make subscription renewals and usage reporting easier. The telemetry data helps us improve our products and services to better meet your needs.

What this means for you

If you’ve enabled automatic upgrades, you need to act before NGINX Plus R33 releases to ensure a smooth upgrade:

Download and apply a valid JSON Web Token (JWT) to each NGINX Plus instance.
Without this token, NGINX Plus won’t start, and the upgrade won’t complete.
Configure your network to allow NGINX Plus to report telemetry data.
If telemetry reporting fails, NGINX Plus will stop accepting new connections.
There’s an exception for previously reported instances — refer to handling outages for more details.

Follow the pre-release steps below to complete the process.

Impacts to NGINX Ingress Controller

Don’t upgrade to NGINX Plus R33 until the next version of NGINX Ingress Controller is released.
NGINX Plus R33 isn’t compatible with NGINX Ingress Controller v3.7.0.

Impacts to previous NGINX Plus versions

No action needed:
If you use NGINX Plus before R33 and haven’t enabled automatic upgrades, no action is required.

Complete these steps before NGINX R33 releases to prepare your systems.

Add the JWT license

Before you install or upgrade to NGINX Plus R33 or later, make sure to:

Download the license from MyF5

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

Copy the license to each NGINX Plus instance

Copy the license file to /etc/nginx/license.jwt on Linux or /usr/local/etc/nginx/license.jwt on FreeBSD for each NGINX Plus instance.
SELinux: If you’re running a Linux distribution with SELinux enabled, set the file security context type with the following command:
```
chcon -t httpd_config_t /etc/nginx/license.jwt
```

Custom paths:

If you plan to use a custom path for the license file, note that custom paths won’t work until after the R33 upgrade. You’ll need to create a placeholder file at /etc/nginx/license.jwt or /usr/local/etc/nginx/license.jwt on FreeBSD before upgrading.

Before upgrading: Create the placeholder file by running:
```
touch /etc/nginx/license.jwt
```
After upgrading: Update the license_token directive in the NGINX configuration mgmt block to point to your custom path:
```
mgmt {
  license_token <custom_path>;
}
```

Set up your network for reporting

To ensure NGINX Plus R33 can report telemetry data, follow these steps based on your environment:

For internet-connected environments:

Allow outbound HTTPS traffic on TCP port 443 to communicate with F5’s licensing endpoint (product.connect.nginx.com). Ensure that the following IP addresses are allowed:

3.135.72.139
3.133.232.50
52.14.85.249

For network-restricted environments

In environments where NGINX Plus instances cannot access the internet, you’ll need NGINX Instance Manager to handle usage reporting.

Configure NGINX Plus to report usage to NGINX Instance Manager

To configure NGINX Plus R33 or later to report usage data to NGINX Instance Manger:

Open port 443 for NGINX Instance Manager.
On each NGINX Plus instance, update the usage_report directive in the mgmt block of the NGINX configuration (/etc/nginx/nginx.conf) to point to your NGINX Instance Manager host:
```
mgmt {
  usage_report endpoint=<NGINX-INSTANCE-MANAGER-FQDN>;
}
```
Reload NGINX:
```
nginx -s reload
```

Submit usage reports to F5 from NGINX Instance Manager

Internet-connected: If NGINX Instance Manager is connected to the internet, see Report usage to F5 for instructions.
Network-restricted: If NGINX Instance Manager cannot access the internet, follow the steps in Report usage to F5 in a network-restricted environment.

Handling outages

If a temporary outage occurs, either on your side or F5’s:

As long as your instance has successfully reported at least once, you’ll have a 180-day grace period to resolve the issue.
During this grace period, NGINX Plus will continue running without any restrictions.

What’s reported

The following JSON example shows the NGINX Plus usage data sent to F5 in a POST request, every hour by default.

{
    "version": "<nginx_version>",
    "uuid": "<nginx_uuid>",
    "nap": "<active/inactive>", // status of NGINX App Protect
    "http": {
        "client": {
            "received": 0, // bytes received
            "sent": 0, // bytes sent
            "requests": 0 // number of HTTP requests processed
        },
        "upstream": {
            "received": 0, // bytes received
            "sent": 0 // bytes sent
        }
    },
    "stream": {
        "client": {
            "received": 0, // bytes received
            "sent": 0 // bytes sent
        },
        "upstream": {
            "received": 0, // bytes received
            "sent": 0 // bytes sent
        }
    },
    "workers": 0, // number of worker processes running
    "uptime": 0, // number of seconds the instance has been running
    "reloads": 0, // number of times the instance has been reloaded
    "start_time": "epoch", // start time of data collection for the report
    "end_time": "epoch" // end time of data collection for the report
}