Read endpoints from DNS

The dns sourceWhere a service reads its endpoints, one of dns, file, url or kubernetes. See Services and sources. turns DNS records into endpointsOne IP address and port that a service gives, with its load balancing weight. See HTTP API.. It suits services already published in DNS, by your own zones or by a registry such as Consul. This guide covers its three lookups and the resolver key. Consul has its own guide, Read Consul services.

type	Use it when
IP (default)	Every address of a name listens on the same port.
SRV	Each endpoint has its own port or weight, published as SRVA DNS record giving the host, port and weight of one instance of a service. See Read endpoints from DNS. records.
TXT	You want to write the endpoints in your zone without SRV, one eds= record each.

Serve the addresses of a name

With type: IP, Vigie looks up the A and AAAA records of name and gives each address on the default_port of the service, with a weight of 0.

config.yml

services
services
Type list · Required yes · Default none
Services the server answers for, at least one.:
  - name
services[].name
Type string · Required yes · Default none
Name clients ask for. A request without a name gets the service named default.: web
    default_port
services[].default_port
Type integer · Required no · Default 80
Port of the endpoints that don’t give their own.: 8080
    dns
services[].dns
Type object · Required one source · Default none
Reads the endpoints from DNS.:
      name
services[].dns.name
Type string · Required yes · Default none
DNS name to look up.: web.example.com

If web.example.com has the A records 10.0.0.5 and 10.0.0.6, the service gives 10.0.0.5:8080 and 10.0.0.6:8080.

Serve the targets of SRV records

With type: SRV, Vigie looks up _<srv_service>._<srv_proto>.<name>, then the addresses of each target. Each address takes the port and the weight of its record. A record with port 0 takes the default_port.

1. Publish the SRV records in your zone.

   _http._tcp.api.example.com. 300 IN SRV 10 5 8080 api-1.example.com.
   _http._tcp.api.example.com. 300 IN SRV 10 1 8080 api-2.example.com.

2. Point the service at them. srv_service and srv_proto default to http and tcp.

   config.yml

   services
   services
   Type list · Required yes · Default none
   Services the server answers for, at least one.:
     - name
   services[].name
   Type string · Required yes · Default none
   Name clients ask for. A request without a name gets the service named default.: api
       default_port
   services[].default_port
   Type integer · Required no · Default 80
   Port of the endpoints that don’t give their own.: 8080
       dns
   services[].dns
   Type object · Required one source · Default none
   Reads the endpoints from DNS.:
         name
   services[].dns.name
   Type string · Required yes · Default none
   DNS name to look up.: api.example.com
         type
   services[].dns.type
   Type string · Required no · Default IP
   IP, SRV or TXT, in any case.: SRV
         srv_service
   services[].dns.srv_service
   Type string · Required no · Default http with SRV
   Service part of the SRV lookup.: http
         srv_proto
   services[].dns.srv_proto
   Type string · Required no · Default tcp with SRV
   Protocol part of the SRV lookup.: tcp

The service gives each address of api-1.example.com with weight 5 and each address of api-2.example.com with weight 1, both on port 8080. Vigie ignores the priority of the records.

Write endpoints in TXT records

With type: TXT, Vigie reads the TXT records of name and keeps those that start with eds=. The rest of each record is an endpoint line, host[:port][#weight], so a TXT record can carry a port and a weight without SRV.

1. Publish one record per endpoint.

   db.example.com. 300 IN TXT "eds=10.0.1.10:5432#2"
   db.example.com. 300 IN TXT "eds=10.0.1.11:5432#1"
   db.example.com. 300 IN TXT "v=spf1 -all"

2. Point the service at the name.

   config.yml

   services
   services
   Type list · Required yes · Default none
   Services the server answers for, at least one.:
     - name
   services[].name
   Type string · Required yes · Default none
   Name clients ask for. A request without a name gets the service named default.: db
       default_port
   services[].default_port
   Type integer · Required no · Default 80
   Port of the endpoints that don’t give their own.: 5432
       dns
   services[].dns
   Type object · Required one source · Default none
   Reads the endpoints from DNS.:
         name
   services[].dns.name
   Type string · Required yes · Default none
   DNS name to look up.: db.example.com
         type
   services[].dns.type
   Type string · Required no · Default IP
   IP, SRV or TXT, in any case.: TXT

The service gives the two endpoints and skips the SPF record. Write IP addresses in the records, because Vigie doesn’t resolve the host of a line.

Query a given DNS server

Without resolver, Vigie uses the resolverThe DNS server a dns source queries over TCP instead of the resolver of the system. See Read endpoints from DNS. of the system. Set resolver to send every lookup of the service to one DNS server instead, the lookups of the SRV targets included:

config.yml

services
services
Type list · Required yes · Default none
Services the server answers for, at least one.:
  - name
services[].name
Type string · Required yes · Default none
Name clients ask for. A request without a name gets the service named default.: api
    default_port
services[].default_port
Type integer · Required no · Default 80
Port of the endpoints that don’t give their own.: 8080
    dns
services[].dns
Type object · Required one source · Default none
Reads the endpoints from DNS.:
      name
services[].dns.name
Type string · Required yes · Default none
DNS name to look up.: api.example.com
      type
services[].dns.type
Type string · Required no · Default IP
IP, SRV or TXT, in any case.: SRV
      resolver
services[].dns.resolver
Type host:port · Required no · Default empty
DNS server to query instead of the resolver of the system, such as 127.0.0.1:8600. An IPv6 address goes in brackets, [::1]:8600.: 10.0.0.53:53

Vigie then asks that server over TCP, which keeps a long answer whole where UDP could cut it, and gives up after 8 seconds. An IPv6 server goes in brackets, such as [fd00::53]:53.

Check the result

1. Check the file and reloadReading the configuration file again to replace the services, on SIGHUP or POST /reload. See Reload the services. the services, see Reload the services.

2. Ask for the service.

   curl -s 'http://localhost:8080/services?service_name=api'

A name that doesn’t resolve answers 500 with resolve service api failed: and the error of the lookup. Compare with dig, against the same server when you set resolver:

dig +tcp @10.0.0.53 -p 53 _http._tcp.api.example.com SRV

Vigie keeps each answer for cache_ttl, 5 seconds by default, whatever the TTL of the records. Configuration lists every key of the source.