Consul 使用

http://www.jianshu.com/p/b4aaf267f7ba

官网Document https://www.consul.io/docs/index.html
一、介绍
Consul有很多组件，但总的来说，它主要用来发现和配置服务。
（1）服务发现：Consul的客户端可以“provide”一个service，例如api或mysql，其他客户端可以使用Consul来“discover”给定服务的providers。通过DNS或HTTP。
（2）健康检查：Consul客户端可以 检查webserver是否返回200 OK，或本地节点的内存使用率是否低于90%，等等。这些信息可以被用来监视集群的健康，也用于服务发现组件在路由时远离不健康的hosts。
（3）Key/Value存储：可以用于动态配置、leader election等等。使用简单的HTTP API使用。
（4）Multi Datacenter（多数据中心）：这意味着Consul的使用者们不需要再创建额外的抽象层来扩展Consul了。

Consul是一个分布式的、高可用HA的系统。
每一个向Consul提供服务的节点都运行一个Consul agent。运行这个agent对于发现其他服务或get/set key/value数据不是必须的。这个agent负责健康检查service和node自身。
这个agent和一个或多个Consul server通话。Consul Servers存储着数据并replicated数据。Servers自己会选举一个leader。虽然一个server也可以工作，但是3到5是推荐的，以防止失败时导致数据丢失。
如果你的infrastructure(基础设施)的组件要发现其他服务或节点，可以向任何一个Consul server或任何一个Consul agent查询，agent会自动转发请求到servers。
每个Datacenter都运行着一个ConsulServer的集群。当一个跨集群的service discovery或configuration request来到时，本地的Consul servers会转发请求到远端的Datacenter并返回结果。

二、GettingStarted
1、下载zip包 https://www.consul.io/downloads.html
2、安装：解压、拷贝consul文件到任何的PATH路径中以方便它可以直接被执行，例如 /usr//local/bin。

三、运行agent:
(1)启动consul:
consul agent -dev #以dev模式运行,这种模式启动一个单节点的Consul环境，它不适用于生产环境。因为不持久化任何state。
consul agent -server #以server模式启动,
consul agent #默认是以client模式运行,client非常轻量级，它注册服务、运行healthchecks、转发query到servers。agent必须运行于集群上的每一个节点。
consul agent -dev -config-dir /etc/consul.d #或-config-file。指定配置文件夹，Consul会加载其中的所有文件。配置文件是json格式，除了提供启动agent时的命令行选项外，还用来提供check和service定义。

kill -HUP ${consulPid} #重新载入配置文件。
consul reload #重新载入配置文件。

(2)关闭consul:
consul leave #关闭consul并离开集群。也可以使用Ctrl+C或kill -INT来gracefully停止agent，这种体面的离开方式让consule可以有机会通知集群其他成员自己的离开。如果你强制地结束了agent，其他member会检测到这个节点的failed。当成员离开时，它的services和checks都会从catalog中移除。当成员failed时，它的health只是简单的被标记为critical，并不会从catalog中移除。Consul会自动尝试重新连接failed节点，允许它从恶劣的网络环境中恢复，显然离开的nodes不会被重新连接。另外，如果这个节点是server，体面的离开对避免潜在的中断的可能很重要。
为了防止dead nodes的积累，consul会自动把dead nodes移除出catalog。这个过程被称为reaping（收割）。默认是72小时的间隔（不建议更改）

(3)consul集群:

consul集群:当一个consul agent启动后，它不知道任何其他节点,要学习到集群中的其他节点，agent必须加入一个已经存在的集群(cluster)。要加入这样的集群，它只需要知道这个集群中的一个节点即可。它加入后，将会和这个member gossip（交谈）并迅速发现集群中的其他节点。一个consul agent可以加入任何类型的其他agent，而不只是那些运行于server mode的agent。

server节点的启动:

consul agent -server -bootstrap-expect 1 -node=agent-one -bind=10.0.209.123 -data-dir /tmp/consul -config-dir /etc/consul.d

