Skip to main content

​
What Is a Consul Service?

In HashiCorp Consul, a service represents any workload or application—web servers, microservices, databases, APIs, and more—that provides functionality within your infrastructure. Consul’s service discovery catalogs these services, enabling clients to locate them through DNS queries or HTTP API calls. Once registered, services can also discover their own dependencies.
The image is an infographic titled "What is a Service?" showing a service catalog and various components like web applications, microservices, databases, and APIs, connected through API requests and DNS queries.
Service registration occurs on the local Consul agent running beside your application. You can register services by:
  • Calling the Consul HTTP API
  • Placing a service definition file on disk
Most deployments automate this step: containers in Kubernetes, Terraform provisioning, or configuration-management tools invoke registration as part of setup. After registration, Consul immediately starts health checks, and only healthy instances receive traffic.
Consul automatically initiates health checks for each registered service. Ensure your checks are correctly configured to prevent unhealthy nodes from serving requests.

​
Service Registration Methods

Choose one of the following approaches to register services with your Consul agent:
MethodDescriptionUsage Example
HTTP APIRegister services programmatically via HTTP requestscurl -X PUT --data @payload.json https://consul.example.com:8500/v1/agent/service/register
Definition FileOn-disk configuration in HCL or JSONDrop files into /etc/consul.d/ or run consul services register /path/to/service.hcl
Agent ReloadReload updated definitions without restarting agentconsul reload

​
1. Register via the HTTP API

Send a PUT request to the agent’s registration endpoint with your service definition: 
curl --request PUT \
     --data @payload.json \
     https://consul.example.com:8500/v1/agent/service/register
Example payload (payload.json): 
{
  "Name": "retail-web",
  "Port": 8080
}
  • Name: A unique identifier for the service in Consul’s catalog.
  • Port: The TCP port on which the service listens on localhost.

​
2. Register via a Service Definition File

Service definitions can be authored in HCL or JSON. The Consul agent loads these files at startup or when reloaded:
  • Single config file
    Launch the agent with -config-file=/path/to/config.hcl to include both agent and service settings.
  • Config directory
    Place one or more .hcl or .json files into /etc/consul.d/. The agent reads all definitions at startup.
  • CLI registration 
    consul services register /path/to/service.hcl
  • Agent reload 
    consul reload
The image provides instructions on registering a service using a service definition file, with options for using .hcl or .json formats and commands like consul services register and consul reload.

​
Example: Registering Multiple Service Instances

In a high-availability setup, you might run identical web applications on three client nodes, each registering as retail-web. Each client uses the same service name and port but can differ in tags or health checks. For instance, on each node: 
consul services register /etc/consul.d/retail-web.hcl
After registration, Consul’s catalog lists all three instances. DNS queries such as: 
dig @127.0.0.1 -p 8600 retail-web.service.consul
or HTTP API calls return the healthy endpoints, enabling load balancing and failover across your infrastructure.

​
Further Reading

Watch Video