Consul-命令行最全文档

共计 10272 个字符，预计需要花费 26 分钟才能阅读完成。

首先，从这个网址下载 consul，解压后发现就是个可执行文件，如果不可以执行，chmod +x consul 一下。

为了试验 Consul 较多的功能，这里我们打算启用一个 dev 模式，带 ACL 控制的 Consul 代理。
配置文件 config.json 如下

{
    "datacenter":"dc1",
    "primary_datacenter":"dc1",
    "data_dir":"/opt/consul/data/",
    "enable_script_checks":false,
    "bind_addr":"127.0.0.1",
    "node_name":"consul-dev",
    "enable_local_script_checks":true,
    "log_file":"/opt/consul/log/",
    "log_level":"info",
    "log_rotate_bytes":100000000,
    "log_rotate_duration":"24h",
    "encrypt":"krCysDJnrQ8dtA7AbJav8g==",
    "acl":{
        "enabled":true,
        "default_policy":"deny",
        "enable_token_persistence":true,
        "tokens":{"master":"cd76a0f7-5535-40cc-8696-073462acc6c7"}
    }
}

下面是参数说明：

datacenter 此标志表示代理运行的数据中心。如果未提供，则默认为“dc1”。Consul 拥有对多个数据中心的一流支持，但它依赖于正确的配置。同一数据中心中的节点应在同一个局域网内。
primary_datacenter: 这指定了对 ACL 信息具有权威性的数据中心。必须提供它才能启用 ACL。
bind_addr: 内部群集通信绑定的地址。这是群集中所有其他节点都应该可以访问的 IP 地址。默认情况下，这是“0.0.0.0”，这意味着 Consul 将绑定到本地计算机上的所有地址，并将第一个可用的私有 IPv4 地址通告给群集的其余部分。如果有多个私有 IPv4 地址可用，Consul 将在启动时退出并显示错误。如果指定“[::]”，Consul 将通告第一个可用的公共 IPv6 地址。如果有多个可用的公共 IPv6 地址，Consul 将在启动时退出并显示错误。Consul 同时使用 TCP 和 UDP，并且两者使用相同的端口。如果您有防火墙，请务必同时允许这两种协议。
advertise_addr: 更改我们向群集中其他节点通告的地址。默认情况下，会使用 -bind 参数指定的地址.
server: 是否是 server agent 节点。
connect.enabled: 是否启动 Consul Connect，这里是启用的。
node_name：节点名称。
data_dir: agent 存储状态的目录。
enable_script_checks：是否在此代理上启用执行脚本的健康检查。有安全漏洞，默认值就是 false，这里单独提示下。
enable_local_script_checks: 与 enable_script_checks 类似，但只有在本地配置文件中定义它们时才启用它们。仍然不允许在 HTTP API 注册中定义的脚本检查。
log-file: 将所有 Consul Agent 日志消息重定向到文件。这里指定的是 /opt/consul/log/ 目录。
log_rotate_bytes：指定在需要轮换之前应写入日志的字节数。除非指定，否则可以写入日志文件的字节数没有限制
log_rotate_duration：指定在需要旋转日志之前应写入日志的最长持续时间。除非另有说明，否则日志会每天轮换（24 小时。单位可以是 ”ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”，比如设置值为 24h
encrypt：用于加密 Consul Gossip 协议交换的数据。在启动各个 server 之前，配置成同一个 UUID 值就行，或者你用命令行 consul keygen 命令来生成也可以。
acl.enabled: 是否启用 acl.
acl.default_policy:“allow”或“deny”; 默认为“allow”，但这将在未来的主要版本中更改。当没有匹配规则时，默认策略控制令牌的行为。在“allow”模式下，ACL 是黑名单：允许任何未明确禁止的操作。在“deny”模式下，ACL 是白名单：阻止任何未明确允许的操作.
acl.enable_token_persistence: 可能值为 true 或者 false。值为 true 时，API 使用的令牌集合将被保存到磁盘，并且当代理重新启动时会重新加载。
acl.tokens.master: 具有全局管理的权限，也就是最大的权限。它允许操作员使用众所周知的令牌密钥 ID 来引导 ACL 系统。需要在所有的 server agent 上设置同一个值，可以设置为一个随机的 UUID。这个值权限最大，注意保管好。

