1--- 2layout: "docs" 3page_title: "Anti-Entropy" 4sidebar_current: "docs-internals-anti-entropy" 5description: > 6 This section details the process and use of anti-entropy in Consul. 7--- 8 9# Anti-Entropy 10 11Consul uses an advanced method of maintaining service and health information. 12This page details how services and checks are registered, how the catalog is 13populated, and how health status information is updated as it changes. 14 15~> **Advanced Topic!** This page covers technical details of 16the internals of Consul. You don't need to know these details to effectively 17operate and use Consul. These details are documented here for those who wish 18to learn about them without having to go spelunking through the source code. 19 20### Components 21 22It is important to first understand the moving pieces involved in services and 23health checks: the [agent](#agent) and the [catalog](#catalog). These are 24described conceptually below to make anti-entropy easier to understand. 25 26<a name="agent"></a> 27#### Agent 28 29Each Consul agent maintains its own set of service and check registrations as 30well as health information. The agents are responsible for executing their own 31health checks and updating their local state. 32 33Services and checks within the context of an agent have a rich set of 34configuration options available. This is because the agent is responsible for 35generating information about its services and their health through the use of 36[health checks](/docs/agent/checks.html). 37 38<a name="catalog"></a> 39#### Catalog 40 41Consul's service discovery is backed by a service catalog. This catalog is 42formed by aggregating information submitted by the agents. The catalog maintains 43the high-level view of the cluster, including which services are available, 44which nodes run those services, health information, and more. The catalog is 45used to expose this information via the various interfaces Consul provides, 46including DNS and HTTP. 47 48Services and checks within the context of the catalog have a much more limited 49set of fields when compared with the agent. This is because the catalog is only 50responsible for recording and returning information *about* services, nodes, and 51health. 52 53The catalog is maintained only by server nodes. This is because the catalog is 54replicated via the [Raft log](/docs/internals/consensus.html) to provide a 55consolidated and consistent view of the cluster. 56 57<a name="anti-entropy"></a> 58### Anti-Entropy 59 60Entropy is the tendency of systems to become increasingly disordered. Consul's 61anti-entropy mechanisms are designed to counter this tendency, to keep the 62state of the cluster ordered even through failures of its components. 63 64Consul has a clear separation between the global service catalog and the agent's 65local state as discussed above. The anti-entropy mechanism reconciles these two 66views of the world: anti-entropy is a synchronization of the local agent state and 67the catalog. For example, when a user registers a new service or check with the 68agent, the agent in turn notifies the catalog that this new check exists. 69Similarly, when a check is deleted from the agent, it is consequently removed from 70the catalog as well. 71 72Anti-entropy is also used to update availability information. As agents run 73their health checks, their status may change in which case their new status 74is synced to the catalog. Using this information, the catalog can respond 75intelligently to queries about its nodes and services based on their 76availability. 77 78During this synchronization, the catalog is also checked for correctness. If 79any services or checks exist in the catalog that the agent is not aware of, they 80will be automatically removed to make the catalog reflect the proper set of 81services and health information for that agent. Consul treats the state of the 82agent as authoritative; if there are any differences between the agent 83and catalog view, the agent-local view will always be used. 84 85### Periodic Synchronization 86 87In addition to running when changes to the agent occur, anti-entropy is also a 88long-running process which periodically wakes up to sync service and check 89status to the catalog. This ensures that the catalog closely matches the agent's 90true state. This also allows Consul to re-populate the service catalog even in 91the case of complete data loss. 92 93To avoid saturation, the amount of time between periodic anti-entropy runs will 94vary based on cluster size. The table below defines the relationship between 95cluster size and sync interval: 96 97<table class="table table-bordered table-striped"> 98 <tr> 99 <th>Cluster Size</th> 100 <th>Periodic Sync Interval</th> 101 </tr> 102 <tr> 103 <td>1 - 128</td> 104 <td>1 minute</td> 105 </tr> 106 <tr> 107 <td>129 - 256</td> 108 <td>2 minutes</td> 109 </tr> 110 <tr> 111 <td>257 - 512</td> 112 <td>3 minutes</td> 113 </tr> 114 <tr> 115 <td>513 - 1024</td> 116 <td>4 minutes</td> 117 </tr> 118 <tr> 119 <td>...</td> 120 <td>...</td> 121 </tr> 122</table> 123 124The intervals above are approximate. Each Consul agent will choose a randomly 125staggered start time within the interval window to avoid a thundering herd. 126 127### Best-effort sync 128 129Anti-entropy can fail in a number of cases, including misconfiguration of the 130agent or its operating environment, I/O problems (full disk, filesystem 131permission, etc.), networking problems (agent cannot communicate with server), 132among others. Because of this, the agent attempts to sync in best-effort 133fashion. 134 135If an error is encountered during an anti-entropy run, the error is logged and 136the agent continues to run. The anti-entropy mechanism is run periodically to 137automatically recover from these types of transient failures. 138 139### Enable Tag Override 140 141Synchronization of service registration can be partially modified to 142allow external agents to change the tags for a service. This can be 143useful in situations where an external monitoring service needs to be 144the source of truth for tag information. For example, the Redis 145database and its monitoring service Redis Sentinel have this kind of 146relationship. Redis instances are responsible for much of their 147configuration, but Sentinels determine whether the Redis instance is a 148primary or a secondary. Using the Consul service configuration item 149[enable_tag_override](/docs/agent/services.html) you can instruct the 150Consul agent on which the Redis database is running to NOT update the 151tags during anti-entropy synchronization. For more information see 152[Services](/docs/agent/services.html#enable-tag-override-and-anti-entropy) page. 153