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

Class CaresDnsResolverConfig

java.lang.Object
com.google.protobuf.AbstractMessageLite
com.google.protobuf.AbstractMessage
com.google.protobuf.GeneratedMessageV3
io.envoyproxy.envoy.extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig
All Implemented Interfaces:
com.google.protobuf.Message, com.google.protobuf.MessageLite, com.google.protobuf.MessageLiteOrBuilder, com.google.protobuf.MessageOrBuilder, CaresDnsResolverConfigOrBuilder, Serializable
public final class CaresDnsResolverConfig extends com.google.protobuf.GeneratedMessageV3 implements CaresDnsResolverConfigOrBuilder
 Configuration for c-ares DNS resolver.
 [#next-free-field: 12]
Protobuf type envoy.extensions.network.dns_resolver.cares.v3.CaresDnsResolverConfig
See Also:

  • Field Details

    • RESOLVERS_FIELD_NUMBER

      public static final int RESOLVERS_FIELD_NUMBER
      See Also:

    • USE_RESOLVERS_AS_FALLBACK_FIELD_NUMBER

      public static final int USE_RESOLVERS_AS_FALLBACK_FIELD_NUMBER
      See Also:

    • FILTER_UNROUTABLE_FAMILIES_FIELD_NUMBER

      public static final int FILTER_UNROUTABLE_FAMILIES_FIELD_NUMBER
      See Also:

    • DNS_RESOLVER_OPTIONS_FIELD_NUMBER

      public static final int DNS_RESOLVER_OPTIONS_FIELD_NUMBER
      See Also:

    • UDP_MAX_QUERIES_FIELD_NUMBER

      public static final int UDP_MAX_QUERIES_FIELD_NUMBER
      See Also:

    • QUERY_TIMEOUT_SECONDS_FIELD_NUMBER

      public static final int QUERY_TIMEOUT_SECONDS_FIELD_NUMBER
      See Also:

    • QUERY_TRIES_FIELD_NUMBER

      public static final int QUERY_TRIES_FIELD_NUMBER
      See Also:

    • ROTATE_NAMESERVERS_FIELD_NUMBER

      public static final int ROTATE_NAMESERVERS_FIELD_NUMBER
      See Also:

    • EDNS0_MAX_PAYLOAD_SIZE_FIELD_NUMBER

      public static final int EDNS0_MAX_PAYLOAD_SIZE_FIELD_NUMBER
      See Also:

    • MAX_UDP_CHANNEL_DURATION_FIELD_NUMBER

      public static final int MAX_UDP_CHANNEL_DURATION_FIELD_NUMBER
      See Also:

    • REINIT_CHANNEL_ON_TIMEOUT_FIELD_NUMBER

      public static final int REINIT_CHANNEL_ON_TIMEOUT_FIELD_NUMBER
      See Also:

  • Method Details

    • newInstance

      protected Object newInstance(com.google.protobuf.GeneratedMessageV3.UnusedPrivateParameter unused)
      Overrides:
      newInstance in class com.google.protobuf.GeneratedMessageV3

    • getDescriptor

      public static final com.google.protobuf.Descriptors.Descriptor getDescriptor()

    • internalGetFieldAccessorTable

      protected com.google.protobuf.GeneratedMessageV3.FieldAccessorTable internalGetFieldAccessorTable()
      Specified by:
      internalGetFieldAccessorTable in class com.google.protobuf.GeneratedMessageV3

    • getResolversList

      public 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;
      Specified by:
      getResolversList in interface CaresDnsResolverConfigOrBuilder

    • getResolversOrBuilderList

      public 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;
      Specified by:
      getResolversOrBuilderList in interface CaresDnsResolverConfigOrBuilder

    • getResolversCount

      public 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;
      Specified by:
      getResolversCount in interface CaresDnsResolverConfigOrBuilder

    • getResolvers

      public 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;
      Specified by:
      getResolvers in interface CaresDnsResolverConfigOrBuilder

    • getResolversOrBuilder

      public 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;
      Specified by:
      getResolversOrBuilder in interface CaresDnsResolverConfigOrBuilder

    • getUseResolversAsFallback

      public 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;
      Specified by:
      getUseResolversAsFallback in interface CaresDnsResolverConfigOrBuilder
      Returns:
      The useResolversAsFallback.

    • getFilterUnroutableFamilies

      public 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;
      Specified by:
      getFilterUnroutableFamilies in interface CaresDnsResolverConfigOrBuilder
      Returns:
      The filterUnroutableFamilies.

    • hasDnsResolverOptions

      public 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;
      Specified by:
      hasDnsResolverOptions in interface CaresDnsResolverConfigOrBuilder
      Returns:
      Whether the dnsResolverOptions field is set.

    • getDnsResolverOptions

      public 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;
      Specified by:
      getDnsResolverOptions in interface CaresDnsResolverConfigOrBuilder
      Returns:
      The dnsResolverOptions.

    • getDnsResolverOptionsOrBuilder

      public 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;
      Specified by:
      getDnsResolverOptionsOrBuilder in interface CaresDnsResolverConfigOrBuilder

    • hasUdpMaxQueries

      public 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;
      Specified by:
      hasUdpMaxQueries in interface CaresDnsResolverConfigOrBuilder
      Returns:
      Whether the udpMaxQueries field is set.

    • getUdpMaxQueries

      public 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;
      Specified by:
      getUdpMaxQueries in interface CaresDnsResolverConfigOrBuilder
      Returns:
      The udpMaxQueries.

    • getUdpMaxQueriesOrBuilder

      public 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;
      Specified by:
      getUdpMaxQueriesOrBuilder in interface CaresDnsResolverConfigOrBuilder

    • hasQueryTimeoutSeconds

      public 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) = { ... }
      Specified by:
      hasQueryTimeoutSeconds in interface CaresDnsResolverConfigOrBuilder
      Returns:
      Whether the queryTimeoutSeconds field is set.

    • getQueryTimeoutSeconds

      public 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) = { ... }
      Specified by:
      getQueryTimeoutSeconds in interface CaresDnsResolverConfigOrBuilder
      Returns:
      The queryTimeoutSeconds.

    • getQueryTimeoutSecondsOrBuilder

      public 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) = { ... }
      Specified by:
      getQueryTimeoutSecondsOrBuilder in interface CaresDnsResolverConfigOrBuilder

    • hasQueryTries

      public 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) = { ... }
      Specified by:
      hasQueryTries in interface CaresDnsResolverConfigOrBuilder
      Returns:
      Whether the queryTries field is set.

    • getQueryTries

      public 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) = { ... }
      Specified by:
      getQueryTries in interface CaresDnsResolverConfigOrBuilder
      Returns:
      The queryTries.

    • getQueryTriesOrBuilder

      public 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) = { ... }
      Specified by:
      getQueryTriesOrBuilder in interface CaresDnsResolverConfigOrBuilder

    • getRotateNameservers

      public 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;
      Specified by:
      getRotateNameservers in interface CaresDnsResolverConfigOrBuilder
      Returns:
      The rotateNameservers.

    • hasEdns0MaxPayloadSize

      public 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) = { ... }
      Specified by:
      hasEdns0MaxPayloadSize in interface CaresDnsResolverConfigOrBuilder
      Returns:
      Whether the edns0MaxPayloadSize field is set.

    • getEdns0MaxPayloadSize

      public 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) = { ... }
      Specified by:
      getEdns0MaxPayloadSize in interface CaresDnsResolverConfigOrBuilder
      Returns:
      The edns0MaxPayloadSize.

    • getEdns0MaxPayloadSizeOrBuilder

      public 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) = { ... }
      Specified by:
      getEdns0MaxPayloadSizeOrBuilder in interface CaresDnsResolverConfigOrBuilder

    • hasMaxUdpChannelDuration

      public 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) = { ... }
      Specified by:
      hasMaxUdpChannelDuration in interface CaresDnsResolverConfigOrBuilder
      Returns:
      Whether the maxUdpChannelDuration field is set.

    • getMaxUdpChannelDuration

      public 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) = { ... }
      Specified by:
      getMaxUdpChannelDuration in interface CaresDnsResolverConfigOrBuilder
      Returns:
      The maxUdpChannelDuration.

    • getMaxUdpChannelDurationOrBuilder

      public 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) = { ... }
      Specified by:
      getMaxUdpChannelDurationOrBuilder in interface CaresDnsResolverConfigOrBuilder

    • getReinitChannelOnTimeout

      public 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;
      Specified by:
      getReinitChannelOnTimeout in interface CaresDnsResolverConfigOrBuilder
      Returns:
      The reinitChannelOnTimeout.

    • isInitialized

      public final boolean isInitialized()
      Specified by:
      isInitialized in interface com.google.protobuf.MessageLiteOrBuilder
      Overrides:
      isInitialized in class com.google.protobuf.GeneratedMessageV3

    • writeTo

      public void writeTo(com.google.protobuf.CodedOutputStream output) throws IOException
      Specified by:
      writeTo in interface com.google.protobuf.MessageLite
      Overrides:
      writeTo in class com.google.protobuf.GeneratedMessageV3
      Throws:
      IOException

    • getSerializedSize

      public int getSerializedSize()
      Specified by:
      getSerializedSize in interface com.google.protobuf.MessageLite
      Overrides:
      getSerializedSize in class com.google.protobuf.GeneratedMessageV3

    • equals

      public boolean equals(Object obj)
      Specified by:
      equals in interface com.google.protobuf.Message
      Overrides:
      equals in class com.google.protobuf.AbstractMessage

    • hashCode

      public int hashCode()
      Specified by:
      hashCode in interface com.google.protobuf.Message
      Overrides:
      hashCode in class com.google.protobuf.AbstractMessage

    • parseFrom

      public static CaresDnsResolverConfig parseFrom(ByteBuffer data) throws com.google.protobuf.InvalidProtocolBufferException
      Throws:
      com.google.protobuf.InvalidProtocolBufferException

    • parseFrom

      public static CaresDnsResolverConfig parseFrom(ByteBuffer data, com.google.protobuf.ExtensionRegistryLite extensionRegistry) throws com.google.protobuf.InvalidProtocolBufferException
      Throws:
      com.google.protobuf.InvalidProtocolBufferException

    • parseFrom

      public static CaresDnsResolverConfig parseFrom(com.google.protobuf.ByteString data) throws com.google.protobuf.InvalidProtocolBufferException
      Throws:
      com.google.protobuf.InvalidProtocolBufferException

    • parseFrom

      public static CaresDnsResolverConfig parseFrom(com.google.protobuf.ByteString data, com.google.protobuf.ExtensionRegistryLite extensionRegistry) throws com.google.protobuf.InvalidProtocolBufferException
      Throws:
      com.google.protobuf.InvalidProtocolBufferException

    • parseFrom

      public static CaresDnsResolverConfig parseFrom(byte[] data) throws com.google.protobuf.InvalidProtocolBufferException
      Throws:
      com.google.protobuf.InvalidProtocolBufferException

    • parseFrom

      public static CaresDnsResolverConfig parseFrom(byte[] data, com.google.protobuf.ExtensionRegistryLite extensionRegistry) throws com.google.protobuf.InvalidProtocolBufferException
      Throws:
      com.google.protobuf.InvalidProtocolBufferException

    • parseFrom

      public static CaresDnsResolverConfig parseFrom(InputStream input) throws IOException
      Throws:
      IOException

    • parseFrom

      public static CaresDnsResolverConfig parseFrom(InputStream input, com.google.protobuf.ExtensionRegistryLite extensionRegistry) throws IOException
      Throws:
      IOException

    • parseDelimitedFrom

      public static CaresDnsResolverConfig parseDelimitedFrom(InputStream input) throws IOException
      Throws:
      IOException

    • parseDelimitedFrom

      public static CaresDnsResolverConfig parseDelimitedFrom(InputStream input, com.google.protobuf.ExtensionRegistryLite extensionRegistry) throws IOException
      Throws:
      IOException

    • parseFrom

      public static CaresDnsResolverConfig parseFrom(com.google.protobuf.CodedInputStream input) throws IOException
      Throws:
      IOException

    • parseFrom

      public static CaresDnsResolverConfig parseFrom(com.google.protobuf.CodedInputStream input, com.google.protobuf.ExtensionRegistryLite extensionRegistry) throws IOException
      Throws:
      IOException

    • newBuilderForType

      public CaresDnsResolverConfig.Builder newBuilderForType()
      Specified by:
      newBuilderForType in interface com.google.protobuf.Message
      Specified by:
      newBuilderForType in interface com.google.protobuf.MessageLite

    • newBuilder

      public static CaresDnsResolverConfig.Builder newBuilder()

    • newBuilder

      public static CaresDnsResolverConfig.Builder newBuilder(CaresDnsResolverConfig prototype)

    • toBuilder

      public CaresDnsResolverConfig.Builder toBuilder()
      Specified by:
      toBuilder in interface com.google.protobuf.Message
      Specified by:
      toBuilder in interface com.google.protobuf.MessageLite

    • newBuilderForType

      protected CaresDnsResolverConfig.Builder newBuilderForType(com.google.protobuf.GeneratedMessageV3.BuilderParent parent)
      Specified by:
      newBuilderForType in class com.google.protobuf.GeneratedMessageV3

    • getDefaultInstance

      public static CaresDnsResolverConfig getDefaultInstance()

    • parser

      public static com.google.protobuf.Parser<CaresDnsResolverConfig> parser()

    • getParserForType

      public com.google.protobuf.Parser<CaresDnsResolverConfig> getParserForType()
      Specified by:
      getParserForType in interface com.google.protobuf.Message
      Specified by:
      getParserForType in interface com.google.protobuf.MessageLite
      Overrides:
      getParserForType in class com.google.protobuf.GeneratedMessageV3

    • getDefaultInstanceForType

      public CaresDnsResolverConfig getDefaultInstanceForType()
      Specified by:
      getDefaultInstanceForType in interface com.google.protobuf.MessageLiteOrBuilder
      Specified by:
      getDefaultInstanceForType in interface com.google.protobuf.MessageOrBuilder