Recursor

The PowerDNS Recursor is a high-performing, low latency DNS resolver.

Configuration Reference

Instance Sets

Sets of instances of Recursor can be defined under the root node recursors. Each instance set should be a key-value pair, with:

key: Name of the instance set
value: Dictionary holding the configuration of the instance set

recursors:
  myrecursor:
    < Recursor configuration >

Parameters which can be used to configure Recursor instances for a specific instance set are shown in the below table.

Parameter	Type	Default	Description
`affinity`	`k8s:`Affinity		Pod affinity (Kubernetes docs: Affinity and anti-affinity). If unset, a default anti-affinity is applied using `antiAffinityPreset` to spread pods across nodes
`agentLogLevel`	`string`	`"info"`	Verbosity of logging for the agent container. Available options: `"debug"` `"info"` `"warn"` `"error"`
`agentLogFormat`	`string`	`"text"`	Format of logging for the agent container. Available options: `"text"` `"json"`
`agentResources`	`k8s:`Resources	`limits: cpu: 250m memory: 256Mi`	Resources allocated to the 'agent' container if `resourceDefaults` is `true`
`antiAffinityPreset`	`string`	`"preferred"`	Pod anti affinity preset. Available options: `"preferred"` `"required"`
`apiKey`	`string`		API key used to access the /api endpoint, used to configure a static key (default: generated and stored in a secret)
`apiKeySecret`	`string`		Name of the secret from which to take the API key, used when there is a pre-provisioned secret holding the api key
`apiKeySecretItem`	`string`		Name of the data item within `apiKeySecret` which holds the API key, used when there is a pre-provisioned secret holding the api key (default: `api_key`)
`config`	`dictionary`	`{}`	Set of `key:value` pairs to configure Recursor. Parameters can be found here: Recursor documentation Parameters reserved by Cloud Control: `"webserver"` `"local"` `"disable-syslog"` `"daemon"` `"chroot"` `"socket"` `"config"`
`containerSecurityContext`	`k8s:`SecurityContext	`allowPrivilegeEscalation: false readOnlyRootFilesystem: true seccompProfile: type: RuntimeDefault capabilities: drop: - "ALL"`	SecurityContext applied to each container
`dnsdist`	dnsdistConfig		Settings to be applied to each Recursor instance when added to dnsdist as a server
`dstoredist`	dstoredist		Settings to configure protobuf message generation and destinations
`filtering`	Filtering		Settings to enable and configure filtering
`forward`	Forward		Settings to configure forward zones in Recursor
`hostNetwork`	`boolean`	`false`	Use host networking for pods
`hpa`	HPA		Horizontal Pod Autoscaling settings
`inboundInterfaces`	List of `string`		List of names of interfaces to which Recursor will bind
`initResources`	`k8s:`Resources	`limits: cpu: 250m memory: 256Mi`	Resources allocated to the 'auth-init' container if `resourceDefaults` is `true`
`luaConfig`	`string`		Lua configuration to be included in each Recursor pod
`luaScript`	`string`		Lua script to be included in each Recursor pod
`metricsInterfaces`	List of `string`		List of names of interfaces to which the metrics aggregator will bind
`nodeSelector`	`k8s:`NodeSelector	`{}`	Kubernetes pod nodeSelector
`outboundInterfaces`	List of `string`		List of names of interfaces from which Recursor will try to send outbound traffic
`podAnnotations`	`k8s:`Annotations	`{}`	Annotations to be added to each pod
`podDisruptionBudget`	`k8s:`PodDisruptionBudgetSpec	`{}`	Spec of PodDisruptionBudget to be applied to deployment
`podLabels`	`k8s:`Labels	`{}`	Labels to be added to each pod
`podSecurityContext`	`k8s:`PodSecurityContext	`fsGroup: 953 runAsUser: 953 runAsGroup: 953 runAsNonRoot: true`	SecurityContext applied to each pod
`replicas`	`integer`	`2`	Default number of replicas in a Deployment
`resources`	`k8s:`Resources	`limits: cpu: 2 memory: 2Gi`	Resources allocated to the 'recursor' container
`serviceLabels`	`k8s:`Labels	`{}`	Labels to be added to each service
`tolerations`			Kubernetes Pod tolerations
`volumes`			List of additional volumes

