【Consul】Consul实践指导-HTTP API

        Consul提供RESTful HTTP API. API可对节点、服务、健康检查、配置等执行CRUD操作（CRUD是指在做计算处理时的增加(Create)、读取查询(Retrieve)、更新(Update)和删除(Delete)）。Endpoint使用版本号标记变化，并支持后向兼容性。

Endpoint支持以下接口：

acl – 访问控制列表

agent – consul agent

catalog – 节点（nodes）或服务（services）

coordinate – 网络协同

event – 用户事件

health – 健康检查

kv – KV存储

query - Prepared Queries

session – 会话

status – consul系统状态

        后续会详细介绍每一个。

        当然consul还支持一些内部API，后续继续调研。

1.1.1 阻塞式查询

        某些Endpoint支持 “阻塞查询”，阻塞查询是通过长轮询来等待可能发生的变化。

        并不是所有的Endpoint都支持阻塞查询，在每一项中会明确说明的。任何支持阻塞查询的Endpoint都会设置HTTP头部X-Consul-Index——标识当前请求资源状态的唯一标识符。客户端可以将index值赋值给X-Consul-Index值，意味着客户端计划等待index值任何变化。

        除了index值，还有参数wait,用来指定阻塞请求的等待时间。最长限制为10分钟，默认是5分钟。Wait参数可以设置为10s或5m。

        需要重点关注的是，阻塞请求返回并不能保证查询的资源发生变化，有可能是超时返回，但不会影响查询结果。

1.1.2 一致性模式

        绝大部分读请求Endpoint都支持多个级别的一致性，没有任何策略适合所有客户的需求，对于一致性模式的选择，用户通过权衡分布式系统的相关需求做出折中。

三种读模式：

        •default - 如果没有指定，默认是强一致性。但是，有很小的可能性出现——新的Leader已经选出，但是旧的leader还在使用旧值。因此需要权衡快速读取和潜在的旧值风险。导致读取旧值的条件很难触发，大多数用户不需要担心此情况发生。此外，请注意，此竞争条件只适用于读取，而不是写入。

        •consistent - 无附加条件的强一致性。要求Leader要与约定的个数的节点核实它仍然是领导者。引入额外的round-trip到所有服节点。因此，需要权衡round-trip带来的延迟增加返。大多数用户不应该使用该模式，除非不能容忍stale read。

        •stale-这种模式允许任何服务器进行读操作，无论它是否是Leader。这意味着读取的值是有可能是旧值，但是，在leader的50ms内结果通常是一致的。需要权衡的是快速和可扩展的读取与更高可能性的久值。由于这种模式允许读操作没有Leader，因此即使集群是无效的，仍然可以响应读操作。

        要切换模式，无论是stale或consistent，在请求时，都需要提供参数。同时提供两个时错误的。

        To support bounding the acceptable staleness of data, responses providethe X-Consul-LastContact header containing the time in milliseconds that a server was lastcontacted by the leader node. The X-Consul-KnownLeader headeralso indicates if there is a known leader. These can be used by clients togauge the staleness of a result and take appropriate action.

1.1.3 JSON格式输出

        默认情况下，HTTP API的输出都是JSON格式。客户端使用参数pretty。

1.1.4 ACLs

        Consul中的多个Endpoint都需要或使用ACL令牌，Agent可以在请求中使用默认令牌——配置参数acl_token设置。但是，令牌也可以在请求之前使用X-Consul-Token请求设置或使用querystring字符串参数。请求头部优先于默认令牌，但是querystring的优先级最高。

1.1.5 地址转换

        Consul 0.7版本增加新功能——基于配置参数translate_wan_addrs设置的HTTP响应的地址换换，为了允许客户端理解地址转换的效果，增加X-Consul-Translate-Addresses header。当开启转换时设置为true，如果转换禁用，则该header不会出现。