Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 37 ยท Service Discovery

Registering Services with Consul

Register services with Consul using definition files, the CLI and the HTTP API. Learn service IDs, ports, addresses, anti-entropy and how to deregister cleanly.

A service is invisible to Consul until it is registered. Registration tells the cluster "there is a service called web, reachable at this address and port, with these tags". Once registered, it shows up in DNS answers, the catalog, the UI and the service mesh.

There are three ways to register: a definition file loaded by the agent, the CLI, and the HTTP API. The definitions are read-only on this site (no Consul to send them to); the stand-ins check definitions and model how the agent keeps the catalog in sync.

A service definition file

The most common production approach is a file dropped into the agent's config directory, for example /etc/consul.d/web.hcl:

HCL
service {
  name = "web"
  id   = "web-1"
  port = 8080
  tags = ["v2", "primary"]

  meta = {
    version = "2.4.1"
    owner   = "storefront-team"
  }

  check {
    name     = "HTTP health"
    http     = "http://127.0.0.1:8080/health"
    interval = "10s"
    timeout  = "2s"
  }
}

The same definition in JSON (also accepted, and common when generated by tools):

JSON
{
  "service": {
    "name": "web",
    "id": "web-1",
    "port": 8080,
    "tags": ["v2", "primary"],
    "meta": { "version": "2.4.1" }
  }
}

Fields:

Field Meaning
name The service name callers look up. Required. Use DNS-safe characters: lowercase letters, digits, hyphens
id Unique ID on this node; defaults to name. Needed when running several instances of one service on one machine
port The port the service listens on
address Service address. If omitted, the node's address is used
tags Free-form labels for filtering and DNS (v2.web.service.consul)
meta Key-value metadata, returned by the API but not used in DNS
check / checks Health checks attached to this service
weights How DNS weights instances for load spreading (see tags, meta and weights)

After placing the file, tell the agent to load it:

Terminal
$ consul validate /etc/consul.d/
$ consul reload

The CLI and the API

For quick experiments you can register from the command line:

Terminal
$ consul services register web.hcl
$ consul services register -name=cache -port=6379 -tag=redis
$ consul services deregister -id=web-1

The API call behind these is on the local agent:

Terminal
$ curl --request PUT --data @web.json \
       http://127.0.0.1:8500/v1/agent/service/register
$ curl --request PUT http://127.0.0.1:8500/v1/agent/service/deregister/web-1

Registering through the agent (not by writing straight to the catalog) matters: the agent owns the lifecycle. It runs the health checks for the service and keeps the catalog correct.

Agent versus catalog: anti-entropy

The agent holds the definitions of the local services and checks. Every so often (and on every change) it synchronizes them to the servers, a process called anti-entropy. If someone changes the catalog directly, the agent notices the difference and corrects it. Services whose agents have left the cluster are removed.

sequenceDiagram
  participant App as web app
  participant A as Local agent
  participant S as Server (catalog)
  App->>A: register web-1 (file or API)
  A->>S: sync service + check
  A->>A: run health checks
  A->>S: update check status
  Note over A,S: anti-entropy repeats the sync periodically

The agent is the source of truth for its local services.

Applications that start and stop frequently (containers) usually register at startup and deregister on shutdown. If the process dies without deregistering, a health check removes it from answers, and a deregister_critical_service_after setting on the check can delete it from the catalog after it has been failing for a while.

Stand-in 1: validate definitions

Consul validates definitions itself, but writing a checker shows what the rules are. This model enforces: a name is required and DNS-safe, the port is in range, IDs are unique per node, and an unsafe address is flagged.

Python Stand-in: check service definitions

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: anti-entropy

A model of how an agent corrects drift. The "catalog" has an extra service that nobody registered and is missing one that should exist; one sync pass repairs both.

Python Stand-in: agent catalog sync

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.

Registering several instances on one node

Two copies of web on one machine must have different IDs and ports:

HCL
service {
  name = "web"
  id   = "web-blue"
  port = 8081
}
service {
  name = "web"
  id   = "web-green"
  port = 8082
}

Both appear under the single name web, which is exactly what makes load spreading work.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why register through the local agent instead of writing directly to the catalog?

    The agent owns local services and checks and synchronizes them to the servers via anti-entropy.
  2. 2. When is the id field required?

    id defaults to name; two instances on one node would clash without distinct IDs.
  3. 3. What address do callers get if a service definition has no address?

    Without a service address Consul uses the node's address.
  4. 4. Which command makes the agent re-read configuration files after you add a service file?

    consul reload re-reads configuration, including service definitions, without a restart.

Summary

  • A service must be registered to be discoverable: by definition file, CLI or HTTP API.
  • Definitions have name, optional id, port, address, tags, meta and check blocks.
  • The local agent owns its services and syncs them to servers (anti-entropy).
  • Use unique IDs when running several instances on one node.
  • Deregister on shutdown and use health checks to remove crashed instances.

Next: Service Tags, Metadata and Weights