接着我们以 dev 模式启动 agent。

./consul agent -dev -config-file ./config.json

启动完之后，你会发现出现下面的错误

这个错误是没有设置 agent-token 造成的，agent-token 主要用于客户端和服务器执行内部操作. 比如 catalog api 的更新，反熵同步等。

1. 先创建 agent-token

curl \
    --request PUT \
    --header "X-Consul-Token: cd76a0f7-5535-40cc-8696-073462acc6c7" \
    --data \
'{"Name":"Agent Token","Type":"client","Rules":"node \"\" { policy = \"write\"} service \"\" {policy = \"read\"}"}' http://127.0.0.1:8500/v1/acl/create

注意这里面的 X -Consul-Token 与上面 config.json 里面的 acl.tokens.master 要是同一个值，此时你会看到生成成功，d118b1fc-77af-d870-8417-667c04b29cdf 这一串就是 agent-token 了。

2. 设置 agent-token
由于这里只有一个 agent，需要调用接口来设置 agent-token。

curl \
    --request PUT \
    --header "X-Consul-Token: cd76a0f7-5535-40cc-8696-073462acc6c7" \
    --data \
'{"Token":"d118b1fc-77af-d870-8417-667c04b29cdf"}' http://127.0.0.1:8500/v1/agent/token/acl_agent_token

然后你会发现之前的错误就消失了。

如此，一个带有 ACL 控制的 agent 就启动好了。如果你想搭建一个带 ACL 控制的集群，请参见我的另一篇文章。

consul 子命令挺多的，如下图，但不要慌，一个个来。

最后设置一下环境变量，增加 CONSUL_HTTP_TOKEN。
我这里是 Mac，改的是~/.bash_profile；其他系统的，请自行搜索。

 sudo vim ~/.bash_profile

在末尾添加

export CONSUL_HTTP_TOKEN=cd76a0f7-5535-40cc-8696-073462acc6c7

然后让新的环境变量生效：

source ~/.bash_profile

关于 acl 部分，后面我们会在 web-ui 里面进行控制，我会单独写一篇文章系统介绍 Consul ACL 如何设置。不过，你可以先看我之前的文章，Consul ACL 集群配置说明以及 ACL Token 的用法，但这篇文章只告诉了怎么用，并没有讲清楚为什么这么用。

agent 就是启动 consul 代理部分。这里面主要是一些配置信息，如何启动。后面会把完整版的配置翻译出来，供大家参考，不过还是强烈建议大家读读命令行的帮助说明, 即 ./consul agent –help

与 consul 的 catalog 打交道。
列出所有的数据中心：./consul catalog datacenters
列出所有的节点：./consul catalog nodes
列出所有的服务：./consul catalog services

config 命令用于与 Consul 的中央配置系统进行交互。
装备一个配置文件 servie-defaults.hcl

Kind = "service-defaults"
Name = "web"
Protocol = "http"

写入一个配置：

./consul config write service-defaults.hcl

读取刚写入的配置：

./consul config  read -kind service-defaults -name web

列出特定类型的配置：

./consul config list -kind service-defaults

删除一个配置：

./consul config delete -kind service-defaults -name web

和 Consul Connect 的进行交互。Consul Connect 使用相互 TLS 提供服务到服务连接授权和加密。应用程序可以使用 sidecar 代理自动为入站和出站连接建立 TLS 连接，而根本不知道 Connect。应用程序还可以与 Connect 本机集成，以实现最佳性能和安全性。

consul debug 命令在指定时间内监视 Consul 代理，将有关代理，集群和环境的信息记录到写入当前目录的归档中。
下面是执行./consul debug 的结果，更多使用说明请执行./consul debug –help

可以看到输出文件被保存到命令行所在路径 /consul-debug-1559985864.tar.gz 中。你可以解压该文件，进行 debug.

监视（watch)可以监视数据视图（例如，节点列表，KV 对，健康检查）的更新。检测到更新时，将调用外部处理程序。处理程序可以是任何可执行文件或 HTTP 端点。

