DNS Filter Table Data

This documentation is for the Envoy v3 API.

As of Envoy v1.18 the v2 API has been removed and is no longer supported.

If you are upgrading from v2 API config you may wish to view the v2 API documentation:

data/dns/v2alpha/dns_table.proto

DNS Filter config overview.

data.dns.v3.DnsTable

[data.dns.v3.DnsTable proto]

This message contains the configuration for the DNS Filter if populated from the control plane

  1. {
  2.   "external_retry_count": "...",
  3.   "virtual_domains": [],
  4.   "known_suffixes": []
  5. }

external_retry_count

(uint32) Control how many times Envoy makes an attempt to forward a query to an external DNS server

virtual_domains

(repeated data.dns.v3.DnsTable.DnsVirtualDomain) Fully qualified domain names for which Envoy will respond to DNS queries. By leaving this list empty, Envoy will forward all queries to external resolvers

known_suffixes

(repeated type.matcher.v3.StringMatcher) This field is deprecated and no longer used in Envoy. The filter’s behavior has changed internally to use a different data structure allowing the filter to determine whether a query is for known domain without the use of this field.

This field serves to help Envoy determine whether it can authoritatively answer a query for a name matching a suffix in this list. If the query name does not match a suffix in this list, Envoy will forward the query to an upstream DNS server

data.dns.v3.DnsTable.AddressList

[data.dns.v3.DnsTable.AddressList proto]

This message contains a list of IP addresses returned for a query for a known name

  1. {
  2.   "address": []
  3. }

address

(repeated string, REQUIRED) This field contains a well formed IP address that is returned in the answer for a name query. The address field can be an IPv4 or IPv6 address. Address family detection is done automatically when Envoy parses the string. Since this field is repeated, Envoy will return as many entries from this list in the DNS response while keeping the response under 512 bytes

data.dns.v3.DnsTable.DnsServiceProtocol

[data.dns.v3.DnsTable.DnsServiceProtocol proto]

Specify the service protocol using a numeric or string value

  1. {
  2.   "number": "...",
  3.   "name": "..."
  4. }

number

(uint32) Specify the protocol number for the service. Envoy will try to resolve the number to the protocol name. For example, 6 will resolve to “tcp”. Refer to: https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml for protocol names and numbers

Precisely one of number, name must be set.

name

(string) Specify the protocol name for the service.

Precisely one of number, name must be set.

data.dns.v3.DnsTable.DnsServiceTarget

[data.dns.v3.DnsTable.DnsServiceTarget proto]

Specify the target for a given DNS service

  1. {
  2.   "host_name": "...",
  3.   "cluster_name": "...",
  4.   "priority": "...",
  5.   "weight": "...",
  6.   "port": "..."
  7. }

host_name

(string) Use a resolvable hostname as the endpoint for a service.

Specify the name of the endpoint for the Service. The name is a hostname or a cluster

Precisely one of host_name, cluster_name must be set.

cluster_name

(string) Use a cluster name as the endpoint for a service.

Specify the name of the endpoint for the Service. The name is a hostname or a cluster

Precisely one of host_name, cluster_name must be set.

priority

(uint32) The priority of the service record target

weight

(uint32) The weight of the service record target

port

(uint32) The port to which the service is bound. This value is optional if the target is a cluster. Setting port to zero in this case makes the filter use the port value from the cluster host

data.dns.v3.DnsTable.DnsService

[data.dns.v3.DnsTable.DnsService proto]

This message defines a service selection record returned for a service query in a domain

  1. {
  2.   "service_name": "...",
  3.   "protocol": "{...}",
  4.   "ttl": "{...}",
  5.   "targets": []
  6. }

service_name

(string, REQUIRED) The name of the service without the protocol or domain name

protocol

(data.dns.v3.DnsTable.DnsServiceProtocol) The service protocol. This can be specified as a string or the numeric value of the protocol

ttl

(Duration) The service entry time to live. This is independent from the DNS Answer record TTL

targets

(repeated data.dns.v3.DnsTable.DnsServiceTarget, REQUIRED) The list of targets hosting the service

data.dns.v3.DnsTable.DnsServiceList

[data.dns.v3.DnsTable.DnsServiceList proto]

Define a list of service records for a given service

  1. {
  2.   "services": []
  3. }

services

(repeated data.dns.v3.DnsTable.DnsService, REQUIRED)

data.dns.v3.DnsTable.DnsEndpoint

[data.dns.v3.DnsTable.DnsEndpoint proto]

  1. {
  2.   "address_list": "{...}",
  3.   "cluster_name": "...",
  4.   "service_list": "{...}"
  5. }

address_list

(data.dns.v3.DnsTable.AddressList) Define a list of addresses to return for the specified endpoint

Precisely one of address_list, cluster_name, service_list must be set.

cluster_name

(string) Define a cluster whose addresses are returned for the specified endpoint

Precisely one of address_list, cluster_name, service_list must be set.

service_list

(data.dns.v3.DnsTable.DnsServiceList) Define a DNS Service List for the specified endpoint

Precisely one of address_list, cluster_name, service_list must be set.

data.dns.v3.DnsTable.DnsVirtualDomain

[data.dns.v3.DnsTable.DnsVirtualDomain proto]

  1. {
  2.   "name": "...",
  3.   "endpoint": "{...}",
  4.   "answer_ttl": "{...}"
  5. }

name

(string, REQUIRED) A domain name for which Envoy will respond to query requests

endpoint

(data.dns.v3.DnsTable.DnsEndpoint) The configuration containing the method to determine the address of this endpoint

answer_ttl

(Duration) Sets the TTL in DNS answers from Envoy returned to the client. The default TTL is 300s