Consul 설정 방법

Tier: Premium, Ultimate Offering: Self-managed

Consul 클러스터는 서버 및 클라이언트 에이전트로 구성됩니다.

서버는 자체 노드에서 실행되며 클라이언트는 다른 노드에서 실행되어 서버와 통신합니다.

GitLab Premium에는 /etc/gitlab/gitlab.rb를 사용하여 관리할 수 있는 서비스 네트워킹 솔루션 Consul의 번들 버전이 포함되어 있습니다.

전제 조건

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 노드 보안

Consul 노드 간의 통신을 보안하기 위해 TLS 또는 Gossip 암호화를 사용할 수 있는 두 가지 방법이 있습니다.

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 인증서 및 키를 tls_certificate_file, tls_key_file을 사용하여 전달해야 합니다.

TLS가 활성화되면, 기본적으로 서버는 mTLS를 사용하고 HTTPS 및 HTTP(및 TLS 및 비TLS RPC)에서 수신 대기합니다. 클라이언트는 TLS 인증을 사용해야 합니다. 클라이언트 TLS 인증을 비활성화하려면 consul['tls_verify_client'] = false로 설정합니다.

반면에, 클라이언트는 서버 노드에 대한 아웃고잉 연결에만 TLS를 사용하고 수신 요청에 대해서는 HTTP(및 비TLS RPC)에서만 수신 대기합니다. 클라이언트 Consul 에이전트가 수신 연결에 대해 TLS를 사용하도록 강제하려면 consul['https_port']를 음이 아닌 정수로 설정해야 합니다(8501은 Consul의 기본 HTTPS 포트). 이 작업을 위해 tls_certificate_file 및 tls_key_file을 전달해야 합니다. 서버 노드가 클라이언트 TLS 인증을 사용할 때, 클라이언트 TLS 인증서 및 키는 클라이언트 TLS 인증 및 수신 HTTPS 연결 모두에 사용됩니다.

기본적으로 Consul 클라이언트 노드는 TLS 클라이언트 인증을 사용하지 않으며(서버와는 반대로) consul['tls_verify_client'] = true로 설정하여 명시적으로 이를 지시해야 합니다.

다음은 TLS 암호화의 몇 가지 예입니다.

최소 TLS 지원

다음 예제에서 서버는 TLS를 사용하여 수신 연결을 처리합니다(클라이언트 TLS 인증 없이).

Consul 서버 노드

  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
Consul 클라이언트 노드

다음은 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는 TLS를 사용하지 않는 로컬 Consul 에이전트와 통신합니다. 따라서 patroni['consul']['url']에 대한 HTTP URL입니다.

기본 TLS 지원

다음 예제에서 서버는 상호 TLS 인증을 사용합니다.

Consul 서버 노드

  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
Consul 클라이언트 노드

다음은 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는 TLS 인증을 사용하여 Consul 서버 노드와 상호 통신하지만, 로컬 Consul 에이전트와는 TLS를 사용하지 않고 통신합니다. 따라서 patroni['consul']['url']에 대한 HTTP URL입니다.

전체 TLS 지원

다음 예제에서 클라이언트와 서버 모두 상호 TLS 인증을 사용합니다.

Consul 서버, 클라이언트, 그리고 Patroni 클라이언트 인증서는 상호 TLS 인증이 작동하려면 동일한 CA에 의해 발급되어야 합니다.

Consul 서버 노드

  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
Consul 클라이언트 노드

다음은 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

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 버전이 변경되면, 새로운 버전을 사용하기 위해 Consul을 재시작해야 한다는 알림이 gitlab-ctl reconfigure 의 끝에 표시됩니다.

각 노드를 한 번에 하나씩 재시작하세요:

sudo gitlab-ctl restart consul

Consul 노드는 raft 프로토콜을 사용하여 통신합니다. 현재 리더가 오프라인 상태가 되면 리더 선출이 필요합니다. 클러스터 전반의 동기화를 촉진하기 위해 리더 노드가 존재해야 합니다. 너무 많은 노드가 동시에 오프라인으로 전환되면 클러스터가 쿼럼을 잃고 리더를 선출하지 못합니다. 이는 손상된 합의(broken consensus) 때문입니다.

업그레이드 후 클러스터가 복구되지 않는 경우 문제 해결 섹션을 참조하세요. 정전 복구가 특히 관심이 있을 수 있습니다.

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 가이드를 따르세요.