Consul

快速服务指引前导

列出现在注册的所有服务：

/opt/gitlab/embedded/bin/consul catalog services

打印出注册服务的相关信息

dig @127.0.0.1 -p 8600 pgbouncer-readonly.service.consul 

通过配置json文件进行服务注册：

配置json文件：

cat pgbouncer-readonly.json 
{"bind_addr": "{{GetInterfaceIP \"eth0\"}}","service":{"name":"pgbouncer-readonly","address":"","port":6432,"check":{"id":"service:pgbouncer","interval":"10s","status":"failing","args":["/opt/gitlab/bin/gitlab-ctl","patroni","check-replica"]}}}

如果对于一台多网卡机器可以绑定网卡：

"bind_addr": "{{GetInterfaceIP \"eth0\"}}"

绑定网卡eth0
echo -n '{"bind_addr": "{{GetInterfaceIP \"eth0\"}}","service":{"name":"pgbouncer-readonly","address":"","port":6432,"check":{"id":"service:pgbouncer","interval":"10s","status":"failing","args":["/opt/gitlab/bin/gitlab-ctl","patroni","check-replica"]}}}' > /var/opt/gitlab/consul/config.d/pgbouncer-readonly.json 

取消本机的注册信息：

/opt/gitlab/embedded/bin/consul services deregister pgbouncer-readonly.json 

关于自动取消注册信息：

关于设定deregister_critical_service_after 设置

echo -n '{"bind_addr": "{{GetInterfaceIP \"eth0\"}}","service":{"name":"pgbouncer-readonly","tags": ["secondary"],"address":"","port":6432,"check":{"id":"service:pgbouncer","deregister_critical_service_after":"60s","interval":"10s","status":"failing","args":["/opt/gitlab/bin/gitlab-ctl","patroni","check-replica"]}}}' > /var/opt/gitlab/consul/config.d/pgbouncer-readonly.json 

• 如果设置了check脚本会在返回非0/1 值之后就会剔除本节点（测试得知即便是设置为1min，也会较快被剔除1-3s）

获取check的一些详情(比如不成功的报错信息)：

curl -G http://127.0.0.1:8500/v1/agent/checks --data-urlencode  'filter=CheckID=="pgbouncer-readonly"'

API

Check - Agent HTTP API

一，列出checks

Method	Path	Produces
GET	/agent/checks	application/json

示例

root@saas-staging-postgres-1:~# curl http://127.0.0.1:8500/v1/agent/checks
{"service:pgbouncer":{"Node":"saas-staging-postgres-1","CheckID":"service:pgbouncer","Name":"Service 'pgbouncer-readonly' check","Status":"warning","Notes":"","Output":"I am not a replica.\n","ServiceID":"pgbouncer-readonly","ServiceName":"pgbouncer-readonly","ServiceTags":[],"Type":"script","Definition":{},"CreateIndex":0,"ModifyIndex":0},"service:postgresql":{"Node":"saas-staging-postgres-1","CheckID":"service:postgresql","Name":"Service 'postgresql' check","Status":"passing","Notes":"","Output":"I am the leader.\n","ServiceID":"postgresql","ServiceName":"postgresql","ServiceTags":[],"Type":"script","Definition":{},"CreateIndex":0,"ModifyIndex":0},"service:postgresql-ha/saas-staging-postgres-1":{"Node":"saas-staging-postgres-1","CheckID":"service:postgresql-ha/saas-staging-postgres-1","Name":"Service 'postgresql-ha' check","Status":"passing","Notes":"","Output":"HTTP GET http://172.20.32.6:8008/master: 200 OK Output: {\"state\": \"running\", \"postmaster_start_time\": \"2022-06-17 07:48:27.291511+00:00\", \"role\": \"master\", \"server_version\": 120007, \"cluster_unlocked\": false, \"xlog\": {\"location\": 3671660762688}, \"timeline\": 92, \"replication\": [{\"usename\": \"gitlab_replicator\", \"application_name\": \"saas-staging-postgres-2\", \"client_addr\": \"172.20.48.13\", \"state\": \"streaming\", \"sync_state\": \"async\", \"sync_priority\": 0}, {\"usename\": \"gitlab_replicator\", \"application_name\": \"saas-staging-postgres-3\", \"client_addr\": \"172.20.32.14\", \"state\": \"streaming\", \"sync_state\": \"async\", \"sync_priority\": 0}], \"database_system_identifier\": \"6968739529780789060\", \"patroni\": {\"version\": \"2.1.0\", \"scope\": \"postgresql-ha\"}}","ServiceID":"postgresql-ha/saas-staging-postgres-1","ServiceName":"postgresql-ha","ServiceTags":["master"],"Type":"http","Definition":{},"CreateIndex":0,"ModifyIndex":0}}

