ArcGIS Enterprise

Migrate to a new machine in ArcGIS Enterprise using the WebGIS DR tool

In May, we wrote about migrating to new machines by creating highly available or multi-machine deployments.

While this approach gets the job done, it will require changes to your production environment and will introduce a small amount of downtime.

A safer, yet slightly more involved workflow to migrate to new machines is to use the WebGIS DR Utility, which is included with the install of Portal. The utility serves two main purposes:

Learn more about the WebGIS DR utility

In order to use the DR tool to migrate machines, there are certain prerequisites depending on the version you’re using. You can check them in the table titled Must this item or setting be identical across deployments when running the webgisdr utility? located in the documentation.

The main settings that must be identical between the original environment and the new environment are the public URL that users use to reach the ArcGIS Enterprise portal, and the services URLs used to federate ArcGIS Server sites with the portal.

This blog will cover migrating your existing deployment to new machines utilizing the WebGIS DR tool.

Pros and cons of this approach

The benefit to using the DR tool to migrate machines is that administrators can isolate the new machines to migrate to without making any changes to production. They can validate whether the migration succeeded before switching over to the new environment.

This approach is slightly more complicated than migrating using the Join Site workflow, as the steps are dependent on your deployment type. You will modify the etc\hosts file on the new machine and on any of your development test machines to manage hostname resolution. At the end of the workflow, you’ll change your organization’s DNS entries as well.

Etc\hosts file

A quick word on the use of the etc\hosts file, located under C:\Windows\System32\drivers\etc on Windows and the \etc folder on Linux: it’s used to resolve hostnames by entering IP addresses and associating the IP addresses to hostnames.

For example, if my machine name has an IP address of 10.0.0.1 and is resolved to enterprise.domain.com via DNS, I can add an entry to the etc\hosts file on the machine to resolve the machine’s IP address to a different hostname:

10.0.0.1 alias.domain.com

If I ping alias.domain.com in a command prompt the etc\hosts file is resolving alias.domain.com to 10.0.0.1, which is enterprise.domain.com. If I had a web server running on the machine, I can reach the web server via alias.domain.com or enterprise.domain.com.

This approach is slightly more complicated than migrating using the Join Site workflow as the steps are dependent on your deployment type and requires modifying the etc\hosts file to manage hostname resolution.

The WebGIS DR approach

When you want to migrate machines, you’ll be in one of two scenarios: You will either have a single-machine environment where all software components and Web Adaptors are on one machine (as installed by ArcGIS Enterprise Builder), or a distributed deployment, where your ArcGIS Web Adaptors or reverse proxy are on a separate machine from the rest of the components.

We’ll first go over how this method can be used on a single-machine deployment.

Steps to migrate single-machine deployments

If you are migrating a single-machine base deployment, the easiest approach is to use the same name between the new and old environment using the \etc\hosts file.

As an example, let’s say you have a deployment on a machine called enterprise.domain.com running on the Windows Server 2008 R2 operating system:

Base ArcGIS Enterprise deployment on one machine

The deployment’s URLs are as follows:

You can migrate this deployment using the following steps.

1. Acquire your new machine. This could be a virtual machine or physical machine. In this example, the machine’s hostname is enterprise1.domain.com, its IP address is 10.0.0.2, and it’s running Windows Server 2016.

2. Before you install any software on the new machine, update its etc\hosts file to resolve the IP address of the new machine to enterprise.domain.com:

10.0.0.2 enterprise.domain.com

3. Repeat this on any other machine you might use to test and validate the new system (other than the existing production machine, of course).

4. Install your ArcGIS Enterprise software on it. If you’re using the ArcGIS Enterprise Builder, run the Setup and then the Configuration Wizard.

5. Once the environment is configured, you can only reach the new environment via the enterprise.domain.com hostname from the machine itself or from any other machine that you’ve added the entry to. Any machines without the entry will resolve enterprise.domain.com to your “old” production environment via DNS:

Two machines during migration

6. Create a backup with the WebGIS DR tool. The thing to consider here is timing: Once you take a backup with the DR tool, only the content present in the deployment will be moved over. If content is created after this point, it may not be moved over unless you take and restore a new backup. It’s best to take a backup during a period of downtime.

7. Restore the backup on the new machine with the DR tool. This will create a replica of the existing deployment on the new machine.

