Skip to content
Tutorials Center
My learning

Topics

Lesson 10 of 37 ยท Service Discovery

The Catalog and Health HTTP APIs

Query Consul service discovery over HTTP: catalog versus health endpoints, passing filters, node lookups, filter expressions, external-service registration and client-side load balancing.

DNS is universal, but it only returns addresses and ports. When your code needs more (tags, metadata, the health of every check, the node it runs on), use the HTTP API. Two endpoint families do the work: catalog for what is registered, and health for what is registered and working.

The requests below are read-only examples. The stand-ins parse realistic (invented) replies and implement a tiny version of Consul's filter syntax.

Listing what exists

Terminal
$ curl http://127.0.0.1:8500/v1/catalog/services          # names and their tags
$ curl http://127.0.0.1:8500/v1/catalog/nodes             # all nodes
$ curl http://127.0.0.1:8500/v1/catalog/service/web       # every instance of web
$ curl http://127.0.0.1:8500/v1/catalog/node/web-1        # a node and its services
$ curl http://127.0.0.1:8500/v1/catalog/datacenters       # known datacenters

/v1/catalog/services returns an object mapping each service name to its list of tags. /v1/catalog/service/<name> returns one entry per instance, with Node, Address, ServiceID, ServiceName, ServiceAddress, ServicePort, ServiceTags and ServiceMeta. Remember: the catalog does not care about health; a crashed instance is listed until it is deregistered.

Asking for healthy instances

Terminal
$ curl "http://127.0.0.1:8500/v1/health/service/web"            # all, with checks
$ curl "http://127.0.0.1:8500/v1/health/service/web?passing"    # only passing
$ curl "http://127.0.0.1:8500/v1/health/service/web?passing&tag=v2"
$ curl "http://127.0.0.1:8500/v1/health/checks/web"             # the checks only
$ curl "http://127.0.0.1:8500/v1/health/state/critical"         # every failing check
$ curl "http://127.0.0.1:8500/v1/health/node/web-1"             # checks on a node

Each item from /v1/health/service/web has three parts: Node (the machine), Service (the instance definition) and Checks (a list with Status set to passing, warning or critical). ?passing keeps instances whose checks all pass. This is the endpoint client-side load balancers should use.

Filtering on the server

Add filter= with an expression to narrow results without downloading everything:

Terminal
$ curl -G http://127.0.0.1:8500/v1/health/service/web \
    --data-urlencode 'filter=Service.Tags contains "v2" and Service.Meta.owner == "billing"' \
    --data-urlencode 'passing=true'

Expressions can use ==, !=, contains, in, not, and, or, and match on selectors that follow the field names of the reply (such as Service.Port or Node.Meta.region). Names are case-sensitive, and quoting inside shell commands needs care, so URL-encode with --data-urlencode.

Other helpful parameters: near=_agent sorts instances by network distance to the answering agent, node-meta=region:eu filters nodes by their metadata, and dc= targets another datacenter.

Registering things that Consul cannot see

An agent can only register its own local services. For something outside the cluster (a managed database, a SaaS endpoint) you can register an external service directly in the catalog:

Terminal
$ curl --request PUT http://127.0.0.1:8500/v1/catalog/register --data '{
  "Node": "legacy-db",
  "Address": "192.0.2.50",
  "NodeMeta": { "external-node": "true", "external-probe": "true" },
  "Service": { "Service": "orders-db", "Port": 5432 }
}'

Callers then resolve orders-db.service.consul like any other service. Health for external services is not checked by an agent; the external-probe node-meta flag makes Consul servers probe it in newer versions, or you can update check results through the API. Remove it again with PUT /v1/catalog/deregister.

A simple client-side load balancer

Clients commonly poll the health endpoint, then rotate through the results:

  1. GET /v1/health/service/web?passing (or a blocking query for efficiency, see watches and blocking queries).
  2. Take Service.Address if it is not empty, otherwise Node.Address, together with Service.Port.
  3. Rotate or randomize through the list; retry another instance on failure.
  4. Refresh the list periodically and when connections fail.

Stand-in 1: read a health reply

The data is invented but uses Consul's real field layout. The program keeps only passing instances and returns host:port pairs, exactly as a client library would.

Python Stand-in: healthy endpoints from a reply

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in 2: a mini filter

This implements a small subset of the filter language (one comparison or contains, joined by and) to show how selectors walk the reply. Consul's real parser is far more complete.

Python Stand-in: evaluate filter expressions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Catalog or health: which one?

Need Endpoint
Inventory, audits, dashboards /v1/catalog/...
Choose where to send traffic /v1/health/service/<name>?passing
Find what is failing /v1/health/state/critical
Details of one agent's own services /v1/agent/services

Prefer the agent endpoints (/v1/agent/...) for information about the local machine. They answer from memory without a trip to the servers, so they are fast and keep working even if the servers are briefly unreachable.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which endpoint should a load balancer poll to get only instances that are working?

    The health endpoints include check results, and ?passing filters to healthy instances.
  2. 2. What does an empty ServiceAddress in a catalog entry mean?

    Without a service-specific address, clients use the node address.
  3. 3. How can you register a managed database that cannot run a Consul agent?

    The catalog register endpoint accepts a node and service directly; it is meant for external services.
  4. 4. What does near=_agent do?

    near sorts instances by estimated round-trip time from the named node; _agent means the agent you queried.

Summary

  • /v1/catalog/... lists what is registered; /v1/health/... adds check status.
  • Use /v1/health/service/<name>?passing for traffic decisions.
  • filter= expressions, near, tag, node-meta and dc narrow results server-side.
  • External services can be added with /v1/catalog/register.
  • Clients take Service.Address or fall back to Node.Address, plus Service.Port.

Next: Prepared Queries and Failover