过滤条件

Selector	Supported Operations
CheckID	Equal, Not Equal, In, Not In, Matches, Not Matches
Name	Equal, Not Equal, In, Not In, Matches, Not Matches
Node	Equal, Not Equal, In, Not In, Matches, Not Matches
Notes	Equal, Not Equal, In, Not In, Matches, Not Matches
Output	Equal, Not Equal, In, Not In, Matches, Not Matches
ServiceID	Equal, Not Equal, In, Not In, Matches, Not Matches
ServiceName	Equal, Not Equal, In, Not In, Matches, Not Matches
ServiceTags	In, Not In, Is Empty, Is Not Empty
Status	Equal, Not Equal, In, Not In, Matches, Not Matches

格式

curl --get <path> --data-urlencode 'filter="<filter expression>"'

带过滤条件示例

root@saas-staging-postgres-1:~# curl --get http://127.0.0.1:8500/v1/agent/checks --data-urlencode  'filter=CheckID=="service:pgbouncer"'
{"service:pgbouncer":{"Node":"saas-staging-postgres-1","CheckID":"service:pgbouncer","Name":"Service 'pgbouncer-readonly' check","Status":"warning","Notes":"","Output":"I am not a replica.\n","ServiceID":"pgbouncer-readonly","ServiceName":"pgbouncer-readonly","ServiceTags":[],"Type":"script","Definition":{},"CreateIndex":0,"ModifyIndex":0}}

二，注册check

通过HTTP API注册/查看/取消注册：

创建json文件：

postgres@pg1:~/scripts$ cat payload.json 
{
	  "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://127.0.0.1",
	  "Method": "POST",
	  "Header": { "Content-Type": ["application/json"] },
	  "Body": "{\"check\":\"mem\"}",
	  "DisableRedirects": true,
	  "TCP": "example.com:22",
	  "Interval": "10s",
          "Timeout": "5s",
	  "TLSSkipVerify": true
}

check体内各参数：

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

• ID (string: "")- 指定节点上此检查的唯一 ID。这默认为"Name"参数，但可能需要提供唯一性 ID。该值将在响应中返回为"CheckId"。

• Namespace (string: "") 【企业】- 指定您注册的支票的命名空间。

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

• Notes (string: "")- 为人类指定任意信息。Consul 内部不使用它。

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

• Args (array<string>)- 指定要运行以更新检查状态的命令参数。在 Consul 1.0 之前，检查使用单个Script字段来定义要运行的命令，并且总是在 shell 中运行。在 Consul 1.0 中，Args添加了数组以便可以在没有 shell 的情况下运行检查。该 Script字段已弃用，您应该在 shell 中包含 shell 以在Argsshell 下运行，例如。"args": ["sh", "-c", "..."].

  注意： Consul 1.0 附带了一个在此 API中Args被错误命名 的问题。ScriptArgs请ScriptArgs与 Consul 1.0（Consul 的未来版本将继续接受）以及ArgsConsul 1.0.1 及更高版本一起使用。

• AliasNode (string: "")- 指定用于别名检查的节点 ID。如果未指定服务，则检查将为节点的运行状况设置别名。如果指定了服务，则检查将在此特定节点上为指定的服务设置别名。