-server 以server模式运行

-bootstrap-expect n：表示期望有多少个server nodes加入。这个选项的目的是delay the bootstrapping of the replicated log 直到所有的server都成功加入

-node=node-name 集群中的每个node必须有一个唯一的名称。默认情况下，Consul使用机器的hostname

-bind=ip 表示Consul监听的地址,而且它必须能够被集群中的其他节点访问。Consul默认会监听第一个private IP,但最好还是提供一个。生产设备上的服务器通常有好几个网卡，所以指定一个不会出错

-data-dir 指定数据目录

-config-dir指定配置文件夹，Consul会加载其中的所有文件

-datacenter 指定数据中心名称，默认是dc1

client节点的启动

consul agent -node=agent-two -bind=10.0.209.122 -data-dir /tmp/consul -config-dir /etc/consul.d

consul members # 现在你有了两个运行中的agent，一个server，一个client。分别在两个节点上运行这个命令，可以看到现在他们还不知道彼此。
consul join 10.0.209.122 #加入集群：现在我们告诉第一个agent加入第二个agent
consul members # 现在看看集群中有2个节点了

那如何在启动时自动加入一个cluster呢?

consul agent ... -join 1.1.1.1 1.1.1.2 #或-retry-join

或者在配置文件中使用 start_join

(4)查询节点:
consul members #查询集群成员
dig @127.0.0.1 -p 8600 agent-two.node.consul #查询节点
dig @127.0.0.1 -p 8600 agent-two.node.[DATACENTER].consul
curl http://127.0.0.1:8500/v1/catalog/nodes #通过API的方式查询节点
curl http://127.0.0.1:8500/v1/catalog/node/agent-two

(5)服务声明和查询:

注：虽然这里使用的是通过文件声明服务，但一般都是使用 HTTP API 动态地增加、移除和修改services。

consul agent -dev -config-dir /etc/consul.d # -config-dir指定配置文件夹，Consul会加载其中的所有文件
#
echo '{"service": {"name": "web", "port": 80, "tags": ["rails"]}}' >/etc/consul.d/web.json #定义一个服务“web”
consul reload #重新载入配置文件

dig @127.0.0.1 -p 8600 web.service.consul #查询web服务 (如果没有dig命令，请yum install bind-utils)
dig @127.0.0.1 -p 8600 rails.web.service.consul #通过tags来过滤services
curl http://127.0.0.1:8500/v1/catalog/services
curl http://127.0.0.1:8500/v1/catalog/service/web #通过HTTP API方式查询web服务
curl 'http://127.0.0.1:8500/v1/health/service/web?passing #使用健康状态过滤服务

(6)健康检查:

定义 Checks

一个检查可以通过提供一个check定义文件或调用HTTP API来注册

这里介绍使用check定义文件的方式

echo '{"check": {"name": "ping","script": "ping -c1 google.com >/dev/null","interval": "30s"}}' >/etc/consul.d/ping.json

echo '{"service": {"name": "web", "tags": ["rails"], "port": 80,"check": {"script":"curl 127.0.0.1 >/dev/null 2>&1", "interval": "10s"}}}' >/etc/consul.d/web.json

第一个definition增加了一个host-level check，名字为ping。这个check每30秒运行一次，调用ping -c1 google.com . 基于脚本的健康检查，在运行脚本时使用的用户就是启动consul agent的用户。如果脚本以非0值退出，那么这个node被标记为unhealthy。

第二个definition修改了web service，增加了一个check，每10秒运行一次，使用curl来验证web server是否可访问。如果脚本以非0值退出，那么这个service被标记为unhealthy。

consul reload #重新载入配置文件

然后我们可以看到service.web is now critical，因为实际上我们还没有在第二个节点上运行web server，check失败了。

curl http://127.0.0.1:8500/v1/health/state/critical #使用HTTP API来查询，这里是查询所有的failing checks。
dig @127.0.0.1 -p 8600 web.service.consul #结果查询不到unhealthy的service。

