Migration Guide

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

See Also:
To perform a clean installation of NGINX Management Suite and Instance Manager, refer to the NGINX Management Suite 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.

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

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

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
```
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.
To verify the NGINX Management Suite services are running, run the following command:
```
ps aufx | grep nms
```
(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
`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:

Follow the instructions to Install NGINX Agent v2.
After the installation finishes, restart the NGINX Agent:
```
sudo systemctl restart nginx-agent
```
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:

Stop the Instance Manager v1 service:
```
sudo systemctl stop nginx-manager
```
Uninstall Instance Manager v1:
- CentOS, RHEL, and RPM-Based
- Debian, Ubuntu, and Deb-Based
```
sudo yum remove nginx-manager
```
```
sudo apt-get remove nginx-manager
```