• AliasService (string: "")- 为别名检查指定服务的 ID。如果服务没有注册到同一个代理， AliasNode也必须指定。请注意，这是服务ID，而不是服务名称（尽管它们通常相同）。

• DockerContainerID (string: "")- 指定检查是 Docker 检查，Consul 将Interval使用指定的Shell. 请注意，Shell目前仅支持 Docker 检查。

• GRPC (string: "")- 指定gRPC支持标准 gRPC 健康检查协议的检查端点。检查的状态将Interval通过探测配置的端点在给定的情况下更新。在检查的端点后添加服务标识符，gRPC格式如下，以检查特定服务而不是整个 gRPC 服务器/:service_identifier。

• GRPCUseTLS (bool: false)- 指定是否使用 TLS 进行此gRPC健康检查。如果启用了 TLS，则默认情况下，需要一个有效的 TLS 证书。TLSSkipVerify可以通过设置来关闭证书验证true。

• H2PING (string "")- 指定使用 http2 运行 ping 检查的地址。在指定Interval的 处，与该地址建立连接，并发送 ping。如果 ping 成功，则检查归类为passing，否则标记为critical。默认使用 TLS。要禁用 TLS 并使用 h2c，请设置H2PingUseTLS为false. 如果启用了 TLS，则默认需要有效的 SSL 证书，但可以使用TLSSkipVerify.

• H2PingUseTLS (bool: true)- 指定是否应将 TLS 用于 H2PING 检查。如果启用了 TLS，则默认需要有效的 SSL 证书，但可以使用TLSSkipVerify.

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

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

• Body (string: "")- 指定应与HTTP检查一起发送的正文。

• DisableRedirects (bool: false)- 指定在执行 HTTP 检查时是否禁用以下 HTTP 重定向。

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

• Timeout (duration: 10s)- 在脚本、HTTP、TCP 或 gRPC 检查的情况下为传出连接指定超时。可以以“10s”或“5m”的形式指定（即分别为10秒或5分钟）。

• OutputMaxSize (positive int: 4096)- 允许为给定的检查放置最大大小的文本。该值必须大于0，默认为4k。check_output_max_size对于给定代理的所有检查，可以使用代理中的标志进一步限制该值 。

• TLSServerName (string: "")- 指定一个可选字符串，用于在通过 TLS 连接时设置 SNI 主机。对于HTTP检查，如果 URL 使用主机名（不是 IP 地址），则会自动设置此值。

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

• TCP (string: "")- 指定 aTCP以连接TCP 每个Interval. 如果连接尝试成功，则检查为passing。如果连接尝试不成功，则检查为critical。对于同时解析为 IPv4 和 IPv6 地址的主机名，将对这两个地址进行尝试，并且第一次成功的连接尝试将导致检查成功。

• TTL (duration: 10s)- 指定这是一个 TTL 检查，并且必须定期使用 TTL 端点来更新检查的状态。如果在指定的持续时间内检查未设置为通过，则检查将设置为失败状态。

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

• Status (string: "")- 指定健康检查的初始状态。

• SuccessBeforePassing (int: 0)- 指定在检查状态转换为通过之前所需的连续成功结果的数量。可用于 HTTP、TCP、gRPC、Docker 和监视器检查。在 Consul 1.7.0 中添加。

• FailuresBeforeWarning (int: 0)- 指定检查状态转换为警告之前所需的连续不成功结果的数量。默认为与 相同的值FailuresBeforeCritical。高于FailuresBeforeCritical的值无效。可用于 HTTP、TCP、gRPC、Docker 和监视器检查。在 Consul 1.11.0 中添加。

• FailuresBeforeCritical (int: 0)- 指定在检查状态转换为关键之前所需的连续不成功结果的数量。可用于 HTTP、TCP、gRPC、Docker 和监视器检查。在 Consul 1.7.0 中添加。

