Consul官方文档【译文】4、API-Agent

最新推荐文章于 2025-02-26 09:51:02 发布

转载最新推荐文章于 2025-02-26 09:51:02 发布 · 695 阅读

0 ·

本内容遵循CC 4.0 BY-SA版权协议

原文链接：https://my.oschina.net/percylee/blog/1524598

标签

#json #运维 #runtime

本文深入探讨了Consul代理API的各种端点，包括成员列表、配置读取、维护模式、日志流、ACL令牌更新等功能，揭示了如何通过API与Consul代理交互，管理服务、检查、配置和维护。

Agent HTTP API

/agent端点用于与当地的Consul agent进行交互。通常，服务和检查是向代理注册的，然后代理商承担保持数据与群集同步的负担。例如，代理商向目录注册服务和检查，并执行反熵以从中断恢复。

除了这些端点之外，附加端点分组在Checks和Services的导航中。

»列出成员

此端点返回代理在群集八卦池中看到的成员。由于八卦的本质，这最终是一致的：结果可能因代理而异。节点的强烈一致视图由/v1/catalog/nodes 。

方法	路径	产生
`GET`	`/agent/members`	`application/json`

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

阻止查询	一致性模式	ACL必需
`NO`	`none`	`node:read`

参数

wan (bool: false) - 指定列出WAN成员而不是LAN成员（这是默认值）。这只适用于以服务器模式运行的代理。这是作为查询参数的URL的一部分指定的。

Request Sample

$ curl \ https://consul.rocks/v1/agent/members

Response Sample

[ 
   { 
     "Name" :   "foobar" , 
     "Addr" :   "10.1.10.12" , 
     "Port" :   8301 , 
     "Tags" :   { 
       "bootstrap" :   "1" , 
       "dc" :   "dc1" , 
       "port" :   "8300" , 
       "role" :   "consul" 
     }, 
     "Status" :   1 , 
     "ProtocolMin" :   1 , 
     "ProtocolMax" :   2 , 
     "ProtocolCur" :   2 , 
     "DelegateMin" :   1 , 
     "DelegateMax" :   3 , 
     "DelegateCur" :   3 
   } 
 ]

»阅读配置

此端点返回本地代理的配置和成员信息。

方法	路径	产生
`GET`	`/agent/self`	`application/json`

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

阻止查询	一致性模式	ACL必需
`NO`	`none`	`agent:read`

Request Sample

$ curl \ https://consul.rocks/v1/agent/self

Response Sample

{ 
   "Config" :   { 
     "Bootstrap" :   true , 
     "Server" :   true , 
     "Datacenter" :   "dc1" , 
     "DataDir" :   "/tmp/consul" , 
     "DNSRecursor" :   "" , 
     "DNSRecursors" :   [], 
     "Domain" :   "consul." , 
     "LogLevel" :   "INFO" , 
     "NodeID" :   "40e4a748-2192-161a-0510-9bf59fe950b5" , 
     "NodeName" :   "foobar" , 
     "ClientAddr" :   "127.0.0.1" , 
     "BindAddr" :   "0.0.0.0" , 
     "AdvertiseAddr" :   "10.1.10.12" , 
     "Ports" :   { 
       "DNS" :   8600 , 
       "HTTP" :   8500 , 
       "RPC" :   8400 , 
       "SerfLan" :   8301 , 
       "SerfWan" :   8302 , 
       "Server" :   8300 
     }, 
     "LeaveOnTerm" :   false , 
     "SkipLeaveOnInt" :   false , 
     "StatsiteAddr" :   "" , 
     "Protocol" :   1 , 
     "EnableDebug" :   false , 
     "VerifyIncoming" :   false , 
     "VerifyOutgoing" :   false , 
     "CAFile" :   "" , 
     "CertFile" :   "" , 
     "KeyFile" :   "" , 
     "StartJoin" :   [], 
     "UiDir" :   "" , 
     "PidFile" :   "" , 
     "EnableSyslog" :   false , 
     "RejoinAfterLeave" :   false 
   }, 
   "Coord" :   { 
     "Adjustment" :   0 , 
     "Error" :   1.5 , 
     "Vec" :   [ 0 , 0 , 0 , 0 , 0 , 0 , 0 , 0 ] 
   }, 
   "Member" :   { 
     "Name" :   "foobar" , 
     "Addr" :   "10.1.10.12" , 
     "Port" :   8301 , 
     "Tags" :   { 
       "bootstrap" :   "1" , 
       "dc" :   "dc1" , 
       "id" :   "40e4a748-2192-161a-0510-9bf59fe950b5" , 
       "port" :   "8300" , 
       "role" :   "consul" , 
       "vsn" :   "1" , 
       "vsn_max" :   "1" , 
       "vsn_min" :   "1" 
     }, 
     "Status" :   1 , 
     "ProtocolMin" :   1 , 
     "ProtocolMax" :   2 , 
     "ProtocolCur" :   2 , 
     "DelegateMin" :   2 , 
     "DelegateMax" :   4 , 
     "DelegateCur" :   4 
   }, 
   "Meta" :   { 
     "instance_type" :   "i2.xlarge" , 
     "os_version" :   "ubuntu_16.04" 
   } 
 }

