Consul官方文档【译文】3、API概述-ACLs

• HTTP API

Consul的主要接口是RESTful HTTP API。 API可以对节点，服务，检查，配置等进行基本的CRUD操作。

»版本前缀

所有API路线都以/v1/为前缀。

此文档仅适用于v1 API。

向后兼容性：在当前版本，即使使用v1前缀，Consul也不承诺向后兼容性。 当此政策更改时，我们会删除此警告。 我们期望通过Consul 1.0达到API的稳定性。

»ACL

Consul的几个端点使用或要求ACL令牌进行操作。 可以将代理配置为使用acl_token配置选项在请求中使用默认令牌。 但是，也可以通过使用X-Consul-Token请求头或token查询字符串参数来指定每个请求的token 。 请求标头优先于默认令牌，查询字符串参数优先于所有内容。

有关ACL的详细信息，请参见“ ACL指南” 。

»认证

当启用身份验证时，应使用X-Consul-Token标头向API请求提供X-Consul-Token 。 这降低了令牌意外记录或暴露的可能性。 使用身份验证时，客户端应通过TLS进行通信。

这是一个使用curl的例子：

$ curl \ --header "X-Consul-Token: abcd1234" \ https://consul.rocks/v1/agent/members

以前，这是通过一个?token= query参数提供的。 此功能存在于许多端点上以实现向后兼容性，但是它的使用非常不鼓励 ，因为它可以作为URL的一部分显示在访问日志中。

»阻止查询

Consul的许多端点支持称为“阻止查询”的功能。 阻塞查询用于使用长轮询等待潜在的更改。 并非所有端点都支持阻塞，但是每个端点都唯一地记录了文档中阻止查询的支持。

支持阻止查询的端点返回一个名为X-Consul-Index的HTTP头。 这是表示所请求资源的当前状态的唯一标识符。

在对该资源的后续请求中，客户端可以将index查询字符串参数设置为X-Consul-Index的值，指示客户端希望等待该索引之后的任何更改。

当提供此提示时，HTTP请求将“挂起”，直到系统发生更改或达到最大超时。 一个关键的注意事项是返回阻塞请求不能保证更改。有可能达到了超时，或者有一个不影响查询结果的幂等写入。

除了index之外，支持阻塞的端点也将遵守指定阻塞请求的最大持续时间的wait参数。 这限制在10分钟。 如果未设置，则等待时间默认为5分钟。 该值可以以“10s”或“5m”的形式指定（即分别为10秒或5分钟）。 在提供的最大wait时间中添加了一小段额外的等待时间，以分散任何并发请求的唤醒时间。 这最多wait / 16额外的时间达到最大持续时间。

»一致性模式

大多数读取查询端点支持多个级别的一致性。 由于没有任何政策将适合所有客户的需求，这些一致性模式允许用户在如何平衡分布式系统固有的权衡方面有最终的理解。

三种读取模式有：

• default - 如果没有指定，默认值在几乎所有情况下都是一致的。 但是，还有一个小窗口，可以选举一位新的领导人，在这个窗口中，老领导人可以服务陈旧的价值观。 权衡是快速阅读，但潜在的陈旧价值观。 导致过期读取的条件很难触发，大多数客户端不需要担心这种情况。 另外请注意，这种竞争条件仅适用于读取而不是写入。

• consistent - 这种模式是强有力的一致，没有警告。 它要求领导人与法定人数同时确认它仍然是领导者。 这将引入对所有服务器节点的额外往返。 由于额外的往返行程，权衡增加了延迟。 大多数客户不应该使用这个，除非他们不能容忍一个陈旧的阅读。

• stale - 此模式允许任何服务器服务于读取，而不管它是否是领导者。 这意味着读取可以任意陈旧; 然而，结果通常与领导者的50毫秒内一致。 权衡是非常快速和可扩展的阅读，具有更高的过时的价值的可能性。 由于此模式允许没有领导者的读取，因此不可用的集群仍然可以响应查询。

要切换这些模式，应该在请求上提供stale或consistent查询参数。 提供两者都是一个错误。

为了支持限制数据的可接受X-Consul-LastContact ，响应提供了X-Consul-LastContact标头，其中包含上一次由领导节点联系服务器的时间（以毫秒为单位）。 X-Consul-KnownLeader标题还指示是否有一个已知的领导者。 这些可以由客户使用来衡量结果的平淡度并采取适当的措施。

»格式化的JSON输出

默认情况下，所有HTTP API请求的输出都将被最小化。 如果客户端pretty传递给查询字符串，则返回格式化的JSON。

»HTTP方法

Consul的API旨在采取REST风格，尽管有一些例外。 API响应标准HTTP动词GET，PUT和DELETE。 每个API方法将清楚地记录其响应的动词和生成的响应。 与不同动词相同的路径可能会触发不同的行为。 例如：

PUT /v1/kv/foo GET /v1/kv/foo

即使这些共享路径， PUT操作创建一个新的密钥，而GET操作读取一个现有的密钥。

