README
¶
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 anint.
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.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Consul ¶
type Consul struct {
Next plugin.Handler // Next handler in the list of plugins.
// Addr is the address of the consul agent used by this plugin, it must be
// be in the scheme://host:port format.
Addr string
// Maximum age of cached service entries.
TTL time.Duration
// Configuration of the cache prefetcher.
PrefetchAmount int
PrefetchPercentage int
PrefetchDuration time.Duration
// HTTP transport used to send requests to consul.
Transport http.RoundTripper
// contains filtered or unexported fields
}
Consul is the implementation of the "consul" CoreDNS plugin.
Consul instances are safe to use concurrently from multiple goroutines.
Consul instances must not be copied after the first time they are used, referencing them by pointer should be preferred to passing them by value.
Source Files