Update NGINX Agent

Overview

Note:

If you are using a version older than NGINX Agent v2.31.0, you must stop NGINX Agent before updating:

• sudo systemctl stop nginx-agent

And start it again after the update:

• sudo systemctl start nginx-agent

Follow the steps below to update NGINX Agent to the latest version. The same steps apply if you are upgrading from NGINX Agent v2 to NGINX Agent v3.

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

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

   • /etc/nginx-agent
   • Every configuration directory specfied in /etc/nginx-agent/nginx-agent.conf as a config_dirs value

3. Install the updated version of NGINX Agent:

   • CentOS, RHEL, RPM-Based

     shell

     Copy

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

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

   • Debian, Ubuntu, Deb-Based

     shell

     Copy

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

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

Migrate NGINX Agent running in containers

To migrate NGINX Agent containers, we provide a script to convert NGINX Agent v2 config files to NGINX Agent v3 config files: NGINX Agent Config Upgrade Script

To upgrade the configuration, you can follow this example:

wget https://github.com/nginx/agent/blob/v3/scripts/packages/upgrade-agent-config.sh
./upgrade-agent-config.sh --v2-config-file=./nginx-agent-v2.conf --v3-config-file=nginx-agent-v3.conf

wget https://github.com/nginx/agent/blob/v3/scripts/packages/upgrade-agent-config.sh
./upgrade-agent-config.sh --v2-config-file=./nginx-agent-v2.conf --v3-config-file=nginx-agent-v3.conf

If your NGINX Agent container was previously a member of a config sync group, then your NGINX Agent config must be manually updated to add the config sync group label. See Add Config Sync Group for more information.

Rolling back from NGINX Agent v3 to v2

If you need to roll back your environment to NGINX Agent v2, the upgrade process creates a backup of the NGINX Agent v2 config in the file /etc/nginx-agent/nginx-agent-v2-backup.conf.

Replace the conents of /etc/nginx-agent/nginx-agent.conf with the contents of /etc/nginx-agent/nginx-agent-v2-backup.conf and then reinstall an older version of NGINX Agent.