• 前提条件
• 配置 Consul 节点
• 保护 Consul 节点
  • TLS 加密
    • 最小 TLS 支持
    • 默认 TLS 支持
    • 完全 TLS 支持
  • Gossip 加密
• 升级 Consul 节点
• 故障排除 Consul
  • 检查集群成员
  • 重启 Consul
  • Consul 节点无法通信
  • Consul 无法启动 - 多个私有 IP
  • 停机恢复
    • 从头重建
    • 恢复故障节点

{{< details >}}

• Tier: 专业,旗舰版
• Offering: 私有化部署

{{< /details >}}

一个 Consul 集群由服务器和客户端代理组成。服务器在自己的节点上运行，客户端在其他节点上运行，并与服务器通信。

极狐GitLab 专业版包含一个捆绑版本的 Consul，这是一种服务网络解决方案，您可以使用 /etc/gitlab/gitlab.rb 进行管理。

前提条件

在配置 Consul 之前：

1. 查看参考架构文档，以确定您应该拥有的 Consul 服务器节点的数量。
2. 如有必要，确保您的防火墙中开放了适当的端口。

配置 Consul 节点

在 每个 Consul 服务器节点上：

1. 按照说明安装极狐GitLab，选择您喜欢的平台，但在询问时不要提供 EXTERNAL_URL 值。

2. 编辑 /etc/gitlab/gitlab.rb，并通过替换 retry_join 部分中注明的值来添加以下内容。在下面的示例中，有三个节点，其中两个用其 IP 表示，一个用其 FQDN 表示，您可以使用任意一种表示方式：

   # 禁用除 Consul 外的所有组件
   roles ['consul_role']
   
   # Consul 节点：可以是 FQDN 或 IP，用空格分隔
   consul['configuration'] = {
     server: true,
     retry_join: %w(10.10.10.1 consul1.gitlab.example.com 10.10.10.2)
   }
   
   # 禁用自动迁移
   gitlab_rails['auto_migrate'] = false
   

3. 重新配置极狐GitLab，以使更改生效。

4. 运行以下命令以确保 Consul 配置正确，并验证所有服务器节点是否正在通信：

   sudo /opt/gitlab/embedded/bin/consul members
   

   输出应类似于：

   Node                 Address               Status  Type    Build  Protocol  DC
   CONSUL_NODE_ONE      XXX.XXX.XXX.YYY:8301  alive   server  0.9.2  2         gitlab_consul
   CONSUL_NODE_TWO      XXX.XXX.XXX.YYY:8301  alive   server  0.9.2  2         gitlab_consul
   CONSUL_NODE_THREE    XXX.XXX.XXX.YYY:8301  alive   server  0.9.2  2         gitlab_consul
   

   如果结果显示任何节点的状态不是 alive，或者缺少任何三个节点，请参见故障排除部分。

保护 Consul 节点

您可以通过使用 TLS 或 Gossip 加密来保护 Consul 节点之间的通信。

TLS 加密

默认情况下，Consul 集群未启用 TLS，默认配置选项及其默认值为：

consul['use_tls'] = false
consul['tls_ca_file'] = nil
consul['tls_certificate_file'] = nil
consul['tls_key_file'] = nil
consul['tls_verify_client'] = nil

这些配置选项适用于客户端和服务器节点。

要在 Consul 节点上启用 TLS，请从 consul['use_tls'] = true 开始。根据节点的角色（服务器或客户端）和您的 TLS 偏好，您需要提供进一步的配置：

• 在服务器节点上，您至少必须指定 tls_ca_file、tls_certificate_file 和 tls_key_file。
• 在客户端节点上，当服务器上禁用客户端 TLS 身份验证（默认启用）时，您至少必须指定 tls_ca_file，否则您必须使用 tls_certificate_file、tls_key_file 传递客户端 TLS 证书和密钥。

启用 TLS 后，默认情况下，服务器使用 mTLS 并监听 HTTPS 和 HTTP（以及 TLS 和非 TLS RPC）。它期望客户端使用 TLS 身份验证。您可以通过设置 consul['tls_verify_client'] = false 来禁用客户端 TLS 身份验证。

另一方面，客户端仅对与服务器节点的传出连接使用 TLS，并且仅对传入请求监听 HTTP（和非 TLS RPC）。您可以通过将 consul['https_port'] 设置为非负整数（8501 是 Consul 的默认 HTTPS 端口）来强制客户端 Consul 代理对传入连接使用 TLS。您还必须传递 tls_certificate_file 和 tls_key_file 以使其正常工作。当服务器节点使用客户端 TLS 身份验证时，客户端 TLS 证书和密钥用于 TLS 身份验证和传入 HTTPS 连接。

默认情况下，Consul 客户端节点不使用 TLS 客户端身份验证（与服务器相反），您需要通过设置 consul['tls_verify_client'] = true 来显式指示它们执行此操作。

以下是一些 TLS 加密的示例。

最小 TLS 支持

在以下示例中，服务器对传入连接使用 TLS（不使用客户端 TLS 身份验证）。

{{< tabs >}}

{{< tab title=”Consul server node” >}}

