Migration Guide

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


This documentation applies to NGINX Management Suite Instance Manager 2.0.0 and later.


See Also:
To perform a clean installation of NGINX Management Suite (NMS) and Instance Manager, refer to the NMS installation guide.

Prerequisites

To complete this tutorial, you need the following:

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

    Note:

    You’ll need to install Instance Manager v2 on this same host in coexistence with 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 Instance Manager v2.

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

Migrate Instance Manager

Begin the migration process by installing Instance Manager v2.

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

  2. To enable the NGINX Management Suite services, take the following steps:

    1. Enable the NGINX Management Suite services:

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

      sudo systemctl start nms
      sudo systemctl start nms-core
      sudo systemctl start nms-dpm
      sudo systemctl start nms-ingestion
      sudo systemctl start nms-integrations
      

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

      ps aufx | grep nms
      

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

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

      ps aufx | grep nms
      
    Overview: NGINX Management Suite services

    The following table lists the services that are installed with NGINX Management Suite. The “NMS Platform” services are installed with Instance Manager, which is the foundation for the NGINX Management Suite platform.

    Service Module Description
    nms NMS Platform A pseudo service used to start the other nms-* services.
    nms-core NMS Platform The core service hosts the APIs for setting up and configuring the control plane and analyzing analytics information (metrics, events, and alerts).
    nms-dpm NMS Platform 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 NMS Platform 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‑integrations NMS Platform Note: This service is for future integrations; no user management or configuration is needed at this time.
    nms-acm API Connectivity Manager The API Connectivity Manager service.

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

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

Instance Manager v1 property Instance Manager v2 equivalent Configuration file
audit_log access_log /etc/nms/nms.conf
beacon.address DEPRECATED N/A
beacon.batch_size DEPRECATED N/A
beacon.flush_interval DEPRECATED N/A
beacon.token DEPRECATED N/A
bind_address server.listen /etc/nginx/conf.d/nms-http.conf
cert server.ssl_certificate /etc/nginx/conf.d/nms-http.conf
gateway_port server.listen /etc/nginx/conf.d/nms-http.conf
grpc_port dpm_grpc_addr /etc/nms/nms.conf
influxdb.address DEPRECATED N/A
influxdb.batch_size DEPRECATED N/A
influxdb.bucket DEPRECATED N/A
influxdb.flush_interval DEPRECATED N/A
influxdb.gzip DEPRECATED N/A
influxdb.org DEPRECATED N/A
influxdb.tls.ca DEPRECATED N/A
influxdb.tls.cert DEPRECATED N/A
influxdb.tls.enable DEPRECATED N/A
influxdb.tls.key DEPRECATED N/A
influxdb.token DEPRECATED N/A
installer.dir DEPRECATED N/A
installer.filename DEPRECATED N/A
installer.port DEPRECATED N/A
installer.username DEPRECATED N/A
key server.ssl_certificate_key /etc/nginx/conf.d/nms-http.conf
license DEPRECATED N/A
log.level log_level /etc/nms/nms.conf
log.path DEPRECATED N/A
metrics.storage-path DEPRECATED N/A
rbac DEPRECATED N/A
scanner.host_discovery DEPRECATED N/A
scanner.icmp_timeout DEPRECATED N/A
scanner.tcp_timeout DEPRECATED N/A
server_name server.server_name /etc/nginx/conf.d/nms-http.conf
skip_validation DEPRECATED N/A
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 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 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 Instance Manager v2. The managed NGINX instance no longer appears as Connected in the Instance Manager v1 “Inventory” view.

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

To uninstall Instance Manager v1, take the following steps:

  1. Stop the Instance Manager v1 service:

    sudo systemctl stop nginx-manager
    
  2. Uninstall Instance Manager v1:

    sudo yum remove nginx-manager 
    

    sudo apt-get remove nginx-manager