Consul API

目录

注: 内容翻译自官网，部分内容省略

一、ACLs

    ACL介绍：https://www.consul.io/docs/guides/acl.html

    1.1 启动ACL

二、Agent

    /agent节点是用来和本地Consul agent交互的。通常情况下，服务和检查在agent上注册，agent负责集群中的数据同步。例如，agent会在Catalog中注册服务和检查，执行anti-entropy并完成终端恢复。

2.1 基础请求

2.1.1 列出集群成员

    这个节点会返回这个agent在gossip池中感知到的所有成员。由于gossip协议的特性，这个请求是最终一致的，即不同agent在同一时间看到的结果也可能不同。节点的强一致性请求由/v1/catalog/nodes提供。

Method	Path	Produces
GET	/agent/members	application/json

2.1.1.1 参数

1. wan（参数类型Boolean）：用于指定返回WAN成员还是LAN成员。仅对以server模式运行的agent有效。以URL中的查询参数提交

2. segment（参数类型String）：用于指定返回成员的网络segment

2.1.1.2 简单请求

$ curl \

https://consul.rocks/v1/agent/members

curl localhost:8500/v1/agent/members

[

    {

        "Name": "lulijun.local",

        "Addr": "127.0.0.1",

        "Port": 8301,

        "Tags": {

            "build": "0.7.2:'a9afa0c",

            "dc": "dc1",

            "port": "8300",

            "role": "consul",

            "vsn": "2",

            "vsn_max": "3",

            "vsn_min": "2"

        },

        "Status": 1,

        "ProtocolMin": 1,

        "ProtocolMax": 5,

        "ProtocolCur": 2,

        "DelegateMin": 2,

        "DelegateMax": 4,

        "DelegateCur": 4

    }

]

2.1.2 读取配置

    这个端点返回本地agent的配置项和成员。返回结果中的Config元素包含了一系列的配置项子集，并且版本会向后兼容。DebugConfig包含了全部的运行时配置项但是格式可能在之后的版本中废弃或是改变。

Method	Path	Produces
GET	/agent/self	application/json

2.1.2.1 请求示例

$ curl \

https://consul.rocks/v1/agent/self

curl localhost:8500/v1/agent/members

2.1.3 重新加载Agent

    此端点会让agent重新加载配置。错误直接返回。不是所有的配置都会重新加载，具体参考https://www.consul.io/docs/agent/options.html#reloadable-configuration

Method	Path	Produces
PUT	/agent/reload	application/json

2.1.3.1 请求示例

$ curl \

    --request PUT \

https://consul.rocks/v1/agent/reload

2.1.4 开启维护模式

    这个端点会让agent的状态置为“维护模式”。维护模式下，节点会被标记不可用，不会出现在查询请求中。这个API是幂等的。

    维护模式是持久的，会在agent重启时恢复。

Method	Path	Produces
PUT	/agent/maintenance	application/json

2.1.4.1 参数

1. enable（Boolean）：指定是否开启维护模型

2. reason（String）：开启维护模式的说明

2.1.4.2 请求示例

$ curl \

    --request PUT \

https://consul.rocks/v1/agent/maintenance?enable=true&reason=For+API+docs

2.1.5 查看指标

    返回本地agent的配置和成员信息

Method	Path	Produces
GET	/agent/metrics	application/json

2.1.5.1 请求示例

$ curl \

https://consul.rocks/v1/agent/metrics

2.1.6 流式日志

    这个端点持续打印本地agent的日志，直到连接断开。

Method	Path	Produces
GET	/agent/monitor	application/json

2.1.6.1 参数

1. loglevel（String）：指定日志级别

2.1.7 join agent

    这个端点会让agent尝试连接指定地址的其他agent

Method	Path	Produces
PUT	/agent/join/:address	application/json

2.1.7.1 参数

1. address（String）：指定要join的agent地址

2. wan（Boolean）：指定是否通过WAN pool来进行join

2.1.7.2 请求示例

$ curl \

https://consul.rocks/v1/agent/join/1.2.3.4

2.1.8 优雅退出和关闭

    这个端点会触发agent的优雅退出和关闭。让其他节点能感知到当前节点的“退出”而不是“失败”。离开的节点将不会从快照重启集群。

2.1.8.1 请求示例

$ curl \

    --request PUT \

https://consul.rocks/v1/agent/leave

2.1.9 强制退出和关闭

    这个端点会让agent将一个节点的状态强制转换为离开的状态。

Method	Path	Produces
PUT	/agent/force-leave	application/json

2.1.9.1 请求示例

$ curl \

    --request PUT \

https://consul.rocks/v1/agent/force-leave