dnsdist Configuration

Using these parameters you can configure additional behaviour when instances of this instance set are added to dnsdist for loadbalancing:

Parameter	Type	Default	Description
`checkClass`	`integer`	`1`	Number to use as QCLASS in the health-check query. Defaults to DNSClass.IN (`1`)
`checkInterval`	`integer`		The time in seconds between health checks
`checkName`	`string`	`"a.root-servers.net"`	String to use as QNAME in the health-check query
`checkTimeout`	`integer`	`1000`	The timeout (in milliseconds) of a health-check query
`checkType`	`string`	`"A"`	String to use as QTYPE in the health-check query
`disableZeroScope`	`boolean`	`false`	If true, disable the EDNS Client Subnet `zero scope` feature, which does a cache lookup for an answer valid for all subnets (ECS scope of 0) before adding ECS information to the query and doing the regular lookup. This requires the `parseECS` option of the corresponding cache to be set to true
`healthCheckMode`	`string`	`"auto"`	Type of health-check to perform, default is `"auto"` which is configured using the checkName, checkType, etc parameters. Alternatives are `"up"` (no healthcheck - always available for traffic) and `"down"` (no healthcheck - never available for traffic)
`maxCheckFailures`	`integer`	`1`	Allow this amount of check failures before declaring the backend down
`mustResolve`	`boolean`	`false`	If true, the health check must return a RCODE different from NXDomain, ServFail and Refused. Default is false, meaning that every RCODE except ServFail is considered valid
`order`	`integer`		The order of servers in this set, used by the `leastOutstanding` and `firstAvailable` policies
`qps`	`integer`		Limit the number of queries per second to this amount, when using the `firstAvailable` policy
`reconnectOnUp`	`boolean`	`false`	If true, close and reopen the sockets when a server transits from Down to Up
`retries`	`integer`		The number of TCP connection attempts to servers for a given query
`rise`	`integer`	`1`	Require NUM consecutive successful checks before declaring the backend up
`setCD`	`boolean`	`false`	Set the CD (Checking Disabled) flag in the health-check query
`sockets`	`integer`	`1`	Number of sockets (and thus source ports) used toward the backend server
`source`	`string`		Name of the interface which Dnsdist will use to try to send traffic to this Recursor
`tcpConnectTimeout`	`integer`		The timeout (in seconds) of a TCP connection attempt
`tcpFastOpen`	`boolean`	`false`	Whether to enable TCP Fast Open
`tcpRecvTimeout`	`integer`		The timeout (in seconds) of a TCP read attempt
`tcpSendTimeout`	`integer`		The timeout (in seconds) of a TCP write attempt
`useClientSubnet`	`boolean`	`false`	Add the client IP address in the EDNS Client Subnet option when forwarding the query to this backend
`useProxyProtocol`	`boolean`	`false`	Add a proxy protocol header to the query, passing along the client IP address and port along with the original destination address and port
`weight`	`integer`	`1`	The weight of servers in this set, used by the `wrandom`, `whashed` and `chashed` policies

dstoredist

You can configure protobuf message generation and distribution via dstoredist via these options. For example:

dstoredists:
  mydstoredist:
    <dstoredist configuration>

recursors:
  myrecursor:
    dstoredist:
      inbound:
        enabled: true
      outbound:
        enabled: true
      dstoredists:
        - group: mydstoredist

In the above example, a set of dstoredist instances named mydstoredist is created, together with a set of recursor instances named myrecursor. We configure a few things on the Recursor:

We instruct it to enable protobuf message generation for traffic inbound to the Recursor
We instruct it to enable protobuf message generation for traffic outbound from the Recursor
We instruct it to send all protobuf messages to a set of dstoredists named mydstoredist

As a result, all inbound and outbound traffic should lead to protobuf messages being generated and distributed to the mydstoredist dstoredist instances.

Parameters which can be used to further configure this:

