Upgrade Guide

This guide explains how to upgrade the NGINX Management Suite and NGINX Agent.


This documentation applies to NGINX Instance Manager 2.0.0 and later.


Before You Begin

Before upgrading, it’s useful to have an upgrade plan. An upgrade plan helps determine what tasks you need to complete before and after installing new versions of Instance Manager and the NGINX Agent.


Review Required Documentation

Review the documentation in this list to understand the requirements for upgrading:

  • NGINX Instance Manager Release Notes

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

  • Technical Specifications Guide

    Confirm the recommended system requirements and settings for the version of Instance Manager you’re upgrading to.


Verify the Upgrade Path

Verify that your current version of Instance Manager can be upgraded to the target version. You may be able to upgrade directly to the target version, or you may need to upgrade to an intermediate version first. You can find the supported upgrade paths in the NGINX Instance Manager Release Notes.


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

    • Look up the installed version of NGINX Instance Manager:

      yum info nms-instance-manager
      
    • Look up the installed version of NGINX Management Suite API Connectivity Manager:

      yum info nms-api-connectivity-manager
      

    • Look up the installed version of NGINX Instance Manager:

      dpkg -s nms-instance-manager
      
    • Look up the installed version of NGINX API Connectivity Manager:

      dpkg -s nms-api-connectivity-manager
      

Schedule a Maintenance Window

Schedule a time in which you will perform the upgrade. Let users know when the upgrade will occur and how they might be affected.

Upgrading doesn’t take long, just under a minute to upgrade the Instance Manager server and as long to upgrade the NGINX Agent. How long the entire upgrade process takes depends on how many Agents you need to upgrade. Make sure to include time to verify and test the upgrade as well.

During an upgrade, you’ll need to stop the NGINX Agent. When the Agent is stopped, the following conditions occur:

  • you won’t be able to publish configuration changes,
  • metrics reporting will be queued and picked up once the Agent is running again,
  • client connections to Instance Manager may be disconnected, and
  • users may be logged out and need to reauthenticate after the upgrade.

Upgrade a Test Server

Upgrade Instance Manager in a test environment before upgrading your production server. Upgrading a test server can help identify issues that may slow down or block the upgrade of your production system.




Upgrade NGINX Instance Manager

This section explains how to upgrade Instance Manager using a Linux package manager – Yum or Apt – to retrieve packages from a public repository. You’ll need to have Internet access to complete these steps.

If you don’t have access to the Internet, refer to the Upgrade in an Offline Environment section.


Upgrade Steps

Important:
If you haven’t done so already, complete the steps to prepare to install NGINX Management Suite before continuing.

  1. To install the latest version of the NGINX Instance Manager module, run the following command:

    sudo yum install -y nms-instance-manager
    
  2. Enable the following NGINX Management Suite services:

    sudo systemctl enable nms
    sudo systemctl enable nms-core
    sudo systemctl enable nms-dpm
    sudo systemctl enable nms-ingestion
    
  3. Start the NGINX Management Suite services:

    sudo systemctl start nms
    

    To verify the NGINX Management Suite services are running, run the following command:

    ps aufx | grep nms
    
  4. Restart the NGINX web server:

    sudo systemctl restart nginx
    

  1. To install the latest version of the NGINX Instance Manager module, run the following commands:

    sudo apt-get update
    sudo apt-get install -y nms-instance-manager
    
  2. Enable the following NGINX Management Suite services:

    sudo systemctl enable nms
    sudo systemctl enable nms-core
    sudo systemctl enable nms-dpm
    sudo systemctl enable nms-ingestion
    
  3. Start the NGINX Management Suite services:

    sudo systemctl start nms
    

    To verify the NGINX Management Suite services are running, run the following command:

    ps aufx | grep nms
    
  4. Restart the NGINX web server:

    sudo systemctl restart nginx
    

Post-Upgrade Steps