2.1.10 更新ACL Token

2.2 Agent-Check相关请求

    /agent/check端点和Consul中本地agent进行check相关的交互。不要和Catalog中的check搞混了。

2.2.1 列出check

    这个端点会列出所有注册到本地agent的check。这个check要么是通过配置文件注册的，要么是通过HTTP API注册的。

    注意，agent感知到的check和catalog报告的check可能会有不同之处。这通常是在没有选举出leader时的变动造成的。agent执行了anti-entropy，所以在大多数情况下信息会在几秒之内同步。

Method	Path	Produces
GET	/agent/checks	application/json

2.2.1.1 请求示例

$ curl \

https://consul.rocks/v1/agent/checks

2.2.2 注册check

    这个端点用来在本地agent上增加一个新的check。Check支持script，HTTP, TCP 以及TTL类型。agent负责管理check的状态以及同步信息到Catalog中。

Method	Path	Produces
PUT	/agent/check/register	application/json

2.2.2.1 参数

1. Name（String）：指定check名称

2. ID（String）：指定节点上check的唯一ID，默认和Name保持一致。但一定需要保证ID的唯一性

3. Interval（Striing）：指定check的运行频率，对HTTP和TCP check来说是必须的。

4. Notes（String）：说明

5. DeregisterCriticalServiceAfter(String)：指定一个时间段。如果check返回critical状态后时间超过这个阈值，那么就会自动注销服务。注意这个值的大小设定。这个值通常要设置的比任何可预期的终端恢复时间长得多。

6. Args（Array）：

7. DockerContainerID（String）：指定check是一个Docker check

8. HTTP（String）：一个get类型的HTTP请求（URL），作为check的内容。如果返回2xx码，说明check通过，如果返回429，check报警。其他情况下，check会返回critical状态。也支持SSL

9. Methos(String)：指定HTTP check的方法，默认为GET

10. Header（Map[String][]）：为HTTP请求指定一个头部

11. TLSSkipVerify：HTTP请求的认证

12. TTL：指定一个TTLcheck

13. ServiceID(String)：指定由agent提供的一个已存在的serviceID，来和check做关联

14. Status：指定健康检查的初始状态

2.2.2.2 请求示例

$ curl \

   --request PUT \

   --data @payload.json \

https://consul.rocks/v1/agent/check/register

payload内容

{

"ID": "mem",

"Name": "Memory utilization",

"Notes": "Ensure we don't oversubscribe memory",

"DeregisterCriticalServiceAfter": "90m",

"Args": ["/usr/local/bin/check_mem.py"],

"DockerContainerID": "f972c95ebf0e",

"Shell": "/bin/bash",

"HTTP": "https://example.com",

"Method": "POST",

"Header": {"x-foo":["bar", "baz"]},

"TCP": "example.com:22",

"Interval": "10s",

"TTL": "15s",

"TLSSkipVerify": true

}

2.2.3 注销Check

从本地agent中注销一个check，agent负责从catalog中注销check。如果提供的checkid不存在，不会进行任何操作

Method	Path	Produces
PUT	/agent/check/deregister/:check_id	application/json

2.2.3.1 参数

1. check_id：指定要注销的checkID

2.2.3.2 请求示例

$ curl \

    --request PUT \

https://consul.rocks/v1/agent/check/deregister/my-check-id

2.2.4 TTL Check通过

    这个端点用来设置TTL类型的check状态为通过并重置TTL的时钟

Method	Path	Produces
PUT	/agent/check/pass/:check_id	application/json

2.2.5 TTL Check报警

    同上

Method	Path	Produces
PUT	/agent/check/warn/:check_id	application/json

2.2.6 TTL Check失败

    同上

Method	Path	Produces
PUT	/agent/check/fail/:check_id	application/json

2.2.7 TTL Check更新

    类似

Method	Path	Produces
PUT	/agent/check/update/:check_id	application/json

参数：

• check_id (string: "") - Specifies the unique ID of the check to use. This is specified as part of the URL.

• Status (string: "") - Specifies the status of the check. Valid values are "passing", "warning", and "critical".

• Output (string: "") - Specifies a human-readable message. This will be passed through to the check's Outputfield.

2.3 Agent-Service相关请求

    /agent/service端点用来和Consul中的本地agent交互，注意不要和catalog中的service混淆。

2.3.1 列出Service列表

    这个端点用于返回所有在本地agent上注册的service。这些service都是通过配置文件或是HTTP API注册进来的。

    注意，agent感知到的服务和catalog中报告的服务可能会有不一致的情况。这通常是在没有被选举出来的leader阶段的变化导致的。agent会执行anti-entropy，所以在大多数情况下信息会在几秒之间同步。