Parameter	Type	Default	Description
`batchBufferSize`	`integer`	`1048576`	Size in bytes of the buffer used to handle message batches internally
`connTimeout`	`go:`DurationString		Idle timeout for connections to dstoredist. Only applies if a value is configured explicitly
`dstoredists`	dstoredistEndpoints		List of sets of dstoredists to distribute messages to
`inbound`	InboundConfiguration		Configuration of protobuf message generation for queries and answers of inbound traffic
`outbound`	OutboundConfiguration		Configuration of protobuf message generation for queries and answers of outbound traffic

Endpoints

Parameter	Type	Required	Default	Description
`group`	`string`	`yes`		Name of set of dstoredist instances
`append_tags`	List of `string`		`[]`	List of tags which will be appended each message
`filters`	Map of filters		`{}`	Filters as defined by the format described in the dstore documentation for the `filters` parameter under `routes`
`tlsconfig`	TLSConfig		`{}`	TLS configuration options

Endpoint TLS Config

Parameters to configure TLS options, these should be child attributes of the tlsconfig node. For example:

recursors:
  myrecursor:
    dstoredist:
      inbound:
        enabled: true
      outbound:
        enabled: true
      dstoredists:
        - group: mydstoredist
          tlsconfig:
            insecure_skip_verify: true

Further parameters to configure:

Parameter	Type	Default	Description
`ca`	`string`		CA in PEM format to use for validation. Use of `caSecret` is recommended for security reasons
`caSecret`	`string`		Name of a pre-existing Kubernetes Secret with a data item named `ca.crt` containing the CA in PEM format to use for validation
`insecure_skip_verify`	`boolean`	`false`	Skip validation of the storage backend's certificate chain and hostname

Inbound

Parameter	Type	Required	Default	Description
`asyncConnect`	`boolean`		`false`	The first connection to the server during startup will block up to timeout seconds, otherwise the connection is done in a separate thread, after the first message has been queued
`enabled`	`boolean`	`yes`	`true`	If true, generate protobuf messages for all queries and corresponding responses to inbound traffic
`exportTypes`	List of `string`		`- "A" - "AAAA" - "CNAME"`	List of record types found in the answer section to export. Available options: `"A"` `"AAAA"` `"CNAME"` `"MX"` `"NS"` `"PTR"` `"SPF"` `"SRV"` `"TXT"`
`logMappedFrom`	`boolean`		`false`	Whether to log the remote address after (`false`) substitution by Table Based Proxy Mapping or before (`true`) (default: `false`)
`logQueries`	`boolean`		`true`	Whether to export queries
`logResponses`	`boolean`		`true`	Whether to export responses
`maxQueuedEntries`	`integer`		`100`	How many entries will be kept in memory if the server becomes unreachable
`reconnectWaitTime`	`integer`		`1`	How long to wait, in seconds, between two reconnection attempts
`taggedOnly`	`boolean`		`false`	Only entries with a policy or a policy tag set will be sent
`timeout`	`integer`		`2`	Time in seconds to wait when sending a message

Outbound

Parameter	Type	Required	Default	Description
`asyncConnect`	`boolean`		`false`	The first connection to the server during startup will block up to timeout seconds, otherwise the connection is done in a separate thread, after the first message has been queued
`enabled`	`boolean`	`yes`	`true`	If true, generate protobuf messages for all queries and corresponding responses to outbound traffic
`exportTypes`	List of `string`		`- "A" - "AAAA" - "CNAME"`	List of record types found in the answer section to export. Available options: `"A"` `"AAAA"` `"CNAME"` `"MX"` `"NS"` `"PTR"` `"SPF"` `"SRV"` `"TXT"`
`logMappedFrom`	`boolean`		`false`	Whether to log the remote address after (`false`) substitution by Table Based Proxy Mapping or before (`true`) (default: `false`)
`logQueries`	`boolean`		`true`	Whether to export queries
`logResponses`	`boolean`		`true`	Whether to export responses
`maxQueuedEntries`	`integer`		`100`	How many entries will be kept in memory if the server becomes unreachable
`reconnectWaitTime`	`integer`		`1`	How long to wait, in seconds, between two reconnection attempts
`taggedOnly`	`boolean`		`false`	Only entries with a policy or a policy tag set will be sent
`timeout`	`integer`		`2`	Time in seconds to wait when sending a message