»重新加载代理

该端点指示代理重新加载其配置。返回此过程中遇到的任何错误。

并非所有配置选项都可重新加载。有关支持哪些选项的详细信息，请参阅代理选项页面上的可重新配置部分。

方法	路径	产生
`PUT`	`/agent/reload`	`application/json`

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

阻止查询	一致性模式	ACL必需
`NO`	`none`	`agent:write`

Request Sample

$ curl \ --request PUT \ https://consul.rocks/v1/agent/reload

»启用维护模式

此端点将代理放入“维护模式”。在维护模式下，节点将被标记为不可用，不会出现在DNS或API查询中。这个API调用是幂等的。

维护模式是持续的，并将在代理重新启动时自动恢复。

方法	路径	产生
`PUT`	`/agent/maintenance`	`application/json`

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

阻止查询	一致性模式	ACL必需
`NO`	`none`	`node:write`

参数

enable (bool: <required>) - 指定是启用还是禁用维护模式。这是作为查询字符串参数的URL的一部分指定的。
reason (string: "") - 指定一个文本字符串，说明将节点置于维护模式的原因。这只是为了帮助人手。如果没有提供任何理由，将使用默认值。这是作为查询字符串参数的URL的一部分指定的，因此必须进行URI编码。

Request Sample

$ curl \ --request PUT \ https://consul.rocks/v1/agent/maintenance?enable=true&reason=For+API+docs

»查看指标

此端点返回本地代理的配置和成员信息。

方法	路径	产生
`GET`	`/agent/metrics`	`application/json`

此端点将转储最近完成间隔的度量。有关度量的更多信息，请参阅遥测页面。

阻止查询	一致性模式	ACL必需
`NO`	`none`	`agent:read`

Request Sample

$ curl \ https://consul.rocks/v1/agent/metrics

Response Sample

{ 
     "Timestamp" :   "2017-08-08 02:55:10 +0000 UTC" , 
     "Gauges" :   [ 
         { 
             "Name" :   "consul.consul.session_ttl.active" , 
             "Value" :   0 , 
             "Labels" :   {} 
         }, 
         { 
             "Name" :   "consul.runtime.alloc_bytes" , 
             "Value" :   4704344 , 
             "Labels" :   {} 
         }, 
         { 
             "Name" :   "consul.runtime.free_count" , 
             "Value" :   74063 , 
             "Labels" :   {} 
         } 
     ], 
     "Points" :   [], 
     "Counters" :   [ 
         { 
             "Name" :   "consul.consul.catalog.service.query" , 
             "Count" :   1 , 
             "Sum" :   1 , 
             "Min" :   1 , 
             "Max" :   1 , 
             "Mean" :   1 , 
             "Stddev" :   0 , 
             "Labels" :   { 
                 "service" :   "consul" 
             } 
         }, 
         { 
             "Name" :   "consul.raft.apply" , 
             "Count" :   1 , 
             "Sum" :   1 , 
             "Min" :   1 , 
             "Max" :   1 , 
             "Mean" :   1 , 
             "Stddev" :   0 , 
             "Labels" :   {} 
         } 
     ], 
     "Samples" :   [ 
         { 
             "Name" :   "consul.consul.http.GET.v1.agent.metrics" , 
             "Count" :   1 , 
             "Sum" :   0.1817069947719574 , 
             "Min" :   0.1817069947719574 , 
             "Max" :   0.1817069947719574 , 
             "Mean" :   0.1817069947719574 , 
             "Stddev" :   0 , 
             "Labels" :   {} 
         }, 
         { 
             "Name" :   "consul.consul.http.GET.v1.catalog.service._" , 
             "Count" :   1 , 
             "Sum" :   0.23342099785804749 , 
             "Min" :   0.23342099785804749 , 
             "Max" :   0.23342099785804749 , 
             "Mean" :   0.23342099785804749 , 
             "Stddev" :   0 , 
             "Labels" :   {} 
         }, 
         { 
             "Name" :   "consul.serf.queue.Query" , 
             "Count" :   20 , 
             "Sum" :   0 , 
             "Min" :   0 , 
             "Max" :   0 , 
             "Mean" :   0 , 
             "Stddev" :   0 , 
             "Labels" :   {} 
         } 
     ] 
 }

Timestamp是显示指标的时间间隔。度量标准以10秒的时间间隔进行聚合，因此此值（以及显示的度量）将每十秒更改一次。
量表是一个存储一个随时间推移更新的值的量表的列表，例如分配的内存量。
Points是点数量表，每个点都存储一个给定名称下的一系列点。
Counters是Counters的列表，它存储有关随时间递增的度量的信息，例如对HTTP端点的请求数。
Samples是样本列表，其中存储有关操作花费的时间的信息，例如向特定http端点提供请求所需的时间。