Method	Path	Produces
GET	/agent/services	application/json

2.3.1.1 请求示例

$ curl \

https://consul.rocks/v1/agent/services

2.3.2 注册service

    这个端点可以在本地agent上添加一个新的service，可以选择是否增加健康检查。

    agent负责维护本地service的状态，并且发送本地service的状态更新到server上来保持全局catalog同步

Method	Path	Produces
PUT	/agent/service/register	application/json

2.3.2.1 参数

1. Name：名称，service实例可以共享逻辑service名

2. ID：service的唯一ID，必须保证在每个agent上唯一。如果没有提供的话默认使用Name

3. Tags：指定一些列的service tag，这些tag可以在之后的API请求中用于筛选

4. Address：指定服务地址，如果没有提供，会使用agent地址

5. Check(类型为Check)：指定一个check。如果没有提供check name或idname系统会自动生成。

6. Checks(Array)：指定一组check，同上

7. EnableTagOverride：指定是否需要针对service tag关闭这个anti-entropy特性。

2.3.2.2 请求示例

Payload

{

"ID": "redis1",

"Name": "redis",

"Tags": [

"primary",

"v1"

],

"Address": "127.0.0.1",

"Port": 8000,

"EnableTagOverride": false,

"Check": {

"DeregisterCriticalServiceAfter": "90m",

"Args": ["/usr/local/bin/check_redis.py"],

"HTTP": "http://localhost:5000/health",

"Interval": "10s",

"TTL": "15s"

}

}

$ curl \

    --request PUT \

    --data @payload.json \

https://consul.rocks/v1/agent/service/register

2.3.3 注销service

    从本地agent中移除service，如果service不存在，不做任何操作。

    agent会负责在catalog中注销service，如果这个service有关联的check也会一并注销。

Method	Path	Produces
PUT	/agent/service/deregister/:service_id	application/json

2.3.3.1 参数

1. service_id

2.3.3.2 请求示例

$ curl \

    --request PUT \

https://consul.rocks/v1/agent/service/deregister/my-service-id

2.3.4 开启维护模式

    为service开启维护模式，类似于agent的维护模式。

Method	Path	Produces
PUT	/agent/service/maintenance/:service_id	application/json

2.3.4.1 参数

• service_id (string: ) - Specifies the ID of the service to put in maintenance mode. This is specified as part of the URL.

• enable (bool: ) - Specifies whether to enable or disable maintenance mode. This is specified as part of the URL as a query string parameter.

• reason (string: "") - Specifies a text string explaining the reason for placing the node into maintenance mode. This is simply to aid human operators. If no reason is provided, a default value will be used instead. This is specified as part of the URL as a query string parameter, and, as such, must be URI-encoded.

2.3.4.2 请求示例

$ curl \

    --request PUT \

https://consul.rocks/v1/agent/service/maintenance/my-service-id?enable=true&reason=For+the+docs

三、Catalog

    /catalog端点注册/注销Consul中的节点、服务。catalog和agent的某些api比较类似，注意不要混淆。

3.1 注册实体

    在catalog中注册实体是一种low-level的机制，一般建议以agent端点提供的服务代替，因为功能一致且具有数据一致性

Method	Path	Produces
PUT	/catalog/register	application/json

3.1.1 参数

参数名	说明
ID
Node
Address
Datacenter
TaggedAddress
NodeMeta
Service
Check
SkipNodeUpdate

3.1.2 请求示例

Payload

{

"Datacenter": "dc1",

"ID": "40e4a748-2192-161a-0510-9bf59fe950b5",

"Node": "foobar",

"Address": "192.168.10.10",

"TaggedAddresses": {

"lan": "192.168.10.10",

"wan": "10.0.10.10"

},

"NodeMeta": {

"somekey": "somevalue"

},

"Service": {

"ID": "redis1",

"Service": "redis",

"Tags": [

"primary",

"v1"

],

"Address": "127.0.0.1",

"Port": 8000

},

"Check": {

"Node": "foobar",

"CheckID": "service:redis1",

"Name": "Redis health check",

"Notes": "Script based health check",

"Status": "passing",

"ServiceID": "redis1",

"Definition": {

"TCP": "localhost:8888",

"Interval": "5s",

"Timeout": "1s",

"DeregisterCriticalServiceAfter": "30s"

}

},

"SkipNodeUpdate": false

}

$ curl \

    --request PUT \

    --data @payload.json \

https://consul.rocks/v1/catalog/register

3.2 注销实体

    同上，推荐使用agent端点

Method	Path	Produces
PUT	/catalog/deregister	application/json

3.2.1 参数