Filtering

If you have a filtering set defined under the filterSettings root node, you can easily apply them to this Recursor via the following configuration:

filterSettings:
  mysettings:
    <Filtering settings>

recursors:
  myrecursor:
    filtering:
      enabled: true
      settings: mysettings

You need to:

Set enabled to true to enable the filtering
Configure settings to a named set of filterSettings

There are no other parameters to configure in this section. All the filtering configuration is done in the filterSettings set itself.

Forward

A set of forward zones can be configured as follows:

recursors:
  myrecursor:
    forward:
      - learnFrom: testauth
        exclude:
          - ".test."
      - serverGroups:
          - group: resolverexample
        recurse: true
        priority: 5
        zones:
          - "google.com"
          - "internal"
          - "nico"

There are 2 main ways of configuring the zones which need to be forwarded:

Learned from a set of Auth instances via learnFrom:
By providing a list of zones in zones:

Above options can also be combined. If you have multiple entries in the forward list, the priority parameter is used to establish precedence (with order in the list being the tiebreaker).

Parameters which can be used to configure each set of forward zones:

Parameter	Type	Default	Description
`exclude`	List of `string`	`[]`	If `learnFrom` is configured, exclude any zones which match this list of regular expressions (this is processed after the `include` filter)
`include`	List of `string`	`[]`	If `learnFrom` is configured, include only zones which match this list of regular expressions (this is processed before the `exclude` filter)
`learnFrom`	`string`		Name of a set of Auth instances from which forward zones must be learned (can be filtered using `include` and/or `exclude`) and to which traffic should be forwarded
`nta`	`boolean`	`false`	Add a negative trust anchor for the forwarded zones
`priority`	`integer`	`100`	Priority when the list of sets of forward zones has multiple entries containing duplicate static and/or learned zones, lowest value for priority has precedence
`recurse`	`boolean`	`false`	If true, set the recursion desired (RD) bit to 1 for the forwarded zones
`serverGroups`	List of ServerGroup		List of server groups to forward to. This can be a set of `auth` `recursor` or `resolver` instances
`zones`	List of `string`	`[]`	List of zones to be forwarded (not affected by `include` and `exclude`)

Forward Server Group

A server group is a reference to a set of instances of auth recursor or resolver to which traffic should be sent. Currently this is a simple configuration with 1 parameter group which should reference the name of an appropriate instance set:

recursors:
  myrecursor:
    forward:
      - serverGroups:
          - group: externalresolvers
        recurse: true
        zones:
          - "powerdns.com"

resolvers:
  externalresolvers:
    ips:
      - 8.8.8.8
      - 1.1.1.1
      - 8.8.4.4
      - 9.9.9.9

The above will create a forward configuration to match traffic for powerdns.com and forward it to the set of resolvers named externalresolvers with the RD bit set to 1 (ie: recursion desired).

HPA

Horizontal Pod Autoscaling (HPA) can be enabled by configuring the necessary parameters and setting enabled: true. For example:

recursors:
  myrecursor:
    hpa:
      enabled: true
      minReplicas: 2
      maxReplicas: 6
      metrics:
        - type: Resource
          resource:
            name: cpu
            target:
              type: Utilization
              averageUtilization: 70

Parameters which can be used to configure HPA:

Parameter	Type	Required	Default	Description
`behavior`	`k8s`HorizontalPodAutoscalerBehavior			Behavior of the Horizontal Pod Autoscaler
`enabled`	`boolean`	`yes`	`false`	If true, enable Horizontal Pod Autoscaling
`maxReplicas`	`integer`		`4`	Maximum number of replicas
`metrics`	List of `k8s`MetricSpec			Metric(s) upon which to make decisions regarding scaling
`minReplicas`	`integer`		`2`	Minimum number of replicas