Upgrade Guide

Overview

This guide explains how to upgrade the F5 NGINX Management Suite modules, NGINX Agent, and NGINX Plus to their latest versions, including how to back up your current configuration, run the upgrade script, and verify the results. Also included are instructions for troubleshooting any potential upgrade errors.

Pre-Upgrade Steps

It’s useful to have an upgrade plan before upgrading. Creating an upgrade plan can help you determine which tasks to complete before and after installing new versions the NGINX Management Suite modules and NGINX Agent.

Review Essential Documentation

Release Notes

Read the release notes for information about the latest features and changes, resolved issues, known issues, and supported upgrade paths.

• Instance Manager Release Notes
• Security Monitoring Module

Tech Specs

Ensure your system meets the recommended requirements and settings NGINX Management Suite:

• Technical Specifications Guide

Verify the Upgrade Path

You can find the supported upgrade paths in the release notes, linked above.

Make sure your current installation can be updated to the target version. You may be able to upgrade directly to the target version, or you may have to upgrade first to an intermediate version.

To see which version of an NGINX Management Suite module is installed, run the following commands:

• CentOS, RHEL, RPM-Based
• Debian, Ubuntu, Deb-Based

Schedule a Maintenance Window

Plan the time when the upgrade will take place. Be sure to let users know when the upgrade will take place and how they might be affected.

Upgrades take under a minute for NGINX Management Suite modules and as long for the NGINX Agent. How long the entire upgrade process takes depends on how many NGINX Agents you need to upgrade. Include time for testing and verifying the upgrade as well.

During an upgrade, you will need to stop the NGINX Agent. Stopping the NGINX Agent results in the following conditions:

• You won’t be able to publish configuration changes;
• Metrics reporting will be queued and picked up once the NGINX Agent is restarted;
• Client connections to the NGINX Management Suite host may be disconnected;
• In the course of the upgrade, users may be logged out and will need to re-authenticate.

Back Up System Files

Follow the steps in the Backup and Recovery Guide to back up essential system files for NGINX Management Suite.

Upgrade a Test Server

We recommend upgrading NGINX Management Suite in a test environment before upgrading your production environment. By doing this, you will be able to identify any potential issues that might interfere with the upgrade.

Upgrade NGINX Management Suite Modules

Instance Manager

• Upgrade Instance Manager on a virtual machine or bare metal
• Upgrade Instance Manager from a Helm Chart
• Upgrade Instance Manager in an offline environment

Security Monitoring

• Upgrade Security Monitoring on a virtual machine or bare metal

Upgrade NGINX Agent

Important:
You should upgrade the NGINX Agent whenever you upgrade NGINX Management Suite in order to ensure compatibility between the two versions. Failing to do so could lead to potential issues.

Upgrade NGINX Agent from version v2.31.0 or later

Note:
Starting from version v2.31.0, NGINX Agent will automatically restart itself during an upgrade.

To upgrade NGINX Agent, follow these steps:

1. Open an SSH connection to the server where you have installed NGINX Agent and log in.

2. Make a backup copy of the following locations to ensure that you can successfully recover if the upgrade has issues:

   • /etc/nginx-agent
   • config_dirs values for any configuration specified in /etc/nginx-agent/nginx-agent.conf

3. Install the updated version of NGINX Agent:

   • CentOS, RHEL, RPM-Based

     sudo yum -y makecache
     sudo yum update -y nginx-agent
     

   • Debian, Ubuntu, Deb-Based

     sudo apt-get update
     sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold"
     

Upgrade NGINX Agent from versions older than v2.31.0

To upgrade NGINX Agent, take the following steps:

1. Open an SSH connection to the server where you have installed NGINX Agent and log in.

2. Make a backup copy of the following locations to ensure that you can successfully recover if the upgrade has issues:

   • /etc/nginx-agent
   • config_dirs values for any configuration specified in /etc/nginx-agent/nginx-agent.conf

3. Stop NGINX Agent:

   sudo systemctl stop nginx-agent
   

4. Install the updated version of NGINX Agent:

   • CentOS, RHEL, RPM-Based

     sudo yum -y makecache
     sudo yum update -y nginx-agent
     

   • Debian, Ubuntu, Deb-Based

     sudo apt-get update
     sudo apt-get install -y --only-upgrade nginx-agent -o Dpkg::Options::="--force-confold"
     

5. Start NGINX Agent:

   sudo systemctl start nginx-agent
   

Upgrade NGINX Plus

We encourage you to upgrade NGINX Plus to take advantage of the latest improvements and features.

1. Follow the steps to upgrade NGINX Plus for your distribution.

2. After upgrading NGINX Plus, restart the NGINX Agent:

   sudo systemctl restart nginx-agent
   

Troubleshooting

• For help with common issues and suggested solutions and workarounds, refer to the NGINX Management Suite Troubleshooting Guide.

• You can create a support package if you have problems with the upgrade. The support package script packages system and service information into a tar archive for troubleshooting and debugging purposes. If you need to contact NGINX Customer support, they may ask you to provide a support package file.

• The AskF5 knowledge base is a helpful place to look for articles related to upgrade issues and solutions.