• Node (string: ) - Specifies the ID of the node. If no other values are provided, this node, all its services, and all its checks are removed.

• Datacenter (string: "") - Specifies the datacenter, which defaults to the agent's datacenter if not provided.

• CheckID (string: "") - Specifies the ID of the check to remove.

• ServiceID (string: "") - Specifies the ID of the service to remove. The service and all associated checks will be removed.

3.2.2 请求示例

{

"Datacenter": "dc1",

"Node": "foobar"

}

{

"Datacenter": "dc1",

"Node": "foobar",

"CheckID": "service:redis1"

}

{

"Datacenter": "dc1",

"Node": "foobar",

"ServiceID": "redis1"

}

$ curl \

    --request PUT \

    --data @payload.json \

https://consul.rocks/v1/catalog/deregister

3.3 列举Datacenter

    返回所有的datacenter。

Method	Path	Produces
GET	/catalog/datacenters	application/json

3.3.1 请求示例

$ curl \

https://consul.rocks/v1/catalog/datacenters

3.4 列举节点

    列举出指定的datacenter中的所有注册节点，默认为当前查询的datacenter。

Method	Path	Produces
GET	/catalog/nodes	application/json

3.4.1 参数

1. dc：指定的datacenter，默认为当前查询的datacenter

2. near：展示排序设置

3. node-meta：过滤展示node

3.4.2 请求示例

$ curl \

https://consul.rocks/v1/catalog/nodes

3.5 列举Service

    返回指定datacenter中的所有注册service

Method	Path	Produces
GET	/catalog/services	application/json

3.5.1 参数

1. dc：指定dc，默认为当前查询的dc

2. node-meta：用于结果过滤

3.6 列举service的节点

    返回指定datacenter中提供某个服务的节点

Method	Path	Produces
GET	/catalog/service/:service	application/json

3.6.1 参数

1. service：指定查询的service

2. dc：指定dc

3. tag：过滤service tag

4. near：展示排序

5. ndoe-meta：结果过滤

3.6.2 请求示例

$ curl \

https://consul.rocks/v1/catalog/service/my-service

3.7 列举节点的service

    返回节点上注册的service

Method	Path	Produces
GET	/catalog/node/:node	application/json

3.7.1 参数

1. node-指定查询的node

2. dc

3.7.2 请求示例

$ curl \

https://consul.rocks/v1/catalog/node/my-node

四、Coordinates

    /coordinate端点查询本地和远程datacenter中的网络协作。略

五、Events

  event是啥？？？https://www.consul.io/docs/commands/event.html

    /event端点触发新event，并查询Consul中的可用event。

5.1 Fire Event

    触发一个新的用户event

Method	Path	Produces
PUT	/event/fire/:name	application/json

5.1.1 参数

1. name：触发的event的名字

2. dc

3. node：正则过滤node的表达式

4. service：正则过滤service

5. tag：正则过滤tag

5.1.2 请求示例

$ curl \

    --request PUT \

    --data @payload \

https://consul.rocks/v1/event/fire/my-event

其中payload是用户定义的，对Consul来说是不透明的

5.2 List Event

    列举出agent最近是别的event。

Method	Path	Produces
GET	/event/list	application/json

六、Health

    /health端点查询健康相关的信息。它独立于/catalog端点

6.1 列举节点的check

    返回指定节点的check

Method	Path	Produces
GET	/health/node/:node	application/json

6.1.1 参数

1. node 指定节点的name或是id

2. dc：指定dc

6.1.2 查询实例

$ curl \

https://consul.rocks/v1/health/node/my-node

6.2 列举Service的check

    返回指定service的check

Method	Path	Produces
GET	/health/checks/:service	application/json

6.2.1 参数

1. service 指定查询的service

2. dc

3. near

4. node-meta

$ curl \

https://consul.rocks/v1/health/checks/my-service

6.3 列举service的node

    返回提供service的node。用户还可以使用健康检查来支持动态负载均衡或是其他功能。

Method	Path	Produces
GET	/health/service/:service	application/json

6.3.1 参数

1. service

2. dc

3. near

4. tag

5. node-meta

6. passing

6.3 列举状态的check

    返回指定状态的check

Method	Path	Produces
GET	/health/state/:state	application/json

6.3.1 参数

1. state

2. dc

3. near

4. node-meta

七、KV Store

    /kv端点访问Consul的kv存储，可以用于存储service的配置或是其他metadata。

    每个datacenter都有自己的kv存储，不同dc之间不会互相备份数据。kv存储中的value不可以超过512kb

7.1 读取key

    返回指定key，如果key不存在返回404

    对于多key读取，请考虑使用transation（最后一张）