注册：

postgres@pg1:~/scripts$ curl    --request PUT    --data @payload.json    http://127.0.0.1:8500/v1/agent/check/register

检查返回状态：

postgres@pg1:~/scripts$ curl http://127.0.0.1:8500/v1/agent/checks
{"mem":{"Node":"192.168.2.10","CheckID":"mem","Name":"Memory utilization","Status":"critical","Notes":"Ensure we don't oversubscribe memory","Output":"Post \"https://127.0.0.1\": dial tcp 127.0.0.1:443: connect: connection refused","ServiceID":"","ServiceName":"","ServiceTags":[],"Type":"http","Interval":"10s","Timeout":"5s","ExposedPort":0,"Definition":{},"CreateIndex":0,"ModifyIndex":0},"service:pgbouncer":{"Node":"192.168.2.10","CheckID":"service:pgbouncer","Name":"Service 'pgbouncer-readonly' check","Status":"warning","Notes":"","Output":"","ServiceID":"pgbouncer-readonly","ServiceName":"pgbouncer-readonly","ServiceTags":[],"Type":"script","Interval":"10s","Timeout":"","ExposedPort":0,"Definition":{},"CreateIndex":0,"ModifyIndex":0}}

注销

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

postgres@pg1:~/scripts$ curl --request PUT http://127.0.0.1:8500/v1/agent/check/deregister/mem

说明：mem为注册时的id值；只能通过check_id来进行注销

检查TTL类型 状态为passing/warning/critical的相关check

需要设置ttl参数

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

pass 示例：

curl --request PUT --get http://127.0.0.1:8500/v1/agent/check/pass/service:postgresql 

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

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

Service - Agent HTTP API

一，列出services

格式：

Method	Path	Produces
GET	/agent/services	application/json

示例：

postgres@pg1:~$ curl --get http://127.0.0.1:8500/v1/agent/services
{"pgbouncer-readonly":{"ID":"pgbouncer-readonly","Service":"pgbouncer-readonly","Tags":[],"Meta":{},"Port":6432,"Address":"","Weights":{"Passing":1,"Warning":1},"EnableTagOverride":false,"Datacenter":"dc1"}}

相关过滤参数

1.1 获得service配置

1.1.1 通过service id

Method	Path	Produces
GET	/agent/service/:service_id	application/json

示例：

postgres@pg1:~$ curl  --get http://127.0.0.1:8500/v1/agent/service/pgbouncer-readonly
{"ID":"pgbouncer-readonly","Service":"pgbouncer-readonly","Tags":[],"Meta":{},"Port":6432,"Address":"","Weights":{"Passing":1,"Warning":1},"EnableTagOverride":false,"ContentHash":"8cbb9ffd03c1e4f","Datacenter":"dc1"}

1.2 获得本地服务健康状态

1.2.1 通过service name

格式：

Method	Path	Produces
GET	/agent/health/service/name/:service_name	application/json
GET	/agent/health/service/name/:service_name?format=text	text/plain

示例1：

postgres@pg1:~$ curl  --get http://127.0.0.1:8500/v1/agent/health/service/name/pgbouncer-readonly
[{"AggregatedStatus":"warning","Service":{"ID":"pgbouncer-readonly","Service":"pgbouncer-readonly","Tags":[],"Meta":{},"Port":6432,"Address":"","Weights":{"Passing":1,"Warning":1},"EnableTagOverride":false,"Datacenter":"dc1"},"Checks":[{"Node":"192.168.2.10","CheckID":"service:pgbouncer","Name":"Service 'pgbouncer-readonly' check","Status":"warning","Notes":"","Output":"","ServiceID":"pgbouncer-readonly","ServiceName":"pgbouncer-readonly","ServiceTags":null,"Type":"","Definition":{"Interval":"0s","Timeout":"0s","DeregisterCriticalServiceAfter":"0s","HTTP":"","Header":null,"Method":"","Body":"","TLSServerName":"","TLSSkipVerify":false,"TCP":"","GRPC":"","GRPCUseTLS":false},"CreateIndex":0,"ModifyIndex":0}]}]