./consul watch -type=event -name=helloserviceevent /Use/cuixin/ConsulStudy/mac-dev/echo_handler.sh -helloservice

上面我们指定监视的类型是 event，名称是 helloserviceevent 的事件，当收到该事件时，将触发执行 echo_handler.sh 这个脚本，并且参数为 helloservice。
下面是 echo_handler.sh 这个脚本的内容:

#!/bin/bash
 echo“hello  $1”>> test.txt

很简单，会将内容追加到 test.txt 中。
注意这里需要给 echo_handler.sh 加下执行权限

chmod +x echo_handler.sh

event 命令提供了一种将自定义用户事件触发到整个数据中心的机制。这些事件对 Consul 不透明，但它们可用于构建脚本基础结构，以执行自动部署，重新启动服务或执行任何其他编排操作。可以使用 watch（监视）处理事件。使用 八卦协议 传播事件。
虽然细节对于使用事件并不重要，但理解语义很有用。八卦层将尽最大努力发放活动，但没有保证发放成功。与大多数使用共识复制的 Consul 数据不同，事件数据纯粹是点对点的八卦。这意味着它没有持久化，也没有总排序。实际上，这意味着您不能依赖消息邮件传递的顺序。然而，优点是即使在没有服务器节点或停机期间仍可以使用事件。
基础八卦也设置了用户事件消息大小的限制。很难给出一个确切的数字，因为它取决于事件的各种参数，但有效载荷应保持非常小（<100 字节）。指定太大的事件将返回错误。

有了上面 watch 部分提供的监视，下面我们就产生对应的事件就行。
./consul event -name=helloserviceevent
这个触发事件的命令可以执行多次，每次触发事件之后，你都会看到 test.txt 多了一行“hello -helloservice”

## exec
exec 命令提供了一种远程执行机制。例如，这可用于在提供 Web 服务的所有计算机上运行 uptime 命令。这里由于安全性问题，我们在配置里面禁用了远程执行（“enable_script_checks”:false）。
否则你可以执行./consul exec uptime 来查看各个节点已经启动多长时间了。

force-leave 命令强制 Consul 集群的成员进入“left”状态。如果该成员仍然存活，它最终将重新加入群集。此方法的真正目的是强制删除“failed”状态的节点。

./consul force-leave node-name

info 命令提供对操作员有用的各种调试信息。根据代理是客户端还是服务器，将返回有关不同子系统的信息。
目前有顶级键：
agent：提供有关代理的信息
consul：有关 Consul（客户或服务器）的信息
raft：提供有关 Raft 共识库的信息
serf_lan：提供有关 LAN 八卦池的信息
serf_wan：提供有关 WAN 八卦池的信息

./consul info

意图通过 Connect 定义服务的访问控制，用于控制哪些服务可以建立连接。可以通过 API，CLI 或 UI 管理意图。（这部分和 Consul Connect 联系较为紧密，后面我研究透了，会单独写篇文章）。
创建一个允许“web”与“db”对话的意图：

$ consul intention create web db

测试是否允许“web”连接到“db”：

$ consul intention check web db

找到与“db”服务进行通信的所有意图：

$ consul intention match db

通过指定至少一个现有成员, 告知正在运行的 Consul 代理（使用“consul agent”）加入群集

   ./consul join cluster_member1_address

其中 cluster_member1_address 是 ip:port 的格式，可以通过运行./consul members 发现现有集群的地址。

keygen 命令生成可用于 Consul 代理流量加密的加密密钥。keygen 命令使用加密强伪随机数生成器来生成密钥。你也可以选择自己生成一个 UUID。

./consul keygen

keyring 命令用于检查和修改 Consul 的 Gossip Pools 中使用的加密密钥。它能够向集群分发新的加密密钥，淘汰旧的加密密钥，以及更改集群用来加密消息的密钥。
查看集群目前使用的所有秘钥

./consul keyring -list

这个值，与我们配置文件中指定的 “encrypt”:”krCysDJnrQ8dtA7AbJav8g==” 是一致的。

