DNS Filter

Attention

DNS Filter is under active development and should be considered alpha and not production ready.

  • v3 API reference

  • This filter should be configured with the name envoy.filters.udp_listener.dns_filter

Overview

The DNS filter allows Envoy to resolve forward DNS queries as an authoritative server for any configured domains. The filter’s configuration specifies the names and addresses for which Envoy will answer as well as the configuration needed to send queries externally for unknown domains.

The filter supports local and external DNS resolution. If a lookup for a name does not match a statically configured domain, or a provisioned cluster name, Envoy can refer the query to an external resolver for an answer. Users have the option of specifying the DNS servers that Envoy will use for external resolution. Users can disable external DNS resolution by omitting the client configuration object.

The filter supports per-filter configuration. An Example configuration follows that illustrates how the filter can be used.

Example Configuration

  1. listener_filters:
  2.   name: envoy.filters.udp.dns_filter
  3.   typed_config:
  4.     "@type": "type.googleapis.com/envoy.extensions.filters.udp.dns_filter.v3alpha.DnsFilterConfig"
  5.     stat_prefix: "dns_filter_prefix"
  6.     client_config:
  7.       resolution_timeout: 5s
  8.       upstream_resolvers:
  9.       - socket_address:
  10.           address: "8.8.8.8"
  11.           port_value: 53
  12.       - socket_address:
  13.           address: "8.8.4.4"
  14.           port_value: 53
  15.       max_pending_lookups: 256
  16.     server_config:
  17.       inline_dns_table:
  18.         known_suffixes:
  19.         - suffix: "domain1.com"
  20.         - suffix: "domain2.com"
  21.         - suffix: "domain3.com"
  22.         - suffix: "domain4.com"
  23.         - suffix: "domain5.com"
  24.         virtual_domains:
  25.           - name: "www.domain1.com"
  26.             endpoint:
  27.               address_list:
  28.                 address:
  29.                 - 10.0.0.1
  30.                 - 10.0.0.2
  31.           - name: "www.domain2.com"
  32.             endpoint:
  33.               address_list:
  34.                 address:
  35.                   - 2001:8a:c1::2800:7
  36.           - name: "www.domain3.com"
  37.             endpoint:
  38.               address_list:
  39.                 address:
  40.                 - 10.0.3.1
  41.           - name: "www.domain4.com"
  42.             endpoint:
  43.               cluster_name: cluster_0
  44.           - name: "voip.domain5.com"
  45.             endpoint:
  46.               service_list:
  47.                 services:
  48.                   - service_name: "sip"
  49.                     protocol: { number: 6 }
  50.                     ttl: 86400s
  51.                     targets:
  52.                     - host_name: "primary.voip.domain5.com"
  53.                       priority: 10
  54.                       weight: 30
  55.                       port: 5060
  56.                     - host_name: "secondary.voip.domain5.com"
  57.                       priority: 10
  58.                       weight: 20
  59.                       port: 5060
  60.                     - host_name: "backup.voip.domain5.com"
  61.                       priority: 10
  62.                       weight: 10
  63.                       port: 5060

In this example, Envoy is configured to respond to client queries for four domains. For any other query, it will forward upstream to external resolvers. The filter will return an address matching the input query type. If the query is for type A records and no A records are configured, Envoy will return no addresses and set the response code appropriately. Conversely, if there are matching records for the query type, each configured address is returned. This is also true for AAAA records. Only A, AAAA, and SRV records are supported. If the filter parses queries for other record types, the filter immediately responds indicating that the type is not supported. The filter can also redirect a query for a DNS name to the enpoints of a cluster. “www.domain4.com” in the configuration demonstrates this. Along with an address list, a cluster name is a valid endpoint for a DNS name.

The DNS filter also supports responding to queries for service records. The records for “domain5.com” illustrate the configuration necessary to support responding to SRV records. The target name populated in the configuration must be fully qualified domain names, unless the target is a cluster. For non-cluster targets, each referenced target name must be defined in the DNS Filter table so that Envoy can resolve the target hosts’ IP addresses. For a cluster, Envoy will return an address for each cluster endpoint.

Each service record’s protocol can be defined by a name or number. As configured in the example, the filter will successfully respond to SRV record requests for “_sip._tcp.voip.domain5.com”. If a numerical value is specified, Envoy will attempt to resolve the number to a name. String values for protocols are used as they appear. An underscore is prepended to both the service and protocol to adhere to the convention outlined in the RFC.

The filter can also consume its domain configuration from an external DNS table. The same entities appearing in the static configuration can be stored as JSON or YAML in a separate file and referenced using the external_dns_table DataSource directive:

Example External DnsTable Configuration

  1. listener_filters:
  2.   name: "envoy.filters.udp.dns_filter"
  3.   typed_config:
  4.     '@type': 'type.googleapis.com/envoy.extensions.filters.udp.dns_filter.v3alpha.DnsFilterConfig'
  5.     stat_prefix: "my_prefix"
  6.     server_config:
  7.       external_dns_table:
  8.         filename: "/home/ubuntu/configs/dns_table.json"

In the file, the table can be defined as follows:

DnsTable JSON Configuration

  1. {
  2.   "known_suffixes": [
  3.     { "suffix": "suffix1.com" },
  4.     { "suffix": "suffix2.com" }
  5.   ],
  6.   "virtual_domains": [
  7.     {
  8.       "name": "www.suffix1.com",
  9.       "endpoint": {
  10.         "address_list": {
  11.           "address": [ "10.0.0.1", "10.0.0.2" ]
  12.         }
  13.       }
  14.     },
  15.     {
  16.       "name": "www.suffix2.com",
  17.       "endpoint": {
  18.         "address_list": {
  19.           "address": [ "2001:8a:c1::2800:7" ]
  20.         }
  21.       }
  22.     }
  23.   ]
  24. }

By utilizing this configuration, the DNS responses can be configured separately from the Envoy configuration.