After an upgrade, take the following steps to restart the services and optionally reapply SELinux Policies:

  1. Reload NGINX:

    sudo nginx -s reload
    
  2. (Optional) Reapply the SELinux policy if it’s enabled:

    sudo semodule -n -i /usr/share/selinux/packages/nms.pp
    sudo /usr/sbin/load_policy
    sudo restorecon -F -R /usr/bin/nms-core
    sudo restorecon -F -R /usr/bin/nms-dpm
    sudo restorecon -F -R /usr/bin/nms-ingestion
    sudo restorecon -F -R /usr/lib/systemd/system/nms.service
    sudo restorecon -F -R /usr/lib/systemd/system/nms-core.service
    sudo restorecon -F -R /usr/lib/systemd/system/nms-dpm.service
    sudo restorecon -F -R /usr/lib/systemd/system/nms-ingestion.service
    sudo restorecon -F -R /var/lib/nms/modules/manager.json
    sudo restorecon -F -R /var/lib/nms/modules.json
    sudo restorecon -F -R /var/lib/nms/streaming
    sudo restorecon -F -R /var/lib/nms
    sudo restorecon -F -R /var/lib/nms/dqlite
    sudo restorecon -F -R /var/run/nms
    sudo restorecon -F -R /var/lib/nms/modules
    sudo restorecon -F -R /var/log/nms
    
  3. Restart the NGINX Instance Manager services:

    sudo systemctl restart nms
    
  4. Don’t forget to upgrade the NGINX Agent.




Upgrade in an Offline Environment

To upgrade Instance Manager in an offline environment, take the following steps:


Upgrade Steps

  1. Log in to the MyF5 Customer Portal and download the Instance Manager package files, or use the package provided by your NGINX Sales Team.

  2. Install the Instance Manager package:

    sudo yum -y --nogpgcheck install /home/user/nms-instance-manager_<version>.x86_64.rpm
    
  3. Upgrade the Instance Manager package:

    sudo yum -y --nogpgcheck upgrade /home/user/nms-instance-manager_<version>.x86_64.rpm
    

  1. Log in to the MyF5 Customer Portal and download the Instance Manager package files, or use the package provided by your NGINX Sales Team.

  2. Install the Instance Manager package:

    sudo apt-get -y install /home/user/nms-instance-manager_<version>_amd64.deb
    
  3. Upgrade the Instance Manager package:

    sudo apt-get -y upgrade /home/user/nms-instance-manager_<version>_amd64.deb
    

Post-Upgrade Steps

After an upgrade, take the following steps to restart the services and optionally reapply SELinux Policies:

  1. Reload NGINX:

    sudo nginx -s reload
    
  2. (Optional) Reapply the SELinux policy if it’s enabled:

    sudo semodule -n -i /usr/share/selinux/packages/nms.pp
    sudo /usr/sbin/load_policy
    sudo restorecon -F -R /usr/bin/nms-core
    sudo restorecon -F -R /usr/bin/nms-dpm
    sudo restorecon -F -R /usr/bin/nms-ingestion
    sudo restorecon -F -R /usr/lib/systemd/system/nms.service
    sudo restorecon -F -R /usr/lib/systemd/system/nms-core.service
    sudo restorecon -F -R /usr/lib/systemd/system/nms-dpm.service
    sudo restorecon -F -R /usr/lib/systemd/system/nms-ingestion.service
    sudo restorecon -F -R /var/lib/nms/modules/manager.json
    sudo restorecon -F -R /var/lib/nms/modules.json
    sudo restorecon -F -R /var/lib/nms/streaming
    sudo restorecon -F -R /var/lib/nms
    sudo restorecon -F -R /var/lib/nms/dqlite
    sudo restorecon -F -R /var/run/nms
    sudo restorecon -F -R /var/lib/nms/modules
    sudo restorecon -F -R /var/log/nms
    
  3. Restart the NGINX Instance Manager services:

    sudo systemctl restart nms
    
  4. Don’t forget to upgrade the NGINX Agent.




Upgrade NGINX Agent

You should upgrade the NGINX Agent whenever you upgrade NGINX Instance Manager to keep the versions in sync. A failure to do so might cause unexpected issues.

Pre-Upgrade Steps

Performing the pre-upgrade tasks in this section helps to ensure that you can successfully recover if the upgrade process has issues.

  1. Make a backup copy of the following locations:

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

Upgrade Steps

To upgrade the NGINX Agent, take the following steps:

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

  2. Stop the NGINX Agent:

    sudo systemctl stop nginx-agent
    
  3. Install the updated version of the NGINX Agent:

    curl https://<NGINX-INSTANCE-MANAGER-FQDN>/install/nginx-agent | sudo su -
    
  4. Start the NGINX Agent:

    sudo systemctl start nginx-agent
    



Troubleshooting

If you experience problems with the upgrade, follow the steps to create a support package. The support package script packages system and service information into a tar archive for troubleshooting and debugging purposes.

If you need help with troubleshooting, contact NGINX Customer Support.

You can search for Instance Manager troubleshooting guides and knowledge base articles on the AskF5 site.