1. 编辑 /etc/gitlab/gitlab.rb：

   consul['enable'] = true
   consul['configuration'] = {
     'server' => true
   }
   
   consul['use_tls'] = true
   consul['tls_ca_file'] = '/path/to/ca.crt.pem'
   consul['tls_certificate_file'] = '/path/to/server.crt.pem'
   consul['tls_key_file'] = '/path/to/server.key.pem'
   consul['tls_verify_client'] = false
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

{{< /tab >}}

{{< tab title=”Consul client node” >}}

以下示例可以在 Patroni 节点上配置。

1. 编辑 /etc/gitlab/gitlab.rb：

   consul['enable'] = true
   consul['use_tls'] = true
   consul['tls_ca_file'] = '/path/to/ca.crt.pem'
   patroni['consul']['url'] = 'http://localhost:8500'
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

Patroni 与本地 Consul 代理通信，该代理对传入连接不使用 TLS。因此，patroni['consul']['url'] 的 HTTP URL。

{{< /tab >}}

{{< /tabs >}}

默认 TLS 支持

在以下示例中，服务器使用相互 TLS 身份验证。

{{< tabs >}}

{{< tab title=”Consul server node” >}}

1. 编辑 /etc/gitlab/gitlab.rb：

   consul['enable'] = true
   consul['configuration'] = {
     'server' => true
   }
   
   consul['use_tls'] = true
   consul['tls_ca_file'] = '/path/to/ca.crt.pem'
   consul['tls_certificate_file'] = '/path/to/server.crt.pem'
   consul['tls_key_file'] = '/path/to/server.key.pem'
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

{{< /tab >}}

{{< tab title=”Consul client node” >}}

以下示例可以在 Patroni 节点上配置。

1. 编辑 /etc/gitlab/gitlab.rb：

   consul['enable'] = true
   consul['use_tls'] = true
   consul['tls_ca_file'] = '/path/to/ca.crt.pem'
   consul['tls_certificate_file'] = '/path/to/client.crt.pem'
   consul['tls_key_file'] = '/path/to/client.key.pem'
   patroni['consul']['url'] = 'http://localhost:8500'
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

Patroni 与本地 Consul 代理通信，该代理对传入连接不使用 TLS，即使它对 Consul 服务器节点使用 TLS 身份验证。因此，patroni['consul']['url'] 的 HTTP URL。

{{< /tab >}}

{{< /tabs >}}

完全 TLS 支持

在以下示例中，客户端和服务器都使用相互 TLS 身份验证。

Consul 服务器、客户端和 Patroni 客户端证书必须由同一个 CA 签发才能使相互 TLS 身份验证正常工作。

{{< tabs >}}

{{< tab title=”Consul server node” >}}

1. 编辑 /etc/gitlab/gitlab.rb：

   consul['enable'] = true
   consul['configuration'] = {
     'server' => true
   }
   
   consul['use_tls'] = true
   consul['tls_ca_file'] = '/path/to/ca.crt.pem'
   consul['tls_certificate_file'] = '/path/to/server.crt.pem'
   consul['tls_key_file'] = '/path/to/server.key.pem'
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

{{< /tab >}}

{{< tab title=”Consul client node” >}}

以下示例可以在 Patroni 节点上配置。

1. 编辑 /etc/gitlab/gitlab.rb：

   consul['enable'] = true
   consul['use_tls'] = true
   consul['tls_verify_client'] = true
   consul['tls_ca_file'] = '/path/to/ca.crt.pem'
   consul['tls_certificate_file'] = '/path/to/client.crt.pem'
   consul['tls_key_file'] = '/path/to/client.key.pem'
   consul['https_port'] = 8501
   
   patroni['consul']['url'] = 'https://localhost:8501'
   patroni['consul']['cacert'] = '/path/to/ca.crt.pem'
   patroni['consul']['cert'] = '/opt/tls/patroni.crt.pem'
   patroni['consul']['key'] = '/opt/tls/patroni.key.pem'
   patroni['consul']['verify'] = true
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

{{< /tab >}}

{{< /tabs >}}

Gossip 加密

可以加密 Gossip 协议以保护 Consul 代理之间的通信。默认情况下未启用加密，要启用加密需要共享加密密钥。为了方便，可以使用 gitlab-ctl consul keygen 命令生成密钥。密钥必须是 32 字节长，Base 64 编码，并在所有代理上共享。

以下选项在客户端和服务器节点上均有效。

要启用 Gossip 协议：

1. 编辑 /etc/gitlab/gitlab.rb：

   consul['encryption_key'] = <base-64-key>
   consul['encryption_verify_incoming'] = true
   consul['encryption_verify_outgoing'] = true
   

2. 重新配置极狐GitLab：

   sudo gitlab-ctl reconfigure
   

要在现有数据中心启用加密，请手动设置这些选项以进行滚动更新。

升级 Consul 节点

要升级您的 Consul 节点，请升级极狐GitLab 软件包。

节点应：

• 在升级 Linux 软件包之前是健康集群的成员。
• 一次升级一个节点。

