Consul's HTTP API and Usage Methods

建议读者先学习笔者的另一篇文章 学习搭建 Consul 服务发现与服务网格-有丰富的示例和图片，这样了解 consul 大体的结构和学习集群搭建，摸清 consul 的服务注册发现配置方法。

本文 HTTP API 请求使用 postman 测试，读者可以打开 https://documenter.getpostman.com/view/5988188/TzCV4jqL 查看 HTTP 文档，并可直接导入 postman 测试。

Set Up Consul

Consul supports service registration and discovery for infrastructure (referred to as internal services), and also supports external services (such as third-party SAAS services and other environments where Consul agents cannot run, like redis).

You can install Consul directly using the command sudo apt-get install consul, or you can refer to another article by the author in the introduction, which details the installation methods.

Then we use the command to start Consul:

consul agent -dev -client 0.0.0.0 -enable-script-checks -node=web -ui

The above configuration allows connections from any IP to this Consul instance, -enable-script-checks enables simple ping-based health checks; -node names this Consul node as web, and enables UI access (-ui) at port 8500.

Note: For production environments, you should enable enable_script_checks = true in the Consul configuration file to persist the configuration.

Consul's HTTP API

The main interface of Consul is the Restful HTTP API, which can perform basic CRUD operations on nodes, services, checks, configurations, etc.

Official API documentation address: https://www.consul.io/api-docs/index

Consul has four types of HTTP APIs: agent, service, check, connect. The common API operations and parameter configurations will be introduced later.

Service API

Service-related APIs are under /v1/agent/service. Here is a list of these API endpoints (omitting /v1 for brevity).

• /agent/services: This endpoint returns all services registered in the local agent;
• /agent/service/{service_id}: Returns the full service definition of a single service instance registered on the local agent;
• /agent/health/service/name/{service_name}/ /agent/health/service/id/{service_id}: Retrieves the aggregated service status on the local agent by name or ID;
• /agent/service/register: Register a service;
• /agent/service/deregister/{service_id}: Deregister a service;
• /agent/service/maintenance/{service_id}: This endpoint places the specified service in "maintenance mode," marking the service as unavailable, and it will not appear in DNS or API queries;

Through these APIs, you can register and deregister services. Below will introduce how to use some essential APIs.

Simple Service Registration

This section introduces how to easily register a service and configure health checks via the HTTP API. We will learn step by step how to register services in Consul using native HTTP API requests, aiming for programming language independence.

Here is a configuration example provided by the official documentation for registering a service:

{
  "id": "web1",
  "name": "web",
  "port": 80,
  "check": {
    "name": "ping check",
    "args": ["ping", "-c1", "learn.hashicorp.com"],
    "interval": "30s",
    "status": "passing"
  }
}

Let's first understand the fields in this configuration.

The id is the unique identifier for this service, while name represents the logical name of this service; check is the health check configuration, which will be explained separately.

To register the service through the HTTP API, the request information is as follows (using curl command):

curl --location -g --request PUT 'http://{{consul}}:8500/v1/agent/service/register' \
--data-raw '{
  "id": "web1",
  "name": "web",
  "port": 80,
  "check": {
    "name": "ping check",
    "args": ["ping", "-c1", "learn.hashicorp.com"],
    "interval": "30s",
    "status": "passing"
  }
}'

If you want to check if the corresponding service is already registered, you can use /v1/catalog/service/{name} to query.

curl http://{{consul}}:8500/v1/catalog/service/web

Since we configured health checks, we can see detailed results in the UI.

Health Check Configuration and Query

Health check configuration:

  "check": {
    "name": "ping check",
    "args": ["ping", "-c1", "learn.hashicorp.com"],
    "interval": "30s",
    "status": "passing"
  }

The check object is used for health checks. The above configuration executes the ping command every 30s to check if learn.hashicorp.com is reachable, with status indicating the initial state of this service upon registration.

The args will eventually form a command: ping -c1 learn.hashicorp.com, where -c1 means to ping just once. If the ping fails, it prompts:

ping: learn.hashicorp.com: Temporary failure in name resolution

Consul supports various methods for monitoring checks, including Script, HTTP, TCP, Time to Live (TTL), Docker, and gPRC. For example, for HTTP checks, you can write the configuration like this:

      "Definition": {
        "http": "https://learn.hashicorp.com/consul/",
        "interval": "30s"
      }

If you want to obtain the health check results of all services on the local node, you can do so via an HTTP GET request to http://{{consul}}:8500/v1/agent/checks. The result is as follows:

{
    "service:web1": {
        "Node": "web",
        "CheckID": "service:web1",
        "Name": "ping check",
        "Status": "critical",
        "Notes": "",
        "Output": "ping: learn.hashicorp.com: Temporary failure in name resolution\n",
        "ServiceID": "web1",
        "ServiceName": "web",
        "ServiceTags": [],
        "Type": "script",
        "Definition": {},
        "CreateIndex": 0,
        "ModifyIndex": 0
    }
}

To query a specific service on a node, you can use:

/health/service/{name}

To query all services on a specific node, you can use:

/health/node/{name}

This article has relatively few contents and many APIs. There's no need to test all of them; you can pick some common ones to understand. Each programming language has corresponding libraries, and you don't need to write code based on the HTTP API, as you can directly call the SDKs provided by the official.