Migrate to the new DNS client

This guide walks you through migrating from the old DNS client to the new one. The new DNS client introduces a new standardized way to configure a service, and helps improve performance.

Migrate the DNS client configuration

Record types

The new DNS client introduces some changes in the support for different record types. To avoid issues, make sure that your SRV records configuration is compatible with the new client before migrating.

SRV

SRV is included by default in the resolver_family directive, however the client will only query SRV records if the domain name follows the RFC 2782 format (_<service>._<proto>.<name>). If the SRV record query fails, the client will not attempt to query the domain’s IP addresses (A and AAAA records) again.

Before enabling SRV support with the new DNS client, make sure that the domain name is registered with your DNS service provider in the supported format. This standard format also works with the old DNS. Once you change the SRV format, it will continue to work with the old client; there will no downtime during migration.

CNAME

CNAME dereferencing is not needed with the new DNS client. This task is entirely handled by the DNS server, as is the industry standard.

The new DNS client does not consider the order of record types when querying a domain. It only queries either IP addresses (A and AAAA records) or SRV records, but not both.

Custom directives

If you had custom values for the directives under DNS RESOLVER in kong.conf, you will need to manually add these values to the corresponding directives under New DNS RESOLVER.

Old DNS resolver directive	New DNS resolver directive	Comment
`dns_resolver`	`resolver_address`	Same behavior
`dns_hostsfile`	`resolver_hostsfile`	Same behavior
`dns_order`	`resolver_family`	The new directive is only used to define the supported query types, there is no a specific order.
`dns_valid_ttl`	`resolver_valid_ttl`	Same behavior
`dns_stale_ttl`	`resolver_stale_ttl`	Same behavior
`dns_not_found_ttl` and `dns_error_ttl`	`resolver_error_ttl`	The two directives are combined into a single one in the new client.
`dns_cache_size`	`resolver_lru_cache_size` and `resolver_mem_cache_size`	The old directive is split into two new ones: `resolver_lru_cache_size` is used to specify the size of the L1 LRU lua VM cache, and `resolver_mem_cache_size` the size of the L2 shared memory cache.
`dns_no_sync`	N/A	This directive no longer exists; requests are always synchronized in the new client.

Enable the new DNS client

The new DNS client is disabled by default. To enable it:

Uncomment the new_dns_client directive in your /etc/kong/kong.conf file.
Set the value to on.