通过在每个节点上运行以下命令来识别集群中任何现有的健康问题。如果集群健康，则命令返回一个空数组：

curl "http://127.0.0.1:8500/v1/health/state/critical"

如果 Consul 版本已更改，您会在 gitlab-ctl reconfigure 结束时看到一条通知，提示您必须重新启动 Consul 才能使用新版本。

一次重启一个 Consul 节点：

sudo gitlab-ctl restart consul

Consul 节点使用 raft 协议进行通信。如果当前领导者下线，则必须进行领导者选举。必须存在领导节点以促进集群的同步。如果同时有太多节点下线，集群将失去法定人数，并且由于共识中断，无法选举出领导者。

如果集群在升级后无法恢复，请查阅故障排除部分。停机恢复可能特别有用。

极狐GitLab 使用 Consul 仅存储易于重新生成的临时数据。如果捆绑的 Consul 未被极狐GitLab 以外的任何进程使用，您可以从头重建集群。

故障排除 Consul

如果您需要调试任何问题，请参见以下操作。 您可以通过运行以下命令查看任何错误日志：

sudo gitlab-ctl tail consul

检查集群成员

要确定哪些节点是集群的一部分，请在集群中的任何成员上运行以下命令：

sudo /opt/gitlab/embedded/bin/consul members

输出应类似于：

Node            Address               Status  Type    Build  Protocol  DC
consul-b        XX.XX.X.Y:8301        alive   server  0.9.0  2         gitlab_consul
consul-c        XX.XX.X.Y:8301        alive   server  0.9.0  2         gitlab_consul
consul-c        XX.XX.X.Y:8301        alive   server  0.9.0  2         gitlab_consul
db-a            XX.XX.X.Y:8301        alive   client  0.9.0  2         gitlab_consul
db-b            XX.XX.X.Y:8301        alive   client  0.9.0  2         gitlab_consul

理想情况下，所有节点的 Status 都为 alive。

重启 Consul

如果需要重启 Consul，重要的是以受控方式进行，以保持法定人数。如果法定人数丢失，为了恢复集群，您需要遵循 Consul 停机恢复 过程。

为了安全起见，建议您一次只在一个节点上重启 Consul，以确保集群保持完整。对于较大的集群，可以一次重启多个节点。请参阅Consul 共识文档以了解它可以容忍的故障数量。这是它可以承受的同时重启次数。

要重启 Consul：

sudo gitlab-ctl restart consul

Consul 节点无法通信

默认情况下，Consul 尝试绑定到 0.0.0.0，但它为其他 Consul 节点通信而在节点上宣传第一个私有 IP 地址。如果其他节点无法在此地址上与某个节点通信，则集群状态失败。

如果遇到此问题，则在 gitlab-ctl tail consul 中输出如下消息：

2017-09-25_19:53:39.90821     2017/09/25 19:53:39 [WARN] raft: no known peers, aborting election
2017-09-25_19:53:41.74356     2017/09/25 19:53:41 [ERR] agent: failed to sync remote state: No cluster leader

要解决此问题：

1. 在每个节点上选择一个地址，使所有其他节点都可以通过该地址访问此节点。

2. 更新您的 /etc/gitlab/gitlab.rb

   consul['configuration'] = {
     ...
     bind_addr: 'IP ADDRESS'
   }
   

3. 重新配置极狐GitLab;

   gitlab-ctl reconfigure
   

如果仍然看到错误，您可能需要擦除 Consul 数据库并在受影响的节点上重新初始化。

Consul 无法启动 - 多个私有 IP

如果某个节点有多个私有 IP，Consul 不知道要宣传哪个私有地址，然后在启动时立即退出。

在 gitlab-ctl tail consul 中输出如下消息：

2017-11-09_17:41:45.52876 ==> Starting Consul agent...
2017-11-09_17:41:45.53057 ==> Error creating agent: Failed to get advertise address: Multiple private IPs found. Please configure one.

要解决此问题：

1. 在节点上选择一个地址，使所有其他节点都可以通过该地址访问此节点。

2. 更新您的 /etc/gitlab/gitlab.rb

   consul['configuration'] = {
     ...
     bind_addr: 'IP ADDRESS'
   }
   

3. 重新配置极狐GitLab;

   gitlab-ctl reconfigure
   

停机恢复

如果您在集群中丢失了足够的 Consul 节点以致打破法定人数，则集群被认为已失败，并且在没有人工干预的情况下无法运行。在这种情况下，您可以从头重建节点或尝试恢复。

从头重建

默认情况下，极狐GitLab 在 Consul 节点中不存储任何无法重建的内容。要擦除 Consul 数据库并重新初始化：

sudo gitlab-ctl stop consul
sudo rm -rf /var/opt/gitlab/consul/data
sudo gitlab-ctl start consul

之后，节点应重新启动，其他服务器代理也应重新加入。不久之后，客户端代理也应重新加入。

如果它们不加入，您可能还需要在客户端上擦除 Consul 数据：

sudo rm -rf /var/opt/gitlab/consul/data

恢复故障节点

如果您利用 Consul 存储其他数据并希望恢复故障节点，请遵循 Consul 指南以恢复故障集群。