In the Run the Consul Agent tutorial, you ran a local Consul agent, and checked for other members of the datacenter. In this tutorial, you will start using Consul by registering a service and a health check.
One of the major use cases for Consul is service discovery. Consul provides a DNS interface that downstream services can use to find the IP addresses of their upstream dependencies.
Consul knows where these services are located because each service registers with its local Consul client. Operators can register services manually, configuration management tools can register services when they are deployed, or container orchestration platforms can register services automatically via integrations.
In this tutorial, you'll register a service and health check manually by providing Consul with a configuration file, and use Consul to discover its location using the DNS interface and HTTP API. Manually registering a service will help you understand the information that your automation tooling will ultimately need to provide Consul in order to take advantage of service discovery.
»Define a service
You can register services either by providing a service definition, which is the most common way to register services, or by making a call to the HTTP API. Here you will use a service definition.
First, create a directory for Consul configuration. Consul loads all
configuration files in the configuration directory, so a common convention on
Unix systems is to name the directory something like /etc/consul.d
(the .d suffix implies "this directory contains a set of configuration
files").
Next, create a file called web.json in the consul.d directory. This will
be the service definition configuration file. Copy the JSON below into the
web.json file.
This configuration defines a service named "web" which runs on port 80. It also defines a tag, "rails", which can be used to locate the service.
Now, restart the agent, using command line flags to specify the configuration directory and enable script checks on the agent.
Security Warning: Enabling script checks in some configurations may
introduce a remote execution vulnerability which is known to be targeted by
malware. In production we strongly recommend -enable-local-script-checks
instead.
You'll notice in the output that Consul "synced" the web service. This means that the agent loaded the service definition from the configuration file, and has successfully registered it in the service catalog.
Note: We never started a web service in this example. Consul can register services that aren't running yet. It correlates each running service with its registration based on the service's port.
In a multi-agent Consul datacenter, each service would register with its local Consul client, and the clients would forward the registration to the Consul servers, which maintain the service catalog.
If you wanted to register multiple services, you could create multiple service definition files in the Consul configuration directory.
»Query services
Once the agent adds the service to Consul's service catalog you can query it using either the DNS interface or HTTP API.
»DNS interface
First query the web service using Consul's DNS interface. The DNS name for a
service registered with Consul is NAME.service.consul, where NAME is the
name you used to register the service (in this case, web). By default, all DNS
names are in the consul namespace, though
this is configurable.
The fully-qualified domain name of the web service is web.service.consul.
Query the DNS interface (which Consul runs by default on port 8600) for the
registered service.
As you can verify from the output, an A record was returned containing the IP
address where the service was registered. A records can only hold IP addresses.
Tip: Since we started consul with a minimal configuration, the A
record will return local host (127.0.0.1). Set the Consul agent -advertise
argument or the address field in the service definition if you want to
advertise an IP address that is meaningful to other nodes in the datacenter.
You can also use the DNS interface to retrieve the entire address/port pair as a
SRV record.
The SRV record says that the web service is running on port 80 and exists on
the node Judiths-MBP.lan.node.dc1.consul.. An additional section is returned
by the DNS with the A record for that node.
Finally, you can also use the DNS interface to filter services by tags. The
format for tag-based service queries is TAG.NAME.service.consul. In
the example below, you'll ask Consul for all web services with the "rails"
tag. You'll get a successful response since you registered the web service with
that tag.
»HTTP API
In addition to the DNS interface, you can also query for the service using the HTTP API.
The HTTP API lists all nodes hosting a given service. As you will confirm later when we discuss health checks, you'll typically want to filter your query for only healthy service instances, which DNS does automatically under the hood. Filter your HTTP API query to look for only healthy instances.
»Update services
Next you'll update the web service by registering a health check for it.
Remember that because you never started a service on port 80 where you
registered web, the health check you register will fail.
You can update service definitions without any downtime by changing the service
definition file and sending a SIGHUP to the agent or running consul reload.
Alternatively, you can use the HTTP API to add, remove, and modify services
dynamically. In this example, you will update the registration file.
First, edit the registration file by running the following command. Copy and
paste the whole code block (excluding the $) into your terminal.
The 'check' stanza of this service definition adds a script-based health check that tries to connect to the web service every 10 seconds via curl. Script based health checks run as the same user that started the Consul process.
If the command exits with an exit code >= 2, then the check will fail and Consul will consider the service unhealthy. An exit code of 1 will be considered as warning state.
Now reload Consul's configuration to make it aware of the new health check.
Notice the following lines in Consul's logs, which indicate that the web check is critical.
Consul's DNS server only returns healthy results. Query DNS for the web service again. It shouldn't return any IP addresses since web's health check is failing.
Notice that there is no answer section in the response, because Consul has marked the web service as unhealthy.
»Next steps
In this tutorial, you registered a service with Consul and learned how to query it using the HTTP API and DNS interface. You also added a script based health check for the service.
Continue to the Secure Service Communication with Consul Service Mesh and Envoy tutorial to learn how to enable Consul service mesh. Consul service mesh lets you secure and observe network traffic between your services, as well as allow or deny inter-service communication.
