Register services and health checks

This topic describes how to register services and health checks with Consul in networks running on virtual machines (VM). Refer to Define Services and Define Health Checks for information about how to define services and health checks.

Overview

Register services and health checks in VM environments by providing the service definition to a Consul agent. You can use several different methods to register services and health checks.

• Start a Consul agent and pass the service definition in the agent's configuration directory.
• Reload the a running Consul agent and pass the service definition in the agent's configuration directory. Use this method when implementing changes to an existing service or health check definition.
• Use the consul services register command to register new service and health checks with a running Consul agent.
• Call the /agent/service/register HTTP API endpoint to to register new service and health checks with a running Consul agent.
• Call the /agent/check/register HTTP API endpoint to register a health check independent from the service.

When a service is registered using the HTTP API endpoint or CLI command, the checks persist in the Consul data folder. If the agent restarts, Consul uses the service and check configurations in the configuration directory to start the services.

Note that health checks associated with a service are application-level checks.

Start an agent

We recommend registering services on startup because the service persists if the agent fails. Specify the directory containing the service definition with the -config-dir option on startup. When the Consul agent starts, it processes all configurations in the directory and registers any services contained in the configurations. In the following example, the Consul agent starts and loads the configurations contained in the configs directory:

$ consul agent -config-dir configs

Refer to Starting the Consul Agent for additional information.

Reload an agent

Store your service definition file in the directory containing your Consul configuration files and either send a SIGHUP signal to the Consul agent service or run the consul reload command. Refer to Consul Reload for additional information.

Register using the CLI

Run the consul services register command and specify the service definition file to register the services and health checks defined in the file. In the following example, a service named web is registered:

$ consul services register -name=web services.hcl

Refer to Consul Agent Service Registration for additional information about using the command.

Register using the API

Use the following methods to register services and health checks using the HTTP API.

Register services

Send a PUT request to the /agent/service/register API endpoint to dynamically register a service and its associated health checks. To register health checks independently, call the checks API endpoint.

The following example request registers the service defined in the service.json file.

$ curl --request PUT --data @service.json http://localhost:8500/v1/agent/service/register

Refer to Service - Agent HTTP API for additional information about the services endpoint.

Register health checks

Send a PUT request to the /agent/check/register API endpoint to dynamically register a health check to the local Consul agent. The following example request registers a health check defined in a payload.json file.

$ curl --request PUT --data @payload.json http://localhost:8500/v1/agent/check/register

Refer to Check - Agent HTTP API for additional information about the check endpoint.