kv 命令用于通过命令行与 Consul 的 KV 存储进行交互。它公开了用于从 KV 存储中插入，更新，读取和删除的顶级命令。
使用值“5”创建或更新名为“redis / config / connections”的键：

./consul kv put redis/config/connections 5

读回这个值：

./consul kv get redis/config/connections

或获取详细的关键信息：

./consul kv get -detailed redis/config/connections

最后，删除密钥：

./consul kv delete redis/config/connections

leave 命令触发代理的正常离开和关闭进程。它用于确保其他节点将代理视为“离开了”而不是“失败了”。离开了的节点在带快照重新启动时不会尝试重新加入群集。

这个是企业级 consul 所带功能，略。

lock 命令提供了一种简单分布式锁的机制。在 KV 存储中的给定前缀处创建锁（或信号量），并且仅在保持时，调用子进程。如果锁丢失或通信中断，子进程将终止。

当 -n = 1 时，只存在一个提供互斥的锁持有者或领导者。设置更高的值会切换到允许多个持有者协调的信号量。另外，提供的前缀必须具有写权限

下面举个互斥锁的例子：
获得锁的进程会睡眠 10s, 没拿到锁的会在 1s 内因超时被终止。
1. 首先在 kv 存储放入一个键值对。

./consul kv put redis/config/connections 1

2. 然后打开两个终端，切换到 consul 安装的目录，分别执行以下命令。

./consul lock -n=1 -timeout=1s  redis/config/connections  sleep 10

拿到锁的正常执行，睡眠 10s 后，执行完毕。

没拿到锁的因获取锁超时（这里设置是 1s）被中止。

bearer-token-file = <string> – 包含要与此 auth 方法一起使用的秘密承载令牌的文件的路径。
meta = <value> – 在令牌上设置的元数据，格式为 key = value。可以多次指定该标志以设置多个元字段。
method = <string> – 要登录的 auth 方法的名称。
token-sink-file = <string> – 最新令牌的 SecretID 在此文件中保持最新。
$ consul login -method ‘minikube’ \
```
   -bearer-token-file '/run/secrets/kubernetes.io/serviceaccount/token' \
   -token-sink-file 'consul.token'
```
$ cat consul.token
36103ae4-6731-e719-f53a-d35188cfa41d

由于这里我还没有学习 kubernetes，后面有机会可以补上。

如果是从 consul login 创建的，则 logout 命令将销毁提供的令牌。

$ consul logout -token-file 'consul.token'

maint 命令提供对服务维护模式的控制。使用该命令，可以将节点提供的服务或节点上的所有服务标记为“维护中”。在此操作模式下，该服务不会出现在 DNS 查询结果或 API 结果中。这有效地将服务从服务的可用“健康”节点池中取出。

通过在服务的紧急状态下注册运行状况检查来激活维护模式，并通过取消注册运行状况检查来取消激活维护模式。
下面注册一个 helloservice1，在 postman 中，对应位置输入以下参数。

 PUT http://localhost:8500/v1/agent/service/register?token=cd76a0f7-5535-40cc-8696-073462acc6c7
{
    "ID": "helloservice1",
    "Name": "helloservice",
    "Tags": [
        "v1",
        "master"
    ],
    "Address": "127.0.0.1",
    "Port": 8000,
    "Meta": {"api_version": "1.0"},
    "EnableTagOverride": false,
    "Check": {
        "DeregisterCriticalServiceAfter": "90m",
        "HTTP": "http://www.baidu.com/",
        "Interval": "10s"
    }
}

让服务处于维护状态

./consul maint -enable -service helloservice1 -reason "need to update"

让服务取消维护状态

./consul maint -disable -service helloservice1

members 命令输出 Consul 代理知道的当前成员列表及其状态。节点的状态只能是“alive”，“left”或“failed”。
处于“failed”状态的节点仍然列出，因为在故障实际上只是网络分区的情况下，Consul 会尝试在一定时间内重新连接故障节点。
单机版输出：

集群版输出：

monitor 命令用于连接和跟踪正在运行的 Consul 代理的日志。Monitor 将显示最近的日志，然后继续关注日志，直到中断或远程代理退出之前不会退出。

