How to migrate to single-cluster ArcGIS Server sites

Since ArcGIS Server was first introduced in 2004, its look, feel, and functionalities have undergone many enhancements, not least of which was its evolution into ArcGIS Enterprise. But its primary task remains — to publish and serve powerful, informative geospatial content for organizations worldwide from their own infrastructure.

At the release of ArcGIS Server 10.1, the concepts of server sites and server clusters were introduced as a way to organize a multi-machine ArcGIS Server deployment. With the 10.5.1 release, multi-cluster sites were announced as deprecated, and the ability to create them will be removed after the 10.6.x series. We introduced single-cluster mode as a way to more effectively manage service requests within multi-machine sites.

We know many ArcGIS Server users adopted clusters in their deployment architecture, so we’d like to explain the evolution on clusters, why they have been deprecated, and how you can migrate from a multi-cluster deployment to single-cluster sites.

What are clusters and sites?

First, some clarification on the terms we’re using. The common IT term “cluster” is closer to what we call an ArcGIS Server “site” — an assemblage of individual machines configured to work together on equal terms. Though an ArcGIS Server site can consist of just one machine, the ability to set up multiple machines in a site is often desirable — and is fundamental to distributed processing workflows such as GeoAnalytics Tools. The ability to join multiple ArcGIS Server machines in a single site has not gone and will not go away.

Clusters, as they were introduced in ArcGIS Server, have a different structure and purpose. They are sub-elements of a single site, with each cluster being specialized — perhaps designated to host services of a particular service type, or to handle a certain size of request. An organization may thus have had one cluster to handle image services, another for geoprocessing services, and so on — all within a single ArcGIS Server site accessed via a single ArcGIS Web Adaptor.

To facilitate this activity, machines in an ArcGIS Server cluster constantly communicate with each other to diagnose status and pass requests. Ultimately, we found that clusters hindered ArcGIS Server performance because they introduced excessive “chatter” between machines.

To improve performance for multi-machine sites, we’ve we introduced single-cluster mode. Single-cluster mode does away with specialization — meaning any machine in the site can take any request. It also turns off load balancing between ArcGIS Server machines, instead delegating load balancing solely to the Web Adaptor configured with the ArcGIS Server site, or to any third-party reverse proxy server or load balancer that you may have configured with it.

Single-cluster mode has been the default since 10.4, but the option to revert to a cluster-based architecture was still available. After the 10.6.x release series, the option to revert ArcGIS Server to a cluster-based architecture will be removed from the software, leaving single-cluster mode as the only server site configuration option. With that in mind, we want to provide recommendations to migrate to single-cluster mode and away from multi-cluster sites.

Translating clusters into sites

There are two basic architecture patterns available to accomplish this:

One site, one cluster: Move all services and machines to a single existing cluster, where all machines run every service and are able to receive any request. This does not require deleting any services.

Multiple single-cluster sites: Split existing clusters into new sites, each serving the specialized purpose of a former cluster and only running that subset of your services. This requires deleting services and republishing them once you’ve created the new sites.

Let’s take a look at the basic steps for both of these migration architecture patterns. For each, we’ll assume a scenario of three existing clusters, each with three machines.

One site, one cluster

To migrate to a single cluster without creating new sites, you’ll first move all services to the cluster that will remain, then move all machines there.

