c-ares DNS resolver (proto)

This extension has the qualified name envoy.network.dns_resolver.cares

Note

This extension is intended to be robust against both untrusted downstream and upstream traffic.

Tip

This extension extends and can be used with the following extension category:

• envoy.network.dns_resolver

This extension must be configured with one of the following type URLs:

• type.googleapis.com/envoy.extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig

extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig

[extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig proto]

Configuration for c-ares DNS resolver.

{
  "resolvers": [],
  "use_resolvers_as_fallback": ...,
  "filter_unroutable_families": ...,
  "dns_resolver_options": {...},
  "udp_max_queries": {...},
  "query_timeout_seconds": {...},
  "query_tries": {...},
  "rotate_nameservers": ...
}

resolvers

(repeated config.core.v3.Address) A list of dns resolver addresses. use_resolvers_as_fallback below dictates if the DNS client should override system defaults or only use the provided resolvers if the system defaults are not available, i.e., as a fallback.

use_resolvers_as_fallback

(bool) If true use the resolvers listed in the resolvers field only if c-ares is unable to obtain a nameserver from the system (e.g., /etc/resolv.conf). Otherwise, the resolvers listed in the resolvers list will override the default system resolvers. Defaults to false.

filter_unroutable_families

(bool) The resolver will query available network interfaces and determine if there are no available interfaces for a given IP family. It will then filter these addresses from the results it presents. e.g., if there are no available IPv4 network interfaces, the resolver will not provide IPv4 addresses.

dns_resolver_options

(config.core.v3.DnsResolverOptions) Configuration of DNS resolver option flags which control the behavior of the DNS resolver.

udp_max_queries

(UInt32Value) This option allows for number of UDP based DNS queries to be capped. Note, this is only applicable to c-ares DNS resolver currently.

query_timeout_seconds

(UInt64Value) The number of seconds each name server is given to respond to a query on the first try of any given server.

Note: While the c-ares library defaults to 2 seconds, Envoy’s default (if this field is unset) is 5 seconds. This adjustment was made to maintain the previous behavior after users reported an increase in DNS resolution times.

query_tries

(UInt32Value) The maximum number of query attempts the resolver will make before giving up. Each attempt may use a different name server.

Note: While the c-ares library defaults to 3 attempts, Envoy’s default (if this field is unset) is 4 attempts. This adjustment was made to maintain the previous behavior after users reported an increase in DNS resolution times.

rotate_nameservers

(bool) Enable round-robin selection of name servers for DNS resolution. When enabled, the resolver will cycle through the list of name servers for each resolution request. This can help distribute the query load across multiple name servers. If disabled (default), the resolver will try name servers in the order they are configured.

Note: This setting overrides any system configuration for name server rotation.