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

• Check - Agent HTTP API

/agent/check端点与Consul中的本地代理的检查进行交互。 这些不应该与目录中的检查混淆。

»列表检查

此端点返回对本地代理注册的所有检查。 这些检查是通过配置文件提供的，也可以使用HTTP API动态添加。

重要的是要注意，代理商知道的检查可能与目录中报告的检查不同。 这通常是由于在没有领导人当选的情况下进行的改变。 代理执行有效的反熵 ，所以在大多数情况下，所有内容都会在几秒钟内同步。

方法	路径	产生
GET	/agent/checks	application/json

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

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

Request Sample

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

Response Sample

{ 
   "service:redis" :   { 
     "Node" :   "foobar" , 
     "CheckID" :   "service:redis" , 
     "Name" :   "Service 'redis' check" , 
     "Status" :   "passing" , 
     "Notes" :   "" , 
     "Output" :   "" , 
     "ServiceID" :   "redis" , 
     "ServiceName" :   "redis" 
   } 
 } 

»注册检查

该端点向本地代理添加新的检查。 检查可能是脚本，HTTP，TCP或TTL类型。 代理人负责管理检查状态并保持目录同步。

方法	路径	产生
PUT	/agent/check/register	application/json

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

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

参数

• Name (string: <required>) - 指定检查的名称。

• ID (string: "") - 指定集群中此检查的唯一ID。 默认为"Name"参数，但可能需要为唯一性提供ID。

• Interval (string: "") - 指定运行此检查的频率。 这是HTTP和TCP检查所必需的。

• Notes (string: "") - 指定人的任意信息。 领事不在内部使用。

• DeregisterCriticalServiceAfter (string: "") - 指定与此服务关联的检查应在此时间后注销。 这被指定为具有诸如“10m”的后缀的持续时间。 如果检查处于关键状态超过此配置值，则其关联服务（及其所有相关检查）将自动取消注册。 最小超时时间为1分钟，并且重新启动服务的进程每隔30秒运行一次，因此可能需要比配置的超时时间略长才能触发注销。 这通常应配置一个超时时间，比给定服务的任何预期的可恢复中断长得多。

• Script (string: "") - 指定要在Interval上运行以更新检查状态的脚本的脚本或路径。 如果指定路径，则此路径必须存在于磁盘上，并可由领事代理人读取。

• DockerContainerID (string: "") - 指定检查是Docker检查，Consul将使用指定的Shell对给定容器中每个Interval的脚本评估脚本。 请注意， Shell目前仅支持Docker检查。

• HTTP (string: "") - 指定HTTP检查，以根据每个Interval的HTTP值（预期为URL）执行GET请求。 如果响应是任何2xx代码，则检查passing 。 如果响应是429 Too Many Requests ，则检查是warning 。 否则，检查critical 。 HTTP检查也支持SSL。 默认情况下，期望有效的SSL证书。 证书验证可以使用TLSSkipVerify进行控制。

• Method (string: "") - 指定用于HTTP检查的不同HTTP方法。 当没有指定值时，使用GET 。

• Header (map[string][]string: {}) - 指定一组应该为HTTP检查设置的标题。 每个标题都可以有多个值。

• TLSSkipVerify (bool: false) - 指定是否应该验证HTTPS检查的证书。

• TCP (string: "") - 指定要连接的每个Interval的TCP （预期为IP或主机名和端口组合）的值。 如果连接尝试成功，则检查passing 。 如果连接尝试失败，则检查critical 。 在主机名解析为IPv4和IPv6地址的情况下，将尝试两个地址，并且第一次成功连接尝试将导致成功的检查。

• TTL (string: "") - 指定这是一个TTL检查，并且必须定期使用TTL端点来更新检查的状态。

• ServiceID (string: "") - 指定将注册的检查与代理提供的现有服务相关联的服务的ID。

• Status (string: "") - 指定运行状况检查的初始状态。

»样本有效载荷

{ 
   "ID" :   "mem" , 
   "Name" :   "Memory utilization" , 
   "Notes" :   "Ensure we don't oversubscribe memory" , 
   "DeregisterCriticalServiceAfter" :   "90m" , 
   "Script" :   "/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 
 } 

Request Sample

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

拒绝检查

此端点从本地代理中删除检查。 代理将负责从目录中注销取消注册。 如果提供的ID的检查不存在，则不采取任何措施。

方法	路径	产生
PUT	/agent/check/deregister/:check_id	application/json

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

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

参数

• check_id (string: "") - 指定要注销的检查的唯一ID。 这是URL的一部分。

Request Sample

$ curl \ --request PUT \ https://consul.rocks/v1/agent/check/deregister/my-check-id

TTL检查通行证

该端点用于TTL类型检查，以将检查状态设置为passing并复位TTL时钟。

方法	路径	产生
GET	/agent/check/pass/:check_id	application/json

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

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

参数

• check_id (string: "") - 指定要使用的检查的唯一ID。 这是URL的一部分。

• note (string: "") - 指定人类可读的消息。 这将被传递到支票的Output字段。

Request Sample

$ curl \ https://consul.rocks/v1/agent/check/pass/my-check-id

»TTL检查警告

该端点与TTL类型检查一起使用，以将检查状态设置为warning并复位TTL时钟。

方法	路径	产生
GET	/agent/check/warn/:check_id	application/json

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

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

参数

• check_id (string: "") - 指定要使用的检查的唯一ID。 这是URL的一部分。

• note (string: "") - 指定人类可读的消息。 这将被传递到支票的Output字段。

Request Sample

$ curl \ https://consul.rocks/v1/agent/check/warn/my-check-id

»TTL检查失败

该端点与TTL类型检查一起使用，将检查的状态设置为critical并重置TTL时钟。

方法	路径	产生
GET	/agent/check/fail/:check_id	application/json

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

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

参数

• check_id (string: "") - 指定要使用的检查的唯一ID。 这是URL的一部分。

• note (string: "") - 指定人类可读的消息。 这将被传递到支票的Output字段。

Request Sample

$ curl \ https://consul.rocks/v1/agent/check/fail/my-check-id

»TTL检查更新

该端点与TTL类型检查一起使用，以设置检查的状态并复位TTL时钟。

方法	路径	产生
PUT	/agent/check/update/:check_id	application/json

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

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

参数

• check_id (string: "") - 指定要使用的检查的唯一ID。 这是URL的一部分。

• Status (string: "") - 指定检查的状态。 有效值为"passing" ， "warning"和"critical" 。

• Output (string: "") - 指定一个人类可读的消息。 这将被传递到支票的Output字段。

»样本有效载荷

{ 
   "Status" :   "passing" , 
   "Output" :   "curl reported a failure: \n\n ..." 
 } 

Request Sample

$ curl \ --request PUT \ --data @payload.json \ https://consul.rocks/v1/agent/check/update/my-check-id