8. Validate that users, content, groups, and services are accessible on the new machine, using any machine on which you’ve added that etc/hosts entry. Again, only machines with the 10.0.0.2 enterprise.domain.com entry in the hosts file will resolve enterprise.domain.com to the new machine. Otherwise, those requests will go to the “old” machine.

9. Once the environment has been validated and you’re ready to switch over, update DNS to resolve enterprise.domain.com to the new machine. All requests to enterprise.domain.com will now resolve to the new machine, including all the content from the old environment.

10. Remove the 10.0.0.2 enterprise.domain.com entry from the etc/hosts file on the new machine, and on any other machine to which you added it.

Migrated machines after DNS resolution

Steps to migrate distributed environments

If you have a distributed environment, you only need to modify the etc\hosts file to make sure that the component acting as the “front-end” for your deployment (its ArcGIS Web Adaptors or reverse proxy) is resolving to the original name.

These steps assume you’re on at least 10.5, which is when the WebGIS DR tool added support for different machine names. As a reminder, there’s a complete table for compatibility located in the documentation.

Let’s say you have two ArcGIS Web Adaptors on a machine called enterprise.domain.com, and your ArcGIS Enterprise portal, ArcGIS Server, and ArcGIS Data Store on a machine called m1.domain.com. Both are running Windows 2008 R2, and you’d like to migrate to Windows Server 2016.

Base ArcGIS Enterprise deployment on two machines

The deployment’s URLs are as follows:

Here’s how you’ll migrate this deployment.

1. Acquire two new machines, one to host ArcGIS Web Adaptors and the other to run the rest of the components. The only IP address that matters in this case is the Web Adaptor machine, because the only settings that needs to be matched between deployment are the https://enterprise.domain.com/portal and https://enterprise.domain.com/server. Let’s say the IP address of the new Web Adaptor machine is 10.0.0.2.

2. Update the etc\hosts file on each new machine to resolve the IP address of the Web Adaptor machine to enterprise.domain.com:

 10.0.0.2 enterprise.domain.com

3. Install the two Web Adaptor instances on enterprise1.domain.com, and install the Portal, Server, and Data Store software on m2.domain.com.

4. Create the Portal and Server sites, register the Data Store to Server, and finally, configure the Web Adaptors on enterprise1.domain.com by reaching the configuration page via https://enterprise.domain.com/portal/webadaptor and https://enterprise.domain.com/server/webadaptor. The requests will be resolved to the new Web Adaptor machine (which is actually enterprise1.domain.com) via the etc\hosts file.

Distributed deployment during migration

5. Federate your server site with the portal, and make sure that you use https://enterprise.domain.com/server as the services URL. The admin URL can either be https://enterprise.domain.com/server or https://m2.esri.com:6443/arcgis.

6. Create a backup of the old deployment with the WebGISDR tool. As with the single-machine example, consider that once you take a backup with the DR tool, only the content present in the deployment will be moved over. If content is created after this point, it may not be moved over unless you take and restore a new backup. It’s best to take a backup during downtime.

7. Restore the backup onto the new deployment with the DR tool. Validate that your users, content, groups, and services are accessible on the new deployment. Again, be aware that only machines with the 10.0.0.2 enterprise.domain.com entry in the hosts file will resolve enterprise.domain.com to the new machine. Otherwise, those requests will go to the primary machine. The DR tool restore will preserve the m2.domain.com machine within the deployment.

8. Once the environment has been validated and you’re ready to switch over, update DNS to resolve enterprise.domain.com to the new machine hosting the Web Adaptor and remove the etc\hosts entry on that machine as well as on m2.domain.com.

All requests to enterprise.domain.com will now resolve to the new machine, which will direct the traffic to m2.domain.com. There, you’ll be able to work with all the content from the old environment on your brand new machines.

Distributed deployment after migration

As you can tell, the steps involved with this approach will likely take more time than the Join Site approach we detailed in our previous blog. But because your users continue to use the old production machines up until the moment you switch your DNS resolution to the new machines, there should be zero downtime involved here.

If ensuring continuous service is your goal, we recommend this method to migrate your deployment to new machines.

For more information about preventing data loss and downtime, visit the ArcGIS Enterprise documentation on high availability and disaster recovery.

Thanks for reading!

About the authors

Jon Quinn

Jon is a product engineer on the ArcGIS Enterprise team, focusing on high availability and disaster recovery.

Scott is a product engineer on the ArcGIS Enterprise team. Follow him on Twitter: @macd_sm.

Connect:

Next Article

Understanding and managing credits in ArcGIS Online

Read this article