HashiCorp Certified: Consul Associate Certification

Register Services and Use Service Discovery

Demo Working with Health Checks

In this tutorial, we’ll walk through enhancing a Consul service definition by adding a TCP health check. You will learn how to:

  • Register a basic Consul service
  • Add a TCP health check on port 80
  • Observe and interpret the service’s health status in the Consul UI

Prerequisites
You need a running Consul agent and an Apache HTTP server on your node.


Registering a Basic Consul Service

First, create a minimal service definition and register it with Consul.

# Open the service definition file
ec2-user@ip-10-0-101-177:~$ vi service.json

# Register the service
ec2-user@ip-10-0-101-177:~$ consul services register service.json
Registered service: front-end-eCommerce

Simulate a service restart to see how Consul handles temporary outages:

ec2-user@ip-10-0-101-177:~$ sudo systemctl stop httpd
ec2-user@ip-10-0-101-177:~$ sudo systemctl start httpd

When you’re done, deregister the service:

ec2-user@ip-10-0-101-177:~$ consul services deregister service.json
Deregistered service: web-server-01

Note

The basic service definition offers no health checks, so Consul assumes it is always healthy.


Adding a TCP Health Check

To ensure only healthy instances are returned by service discovery, update the definition to include a TCP health check on port 80. Save the following as service-with-health.json:

{
  "node_name": "web-server-01",
  "service": {
    "id": "web-server-01",
    "name": "front-end-eCommerce",
    "tags": ["v7.05", "production"],
    "address": "10.0.101.177",
    "port": 80,
    "check": {
      "id": "web",
      "name": "Check web on port 80",
      "tcp": "localhost:80",
      "interval": "10s",
      "timeout": "1s"
    }
  }
}

Register the enhanced service:

ec2-user@ip-10-0-101-177:~$ consul services register service-with-health.json
Registered service: front-end-eCommerce

Warning

Until the first TCP check passes, Consul marks the service as failing and will not return it in discovery queries.


Observing Health Check Status

  1. Open the Consul UI.
  2. Look for the front-end-eCommerce entry under Services.
  3. If the check is still pending or failing, you’ll see a red “X” icon.

After approximately 10 seconds, Consul performs the TCP check against localhost:80. A successful connection flips the status to passing, indicated by a green checkmark.

Simulating Failure and Recovery

To test Consul’s failure detection:

ec2-user@ip-10-0-101-177:~$ sudo systemctl stop httpd

Within the next interval, the Consul UI shows the failure details:

Check NameStatusOutput
Check web on port 80faileddial tcp 127.0.0.1:80: connect: connection refused
Serf Health StatuspassingAgent alive and reachable

Restart Apache to restore health:

ec2-user@ip-10-0-101-177:~$ sudo systemctl start httpd

After the next 10-second interval, the TCP check passes and Consul marks the service as healthy again.


Service Definition Comparison

FeatureBasic DefinitionWith TCP Health Check
check blockNot presentPresent with tcp, interval, timeout
Initial health statusAlways passingMarked failing until first check
Service discoverabilityImmediateDelayed until healthy

Watch Video

Watch video content

Practice Lab

Practice lab

Previous
Configuring Service Health Checks