monitor 命令的强大之处在于它允许您以相对较高的日志级别（例如“warn”）记录代理，但仍然可以访问 debug 日志并在必要时查看 debug 日志。

log-level – 要显示的消息的日志级别。默认情况下，这是“info”。此日志级别可能比代理配置为运行时更详细。可用的日志级别为“trace”，“debug”，“info”，“warn”和“err”。

举个例子

./consul monitor debug

operator 命令为 Consul 操作员提供集群级工具，例如与 Raft 子系统交互。具体子命令的使用说明记得使用 –help
比如：

./consul operator raft --help

下面列出 raft 对等集：
单机版

集群版

可以看到只有 server agent 才参加 raft 对等集的一部分。

reload 命令会触发代理的配置文件重新加载。

SIGHUP 信号通常用于触发重新加载配置，但在某些情况下，触发 CLI 可能更方便。

此命令与信号的操作相同，这意味着它将触发重新加载，但不会等待重新加载完成。重新加载的任何错误都将出现在代理日志中，而不会出现在此命令的输出中。

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

举个例子：
我们将一开始的配置文件，config.json 中的 log_level 由 info 改为 debug。

./consul reload

可以在 consul agent 运行的命令行中看到在重新加载配置。

rtt 命令使用 Consul 的集群网络坐标模型估计两个节点之间的网络往返时间。
由于这里需要多个 server，所以这里我用了前面一篇文章在虚拟机上搭建的集群。

这里由于我只有一个数据中心，没法实验多个数据中心的 rtt，不过使用方法类似，如下

 $ consul rtt -wan n1.dc1 n2.dc2
    Estimated n1.dc1 <-> n2.dc2 rtt: 1.275 ms (using WAN coordinates)

services 命令具有子命令，用于与向本地代理注册的 Consul 服务进行交互。它们提供了有用的命令，例如注册和注销，以便在脚本，开发模式等中轻松注册服务。要查看目录中的所有服务，而不是仅查看代理本地服务，请使用./consul catalog services 命令。
创建一个简单的服务：

./consul services register -name=web

从一个配置文件中创建服务

$ cat web.json
{
  "Service": {"Name": "web"}
}

$  ./consul services register web.json

注销一个服务(两种方式都可以）：

$ ./consul services deregister web.json

$ ./consul services deregister -id web

snapshot 命令具有子命令，用于保存，恢复和检查 Consul 服务器的状态以进行灾难恢复。这些是原子时间点快照，包括键 / 值条目，服务目录，准备好的查询，会话和 ACL。
save：保存 Consul 服务器状态的快照
restore: 恢复 Consul 服务器状态的快照
inspect: 显示有关 Consul 快照文件的信息

tls 命令用于帮助为 Consul TLS 设置 CA 和证书。

consul validate 命令对 Consul 配置文件执行彻底的健全性测试。对于给定的每个文件或目录，该命令将尝试像 consul agent 命令那样解析内容，并捕获任何错误。

这对于仅对配置进行测试很有用，而无需实际启动代理。 这将执行代理程序将执行的所有验证，因此应该为此提供将由代理程序加载的完整配置文件集。此命令无法对部分配置片段进行操作，因为这些片段不会通过完整的代理验证。
比如说验证下我们一开始的配置文件

./consul validate config.json

version 命令打印 Consul 的版本以及它与其他代理进行通信时理解的协议版本。

./consul version

1. 由于篇幅有限，本文的大体上是对命令行的基本介绍，想要用好命令行还需要读读官方文档和 linux 的说明文档。

2. 另外文中出现的集群版：请参考我的另一篇文章，Consul1.5.0 带 ACL 控制集群搭建

https://www.consul.io/docs/co…
https://www.consul.io/docs/ac…
https://www.consul.io/docs/ag…

1. 启动一个带 ACL 控制的 Agent

2. 命令行

acl

agent

catalog

config

connect

debug

watch

event

force-leave

info

intention

join

keygen

keyring

kv

leave

license

lock

login

logout

maint

members

monitor

operator

reload

rtt（round trip time)

services

snapshot

tls

validate

version

最后的说明

参考：

Just My Socks（注册教程内含优惠码）