示例2:

postgres@pg2:~$ curl  --get http://127.0.0.1:8500/v1/agent/health/service/name/pgbouncer-readonly?format=text
passing

1.2.2 通过service id

格式：

Method	Path	Produces
GET	/agent/health/service/id/:service_id	application/json
GET	/agent/health/service/id/:service_id?format=text	text/plain

示例1:

postgres@pg2:~$ curl  --get http://127.0.0.1:8500/v1/agent/health/service/id/pgbouncer-readonly
{"AggregatedStatus":"passing","Service":{"ID":"pgbouncer-readonly","Service":"pgbouncer-readonly","Tags":[],"Meta":{},"Port":6432,"Address":"","Weights":{"Passing":1,"Warning":1},"EnableTagOverride":false,"Datacenter":"dc1"},"Checks":[{"Node":"192.168.2.2","CheckID":"service:pgbouncer","Name":"Service 'pgbouncer-readonly' check","Status":"passing","Notes":"","Output":"(Not all processes could be identified, non-owned process info\n will not be shown, you would have to be root to see it all.)\n","ServiceID":"pgbouncer-readonly","ServiceName":"pgbouncer-readonly","ServiceTags":null,"Type":"","Definition":{"Interval":"0s","Timeout":"0s","DeregisterCriticalServiceAfter":"0s","HTTP":"","Header":null,"Method":"","Body":"","TLSServerName":"","TLSSkipVerify":false,"TCP":"","GRPC":"","GRPCUseTLS":false},"CreateIndex":0,"ModifyIndex":0}]}

示例2:

postgres@pg2:~$ curl  --get http://127.0.0.1:8500/v1/agent/health/service/id/pgbouncer-readonly?format=text
passing

二，注册service

格式：

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

相当于命令： consul services register.

json请求参数解释：

• Name (string: <required>)- 指定服务的逻辑名称。许多服务实例可能共享相同的逻辑服务名称。我们建议使用 有效的 DNS 标签 以与外部 DNS 兼容。

• ID (string: "")- 指定此服务的唯一 ID。这对于每个代理必须是唯一的。如果未提供，则默认为Name参数。

• Tags (array<string>: nil)- 指定要分配给服务的标签列表。这些标签可用于以后的过滤，并通过 API 公开。我们建议使用有效的 DNS 标签 以与外部 DNS 兼容

• Address (string: "")- 指定服务的地址。如果未提供，代理的地址将在 DNS 查询期间用作服务的地址。

• TaggedAddresses (map<string|object>: nil)- 指定服务实例的显式 LAN 和 WAN 地址映射。地址和端口都可以在映射值中指定。

• Meta (map<string|string>: nil)- 指定链接到服务实例的任意 KV 元数据。

• Namespace (string: "") 【企业】

  - 指定您注册的服务的命名空间。此字段优先于

  ns
  

  查询参数，这是指定命名空间的其他几种方法之一。

• Port (int: 0)- 指定服务的端口。

• Kind (string: "")- 服务的种类。默认为“”，这是典型的 Consul 服务。对于代表另一个服务的连接代理，此值也可以是“connect-proxy”，对于 网状网关的实例，可以是“ mesh -gateway”，对于终止网关的实例，也可以是“terminating-gateway” ，或者对于入口网关。

• Proxy (Proxy: nil)- 从 1.2.3 开始，指定 Connect 服务代理实例的配置。这仅在Kind定义代理或网关时有效。有关完整详细信息，请参阅代理文档 。

• Connect (Connect: nil)- 指定 Connect 的配置。有关支持的字段，请参阅下面的 连接结构部分。

• Check (Check: nil)- 指定检查。有关已接受字段的更多信息，请参阅 检查文档。如果您没有为支票提供名称或 ID，则会生成它们。要提供自定义 id 和/或名称，请设置CheckID 和/或Name字段。

