How to Use Consul for Service Discovery in Microservices

Use Consul by registering your services with it and then querying Consul to discover service locations dynamically. Services register themselves with Consul agent, and clients query Consul's DNS or HTTP API to find healthy service instances.

Syntax

Consul service discovery involves two main steps: service registration and service discovery.

• Service Registration: Services register with Consul by sending their name, ID, address, port, and health check info to the Consul agent.
• Service Discovery: Clients query Consul using DNS or HTTP API to get the list of healthy service instances.

bash

curl --request PUT --data '{
  "ID": "service1",
  "Name": "web",
  "Address": "10.0.0.1",
  "Port": 8080,
  "Check": {
    "HTTP": "http://10.0.0.1:8080/health",
    "Interval": "10s"
  }
}' http://localhost:8500/v1/agent/service/register

curl http://localhost:8500/v1/health/service/web?passing=true

Example

This example shows how to register a service named web with Consul and then query for healthy instances.

bash

curl --request PUT --data '{
  "ID": "web1",
  "Name": "web",
  "Address": "192.168.1.100",
  "Port": 5000,
  "Check": {
    "HTTP": "http://192.168.1.100:5000/health",
    "Interval": "10s"
  }
}' http://localhost:8500/v1/agent/service/register

curl http://localhost:8500/v1/health/service/web?passing=true

Output

[
  {
    "Node": {
      "Node": "node1",
      "Address": "192.168.1.100"
    },
    "Service": {
      "ID": "web1",
      "Service": "web",
      "Address": "192.168.1.100",
      "Port": 5000
    },
    "Checks": [
      {
        "Status": "passing"
      }
    ]
  }
]

Common Pitfalls

• Not registering health checks causes Consul to mark services as unhealthy or unavailable.
• Forgetting to update service address or port when they change leads to stale data.
• Querying without filtering for passing health checks returns unhealthy instances.
• Running multiple Consul agents without proper configuration can cause inconsistent service data.

bash

curl --request PUT --data '{
  "ID": "web1",
  "Name": "web",
  "Address": "192.168.1.100",
  "Port": 5000
}' http://localhost:8500/v1/agent/service/register

# This registers without health check, which is bad

# Correct way includes health check:

curl --request PUT --data '{
  "ID": "web1",
  "Name": "web",
  "Address": "192.168.1.100",
  "Port": 5000,
  "Check": {
    "HTTP": "http://192.168.1.100:5000/health",
    "Interval": "10s"
  }
}' http://localhost:8500/v1/agent/service/register

Quick Reference

• Register Service: Use HTTP PUT to /v1/agent/service/register with JSON payload.
• Health Checks: Always include health checks for reliable discovery.
• Discover Services: Query /v1/health/service/{service-name}?passing=true to get healthy instances.
• Use DNS: Consul also supports DNS queries like web.service.consul.

Key Takeaways

Register services with Consul including health checks for accurate discovery.

Query Consul's HTTP API or DNS to find healthy service instances dynamically.

Always filter queries to only include passing health checks to avoid unhealthy services.

Keep service registration data updated to prevent stale or incorrect service info.

Run Consul agents properly configured to maintain consistent service state.