Method	Path	Produces
GET	/kv/:key	application/json

7.1.1 参数

1. key

2. dc

3. recurse：是否递归查询

4. raw：返回结果是否只返回原始数据，不包含metadta

5. keys：是否只返回key，不反悔values和metadata

6. separator：指定递归查询的分隔符（为什么递归和分隔符有关系）

7.1.2 请求示例

$ curl \

https://consul.rocks/v1/kv/my-key

7.2 创建/更新key

Method	Path	Produces
PUT	/kv/:key	application/json

7.2.1 请求参数

1. key

2. dc

3. flags

4. cas: 校验操作

5. acquire: 锁请求机制

6. release: 锁释放机制

7.3 删除key

    指定key或是指定key的前缀来删除key

Method	Path	Produces
DELETE	/kv/:key	application/json

7.3.1 参数

1. recurse: 是否前缀匹配删除

2. case: 校验操作

八、Operator

    提供集群级别的操作。略

九、Prepared Queries

    /query端点创建、更新、销毁以及执行查询。......................................

十、Sessions

    /session端点创建、销毁以及查询Consul中的session

10.1 创建Session

    初始化一个session。session必须和一个node绑定（？？？），可能会和任意数量的check绑定。

Method	Path	Produces
PUT	/session/create	application/json

10.1.1 参数

1. dc：指定查询的datacenter，可以为空，为空时默认为当前dc

2. LockDelay：指定锁延迟时间

3. Node：指定node名，必须指向一个已经注册的node？？？

4. Name：session名称

5. Checks：指定一系列相关的健康检查集合。

6. Behaviro：session失效时的默认操作，可以选择release或是delete

7. TTL：指定session的更新失效时间

10.1.2 请求示例

$ curl \

    --request PUT \

    --data @payload.json \

https://consul.rocks/v1/session/create

{

"LockDelay": "15s",

"Name": "my-service-lock",

"Node": "foobar",

"Checks": ["a", "b", "c"],

"Behavior": "release",

"TTL": "30s"

}

注意payload可以为空，有默认值

curl --request PUT localhost:8500/v1/session/create

{

    "ID": "92d45909-867e-7043-fee6-6d76ad082f3b"

}

10.2 删除Session

    删除指定名称的session，如果session的uuid不合规范，返回error。如果session的uuid不存在或是已经过期，返回200.

Method	Path	Produces
PUT	/session/destroy/:uuid	application/json

10.2.1 参数

1. uuid：指定需要删除的session的uuid

2. dc

10.2.2 请求示例

$ curl \

    --request PUT

https://consul.rocks/v1/session/destroy/adf4238a-882b-9ddc-4a9d-5b6758e4159e

10.3 读Session

    返回请求的session相关信息

Method	Path	Produces
GET	/session/info/:uuid	application/json

10.3.1 参数

1. uuid：session的uuid

2. dc

10.3.2 请求示例

$ curl \

https://consul.rocks/v1/session/info/adf4238a-882b-9ddc-4a9d-5b6758e4159e

10.4 列举节点的Session

    返回查询节点上的存活session

Method	Path	Produces
GET	/session/node/:node	application/json

10.4.1 参数

1. node：节点的name或是id

2. dc

10.4.2 查询示例

$ curl \

https://consul.rocks/v1/session/node/node-abcd1234

10.5 列举Session

    列举出当前存活的session，不指定node

Method	Path	Produces
GET	/session/list	application/json

10.5.1 参数

1. dc

10.6 更新Session

    更新给定的session。用于更新具有TTL的session，延长TTL有效期

Method	Path	Produces
PUT	/session/renew/:uuid	application/json

10.6.1 参数

1. uuid：session的uuid

2. dc

10.6.2 查询示例

$ curl \

    --request PUT \

https://consul.rocks/v1/session/renew/adf4238a-882b-9ddc-4a9d-5b6758e4159e

十一、Snapshots

    /snapshot端点可以保存和恢复用于灾难恢复的Consul server的状态。

11.1 生成Snapshot

    这个端点生成并返回一个原子的、实时的Consul server状态的快照。

Method	Path	Produces
GET	/snapshot	200 application/x-gzip

11.2 恢复Snapshot

    恢复Consul server在某一时刻的snapshot

Method	Path	Produces
PUT	/snapshot	200 text/plain (empty body)

十二、Status

    /status端点返回Consul cluster的信息。

12.1 获取Raft Leader

    获取运行中的Raft Leader

Method	Path	Produces
GET	/status/leader	application/json

12.2 获取Raft Peers

Method	Path	Produces
GET	/status/peers	application/json

十三、Transactions

略