Package io.envoyproxy.envoy.extensions.network.dns_resolver.cares.v3

Interface CaresDnsResolverConfigOrBuilder

All Superinterfaces:
com.google.protobuf.MessageLiteOrBuilder, com.google.protobuf.MessageOrBuilder
All Known Implementing Classes:
CaresDnsResolverConfig, CaresDnsResolverConfig.Builder
public interface CaresDnsResolverConfigOrBuilder extends com.google.protobuf.MessageOrBuilder

  • Method Summary

    Modifier and Type
    Method
    Description
    DnsResolverOptions
    getDnsResolverOptions()
    Configuration of DNS resolver option flags which control the behavior of the DNS resolver.
    DnsResolverOptionsOrBuilder
    getDnsResolverOptionsOrBuilder()
    Configuration of DNS resolver option flags which control the behavior of the DNS resolver.
    com.google.protobuf.UInt32Value
    getEdns0MaxPayloadSize()
    Maximum EDNS0 UDP payload size in bytes.
    com.google.protobuf.UInt32ValueOrBuilder
    getEdns0MaxPayloadSizeOrBuilder()
    Maximum EDNS0 UDP payload size in bytes.
    boolean
    getFilterUnroutableFamilies()
    The resolver will query available network interfaces and determine if there are no available interfaces for a given IP family.
    com.google.protobuf.Duration
    getMaxUdpChannelDuration()
    The maximum duration for which a UDP channel will be kept alive before being refreshed.
    com.google.protobuf.DurationOrBuilder
    getMaxUdpChannelDurationOrBuilder()
    The maximum duration for which a UDP channel will be kept alive before being refreshed.
    com.google.protobuf.UInt64Value
    getQueryTimeoutSeconds()
    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.
    com.google.protobuf.UInt64ValueOrBuilder
    getQueryTimeoutSecondsOrBuilder()
    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.
    com.google.protobuf.UInt32Value
    getQueryTries()
    The maximum number of query attempts the resolver will make before giving up.
    com.google.protobuf.UInt32ValueOrBuilder
    getQueryTriesOrBuilder()
    The maximum number of query attempts the resolver will make before giving up.
    boolean
    getReinitChannelOnTimeout()
    If true, reinitialize the c-ares channel when a DNS query fails with ``ARES_ETIMEOUT``.
    Address
    getResolvers(int index)
    A list of DNS resolver addresses.
    int
    getResolversCount()
    A list of DNS resolver addresses.
    List<Address>
    getResolversList()
    A list of DNS resolver addresses.
    AddressOrBuilder
    getResolversOrBuilder(int index)
    A list of DNS resolver addresses.
    List<? extends AddressOrBuilder>
    getResolversOrBuilderList()
    A list of DNS resolver addresses.
    boolean
    getRotateNameservers()
    Enable round-robin selection of name servers for DNS resolution.
    com.google.protobuf.UInt32Value
    getUdpMaxQueries()
    This option allows the number of UDP based DNS queries to be capped. .. note:: This is only applicable to c-ares DNS resolver currently.
    com.google.protobuf.UInt32ValueOrBuilder
    getUdpMaxQueriesOrBuilder()
    This option allows the number of UDP based DNS queries to be capped. .. note:: This is only applicable to c-ares DNS resolver currently.
    boolean
    getUseResolversAsFallback()
    If true use the resolvers listed in the :ref:`resolvers <envoy_v3_api_field_extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig.resolvers>` field only if c-ares is unable to obtain a nameserver from the system (e.g., ``/etc/resolv.conf``).
    boolean
    hasDnsResolverOptions()
    Configuration of DNS resolver option flags which control the behavior of the DNS resolver.
    boolean
    hasEdns0MaxPayloadSize()
    Maximum EDNS0 UDP payload size in bytes.
    boolean
    hasMaxUdpChannelDuration()
    The maximum duration for which a UDP channel will be kept alive before being refreshed.
    boolean
    hasQueryTimeoutSeconds()
    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.
    boolean
    hasQueryTries()
    The maximum number of query attempts the resolver will make before giving up.
    boolean
    hasUdpMaxQueries()
    This option allows the number of UDP based DNS queries to be capped. .. note:: This is only applicable to c-ares DNS resolver currently.

    Methods inherited from interface com.google.protobuf.MessageLiteOrBuilder

    isInitialized

    Methods inherited from interface com.google.protobuf.MessageOrBuilder

    findInitializationErrors, getAllFields, getDefaultInstanceForType, getDescriptorForType, getField, getInitializationErrorString, getOneofFieldDescriptor, getRepeatedField, getRepeatedFieldCount, getUnknownFields, hasField, hasOneof

  • Method Details

    • getResolversList

      List<Address> getResolversList()
       A list of DNS resolver addresses.
 :ref:`use_resolvers_as_fallback <envoy_v3_api_field_extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig.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.
      repeated .envoy.config.core.v3.Address resolvers = 1;

    • getResolvers

      Address getResolvers(int index)
       A list of DNS resolver addresses.
 :ref:`use_resolvers_as_fallback <envoy_v3_api_field_extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig.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.
      repeated .envoy.config.core.v3.Address resolvers = 1;

    • getResolversCount

      int getResolversCount()
       A list of DNS resolver addresses.
 :ref:`use_resolvers_as_fallback <envoy_v3_api_field_extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig.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.
      repeated .envoy.config.core.v3.Address resolvers = 1;

    • getResolversOrBuilderList

      List<? extends AddressOrBuilder> getResolversOrBuilderList()
       A list of DNS resolver addresses.
 :ref:`use_resolvers_as_fallback <envoy_v3_api_field_extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig.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.
      repeated .envoy.config.core.v3.Address resolvers = 1;

    • getResolversOrBuilder

      AddressOrBuilder getResolversOrBuilder(int index)
       A list of DNS resolver addresses.
 :ref:`use_resolvers_as_fallback <envoy_v3_api_field_extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig.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.
      repeated .envoy.config.core.v3.Address resolvers = 1;

    • getUseResolversAsFallback

      boolean getUseResolversAsFallback()
       If true use the resolvers listed in the
 :ref:`resolvers <envoy_v3_api_field_extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig.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.
      bool use_resolvers_as_fallback = 3;
      Returns:
      The useResolversAsFallback.

    • getFilterUnroutableFamilies

      boolean getFilterUnroutableFamilies()
       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.
      bool filter_unroutable_families = 4;
      Returns:
      The filterUnroutableFamilies.

    • hasDnsResolverOptions

      boolean hasDnsResolverOptions()
       Configuration of DNS resolver option flags which control the behavior of the DNS resolver.
      .envoy.config.core.v3.DnsResolverOptions dns_resolver_options = 2;
      Returns:
      Whether the dnsResolverOptions field is set.

    • getDnsResolverOptions

      DnsResolverOptions getDnsResolverOptions()
       Configuration of DNS resolver option flags which control the behavior of the DNS resolver.
      .envoy.config.core.v3.DnsResolverOptions dns_resolver_options = 2;
      Returns:
      The dnsResolverOptions.

    • getDnsResolverOptionsOrBuilder

      DnsResolverOptionsOrBuilder getDnsResolverOptionsOrBuilder()
       Configuration of DNS resolver option flags which control the behavior of the DNS resolver.
      .envoy.config.core.v3.DnsResolverOptions dns_resolver_options = 2;

    • hasUdpMaxQueries

      boolean hasUdpMaxQueries()
       This option allows the number of UDP based DNS queries to be capped.

 .. note::
   This is only applicable to c-ares DNS resolver currently.
      .google.protobuf.UInt32Value udp_max_queries = 5;
      Returns:
      Whether the udpMaxQueries field is set.

    • getUdpMaxQueries

      com.google.protobuf.UInt32Value getUdpMaxQueries()
       This option allows the number of UDP based DNS queries to be capped.

 .. note::
   This is only applicable to c-ares DNS resolver currently.
      .google.protobuf.UInt32Value udp_max_queries = 5;
      Returns:
      The udpMaxQueries.

    • getUdpMaxQueriesOrBuilder

      com.google.protobuf.UInt32ValueOrBuilder getUdpMaxQueriesOrBuilder()
       This option allows the number of UDP based DNS queries to be capped.

 .. note::
   This is only applicable to c-ares DNS resolver currently.
      .google.protobuf.UInt32Value udp_max_queries = 5;

    • hasQueryTimeoutSeconds

      boolean hasQueryTimeoutSeconds()
       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.
      .google.protobuf.UInt64Value query_timeout_seconds = 6 [(.validate.rules) = { ... }
      Returns:
      Whether the queryTimeoutSeconds field is set.

    • getQueryTimeoutSeconds

      com.google.protobuf.UInt64Value getQueryTimeoutSeconds()
       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.
      .google.protobuf.UInt64Value query_timeout_seconds = 6 [(.validate.rules) = { ... }
      Returns:
      The queryTimeoutSeconds.

    • getQueryTimeoutSecondsOrBuilder

      com.google.protobuf.UInt64ValueOrBuilder getQueryTimeoutSecondsOrBuilder()
       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.
      .google.protobuf.UInt64Value query_timeout_seconds = 6 [(.validate.rules) = { ... }

    • hasQueryTries

      boolean hasQueryTries()
       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.
      .google.protobuf.UInt32Value query_tries = 7 [(.validate.rules) = { ... }
      Returns:
      Whether the queryTries field is set.

    • getQueryTries

      com.google.protobuf.UInt32Value getQueryTries()
       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.
      .google.protobuf.UInt32Value query_tries = 7 [(.validate.rules) = { ... }
      Returns:
      The queryTries.

    • getQueryTriesOrBuilder

      com.google.protobuf.UInt32ValueOrBuilder getQueryTriesOrBuilder()
       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.
      .google.protobuf.UInt32Value query_tries = 7 [(.validate.rules) = { ... }

    • getRotateNameservers

      boolean getRotateNameservers()
       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.
      bool rotate_nameservers = 8;
      Returns:
      The rotateNameservers.

    • hasEdns0MaxPayloadSize

      boolean hasEdns0MaxPayloadSize()
       Maximum EDNS0 UDP payload size in bytes.
 If set, c-ares will include EDNS0 in DNS queries and use this value as the maximum UDP response size.

 Recommended values:

 * **1232**: Safe default (avoids fragmentation).
 * **4096**: Maximum allowed.

 If unset, c-ares uses its internal default (usually 1232).
      .google.protobuf.UInt32Value edns0_max_payload_size = 9 [(.validate.rules) = { ... }
      Returns:
      Whether the edns0MaxPayloadSize field is set.

    • getEdns0MaxPayloadSize

      com.google.protobuf.UInt32Value getEdns0MaxPayloadSize()
       Maximum EDNS0 UDP payload size in bytes.
 If set, c-ares will include EDNS0 in DNS queries and use this value as the maximum UDP response size.

 Recommended values:

 * **1232**: Safe default (avoids fragmentation).
 * **4096**: Maximum allowed.

 If unset, c-ares uses its internal default (usually 1232).
      .google.protobuf.UInt32Value edns0_max_payload_size = 9 [(.validate.rules) = { ... }
      Returns:
      The edns0MaxPayloadSize.

    • getEdns0MaxPayloadSizeOrBuilder

      com.google.protobuf.UInt32ValueOrBuilder getEdns0MaxPayloadSizeOrBuilder()
       Maximum EDNS0 UDP payload size in bytes.
 If set, c-ares will include EDNS0 in DNS queries and use this value as the maximum UDP response size.

 Recommended values:

 * **1232**: Safe default (avoids fragmentation).
 * **4096**: Maximum allowed.

 If unset, c-ares uses its internal default (usually 1232).
      .google.protobuf.UInt32Value edns0_max_payload_size = 9 [(.validate.rules) = { ... }

    • hasMaxUdpChannelDuration

      boolean hasMaxUdpChannelDuration()
       The maximum duration for which a UDP channel will be kept alive before being refreshed.

 If set, the DNS resolver will periodically reinitialize its c-ares channel after the
 specified duration. This can help with avoiding stale socket states, and providing
 better load distribution across UDP ports.

 If not specified, no periodic refresh will be performed.
      .google.protobuf.Duration max_udp_channel_duration = 10 [(.validate.rules) = { ... }
      Returns:
      Whether the maxUdpChannelDuration field is set.

    • getMaxUdpChannelDuration

      com.google.protobuf.Duration getMaxUdpChannelDuration()
       The maximum duration for which a UDP channel will be kept alive before being refreshed.

 If set, the DNS resolver will periodically reinitialize its c-ares channel after the
 specified duration. This can help with avoiding stale socket states, and providing
 better load distribution across UDP ports.

 If not specified, no periodic refresh will be performed.
      .google.protobuf.Duration max_udp_channel_duration = 10 [(.validate.rules) = { ... }
      Returns:
      The maxUdpChannelDuration.

    • getMaxUdpChannelDurationOrBuilder

      com.google.protobuf.DurationOrBuilder getMaxUdpChannelDurationOrBuilder()
       The maximum duration for which a UDP channel will be kept alive before being refreshed.

 If set, the DNS resolver will periodically reinitialize its c-ares channel after the
 specified duration. This can help with avoiding stale socket states, and providing
 better load distribution across UDP ports.

 If not specified, no periodic refresh will be performed.
      .google.protobuf.Duration max_udp_channel_duration = 10 [(.validate.rules) = { ... }

    • getReinitChannelOnTimeout

      boolean getReinitChannelOnTimeout()
       If true, reinitialize the c-ares channel when a DNS query fails with ``ARES_ETIMEOUT``.

 This can help recover from rare cases where the UDP sockets held by the c-ares
 channel become unusable after timeouts, causing subsequent queries to fail or
 Envoy to keep serving stale DNS results. When enabled, a timeout-triggered
 reinitialization attempts to restore healthy state quickly. In environments
 where timeouts are caused by intermittent network issues, enabling this may
 increase channel churn; consider using
 :ref:`max_udp_channel_duration <envoy_v3_api_field_extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig.max_udp_channel_duration>`
 for periodic refresh instead.

 Default is false.
      bool reinit_channel_on_timeout = 11;
      Returns:
      The reinitChannelOnTimeout.