这是使用curl的相同示例：

$ curl \ --request PUT \ --data 'hello consul' \ https://consul.rocks/v1/kv/foo

»翻译地址

Consul 0.7增加了基于translate_wan_addrs的配置设置在HTTP响应中翻译地址的功能。 为了允许客户端知道地址转换是否有效，如果启用了X-Consul-Translate-Addresses ，则X-Consul-Translate-Addresses标题将被添加，并且值为true 。 如果未启用翻译，则该标题将不存在。

• 客户端库和SDK

本页上列出的编程库可以更方便地使用API​​。 有些则正式保留，而其他则由社区提供。

• api - Consul HTTP API的官方Go客户端
• consulate - Consul HTTP API的Python客户端
• python-consul - 用于Consul HTTP API的Python客户端
• consul-kv - 面向ConsulKV Store的Python 3客户端
• consul-php-sdk - Consul HTTP API的PHP客户端
• php-consul-api - 用于Consul HTTP API的GO类PHP客户端
• envoy - Consul Clojure客户与观察员和其他好东西
• clj-consul-catalog - Consul HTTP API的Clojure发现客户端
• helm - 与Consul 交互的本地Scala客户端
• consul-client - Consul HTTP API的Java客户端
• consul-api - Consul HTTP API的Java客户端
• Spring Cloud Consul - Spring Boot应用程序的Consul整合（内部使用consul-api ）
• Vertx-consul-client - 用于Consul HTTP API的Vert.x客户端
• discovery - Consul HTTP API的Erlang / OTP客户端
• consul-client - 用于Consul HTTP API的Ruby客户端
• diplomat - Ruby library 查询领Consul 的KV store和服务目录
• Node-consul - Consul HTTP API的Node.js客户端
• Consul.NET - Consul HTTP API的C＃客户端
• Consul - Consul HTTP API的Perl客户端
• CondenserDotNet - C＃一个意见相当的API for .NET，为使用HTTP API的服务提供更高级的功能
• ConsulSwift - 用于Consul HTTP API的Swift客户端

  

• 访问控制列表ACLs

ACL HTTP API

/acl端点在Consul中创建，更新，销毁和查询ACL令牌。 有关ACL的详细信息，请参阅ACL指南 。

引导ACL

该端点执行ACL系统的特殊一次性引导，如果在Consul服务器配置中未指定acl_master_token ，并且以前尚未引导群集，则会创建第一个管理令牌。 这在领事0.9.1及更高版本中可用，并要求所有领事服务器进行升级才能运行。

这提供了引导ACL的机制，而不会在Consul的配置文件中存在任何秘密。

方法	路径	产生
PUT	/acl/bootstrap	application/json

下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询	一致性模式	ACL必需
NO	none	none

Sample Request

$ curl \ --request PUT \ https://consul.rocks/v1/acl/bootstrap

样品响应

{ 
   "ID" :   "adf4238a-882b-9ddc-4a9d-5b6758e4159e" 
 } 

您可以通过检查响应代码来检测某些事件是否干扰了ACL引导过程。 200响应意味着引导是成功的，403表示集群已经被引导，在这一点上，您应该考虑集群处于潜在的受损状态。

返回的令牌将是一个管理令牌，可用于进一步配置ACL系统。 有关详细信息，请参阅ACL指南 。

»创建ACL令牌

此端点创建一个新的ACL令牌。

方法	路径	产生
PUT	/acl/create	application/json

下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询	一致性模式	ACL必需
NO	none	management

参数

• ID (string: "") - 指定ACL的ID。 如果未提供，则会生成UUID。

• Name (string: "") - 指定ACL令牌的人性化名称。

• Type (string: "client") - 指定ACL令牌的类型。 有效值为： client和management 。

• Rules (string: "") - 指定此ACL标记的规则。 “ Rules属性的格式记录在“ ACL指南”中 。

Sample有效载荷

{ 
   "Name" :   "my-app-token" , 
   "Type" :   "client" , 
   "Rules" :   "" 
 } 

Sample Request

$ curl \ --request PUT \ --data @payload.json \ https://consul.rocks/v1/acl/create

样品响应

{ 
   "ID" :   "adf4238a-882b-9ddc-4a9d-5b6758e4159e" 
 } 

»更新ACL令牌

此端点用于修改给定ACL令牌的策略。 不必生成新的令牌ID，必须提供ID字段。

方法	路径	产生
PUT	/acl/update	application/json

下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询	一致性模式	ACL必需
NO	none	management

»参数

参数与创建端点相同，但ID字段是必需的。

»样本有效载荷

{ 
   "ID" :   "adf4238a-882b-9ddc-4a9d-5b6758e4159e" , 
   "Name" :   "my-app-token-updated" , 
   "Type" :   "client" , 
   "Rules" :   "# New Rules" , 
 } 

» Sample Request

$ curl \ --request PUT \ --data @payload.json \ https://consul.rocks/v1/acl/update

»删除ACL令牌