(7)KEY/VALUE存储:
curl -v http://127.0.0.1:8500/v1/kv/?recurse #因为现在还没有值，所以不会返回任何内容，使用-v参数是为了让你看看返回的详细信息
curl -X PUT -d 'test' http://127.0.0.1:8500/v1/kv/web/key1 #增加键web/key1,值为test
curl -X PUT -d 'test' http://127.0.0.1:8500/v1/kv/web/key2?flags=42 #增加键web/key2=test,同时指定flags=42，flags默认值是0，flags值可以是一个64位的整数值，flags对于Consul没有任何意义，但你可以将他作为有意义的metadata
curl http://127.0.0.1:8500/v1/kv/?recurse #现在再查询可以看到返回结果中value为base64编码后的值，这是为了允许一些non-UTF8的字符。

?recurse表示取得遍历所有的key的值，在删除时也一样

curl http://127.0.0.1:8500/v1/kv/web/key1 #单个key的查询

curl -X DELETE http://127.0.0.1:8500/v1/kv/web/sub?recurse #删除

curl -X PUT -d 'newval' http://127.0.0.1:8500/v1/kv/web/key1?cas=97
curl -X PUT -d 'newval' http://127.0.0.1:8500/v1/kv/web/key1?cas=97

更新值时consul提供了一个Check-and-Set操作，通过使用?cas=[ModifyIndex],这个值在get的结果里通过 ModifyIndex提供。如果该值不是get结果里的 ModifyIndex ，那么更新操作将失败。

例如上面的例子中，假设当前的web/key1的ModifyIndex是97，那么第一次更新成功，第二次更新就会失败。

curl "http://127.0.0.1:8500/v1/kv/web/key2?index=101&wait=5s" #表示等待web/key2的ModifyIndex大于等于101，并且最多等5秒，然后返回当前的值

另外，查询是还可以指定?dc=xx，默认是查询agent所在的Datacenter，注意到每个Datacenter都有自己的kv系统，并且没有内置的replication。

四、consul cli:
consul -v #查看consul版本
consul info #提供了各种debugging信息，这些信息对operator会有用的。

consul reload：触发重新加载配置文件。等于kill -1或kill -HUP

consul configtest -config-file 或 -config-dir #只验证配置文件，不真正启动agent。

consul join 10.0.209.123 10.0.209.124 #可以指定多个node
consul leave #优雅的离开并shutdown
consul force-leave #强制集群中某个member进入“left”状态。注意，如果member实际上还是alive，它会rejoin the cluster。这个方法的真正意图是强制移除那些“failed”的节点。

consul members：
consul monitor #用来连接一个运行中的consul agent，并follow它的logs。这个命令的强大之处在于你可以使用一个非常高的log level（例如warn）来追踪日志，
consul monitor -log-level trace/debug/info/warn/err

consul kv delete/export/get/import/put #kv操作

consul event #fire一个自定义的user event到整个Datacenter。它们可以用于自动化部署、重启services、或执行其他协同动作。events可以通过使用watch的方式被处理。 event通过gossip协议传播,不保证一定传播到。不像其他的大部分consul data（它们都通过consensus协议被replicated），event数据是通过gossip 一点一点传播的。这意味着它没有被持久化并且没有顺序（例如fire两个event，不代表后面fire的就一定后收到）。 同时event的payload也有限制，但是没有一个准确的值，一般应该小于100bytes。

consul exec #在集群中所有的节点上远程执行并返回命令回显。例如，可以运行uptime命令在所有提供web service的机制上。 远程执行通过在KV中存储一个job，然后通过event系统通知节点有新的job并执行。 注意命令的输出结果不要太多，输出结果也是存储在KV中，如果有一个大的集群，这可能会让集群不可达。

consul keygen
consul keyring

