Read Consul services

Consul answers DNS for the services it knows, so the dns source reads them without a Consul-specific sourceWhere a service reads its endpoints, one of dns, file, url or kubernetes. See Services and sources.. Each instance gives one endpointOne IP address and port that a service gives, with its load balancing weight. See HTTP API., with the port it registered and its weight.

Before you start

You need a Consul agent that Vigie can reach, with its DNS interface on, by default on port 8600.

Set up the Consul agent

Two settings of the dns_config block of the agent change what Vigie sees:

consul.hcl

dns_config {
  only_passing    = true
  enable_truncate = true
}

• only_passing = true keeps only the instances whose checks pass. By default, Consul DNS leaves out the instances whose checks are critical but keeps those in warning, and Vigie would hand them to its clients.
• enable_truncate = true matters when Vigie goes through 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 rather than resolver. Over UDP, Consul cuts a long answer to a few records without telling the client, so a service with many instances would lose some of them. With resolver, Vigie asks over TCP and gets every record.

Read a service

Point a dns service with type: SRV at the DNS port of the agent:

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.: payments
    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.: service.consul
      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.: payments
      srv_proto
services[].dns.srv_proto
Type string · Required no · Default tcp with SRV
Protocol part of the SRV lookup.: tcp
      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.: 127.0.0.1:8600

This looks up _payments._tcp.service.consul, the RFC 2782 form of Consul. Each instance gives one endpoint, with the port it registered and its weight Weights.Passing, which is 1 when the instance registered none.

Instead of resolver, the host can forward the .consul domain to the agent, with dnsmasq or systemd-resolved for instance. Leave resolver empty then, and set enable_truncate on the agent.

Keep only the instances with a tag

Put the tag in place of tcp. With srv_proto: primary, Vigie looks up _payments._primary.service.consul and gets only the instances tagged primary.

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.: payments-primary
    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.: service.consul
      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.: payments
      srv_proto
services[].dns.srv_proto
Type string · Required no · Default tcp with SRV
Protocol part of the SRV lookup.: primary
      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.: 127.0.0.1:8600

Read another datacenter

Put the datacenter in the name. name: service.dc2.consul reads the instances of the datacenter dc2.

Check the result

Compare what Consul answers with what Vigie serves:

dig +tcp @127.0.0.1 -p 8600 _payments._tcp.service.consul SRV
curl -s 'http://localhost:8080/services?service_name=payments'

A service unknown to Consul makes the lookup fail, and Vigie answers 500 with resolve service payments failed: and the error.