consul

Name

consul - DNS interface to consul with caching support

Description

Consul's DNS interface make it possible to transparently introduce dynamic service discory in an infrastructure. However, the implementation has major limitations:

• Latency of DNS lookups increases linearly with the number of services registered under the same name. Large infrastructures must use a DNS caching and load balacing layer in order to achieve acceptable performances.

• In order to offer proper DNS load balancing, the DNS server running in front of consul must have access to a large enough set of the service endpoints, this is made possible by using DNS resolution over TCP. However, when thousands of service instances are registered, the response generated by consul exceeds the maximum size of a DNS message and no results are sent at all, effectively preventing services from discovering each other over DNS.

The consul plugin addresses those issues by providing a DNS interface which mirrors consul's, and implementing an in-memory cache to serve DNS queries efficiently at large scale.

Syntax

consul [ADDR:PORT]

• ADDR Address at which a consul agent is available.
• PORT Port number at which the consul agent's HTTP API can be queried.

If you want more control:

consul [ADDR:PORT] {
    ttl DURATION
    prefetch AMOUNT [[DURATION] [PERCENTAGE%]]
}

• ttl configured how long responses from querying lists of services from consul are cached for. DURATION defaults to 1m.
• prefetch* will prefetch popular items when they are about to be expunged from the cache. Popular means AMOUNT queries have been seen with no gaps of DURATION or more between them. DURATION defaults to 1m. Prefetching will happen when the TTL drops below PERCENTAGE, which defaults to 10%, or latest 1 second before TTL expiration. Values should be in the range [10%, 90%]. Note the percent sign is mandatory. PERCENTAGE is treated as an int.

Metrics

If monitoring is enabled (via the prometheus directive) then the following metrics are exported:

• coredns_consul_cache_size{type} - Total elements in the cache by cache type.
• coredns_consul_cache_services_total{} - Total number of service endpoints cached.
• coredns_consul_cache_hits_total{type} - Counter of cache hits by cache type.
• coredns_consul_cache_misses_total{} - Counter of cache misses.
• coredns_consul_cache_prefetch_total{} - Counter of cache prefetches.
• coredns_consul_cache_fetch_size{} - Histogram of response sizes from requests to consul.

Cache types are either "denial" or "success".

Examples

Enable the consul plugin, expire cached entries after 10s and prefetch those that have been queried more than twice over 10s.

. {
    consul localhost:8500 {
        ttl 10s
        prefetch 2 10s
    }
}

plugin.cfg

This plugin is intended to appear twoard the end of the plugin list, usually near the proxy plugin declaration.