consul 的 HTTP API 和使用方法

目录

• • 搭建起 consul
  • Consul 的 HTTP API
• Service API
  • 简单地注册服务
  • 健康检查的配置和查询

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

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

搭建起 consul

Consul 支持基础结构的服务注册和发现(称为内部服务)，也支持外部服务(第三方 SAAS服务以及无法直接运行 Consul 代理的其它环境，例如 redis)。

直接使用 sudo apt-get install consul命令即可安装 consul，你也可以参考导读中笔者的另一篇文章，里面提到了详细的安装方法。

然后我们使用命令启动 consul：

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

上面配置指定了允许任何 ip 连接到此 consul，-enable-script-checks 开启 consul 进行简单的基于 ping 的运行状况检查；-node 命名此 consul 节点名称为 web，并开启 UI(-ui)访问(端口8500)。

注：如果是生产环境，则应在 consul 的配置文件中启用 enable_script_checks = true，以持久化配置。

Consul 的 HTTP API

Consul 的主要接口是 Restful HTTP API，这些 API 可以对节点、服务、检查、配置等对象执行基本的 CRUD 操作。

官方 API 文档地址：https://www.consul.io/api-docs/index

在 consul 中，有四类 HTTP API，agent、service、check、connect，后面会介绍这些 API 中常用 API 的操作和参数配置。

Service API

Service 相关的 API 都在 /v1/agent/service 下，这里来列一下这些 API 地址(省略了/v1)，凑些字数。

• /agent/services：该端点返回在本地代理程序中注册的所有服务；
• /agent/service/{service_id}：返回在本地代理上注册的单个服务实例的完整服务定义；
• /agent/health/service/name/{service_name}/ /agent/health/service/id/{service_id}：通过名称或id检索本地代理上的聚合服务状态；
• /agent/service/register：注册服务；
• /agent/service/deregister/{service_id} ：注销服务；
• /agent/service/maintenance/{service_id}：该端点将给定的服务置于“维护模式”，在维护模式下，该服务将被标记为不可用，并且不会出现在DNS或API查询中；

通过这些 API，可以注册服务以及注销服务，下面介绍一下一些只要的 API 的使用方法。

简单地注册服务

本小节介绍通过 HTTP API 方式，简单注册一个服务并配置健康检查，接下来我们将使用 HTTP API 原生请求的方式，一步步了解 consul 中如何注册服务，并了解一些参数的使用，这里尽量做到与编程语言无关。

这是官方文档给出的一个注册服务的配置示例：

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

我们先来了解一下这个配置的字段。

id 为这个服务的唯一标记，而 name 表示此服务的逻辑名称； check 是健康检查的配置，后面会单独介绍。

通过 HTTP API 注册服务，请求的信息如下(curl命令)：

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"
  }
}
'

如果要查询相应的服务是否已经注册，则可使用 /v1/catalog/service/{name} 查询。

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

由于我们配置了健康检查，可以在 UI 上看到详细结果。

健康检查的配置和查询

健康检查配置：

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

check 对象用于运行状况检查，上面的配置就是每 30s 执行 ping 命令，检查 learn.hashicorp.com 是否可以访问，status 表示注册时此服务的初始状态。

args 最终会组合成一条命令： ping -c1 learn.hashicorp.com， -c1 即表示只 ping 1次。ping 失败时提示：

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

Consul 支持 Script, HTTP, TCP, Time to Live (TTL), Docker, and gPRC 等方式进行监控检查，例如 HTTP 形式，可以这样写配置：

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

如果要获得读取本地节点上所有服务的运行状况检查结果，则可以直接通过 HTTP GET 请求 http://{{consul}}:8500/v1/agent/checks 获得。结果如下：

{
    "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
    }
}

如果要单独查询节点上的某个服务，可以使用：

/health/service/{name}

如果要查询某个节点上的所有服务，可以使用：

/health/node/{name}

本文内容较少，API 较多，不需要全部都测试一次，可以挑一些常用的了解即可。不同编程语言都有相应的库，不需要基于 HTTP API 编写代码，可以直接调用官方提供的 SDK。