此端点将删除具有给定ID的ACL令牌。

方法	路径	产生
PUT	/acl/destroy/:uuid	application/json

下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询	一致性模式	ACL必需
NO	none	management

»参数

• uuid (string: <required>) - 指定要销毁的ACL令牌的UUID。 这是必需的，并被指定为URL路径的一部分。

» Sample Request

$ curl \ --request PUT \ https://consul.rocks/v1/acl/destroy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05

»读取ACL令牌

此端点读取具有给定ID的ACL令牌。

方法	路径	产生
GET	/acl/info/:uuid	application/json

下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询	一致性模式	ACL必需
YES	all	none

注意：不需要ACL，因为在URL路径中指定了ACL。

参数

• uuid (string: <required>) - 指定要读取的ACL令牌的UUID。 这是必需的，并被指定为URL路径的一部分。

Sample Request

$ curl \ https://consul.rocks/v1/acl/info/8f246b77-f3e1-ff88-5b48-8ec93abf3e05

Sample Response

[ 
   { 
     "CreateIndex" :   3 , 
     "ModifyIndex" :   3 , 
     "ID" :   "8f246b77-f3e1-ff88-5b48-8ec93abf3e05" , 
     "Name" :   "Client Token" , 
     "Type" :   "client" , 
     "Rules" :   "..." 
   } 
 ] 

»克隆ACL令牌

此端点克隆ACL并返回新的令牌ID 。 这允许令牌作为其他人的模板，使得在没有复杂规则管理的情况下生成新的令牌变得简单。

方法	路径	产生
PUT	/acl/clone/:uuid	application/json

下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询	一致性模式	ACL必需
NO	none	management

参数

• uuid (string: <required>) - 指定要克隆的ACL令牌的UUID。 这是必需的，并被指定为URL路径的一部分。

Sample Request

$ curl \ --request PUT \ https://consul.rocks/v1/acl/clone/8f246b77-f3e1-ff88-5b48-8ec93abf3e05

Sample Response

{ 
   "ID" :   "adf4238a-882b-9ddc-4a9d-5b6758e4159e" 
 } 

»列出ACL

此端点列出所有活动的ACL令牌。

方法	路径	产生
GET	/acl/list	application/json

下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询	一致性模式	ACL必需
YES	all	management

 Sample Request

$ curl \ https://consul.rocks/v1/acl/list

Sample Response

[ 
   { 
     "CreateIndex" :   3 , 
     "ModifyIndex" :   3 , 
     "ID" :   "8f246b77-f3e1-ff88-5b48-8ec93abf3e05" , 
     "Name" :   "Client Token" , 
     "Type" :   "client" , 
     "Rules" :   "..." 
   } 
 ] 

»检查ACL复制

此端点返回数据中心中ACL复制进程的状态。 这是由运营商使用，或通过自动化来检查ACL复制的运行状况。

有关详细信息，请参阅ACL指南复制部分。

方法	路径	产生
GET	/acl/replication	application/json

下表显示了此端点对阻止查询 ， 一致性模式和所需ACL的支持 。

阻止查询	一致性模式	ACL必需
NO	consistent	none

参数

• dc (string: "") - 指定要查询的数据中心。 这将默认为要查询的代理的数据中心。 这是作为查询参数的URL的一部分指定的。

Sample Request

$ curl \ https://consul.rocks/v1/acl/replication

Sample Response

{ 
   "Enabled" :   true , 
   "Running" :   true , 
   "SourceDatacenter" :   "dc1" , 
   "ReplicatedIndex" :   1976 , 
   "LastSuccess" :   "2016-08-05T06:28:58Z" , 
   "LastError" :   "2016-08-05T06:28:28Z" 
 } 

• Enabled报告是否为数据中心启用ACL复制。

• Running报告ACL复制过程是否正在运行。 领导选举发生后，进程可能需要大约60秒才能开始运行。

• SourceDatacenter是正在复制ACL的权威ACL数据中心，并与acl_datacenter配置匹配。

• ReplicatedIndex是成功复制的最后一个索引。 您可以将其与/v1/acl/list端点返回的X-Consul-Index标头进行比较，以确定复制过程是否已获得所有可用的ACL。 复制以大约每30秒钟作为后台进程运行，并且本地更新的速率限制为100次更新/秒，因此执行大量ACL的初始同步可能需要几分钟时间。 在初始同步之后，副本滞后应该在大约30秒左右。

• LastSuccess是最后一次成功执行同步操作的UTC时间。 由于ACL复制是通过阻止查询完成的，所以如果没有ACL更改要复制，则可能不会更新最多5分钟。 如果没有同步成功，将显示零值“0001-01-01T00：00：00Z”。

• LastError是同步操作期间遇到的最后一个错误的UTC时间。 如果这个时间晚于LastSuccess ，您可以假定复制过程处于LastSuccess状态。 如果没有同步导致错误，则零值“0001-01-01T00：00：00Z”将出现。

 

转载于:https://my.oschina.net/percylee/blog/1524591