• Checks (array<Check>: nil)- 指定检查列表。有关已接受字段的更多信息，请参阅 检查文档。如果您没有为支票提供名称或 ID，则会生成它们。要提供自定义 id 和/或名称，请设置CheckID 和/或Name字段。自动生成Name并CheckID取决于检查在数组中的位置，因此即使行为是确定性的，建议所有检查都让 consul CheckID通过将字段留空/省略或提供唯一值来设置。

• EnableTagOverride (bool: false)- 指定禁用此服务标签的反熵功能。如果EnableTagOverride设置为true，则外部代理可以在catalog中更新此服务 并修改标签。此代理的后续本地同步操作将忽略更新的标签。例如，如果外部代理修改了此服务的标签和端口，EnableTagOverride并设置为true， 则在下一个同步周期之后，服务的端口将恢复为原始值，但标签将保持更新后的值。作为一个反例，如果外部代理修改了此服务的标签和端口，并 设置为在下一个同步周期之后服务的端口和EnableTagOverride标签将恢复为原始值false，所有修改都将丢失。

• Weights (Weights: nil)- 指定服务的权重。有关权重的更多信息，请参阅 服务文档。如果未提供此字段，权重将默认为 {"Passing": 1, "Warning": 1}.需要注意的是，这仅适用于本地注册的服务。如果您有多个节点都注册相同的服务，则它们的 EnableTagOverride配置和所有其他服务配置项相互独立。更新在一个节点上注册的服务的标签独立于在另一个节点上注册的相同服务（按名称）。如果EnableTagOverride未指定，则默认值为 false。有关更多信息，请参阅反熵同步。

»连接结构

对于Connect字段，参数为：

• Native (bool: false)- 指定此服务是否本机支持Connect协议。如果这是真的，那么连接代理、DNS 查询等将能够服务发现该服务。
• Proxy (Proxy: nil)- 不推荐使用指定应为此服务实例启动托管连接代理，并可选择为代理提供配置。格式如Managed Proxy Deprecation中所述。
• SidecarService (ServiceDefinition: nil)- 指定要注册的可选嵌套服务定义。有关详细信息，请参阅 Sidecar 服务注册。

示例：

{
  "ID": "redis1",
  "Name": "redis",
  "Tags": ["primary", "v1"],
  "Address": "127.0.0.1",
  "Port": 8000,
  "Meta": {
    "redis_version": "4.0"
  },
  "EnableTagOverride": false,
  "Check": {
    "DeregisterCriticalServiceAfter": "90m",
    "Args": ["/usr/local/bin/check_redis.py"],
    "Interval": "10s",
    "Timeout": "5s"
  },
  "Weights": {
    "Passing": 10,
    "Warning": 1
  }
}

请求：

curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/agent/service/register?replace-existing-checks=true

三，注销服务

此端点从本地代理中删除服务。如果服务不存在，则不采取任何措施。

格式：

方法	小路	生产
PUT	/agent/service/deregister/:service_id	application/json

对应的 CLI 命令是consul services deregister

示例：

curl \
    --request PUT \
    http://127.0.0.1:8500/v1/agent/service/deregister/my-service-id

四，启用维护模式

该端点将给定服务置于“维护模式”。在维护模式期间，该服务将被标记为不可用，并且不会出现在 DNS 或 API 查询中。

格式：

方法	小路	生产
PUT	/agent/service/maintenance/:service_id	application/json

路径参数

• service_id (string: <required>)- 指定要置于维护模式的服务的 ID。

查询参数

• enable (bool: <required>)- 指定是启用还是禁用维护模式。这被指定为 URL 的一部分，作为查询字符串参数。

• reason (string: "")- 指定一个文本字符串，解释将节点置于维护模式的原因。这只是为了帮助人类操作员。如果未提供任何原因，则使用默认值。此参数必须是 URI 编码的。