1. Identify the cluster you want to keep as your single remaining cluster. This is probably the one named “default,” but could also be the cluster with the most existing services, to minimize the amount of migration you’ll need to do. We’ll call this your master cluster.
2. Move each service in your deployment not currently in the master cluster. Log in to the ArcGIS Server Administrator Directory for your site, and navigate to the services folder to view all services running in the site. For each service that needs to be migrated to the master cluster, click edit, locate the “clusterName” property in the service JSON file, and rename it to the master cluster’s name. Click Save Edits. This will restart the service, and in so doing, will move it to the master cluster.
3. Move each machine to the master cluster. Once you’ve iterated the service migration process for all of your remaining services, each machine outside of your master cluster will be empty. Navigate to the clusters folder, then select each of your “non-master” clusters in turn. From the cluster’s page, click machines, then remove. Select all machines from the JSON list and click Remove. Once all clusters are empty, navigate to the master cluster’s page, click machines > add, and add all of those machines to its JSON list. When you save this, all machines in your ArcGIS Server site will reside in the master cluster.
4. Delete the other clusters after they’ve been emptied of their machines. From each cluster’s page in the Administrator Directory, select delete, and confirm it.
5. Turn on single-cluster mode in your master cluster. Log in to the site’s ArcGIS Server Administrator Directory as an administrator. Navigate to the system folder, then to deployment and click update. On the Single Cluster Mode drop-down box, select TRUE and confirm Update.
6. Restart the ArcGIS Server service on all machines in the site. For Windows users, you’ll do this from the Task Manager: navigate to the Services tab, right-click on the ArcGIS Server service, and click Restart. For Linux users, use the stopserver.sh and startserver.sh commands.

When you’re done with this workflow, you will have migrated from a multi-cluster site to single-cluster mode.

Multiple single-cluster sites

This workflow assumes you intend to preserve the functional structure of your deployment, by creating sites that replicate the workflow separation of your clusters.

Unless you have an additional load balancer or reverse proxy server, service requests will be handled by each site’s Web Adaptor or load balancer, and each site will have its own top-level domain.

1. As above, identify your master cluster. Your consideration here might be different, as the services in the master cluster will be the only ones not republished during the migration process. Identify all services and machines not in this cluster, too.
2. Delete each service outside of the master cluster. Before taking this step, ensure you have all the information you’ll need to republish each service. When you’re ready, navigate to the services folder of your Administrator Directory, select each of these services in turn, click delete, and confirm. Iterate this process until the only services remaining in your site are those in the master cluster.
3. Remove each now-empty machine from the site. To do this, you’ll use the Unregister Machine operation accessible from each machine’s page in the machines folder. Make sure the machine is truly empty of all services before unregistering it.
4. Delete each now-empty cluster from the site. As above, use the delete operation on each cluster’s page in the directory. At the conclusion of this step, you’ll have a single cluster in your existing ArcGIS Server site, and each of your additional machines will be roaming free in the infrastructure void.
5. Create new ArcGIS Server sites that replicate your previous cluster architecture. For each site, you’ll need to select one of your “free-floating” machines as an anchor. Open the Server Manager for that machine and click on the Create Site operation. Enter all of the appropriate parameters, and create the site. (It goes without saying that you should keep the “clusterName” property as “default.”) Repeat this for each new site in your deployment.
6. Join additional machines to each new site you’ve created. You can perform this operation by logging into each “free-floating” machine’s Server Manager and joining the site, or by using the “Add Machine” operation from your anchor machine’s Server Manager. Iterate this step for each machine in your ArcGIS Server deployment; of course, you can shuffle around machines as you see necessary for your resources.
7. Install and configure ArcGIS Web Adaptor instances if you plan to use them – refer to our documentation for the step-by-step process.
8. Republish all services you had deleted in step 2 to the new sites you’ve created and populated.
9. Configure your reverse proxy, if you have it, to communicate with your new ArcGIS Server sites. If you were using clusters to each handle one or more designated service types, you can configure your reverse proxy server to direct requests for each of those service types to the new corresponding site.

Closing thoughts

The evolution of ArcGIS Enterprise, and its ArcGIS Server component, is a constant work in progress, as is any software product. The deprecation of multi-cluster sites is part of that progress.

Our Technical Support and Esri Services teams are always here to help out, as is your account manager; they can help your organization navigate the process of migrating from multi-cluster to single-cluster ArcGIS Server sites while minimizing interruption of your workflows.

While we understand some organizations may choose to “park” their multi-cluster deployment on the 10.6.x series to avoid migrating, we urge you to consider the improved performance of single-cluster mode as worth the costs of migration – not to mention receiving all the new features, enhancements, and security improvements that each new ArcGIS Enterprise release brings. That’s part of our constant progress, too.