HashiCorp Certified: Consul Associate Certification
Register Services and Use Service Discovery
Creating a Service Definition
A service definition is a JSON file that the Consul agent uses to register your application in the Consul catalog. Once registered—and if any defined health checks pass—the service is discoverable by other nodes and can receive traffic. Failed health checks mark the service as unhealthy in the registry, and Consul will not return it in queries until it recovers.
Service Definition Parameters
You can customize a service definition with the following fields:
Parameter | Description | Example |
---|---|---|
id | Unique identifier for this service instance (defaults to name ) | web-server-01 |
name | Logical service name (DNS-compliant) [required] | front-end-ecommerce |
tags | Optional metadata to filter queries (e.g., version, environment) | ["v7.05","production"] |
address | IP address where the service listens (defaults to agent’s bind address) | 10.3.13.112 |
port | Port on which the service is running | 8080 |
checks | Array of health checks (script, HTTP, TCP, etc.) | See below |
Note
Only the name
field is required. If you omit id
, Consul uses the value of name
. Explicitly setting id
helps avoid collisions when running multiple instances.
Example Service Definition
{
"service": {
"id": "web-server-01",
"name": "front-end-ecommerce",
"tags": ["v7.05", "production"],
"address": "10.3.13.112",
"port": 8080,
"checks": [
{
"args": ["/usr/local/bin/check_mem.py"],
"interval": "30s"
}
]
}
}
Field Breakdown
- id: Unique per instance (e.g.,
web-server-01
,web-server-02
). - name: Service identifier for discovery (e.g.,
front-end-ecommerce
). - tags: Filterable attributes like
v7.05
orproduction
. - address: Interface IP for the service (agent bind address if omitted).
- port: Network port (e.g.,
8080
for HTTP). - checks: Health checks; here, a memory-check script running every 30 seconds.
Warning
If health checks continually fail, the service remains in the catalog but marked unhealthy—it will not receive traffic until the check passes.
Discovery via DNS
Consul exposes services under the service.consul
domain. Only healthy instances are returned:
dig A front-end-ecommerce.service.consul
;; ANSWER SECTION:
front-end-ecommerce.service.consul. 0 IN A 10.3.13.112
High Availability and Elasticity
Registering multiple instances under the same name
delivers:
- High availability: Traffic shifts to other healthy nodes if one fails.
- Elasticity: Scale instances up or down to match load and optimize resource usage.
Next Steps
- Save your JSON definition in the Consul agent’s configuration directory (e.g.,
/etc/consul.d/
). - Reload or restart the Consul agent:
consul reload # For HCL- or JSON-based configs consul agent restart
- Verify registration and health status:
consul catalog services consul health node web-server-01
Links and References
Watch Video
Watch video content