Skip to main content
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:
ParameterDescriptionExample
idUnique identifier for this service instance (defaults to name)web-server-01
nameLogical service name (DNS-compliant) [required]front-end-ecommerce
tagsOptional metadata to filter queries (e.g., version, environment)["v7.05","production"]
addressIP address where the service listens (defaults to agent’s bind address)10.3.13.112
portPort on which the service is running8080
checksArray of health checks (script, HTTP, TCP, etc.)See below
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 or production.
  • 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.
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.
The image illustrates the concept of creating a service definition with multiple nodes providing the same service, emphasizing high availability and elasticity. It shows an API request and response process, highlighting that only registered services passing health checks are returned.

​
Next Steps

  1. Save your JSON definition in the Consul agent’s configuration directory (e.g., /etc/consul.d/).
  2. Reload or restart the Consul agent: 
    consul reload      # For HCL- or JSON-based configs
consul agent restart
  3. Verify registration and health status: 
    consul catalog services
consul health node web-server-01

Watch Video