DNS cluster configuration (proto)

This extension has the qualified name envoy.clusters.dns

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.clusters

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

type.googleapis.com/envoy.extensions.clusters.dns.v3.DnsCluster

Configuration for DNS discovery clusters.

extensions.clusters.dns.v3.DnsCluster

[extensions.clusters.dns.v3.DnsCluster proto]

{
  "dns_refresh_rate": {...},
  "dns_failure_refresh_rate": {...},
  "respect_dns_ttl": ...,
  "dns_jitter": {...},
  "typed_dns_resolver_config": {...},
  "dns_lookup_family": ...,
  "all_addresses_in_single_endpoint": ...
}

dns_refresh_rate: (Duration) This value is the cluster’s DNS refresh rate. The value configured must be at least 1ms. If this setting is not specified, the value defaults to 5000ms.

dns_failure_refresh_rate: (extensions.clusters.dns.v3.DnsCluster.RefreshRate) This is the cluster’s DNS refresh rate when requests are failing. If this setting is not specified, the failure refresh rate defaults to the DNS refresh rate.

respect_dns_ttl: (bool) Optional configuration for setting cluster’s DNS refresh rate. If the value is set to true, cluster’s DNS refresh rate will be set to resource record’s TTL which comes from DNS resolution.

dns_jitter: (Duration) DNS jitter causes the cluster to refresh DNS entries later by a random amount of time to avoid a stampede of DNS requests. This value sets the upper bound (exclusive) for the random amount. There will be no jitter if this value is omitted.

typed_dns_resolver_config

(config.core.v3.TypedExtensionConfig) DNS resolver type configuration extension. This extension can be used to configure c-ares, apple, or any other DNS resolver types and the related parameters. For example, an object of CaresDnsResolverConfig can be packed into this typed_dns_resolver_config. This configuration replaces the Cluster.typed_dns_resolver_config configuration which replaces Cluster.dns_resolution_config. During the transition period when DnsCluster.typed_dns_resolver_config, Cluster.typed_dns_resolver_config, and Cluster.dns_resolution_config exist, Envoy will use DnsCluster.typed_dns_resolver_config and ignore DNS resolver-related fields in Cluster if the cluster is configured via the Cluster.cluster_type extension point with the DnsCluster extension type. Otherwise, see Cluster.typed_dns_resolver_config.

Tip

This extension category has the following known extensions:

dns_lookup_family: (extensions.clusters.common.dns.v3.DnsLookupFamily) The DNS IP address resolution policy. If this setting is not specified, the value defaults to AUTO.

all_addresses_in_single_endpoint: (bool) If true, all returned addresses are considered to be associated with a single endpoint, which maps to logical DNS discovery semantics. Otherwise, each address is considered to be a separate endpoint, which maps to strict DNS discovery semantics.

extensions.clusters.dns.v3.DnsCluster.RefreshRate

[extensions.clusters.dns.v3.DnsCluster.RefreshRate proto]

{
  "base_interval": {...},
  "max_interval": {...}
}

base_interval: (Duration, REQUIRED) Specifies the base interval between refreshes. This parameter is required and must be greater than zero and less than max_interval.

max_interval: (Duration) Specifies the maximum interval between refreshes. This parameter is optional, but must be greater than or equal to the base_interval if set. The default is 10 times the base_interval.