Migration Guide

Follow the instructions in this guide to migrate from NGINX Instance Manager v1 to v2

Prerequisites

To complete this tutorial, you need the following:

• A host with NGINX Instance Manager v1 installed that’s managing NGINX instances.

  Note:
  

  You’ll need to install NGINX Instance Manager v2 on this same host in coexistence with NGINX Instance Manager v1. This allows you to migrate the managed NGINX instances to the newer version. Verify that the host meets the technical requirements for NGINX Instance Manager v2.

  The package name for NGINX Instance Manager changed from nginx-manager to nms-instance-manager. You can run these packages in parallel.

Migrate NGINX Instance Manager

Begin the migration process by installing NGINX Instance Manager v2.

1. Follow the instructions for Installing NGINX Instance Manager v2. License NGINX Instance Manager v2 according to the installation guide.

2. For systemd systems, take the following steps to start or reload NGINX Instance Manager:

   1. Start the ClickHouse database server if it’s not running:

      • Check to see if the ClickHouse server is running:

        sudo systemctl status clickhouse-server
        

      • If necessary, start the ClickHouse server:

        sudo systemctl start clickhouse-server
        

   2. Start or restart the NGINX web server:

      • Check to see if the NGINX is running:

        sudo systemctl status nginx
        

      • Start NGINX if it’s not running:

        sudo systemctl start nginx
        

        
        

        —Or—

      • If NGINX is already running, reload it:

        sudo service nginx reload
        

   3. Enable the following NGINX Instance Manager services:

      sudo systemctl enable nms-core
      sudo systemctl enable nms-dpm
      sudo systemctl enable nms-ingestion
      sudo systemctl enable nms
      

      
      

      Description of the services:

      • nms-core: The core service hosts the APIs for setting up and configuring the control plane and analyzing analytics information (metrics, events, and alerts).
      • nms-dpm: The data plane manager (DPM) service hosts the APIs for managing and configuring NGINX instances on the data plane. The DPM also monitors the state of data plane resources and generates reports and event messages.
      • nms-ingestion: The ingestion service collects metrics, security violations, and events from NGINX Agents that aren’t sent to the data plane manager. These metrics can be forwarded to external datastores.
      • nms : A pseudo service used to start the the other nms-* services.

   4. Start the NGINX Instance Manager service:

      sudo systemctl start nms
      

      NGINX Instance Manager components started this way run by default as the non-root nms user inside the nms group, both of which are created during installation.

   5. To verify the NGINX Instance Manager services are running, run the following command:

      ps aufx | grep nms
      

      The output should show processes for:

      • nms-core
      • nms-dpm
      • nms-ingestion

   6. (Optional) If a new admin password was generated for you, change this password with your own as soon as possible. To do so, follow the steps in the Set up Authentication guide.

3. (Optional) After the installation finishes, you need to migrate any customized configurations.

   Refer to the following table for mapping NGINX Instance Manager v1 properties to their v2 equivalents. For NGINX Instance Manager v2, the properties are split between NGINX Instance Manager’s configuration file (nms.conf) and the NGINX proxy instance’s configuration (nms-http.conf).

Important:

The default dpm_grpc_addr value uses Unix domain sockets. We advise against replacing the default value.

Also, the license must be passed using the NGINX Instance Manager REST API or web interface and is no longer configurable.

After you’ve updated the configuration, you can migrate the managed NGINX instances. To do this, upgrade the NGINX Agents from v1 to v2. See the instructions in the following section for how to migrate the NGINX Agents.

Upgrade the NGINX Agent

To upgrade the NGINX Agent from v1 to v2, take the following steps:

1. Follow the instructions to Install NGINX Agent v2.

2. After the installation finishes, restart the NGINX Agent:

   sudo systemctl restart nginx-agent
   

3. Continue to the next section to migrate the managed NGINX instances to NGINX Instance Manager v2.

Transfer Managed NGINX Instances

After each NGINX Agent has been upgraded to v2, the managed instance should appear in the “Inventory” view for NGINX Instance Manager v2. The managed NGINX instance no longer appears as Connected in the NGINX Instance Manager v1 “Inventory” view.

After you finish migrating all of the managed NGINX instances, you can uninstall the NGINX Instance Manager v1.

To uninstall NGINX Instance Manager v1, take the following steps:

1. Stop the NGINX Instance Manager v1 service:

   sudo systemctl stop nginx-manager
   

2. Uninstall NGINX Instance Manager v1:

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

   sudo yum remove nginx-manager 
   

   sudo apt-get remove nginx-manager