consul lock #提供了一种简单的分布式锁机制。锁或semaphore通过给定的前缀在KV里创建，并且只有持有时，子进程才调用。如果lock丢失了或通信破坏了，子进程就被终止了。

consul maint #提供了对service和node的maintenance mode的control。使用这个命令，可以 标记某个节点提供的一个service或者某个节点整体为“under maintenance” 。在这种模式下，service和node将不会出现在DNS查询结果里或API结果里。实际上这让service或node离开了available “healthy” nodes 池。 实际上，maintenance mode是在health check为critical status时激活，取消注册health check后去激活。

consul operator #提供集群级别的工具，例如与Raft subsystem交互。使用这个命令要特别特别小心。因为不适当的使用可能导致Consul中断甚至丢失数据。

consul rtt #估算两个节点之间网络往返时间。round trip time

consul watch #监控一个节点的data view（list of nodes,services members,key value等等）的变化，并且调用一个进程（使用data view的最新的数据）。如果没有指定process，当前值会被dumped到stdout。

五、HTTP API: https://www.consul.io/docs/agent/http.html
1、所有的API路径的前缀都是 /v1/ 。这个文档也只是介绍 v1 API。例如:
http://10.245.6.90:8500/v1/agent/members
2、有些 endpoints 使用或需要 ACL token 来操作。虽然agent可以被配置为使用默认的token，但是token可以在每次请求时都指定，通过在请求的Header里加入 X-Consul-Token 的值 或 在请求url中加入 token 参数(优先级最高)。但是推荐使用请求头里加入Header的方式。
3、当启用了authentication(认证)时，就应该在请求中传递token。下面是一个例子:
curl --header "X-Consul-Token: abcd1234" https://10.245.6.90:8500/v1/agent/members
4、很多(但不是所有的)endpoints都支持阻塞查询特色。支持该特色的endpoints会在response的HTTP header里包含一个 X-Consul-Index 的key。这个key标识了请求资源的当前状态。 然后在接下来的查询里可以在请求头里加入这个 X-Consul-Index key，表示你想等待任何在这个key表示的index之后的更改后的资源值。
5、一致性模型(consistency modes)：很多查询的endpoints都支持多个级别的一致性。模型有:

• default : 如果没有指定，default一般都是强一致的。除了短暂的leader重选时的空窗期。
• consistent : 一般不要使用这种模式，除非你实在不能忍受 a stale read。