• ns (string: "") 【企业】

  - 指定您置于维护模式的服务的命名空间。您还可以

  通过其他方法指定命名空间

示例：

curl \
    --request PUT \
    http://127.0.0.1:8500/v1/agent/service/maintenance/my-service-id?enable=true&reason=For+the+docs

Consul命令行

Consul 通过一个非常易于使用的命令行界面 (CLI) 进行控制。Consul 只是一个单一的命令行应用程序：consul. 然后，此应用程序采用诸如“agent”或“members”之类的子命令。

consulCLI 是一个行为良好的命令行应用程序。在错误的情况下，将返回非零退出状态。

Usage: consul [--version] [--help] <command> [<args>]

Available commands are:
    acl            Interact with Consul's ACLs
    agent          Runs a Consul agent
    catalog        Interact with the catalog
    config         Interact with Consul's Centralized Configurations
    connect        Interact with Consul Connect
    debug          Records a debugging archive for operators
    event          Fire a new event
    exec           Executes a command on Consul nodes
    force-leave    Forces a member of the cluster to enter the "left" state
    info           Provides debugging information for operators.
    intention      Interact with Connect service intentions
    join           Tell Consul agent to join cluster
    keygen         Generates a new encryption key
    keyring        Manages gossip layer encryption keys
    kv             Interact with the key-value store
    leave          Gracefully leaves the Consul cluster and shuts down
    lock           Execute a command holding a lock
    login          Login to Consul using an auth method
    logout         Destroy a Consul token created with login
    maint          Controls node or service maintenance mode
    members        Lists the members of a Consul cluster
    monitor        Stream logs from a Consul agent
    operator       Provides cluster-level tools for Consul operators
    reload         Triggers the agent to reload configuration files
    rtt            Estimates network round trip time between nodes
    services       Interact with services
    snapshot       Saves, restores and inspects snapshots of Consul server state
    tls            Builtin helpers for creating CAs and certificates
    validate       Validate config files/directories
    version        Prints the Consul version
    watch          Watch for changes in Consul

要获得任何特定命令的帮助，请将-h标志传递给相关的子命令。例如，要查看有关join子命令的帮助：

postgres@pg1:~$ consul  join --help
Usage: consul join [options] address ...

  Tells a running Consul agent (with "consul agent") to join the cluster
  by specifying at least one existing member.

HTTP API Options

  -ca-file=<value>
     Path to a CA file to use for TLS when communicating with Consul.
     This can also be specified via the CONSUL_CACERT environment
     variable.

  -ca-path=<value>
     Path to a directory of CA certificates to use for TLS when
     communicating with Consul. This can also be specified via the
     CONSUL_CAPATH environment variable.

  -client-cert=<value>
     Path to a client cert file to use for TLS when 'verify_incoming'
     is enabled. This can also be specified via the CONSUL_CLIENT_CERT
     environment variable.

  -client-key=<value>
     Path to a client key file to use for TLS when 'verify_incoming'
     is enabled. This can also be specified via the CONSUL_CLIENT_KEY
     environment variable.

  -http-addr=<address>
     The `address` and port of the Consul HTTP agent. The value can be
     an IP address or DNS address, but it must also include the port.
     This can also be specified via the CONSUL_HTTP_ADDR environment
     variable. The default value is http://127.0.0.1:8500. The scheme
     can also be set to HTTPS by setting the environment variable
     CONSUL_HTTP_SSL=true.

  -tls-server-name=<value>
     The server name to use as the SNI host when connecting via
     TLS. This can also be specified via the CONSUL_TLS_SERVER_NAME
     environment variable.

  -token=<value>
     ACL token to use in the request. This can also be specified via the
     CONSUL_HTTP_TOKEN environment variable. If unspecified, the query
     will default to the token of the Consul agent at the HTTP address.

  -token-file=<value>
     File containing the ACL token to use in the request instead of one
     specified via the -token argument or CONSUL_HTTP_TOKEN environment
     variable. This can also be specified via the CONSUL_HTTP_TOKEN_FILE
     environment variable.