»流日志

此端点从本地代理流式传输日志，直到连接关闭。

方法	路径	产生
`GET`	`/agent/monitor`	`application/json`

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

阻止查询	一致性模式	ACL必需
`NO`	`none`	`agent:read`

»参数

loglevel (string: "info") - 指定包含要过滤的日志级别的文本字符串，如info 。

Request Sample

$ curl \ https://consul.rocks/v1/agent/monitor

Response Sample

YYYY/MM/DD HH:MM:SS [INFO] raft: Initial configuration (index=1): [{Suffrage:Voter ID:127.0.0.1:8300 Address:127.0.0.1:8300}] YYYY/MM/DD HH:MM:SS [INFO] raft: Node at 127.0.0.1:8300 [Follower] entering Follower state (Leader: "") YYYY/MM/DD HH:MM:SS [INFO] serf: EventMemberJoin: machine-osx 127.0.0.1 YYYY/MM/DD HH:MM:SS [INFO] consul: Adding LAN server machine-osx (Addr: tcp/127.0.0.1:8300) (DC: dc1) YYYY/MM/DD HH:MM:SS [INFO] serf: EventMemberJoin: machine-osx.dc1 127.0.0.1 YYYY/MM/DD HH:MM:SS [INFO] consul: Handled member-join event for server "machine-osx.dc1" in area "wan" # ...

»加盟代理

该端点指示代理尝试连接到给定的地址。

方法	路径	产生
`GET`	`/agent/join/:address`	`application/json`

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

阻止查询	一致性模式	ACL必需
`NO`	`none`	`agent:write`

»参数

address (string: <required>) - 指定要加入的其他代理的地址。这是URL的一部分。
wan (bool: false) - 指定尝试通过WAN池加入。这仅适用于以服务器模式运行的代理。这是作为查询参数的URL的一部分指定的

Request Sample

$ curl \ https://consul.rocks/v1/agent/join/1.2.3.4

优雅的假期和关闭

此端点触发代理的正常休假和关闭。它用于确保其他节点将代理视为“左”而不是“失败”。离开的节点不会在使用快照重新启动时尝试重新加入集群。

对于服务器模式下的节点，节点将以优雅的方式从Raft对等体集中删除。这是至关重要的，因为在某些情况下，非优雅假可能会影响群集的可用性。

方法	路径	产生
`PUT`	`/agent/leave`	`application/json`

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

阻止查询	一致性模式	ACL必需
`NO`	`none`	`agent:write`

Request Sample

$ curl \ --request PUT \ https://consul.rocks/v1/agent/leave

»强制离开和关机

该端点指示代理强制节点进入left状态。如果节点意外失败，那么它将处于failed状态。一旦处于failed状态，Consul将尝试重新连接，并且属于该节点的服务和检查将不会被清除。将节点强制为left状态允许其旧条目被删除。

方法	路径	产生
`PUT`	`/agent/force-leave`	`application/json`

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

阻止查询	一致性模式	ACL必需
`NO`	`none`	`agent:write`

Request Sample

$ curl \ --request PUT \ https://consul.rocks/v1/agent/force-leave

»更新ACL令牌

此端点更新代理当前正在使用的ACL令牌。它可以用于首次向代理引入ACL令牌，或更新从代理配置最初加载的令牌。令牌不会持久化，所以如果代理重新启动，则需要再次更新令牌。

方法	路径	产生
`PUT`	`/agent/token/acl_token`	`application/json`
`PUT`	`/agent/token/acl_agent_token`	`application/json`
`PUT`	`/agent/token/acl_agent_master_token`	`application/json`
`PUT`	`/agent/token/acl_replication_token`	`application/json`

上面的路径对应于在代理配置中找到的令牌名称： acl_token ， acl_agent_token ， acl_agent_master_token和acl_replication_token 。

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

阻止查询	一致性模式	ACL必需
`NO`	`none`	`agent:write`

»参数

Token (string: "") - 指定要设置的ACL令牌。

»样本有效载荷

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

Request Sample

$ curl \ --request PUT \ --data @payload.json \ https://consul.rocks/v1/agent/token/acl_token

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

Consul官方文档【译文】4、API-Agent

Agent HTTP API

»列出成员

参数

Request Sample

Response Sample

»阅读配置

Request Sample

Response Sample

»重新加载代理

Request Sample

»启用维护模式

参数

Request Sample

»查看指标

Request Sample

Response Sample

»流日志

»参数

Request Sample

Response Sample

»加盟代理

»参数

Request Sample

优雅的假期和关闭

Request Sample

»强制离开和关机

Request Sample

»更新ACL令牌

»参数

»样本有效载荷

Request Sample