• stale : 这个模式允许任意的server来服务读请求，而不管它是不是leader。这意味着read可以任意的stale(不新鲜)。然而一般来说result都会在50ms内被同步完成。
  要想切换这些模式，应该在请求url中提供 stale 或 consistent 参数，如果同时提供会报错。
  为了支持数据的staleness不新鲜程度，response的HTTP Header中会包含 X-Consul-LastContact(表示最近和leader node的通信时间毫秒数)、X-Consul-KnownLeader(表明是否有已知的leader) 字段。这些数据可以被client用来判断数据的不新鲜程度并作出相应的动作决策。
  6、默认情况下，所有的response输出都是最小化的JSON格式的。如果请求url中传递了pretty参数，会返回格式化的JSON数据。
  7、HTTP 方法:Consul的API目标是RESTful，虽然有一些例外。API响应标准的HTTP GET、PUT、DELETE方法。例子:
  curl --request PUT --data 'hello world!' https://consul.rocks/v1/kv/foo
  8、有些库文件可以用来更方便的调用API。一些是官方的，一些是第三方提供的。
  https://www.consul.io/api/libraries-and-sdks.html
  9、具体的API请自行查看。
  10、一些常用的:
  agent相关的API

  列出所有的members

  curl http://10.245.6.90:8500/v1/agent/members

  列出所有注册到本地agent的checks，本地知道的checks可能和catalog报告的不一致。

  curl http://10.245.6.90:8500/v1/agent/checks

  注册check到本地agent。checks可以是script、HTTP、TCP或TTL 类型。agent负责管理check的状态并同步到catalog。

  curl --request PUT --data @payload.json http://10.245.6.90:8500/v1/agent/check/register

  取消注册check到本地agent。agent会小心的从catalog中取消注册check。如果提供的check ID不存在，则不采取任何动作

  curl --request PUT http://10.245.6.90:8500/v1/agent/check/deregister/:check_id

  TTL check pass

  curl http://10.245.6.90:8500/v1/agent/check/pass/:check_id

  TTL check warn

  curl http://10.245.6.90:8500/v1/agent/check/warn/:check_id

  TTL check fail

  curl http://10.245.6.90:8500/v1/agent/check/fail/:check_id

  TTL check update

  curl http://10.245.6.90:8500/v1/agent/check/update/:check_id

  列出所有注册到本地agent的服务

  curl http://10.245.6.90:8500/v1/agent/services

  注册服务到本地agent、可以同时提供健康检查。agent负责管理服务的状态，并同步到global catalog

  curl --request PUT --data @payload.json http://10.245.6.90:8500/v1/agent/service/register

  取消注册服务到本地agent，如果服务不存在，则不采取任何动作。agent负责从catalog中删除该服务。如果该服务关联了一个check，那么check也会被删除。

  curl --request PUT http://10.245.6.90:8500/v1/agent/service/deregister/:service_id

  将服务设置为maintenance mode，这个模式下的服务被标记为不可达而且对外不可见。而且服务的这个状态会被持久化，当agent重启时服务也会自动恢复到这个状态。

  curl --request PUT http://10.245.6.90:8500/v1/agent/service/maintenance/:service_id

  catalog相关的API

  注册Entity，是较低级别的注册或更新entries到catalog。一般都是使用agent endpoints来注册。

  curl --request PUT --data @payload.json http://10.245.6.90:8500/v1/catalog/register

  取消注册Entity，

  curl --request PUT --data @payload.json http://10.245.6.90:8500/v1/catalog/register

  列出所有的datacenters

  curl http://10.245.6.90:8500/v1/catalog/datacenters

  列出所有的nodes

  curl http://10.245.6.90:8500/v1/catalog/nodes

  列出所有的服务

  curl http://10.245.6.90:8500/v1/catalog/services

  列出提供某服务的所有节点

  curl http://10.245.6.90:8500/v1/catalog/service/:service

  列出提供某节点提供的所有服务 :node是"Node"字段的值 不是"ID"的值

  curl http://10.245.6.90:8500/v1/catalog/node/:node

  KV相关的API

  读取 Key 的值

  curl http://10.245.6.90:8500/v1/kv/:key

  创建/更新 key ,返回的内容只有true或false

  curl --request PUT --data 'xxx' http://10.245.6.90:8500/v1/kv/:key

  删除key ,返回的内容只有true或false

  curl --request DELETE http://10.245.6.90:8500/v1/kv/:key

  Health相关的API

  列出某个节点的所有Checks

  curl http://10.245.6.90:8500/v1/health/node/:node

  列出某服务的所有Checks

  curl http://10.245.6.90:8500/v1/health/checks/:service

  列出某服务的所有节点

  curl http://10.245.6.90:8500/v1/health/service/:service

  列出某状态的所有Checks

  curl http://10.245.6.90:8500/v1/health/state/:state

六、consul agent 启动选项和配置文件: https://www.consul.io/docs/agent/options.html
七、使用的端口:
8300:TCP # Server RPC :agent server 使用的，用于处理其他agent发来的请求
8301:TCP and UDP # Serf LAN: 所有的agent都要使用这个端口，用于处理LAN中的gossip，
8302:TCP and UDP # Serf WAN：agent Server使用的，处理WAN中的与其他server的gossip
8400:TCP # 所有agent都要使用的端口，用于处理从CLI来的RPC。
8500:TCP # 所有agent都要使用的端口，用于处理HTTP API。
8600:TCP and UDP # 用于处理 DNS 查询。