Command Options

  -partition=<default>
     Specifies the admin partition to query. If not provided, the admin
     partition will be inferred from the request's ACL token, or will
     default to the `default` admin partition. Admin Partitions are a
     Consul Enterprise feature.

  -wan
     Joins a server to another server in the WAN pool.

环境变量

除了 CLI 标志之外，Consul 还读取环境变量以获取行为默认值。CLI 标志总是优先于环境变量，但使用环境变量来配置 Consul 代理通常很有帮助，尤其是在配置管理和初始化系统中。

CONSUL_HTTP_ADDR

这是本地Consul 代理（不是远程服务器）的 HTTP API 地址，指定为带有可选方案的 URI：

CONSUL_HTTP_ADDR=127.0.0.1:8500

或作为 Unix 套接字路径：

CONSUL_HTTP_ADDR=unix:///var/run/consul_http.sock

如果https://使用该方案，CONSUL_HTTP_SSL则暗示为真。

CONSUL_HTTP_TOKEN

这是启用访问控制列表 (ACL) 时所需的 API 访问令牌，例如：

CONSUL_HTTP_TOKEN=aba7cbe5-879b-999a-07cc-2efd9ac0ffe

CONSUL_HTTP_TOKEN_FILE

这是包含启用访问控制列表 (ACL) 时所需的 API 访问令牌的文件的路径，例如：

CONSUL_HTTP_TOKEN_FILE=/path/to/consul.token

CONSUL_HTTP_AUTH

这将 HTTP 基本访问凭据指定为用户名：密码对：

CONSUL_HTTP_AUTH=operations:JPIMCmhDHzTukgO6

CONSUL_HTTP_SSL

这是一个布尔值（默认为 false），它启用 HTTPS URI 方案和与 HTTP API 的 SSL 连接：

CONSUL_HTTP_SSL=true

CONSUL_HTTP_SSL_VERIFY

这是一个布尔值（默认为 true），用于指定 SSL 证书验证；false不建议将此值设置为用于生产用途。用于开发目的的示例：

CONSUL_HTTP_SSL_VERIFY=false

CONSUL_CACERT

与 Consul 通信时用于 TLS 的 CA 文件的路径。

CONSUL_CACERT=ca.crt

CONSUL_CAPATH

与 Consul 通信时用于 TLS 的 CA 证书目录的路径。

CONSUL_CAPATH=ca_certs/

CONSUL_CLIENT_CERT

verify_incoming启用时用于 TLS 的客户端证书文件的路径。

CONSUL_CLIENT_CERT=client.crt

CONSUL_CLIENT_KEY

verify_incoming启用时用于 TLS 的客户端密钥文件的路径。

CONSUL_CLIENT_KEY=client.key

CONSUL_TLS_SERVER_NAME

通过 TLS 连接时用作 SNI 主机的服务器名称。

CONSUL_TLS_SERVER_NAME=consulserver.domain

CONSUL_GRPC_ADDR

类似CONSUL_HTTP_ADDR但配置本地代理正在侦听 gRPC 请求的地址。目前 gRPC 仅用于集成Envoy 代理，必须在代理配置中显式启用。

CONSUL_GRPC_ADDR=127.0.0.1:8502

​ 或作为 Unix 套接字路径：

CONSUL_GRPC_ADDR=unix://var/run/consul_grpc.sock

如果代理配置了 TLS 证书，则 gRPC 侦听器将需要 TLS 并提供与 https 侦听器相同的证书。与一样CONSUL_HTTP_ADDR，如果启用了 TLS，https:// 则应使用或CONSUL_HTTP_SSL设置该方案。

CONSUL_NAMESPACE

【仅限企业】 如果您使用 Consul Enterprise 命名空间，您可以为 CLI 设置此项以显式使用单个命名空间。这在所有支持企业名称空间的 Hashicorp 产品中都很常见。

CONSUL_NAMESPACE=default