About

The network filter half of the dns-gateway extension set. When an application opens a TCP connection to a virtual IP previously allocated by the resolver UDP listener filter, this filter looks up the original domain and its configured metadata from the shared, process-wide cache and sets them as Envoy filter state.

Downstream filters (e.g. tcp_proxy, set_filter_state) can then use this to select the upstream cluster, set headers, or apply policy. Both filters ship in the same dns-gateway dynamic module, so the cache is shared in-process.

Backward compatibility: this filter is also reachable under the legacy name dns-gateway via --extension dns-gateway --filter-type network.

Configuration

Field Type Required Description
filter_state_prefix string no Prefix for filter state keys. Default: io.builtonenvoy.dns_gateway

Filter State

This filter writes the following keys to Envoy filter state, readable by downstream filters via %FILTER_STATE(<key>:PLAIN)%:

Key Example Description
<prefix>.domain bucket-1.aws.com The matched domain from the DNS query
<prefix>.metadata.<key> aws_cluster Per-domain metadata values from config

The default prefix is io.builtonenvoy.dns_gateway.

Prerequisites

Requires iptables/nftables rules to redirect outbound connections to virtual IP ranges to Envoy's TCP listener.

Usage Examples

Resolve virtual IPs to filter state

The lookup network filter requires no configuration. Pair it with the resolver UDP listener filter, which allocates the virtual IPs and populates the shared cache this filter reads from.

boe run \
  --extension dns-gateway/resolver --config '
    {
      "domains": [
        {
          "domain": "*.aws.com",
          "base_ip": "10.0.0.0",
          "prefix_len": 24,
          "metadata": {
            "cluster": "aws_cluster"
          }
        }
      ]
    }' \
  --extension dns-gateway/lookup

Custom filter state prefix

Override the default io.builtonenvoy.dns_gateway prefix used for the filter state keys written by this filter.

boe run \
  --extension dns-gateway/resolver --config '
    {
      "domains": [
        { "domain": "*.aws.com", "base_ip": "10.0.0.0", "prefix_len": 24 }
      ]
    }' \
  --extension dns-gateway/lookup --config '{"filter_state_prefix": "egress.dns"}'