Replacing an Enterprise Agent using the agent clustering method

Last updated: Mon Apr 22 13:11:56 GMT 2019

For a variety of reasons, customers may need to replace an Enterprise Agent which is currently operational.  When replacement is required, customers may want to preserve the Agent's configuration (such as the Agent's name, or settings from the Advanced Settings tab of the Agent's entry on the Enterprise Agent page) and the tests and Account Groups to which the Enterprise Agent has been assigned. The information below provides a process to quickly substitute the new Enterprise Agent for the old, using the ThousandEyes Enterprise Agent cluster feature.

Replacement using the process below not only makes replacement faster and simpler than manual reconfiguration of an Agent, but ensures that organizations which have limits or which are billed for overages to their contracted number of concurrently active Enterprise Agents do not encounter problems due to those limits.

NOTICE: Customers with accounts using metered billing model are advised against using this method.

For more information and alternative upgrading methods, head over to the How to plan for Enterprise Agent upgrades article.


The replacement process consists principally of the following steps:

  1. Create a new cluster using the Agent requiring replacement
  2. Disable the new cluster
  3. Create the new Agent
  4. Add the new Agent to the cluster
  5. Delete the old Agent
  6. Enable the new cluster or remove the cluster and enable the Agent

For more detailed instructions, refer to the section below.

Detailed Instructions

  1. Create a new cluster using the Agent requiring replacement

    Navigate to the Enterprise Agents page, expand the row of the Agent requiring replacement, and click the Add agent to cluster button.
    More info about clusters can be found in the Knowledge Base article Working with Enterprise Agent Clusters.

    User-added image
  2. Name the new cluster

    User-added image
  3. Disable the new cluster

    Disabling the cluster will prevent overages for additional Agents or errors for exceeding your contracted number of concurrent Agents.

    User-added image
  4. Create the new Agent

    Links to our most common deployment options are below.

  5. Add the new Agent to the cluster

    Expand the row belonging to the new Agent and click the Add agent to cluster link.

    User-added image
  6. When the Add Agent to Cluster window appears, click the Add to existing cluster radio button, then select the name of the cluster in the drop-down box

    User-added image
  7. Delete the old Agent

    User-added image
  8. Confirm deletion

    User-added image
  9. Enable the new cluster (1) or convert the Cluster back into an Agent (2)

    User-added image

Related information

Consult the How to plan for Enterprise Agent upgrades article for more information regarding Enterprise Agent upgrades and available upgrading options.

If you have any questions, reach out to ThousandEyes Customer Success team.