- 요구 사항
- 설정 지침
- 복제 요인 구성
- 리포지터리 확인
- 자동 장애 조치 및 주 선출 전략
Gitaly 클러스터 구성
다음 중 하나를 사용하여 Gitaly 클러스터를 구성하세요.
- 설치 참조 구조의 일부로 제공되는 Gitaly 클러스터 구성 지침은 다음과 같습니다.
- 이 페이지에서 이어지는 사용자 정의 구성 지침.
더 작은 GitLab 설치에는 Gitaly 자체만 필요할 수 있습니다.
요구 사항
Gitaly 클러스터의 최소 권장 구성은 다음과 같습니다.
- 로드 밸런서 1대
- PostgreSQL 서버 1대 (PostgreSQL 11 이상)
- Praefect 노드 3대
- Gitaly 노드 3대 (기본 1대, 보조 2대)
트랜잭션이 변이 RPC 호출 중 하나의 Gitaly 노드가 실패하는 경우를 위해 Gitaly 노드를 홀수로 구성해야합니다.
구현 세부 정보는 설계 문서를 참조하십시오.
네트워크 지연 및 연결성
Gitaly 클러스터의 네트워크 지연은 이상적으로 싱글 디지트 밀리초로 메트릭 가능해야 합니다. 지연은 특히 다음에 중요합니다.
- Gitaly 노드의 상태 확인: 노드는 1초 이내에 응답해야 합니다.
- 강력한 일관성을 요구하는 참조 트랜잭션: 낮은 지연 시간은 Gitaly 노드가 변경 사항에 대해 더 빨리 합의할 수 있음을 의미합니다.
Gitaly 노드 간에 적합한 지연 시간을 달성하는 방법:
- 물리적 네트워크의 경우 일반적으로 고대역폭, 단일 위치 연결이 필요합니다.
- 클라우드의 경우 같은 지역 (가용 영역 간 복제를 허용하는 것을 포함하여)에서 작동하는 것을 의미합니다. 이러한 링크는 이 유형의 동기화를 위해 설계되었습니다. Gitaly 클러스터에는 2밀리초 미만의 지연 시간이 충분합니다.
복제를 위한 낮은 네트워크 지연 시간을 제공할 수 없는 경우(예: 먼 위치 간), Geo를 고려하십시오. 추가 정보는 Geo와의 비교를 참조하십시오.
Gitaly 클러스터 컴포넌트는 서로 다양한 노선으로 통신합니다. 방화벽 규칙은 Gitaly 클러스터가 올바르게 작동하도록 다음을 허용해야 합니다.
출발지 | 목적지 | 기본 포트 | TLS 포트 |
---|---|---|---|
GitLab | Praefect 로드 밸런서 | 2305
| 3305
|
Praefect 로드 밸런서 | Praefect | 2305
| 3305
|
Praefect | Gitaly | 8075
| 9999
|
Praefect | GitLab (내부 API) | 80
| 443
|
Gitaly | GitLab (내부 API) | 80
| 443
|
Gitaly | Praefect 로드 밸런서 | 2305
| 3305
|
Gitaly | Praefect | 2305
| 3305
|
Gitaly | Gitaly | 8075
| 9999
|
Praefect 데이터베이스 리포지터리
요구 사항은 비교적 낮습니다. 데이터베이스에는 다음의 메타데이터만 포함되어 있습니다.
- 리포지터리의 위치
- 일부 대기 작업
리포지터리 수에 따라 다르지만, 좋은 최소값은 주로 GitLab 애플리케이션 데이터베이스와 유사한 5-10 GB입니다.
설정 지침
Linux 패키지를 사용하여 GitLab을 설치한 경우 다음 단계를 따르세요.
- 준비
- Praefect 데이터베이스 구성
- Praefect 프록시/라우터 구성
- 각 Gitaly 노드 구성 (각 Gitaly 노드에 대해 1회씩)
- 로드 밸런서 구성
- GitLab 서버 구성 업데이트
- Grafana 구성
준비
시작하기 전에 이미 작동 중인 GitLab 인스턴스가 있어야 합니다. GitLab을 설치하는 방법을 알아보세요.
PostgreSQL 서버를 프로비저닝하세요. Linux 패키지에 포함된 PostgreSQL을 사용하고 PostgreSQL 데이터베이스를 구성하기 위해 해당 PostgreSQL을 사용해야합니다. 외부 PostgreSQL 서버(버전 11 이상)를 사용할 수도 있지만 매뉴얼으로 설정해야합니다.
새 노드를 모두 설치하여 준비하세요. 다음이 필요합니다.
- PostgreSQL 노드 1대
- PgBouncer 노드 1대 (선택 사항)
- 최소 필수 리포지터리가 필요한 Praefect 노드 1대
- 고성능 CPU, 고성능 메모리, 빠른 리포지터리가 필요한 Gitaly 노드 3대
- GitLab 서버 1대
또한 각 노드의 IP/호스트 주소가 필요합니다.
-
PRAEFECT_LOADBALANCER_HOST
: Praefect 로드 밸런서의 IP/호스트 주소 -
POSTGRESQL_HOST
: PostgreSQL 서버의 IP/호스트 주소 -
PGBOUNCER_HOST
: PostgreSQL 서버의 IP/호스트 주소 -
PRAEFECT_HOST
: Praefect 서버의 IP/호스트 주소 -
GITALY_HOST_*
: 각 Gitaly 서버의 IP 또는 호스트 주소 -
GITLAB_HOST
: GitLab 서버의 IP/호스트 주소
Google Cloud Platform, SoftLayer 또는 가상 사설 클라우드(VPC)를 제공하는 기타 공급업체를 사용하는 경우 각 클라우드 인스턴스에 대한 사설 주소(“Google Cloud Platform의 내부 주소”에 해당)를 PRAEFECT_HOST
, GITALY_HOST_*
, GITLAB_HOST
로 사용할 수 있습니다.
Secrets
컴포넌트 간의 통신은 아래에 설명된 다양한 시크릿(secrets)으로 안전하게 보호됩니다. 시작하기 전에 각각에 대해 고유한 시크릿을 생성하고 메모해 놓으세요. 이를 통해 설정 프로세스를 완료하는 동안 이러한 플레이스홀더 토큰을 안전한 토큰으로 교체할 수 있게 됩니다.
-
GITLAB_SHELL_SECRET_TOKEN
: 이 토큰은 Git 훅이 Git 푸시를 수락할 때 GitLab에 대한 HTTP API 요청을 만들기 위해 사용됩니다. 이 시크릿은 레거시 이유로 GitLab 셸과 공유됩니다. -
PRAEFECT_EXTERNAL_TOKEN
: 귀하의 Praefect 클러스터에 호스팅된 리포지터리는 이 토큰을 지닌 Gitaly 클라이언트만이 접근할 수 있습니다. -
PRAEFECT_INTERNAL_TOKEN
: 이 토큰은 Praefect 클러스터 내부의 복제 트래픽에 사용됩니다. 이 토큰은PRAEFECT_EXTERNAL_TOKEN
과 구분됩니다. 왜냐하면 Gitaly 클라이언트는 Praefect 클러스터의 내부 노드에 직접 액세스해서는 안 되기 때문입니다. 그런 경우에는 데이터 손실이 발생할 수 있습니다. -
PRAEFECT_SQL_PASSWORD
: 이 비밀번호는 Praefect가 PostgreSQL에 연결하는 데 사용됩니다. -
PRAEFECT_SQL_PASSWORD_HASH
: Praefect 사용자의 비밀번호 해시입니다. 해시를 생성하려면gitlab-ctl pg-password-md5 praefect
를 사용하세요. 이 명령은praefect
사용자의 비밀번호를 요청합니다.PRAEFECT_SQL_PASSWORD
평문 비밀번호를 입력하세요. 기본적으로 Praefect는praefect
사용자를 사용하지만 변경할 수 있습니다. -
PGBOUNCER_SQL_PASSWORD_HASH
: PgBouncer 사용자의 비밀번호 해시입니다. PgBouncer는 PostgreSQL에 연결할 때 이 비밀번호를 사용합니다. 자세한 내용은 bundled PgBouncer 문서를 참조하세요.
이 매뉴얼에서 이러한 시크릿이 필요한 위치를 나타냅니다.
참고:
리눅스 패키지 설치에서는 gitlab-secrets.json
파일을 GITLAB_SHELL_SECRET_TOKEN
에 사용할 수 있습니다.
시간 서버 설정 사용자 정의
기본적으로, Gitaly와 Praefect 노드는 시간 동기화 확인을 위해 pool.ntp.org
의 시간 서버를 사용합니다. 이 설정을 gitlab.rb
에 추가하여 이를 사용자 정의할 수 있습니다:
-
gitaly['env'] = { "NTP_HOST" => "ntp.example.com" }
, Gitaly 노드용. -
praefect['env'] = { "NTP_HOST" => "ntp.example.com" }
, Praefect 노드용.
PostgreSQL
참고: 만약 Geo를 사용하는 경우 GitLab 애플리케이션 데이터베이스와 Praefect 데이터베이스를 동일한 PostgreSQL 서버에 저장하지 마세요. 복제 상태는 각 GitLab 인스턴스의 내부에 있어야 하며 복제되어서는 안 됩니다.
이 지침은 단일 PostgreSQL 데이터베이스를 설정하는 데 도움이 됩니다. 이는 단일 장애 지점을 만들어냅니다. 이를 피하기 위해서는 기본적으로 군집화된 PostgreSQL을 구성할 수 있습니다. 리눅스 패키지를 통해 PostgreSQL 복제 및 장애 조치 지원은 epic 7814에서 제안되었습니다. 다른 데이터베이스(예: Praefect 및 Geo 데이터베이스)에 대한 클러스터 데이터베이스 지원은 issue 7292에서 제안되었습니다.
다음 옵션이 제공됩니다:
- 비-Geo 설치의 경우:
- 문서화된 PostgreSQL 설정 중 하나를 사용하십시오.
- 고유한 서드파티 데이터베이스 설정을 사용하십시오. 이를 위해서는 매뉴얼 설정이 필요합니다.
- Geo 인스턴스의 경우:
- 별도의 PostgreSQL 인스턴스 설정을 구성하십시오.
- 클라우드 관리형 PostgreSQL 서비스를 사용하십시오. AWS 관계형 데이터베이스 서비스를 권장합니다.
PostgreSQL 설정은 빈 Praefect 테이블을 생성합니다. 자세한 내용은 해당 문제 해결 섹션을 참조하십시오.
GitLab 및 Praefect 데이터베이스를 동일한 서버에서 실행
GitLab 애플리케이션 데이터베이스와 Praefect 데이터베이스를 동일한 서버에서 실행할 수 있습니다. 그러나, 리눅스 패키지를 통해 PostgreSQL을 사용할 때는 Praefect가 자체 데이터베이스 서버를 가져야 합니다. 장애 조치가 있을 경우 Praefect는 이를 인지하지 않고 다음과 같은 문제가 발생할 수 있습니다:
- 사용 불가능한 상태.
- 읽기 전용 모드.
매뉴얼 데이터베이스 설정
이 섹션을 완료하려면 다음이 필요합니다:
- Praefect 노드 1대
- PostgreSQL 노드 1대(버전 11 이상)
- 데이터베이스 서버를 관리할 권한이 있는 PostgreSQL 사용자
이 섹션에서는 PostgreSQL 데이터베이스를 구성합니다. 이는 외부 및 리눅스 패키지로 제공되는 PostgreSQL 서버에 모두 사용할 수 있습니다.
다음 지침을 실행하려면 리눅스 패키지에서 psql
이 설치된 Praefect 노드를 사용할 수 있습니다(/opt/gitlab/embedded/bin/psql
). 리눅스 패키지로 제공되는 PostgreSQL을 사용하는 경우 PostgreSQL 노드에서는 gitlab-psql
을 대신 사용할 수 있습니다.
-
Praefect에서 사용할 새로운 사용자
praefect
를 생성합니다:CREATE ROLE praefect WITH LOGIN PASSWORD 'PRAEFECT_SQL_PASSWORD';
준비 단계에서 생성한 강력한 비밀번호로
PRAEFECT_SQL_PASSWORD
를 바꿉니다. -
praefect
사용자가 소유한praefect_production
이라는 새 데이터베이스를 생성합니다.CREATE DATABASE praefect_production WITH OWNER praefect ENCODING UTF8;
리눅스 패키지로 제공되는 PgBouncer를 사용하는 경우, 다음 추가 단계를 수행해야 합니다. 우리는 백엔드로 리눅스 패키지에 포함된 PostgreSQL을 강력히 권장합니다. 다음 지침은 리눅스 패키지로 제공되는 PostgreSQL에서만 작동합니다.
-
리눅스 패키지로 제공되는 PgBouncer를 위해
praefect
비밀번호의 해시를 사용해야 합니다:ALTER ROLE praefect WITH PASSWORD 'md5<PRAEFECT_SQL_PASSWORD_HASH>';
준비 단계에서 생성한 해시의 비밀번호로
<PRAEFECT_SQL_PASSWORD_HASH>
를 바꿉니다. 이는 리터럴md5
가 앞에 붙습니다. -
리눅스 패키지로 제공되는 PgBouncer는
auth_query
를 사용하며pg_shadow_lookup
함수를 사용합니다. 이 함수를praefect_production
데이터베이스에 생성해야 합니다:CREATE OR REPLACE FUNCTION public.pg_shadow_lookup(in i_username text, out username text, out password text) RETURNS record AS $$ BEGIN SELECT usename, passwd FROM pg_catalog.pg_shadow WHERE usename = i_username INTO username, password; RETURN; END; $$ LANGUAGE plpgsql SECURITY DEFINER; REVOKE ALL ON FUNCTION public.pg_shadow_lookup(text) FROM public, pgbouncer; GRANT EXECUTE ON FUNCTION public.pg_shadow_lookup(text) TO pgbouncer;
Praefect에서 사용하는 데이터베이스가 이제 구성되었습니다.
이제 Praefect가 데이터베이스를 사용하도록 구성할 수 있습니다:
praefect['configuration'] = {
# ...
database: {
# ...
host: POSTGRESQL_HOST,
user: 'praefect',
port: 5432,
password: PRAEFECT_SQL_PASSWORD,
dbname: 'praefect_production',
}
}
PostgreSQL을 구성한 후 Praefect 데이터베이스 오류를 발견하면 문제 해결 단계를 확인하세요.
Reads distribution caching
Praefect의 성능은 추가적으로 database_direct
설정을 구성함으로써 향상될 수 있습니다:
praefect['configuration'] = {
# ...
database: {
# ...
session_pooled: {
# ...
host: POSTGRESQL_HOST,
port: 5432
# 다이렉트 데이터베이스 연결의 매개변수를 재정의하려면 다음을 사용하십시오.
# 매개변수가 두 연결 모두 동일한 경우 주석 처리하십시오.
user: 'praefect',
password: PRAEFECT_SQL_PASSWORD,
dbname: 'praefect_production',
# sslmode: '...',
# sslcert: '...',
# sslkey: '...',
# sslrootcert: '...',
}
}
}
구성된 후 이 연결은 SQL LISTEN 기능을 자동으로 사용하고, Praefect가 캐시 무효화를 위해 PostgreSQL에서 알림을 수신할 수 있게 합니다.
이 기능이 작동하는지 확인하려면 Praefect 로그에서 다음 로그 항목을 찾으세요:
reads distribution caching is enabled by configuration
PgBouncer 사용하기
PostgreSQL 리소스 사용을 줄이기 위해 PostgreSQL 인스턴스 앞에 PgBouncer를 설치하고 구성해야 합니다. 그러나 Praefect는 연결을 적게 사용하기 때문에 PgBouncer가 필수는 아닙니다. PgBouncer를 사용하려는 경우 GitLab 응용 프로그램 데이터베이스와 Praefect 데이터베이스에 모두 동일한 PgBouncer 인스턴스를 사용할 수 있습니다.
PostgreSQL 인스턴스 앞에 PgBouncer를 구성하려면 Praefect 구성에 데이터베이스 매개변수를 설정하여 Praefect를 PgBouncer로 연결해야 합니다:
praefect['configuration'] = {
# ...
database: {
# ...
host: PGBOUNCER_HOST,
port: 6432,
user: 'praefect',
password: PRAEFECT_SQL_PASSWORD,
dbname: 'praefect_production',
# sslmode: '...',
# sslcert: '...',
# sslkey: '...',
# sslrootcert: '...',
}
}
Praefect는 LISTEN 기능을 지원하는 PostgreSQL에 추가적인 연결이 필요합니다.
PgBouncer를 사용하면 이 기능은 session
풀 모드 (pool_mode = session
)에서만 사용할 수 있습니다.
transaction
풀 모드 (pool_mode = transaction
)에서는 지원되지 않습니다.
추가 연결을 구성하려면 다음 중 하나를 수행해야 합니다:
- 동일한 PostgreSQL 데이터베이스 엔드포인트를 사용하여 새로운 PgBouncer 데이터베이스를 구성하되, 다른 풀 모드를 사용합니다 (
pool_mode = session
). - PgBouncer를 우회하지 않고 Praefect를 PostgreSQL에 직접 연결합니다.
pool_mode = session
을 사용하는 새로운 PgBouncer 데이터베이스 구성
session
풀 모드로 PgBouncer를 사용해야 합니다. 번들된 PgBouncer를 사용하거나 외부 PgBouncer를 사용하고
매뉴얼으로 구성할 수 있습니다.
다음 예제는 번들된 PgBouncer를 사용하고 PostgreSQL 호스트에서 두 개의 별도 연결 풀을 설정하며,
하나는 session
풀 모드이고 다른 하나는 transaction
풀 모드입니다. 이 예제를 사용하려면
설치 지침에 문서화된대로 PostgreSQL 서버를 준비해야 합니다:
pgbouncer['databases'] = {
# gitlabhq_production을 포함한 다른 데이터베이스 구성
...
praefect_production: {
host: POSTGRESQL_HOST,
# 데이터베이스 백엔드에 연결할 때 `pgbouncer` 사용합니다.
user: 'pgbouncer',
password: PGBOUNCER_SQL_PASSWORD_HASH,
pool_mode: 'transaction'
},
praefect_production_direct: {
host: POSTGRESQL_HOST,
# 데이터베이스 백엔드에 연결할 때 `pgbouncer` 사용합니다.
user: 'pgbouncer',
password: PGBOUNCER_SQL_PASSWORD_HASH,
dbname: 'praefect_production',
pool_mode: 'session'
},
...
}
# praefect 사용자가 PgBouncer에 연결하도록 허용합니다
pgbouncer['users'] = {
'praefect': {
'password': PRAEFECT_SQL_PASSWORD_HASH,
}
}
praefect_production
및 praefect_production_direct
은 동일한 데이터베이스 엔드포인트(praefect_production
)를 사용하지만 다른 풀 모드를 사용합니다.
이는 PgBouncer의 다음 databases
섹션으로 해석됩니다:
[databases]
praefect_production = host=POSTGRESQL_HOST auth_user=pgbouncer pool_mode=transaction
praefect_production_direct = host=POSTGRESQL_HOST auth_user=pgbouncer dbname=praefect_production pool_mode=session
이제 Praefect가 두 연결 유형 모두에 대해 PgBouncer를 사용하도록 구성할 수 있습니다:
praefect['configuration'] = {
# ...
database: {
# ...
host: PGBOUNCER_HOST,
port: 6432,
user: 'praefect',
# `PRAEFECT_SQL_PASSWORD`는 Praefect 사용자의 평문 암호입니다.
# `PRAEFECT_SQL_PASSWORD_HASH`와 혼동하지 마십시오.
password: PRAEFECT_SQL_PASSWORD,
dbname: 'praefect_production',
session_pooled: {
# ...
dbname: 'praefect_production_direct',
# 다음을 반복할 필요가 없습니다.
# 직접 데이터베이스 연결의 매개변수는 위의 값으로 되돌아갑니다.
#
# host: PGBOUNCER_HOST,
# port: 6432,
# user: 'praefect',
# password: PRAEFECT_SQL_PASSWORD,
},
},
}
이 구성을 사용하면 Praefect가 두 연결 유형에 대해 PgBouncer를 사용합니다.
praefect
사용자 및
PgBouncer에서 사용하는 파일에 패스워드를 포함해야 합니다. 예를 들어, auth_file
설정 옵션에 따라 userlist.txt
를 사용합니다.
자세한 내용은 PgBouncer 문서를 참조하십시오.PostgreSQL에 직접 연결하도록 Praefect 구성
session
풀 모드로 PgBouncer를 구성하는 대신 Praefect는 다른 연결 매개변수를 사용하여 PostgreSQL에 직접 액세스하도록 구성될 수 있습니다. 이 연결은 LISTEN
기능을 지원합니다.
PgBouncer를 우회하고 PostgreSQL에 직접 연결하는 Praefect 구성 예시:
praefect['configuration'] = {
# ...
database: {
# ...
session_pooled: {
# ...
host: POSTGRESQL_HOST,
port: 5432,
# 직접 데이터베이스 연결 매개변수를 덮어씁니다.
# 매개변수가 두 연결 모두 동일한 경우 주석 처리합니다.
#
user: 'praefect',
password: PRAEFECT_SQL_PASSWORD,
dbname: 'praefect_production',
# sslmode: '...',
# sslcert: '...',
# sslkey: '...',
# sslrootcert: '...',
},
},
}
Praefect
- GitLab 13.4에서 도입됨에 따라, Praefect 노드를
기본(primary)
으로 지정할 수 없게 되었습니다.
여러 Praefect 노드가 있는 경우:
- 한 노드를 배포 노드로 지정하고 다음 단계를 사용하여 구성합니다.
- 추가 노드마다 다음 단계를 완료합니다.
본 섹션을 완료하려면 구성된 PostgreSQL 서버가 필요합니다:
Praefect 노드에서:
-
/etc/gitlab/gitlab.rb
파일을 편집하여 모든 다른 서비스를 비활성화합니다.:
# Praefect 서버에서 불필요한 서비스 실행을 피합니다
gitaly['enable'] = false
postgresql['enable'] = false
redis['enable'] = false
nginx['enable'] = false
puma['enable'] = false
sidekiq['enable'] = false
gitlab_workhorse['enable'] = false
prometheus['enable'] = false
alertmanager['enable'] = false
grafana['enable'] = false
gitlab_exporter['enable'] = false
gitlab_kas['enable'] = false
# Praefect 서비스만 활성화합니다
praefect['enable'] = true
# 업그레이드 시 데이터베이스 마이그레이션이 자동으로 실행되지 않도록 합니다
praefect['auto_migrate'] = false
gitlab_rails['auto_migrate'] = false
-
/etc/gitlab/gitlab.rb
파일을 편집하여 Praefect가 네트워크 인터페이스에서 수신하도록 구성합니다.:praefect['configuration'] = { # ... listen_addr: '0.0.0.0:2305', }
-
/etc/gitlab/gitlab.rb
파일을 편집하여 Prometheus 메트릭을 구성합니다.:praefect['configuration'] = { # ... # # Praefect에 대한 Prometheus 메트릭 액세스를 활성화합니다. 방화벽을 사용하여 # 이 주소/포트로의 액세스를 제한해야 합니다. # 기본 메트릭 엔드포인트는 /metrics입니다. prometheus_listen_addr: '0.0.0.0:9652', # 일부 메트릭은 데이터베이스 쿼리를 실행합니다. 별도의 데이터베이스 메트릭을 활성화하면 # 이러한 메트릭이 수집될 수 있도록 합니다. prometheus_exclude_database_from_default_metrics: true, }
-
/etc/gitlab/gitlab.rb
파일을 편집하여 Praefect의 강력한 인증 토큰을 구성합니다. 이는 클러스터 외부의 클라이언트(GitLab Shell과 같은)가 Praefect 클러스터와 통신할 때 필요합니다.:praefect['configuration'] = { # ... auth: { # ... token: 'PRAEFECT_EXTERNAL_TOKEN', }, }
-
Praefect를 PostgreSQL 데이터베이스에 연결하도록 구성합니다. PgBouncer를 사용하는 것을 강력히 권장합니다.
TLS 클라이언트 인증서를 사용하려면 아래 옵션을 사용할 수 있습니다:
praefect['configuration'] = { # ... database: { # ... # # TLS 클라이언트 인증서를 사용하여 PostgreSQL에 연결 # sslcert: '/path/to/client-cert', # sslkey: '/path/to/client-key', # # 사용자 정의 인증 기관 신뢰 # sslrootcert: '/path/to/rootcert', }, }
기본적으로 Praefect는 PostgreSQL에 암호화되지 않은 연결을 거부합니다. 이를 주석 처리 해제하여 재정의할 수 있습니다.
praefect['configuration'] = { # ... database: { # ... # sslmode: 'disable', }, }
-
/etc/gitlab/gitlab.rb
파일을 편집하여 Praefect 클러스터가 클러스터 내 각 Gitaly 노드에 연결하도록 구성합니다.가상 스토리지의 이름은 GitLab 구성에서 구성된 스토리지 이름과 일치해야 합니다. 나중에 리포지터리 이름을
default
로 구성하므로 여기서도default
를 사용합니다. 이 클러스터에는 각각 복제본인gitaly-1
,gitaly-2
,gitaly-3
세 개의 Gitaly 노드가 있습니다.이미default
라는 기존 리포지터리에 데이터가 있는 경우, 다른 이름으로 가상 스토리지를 구성하고 나중에 Gitaly 클러스터 리포지터리로 데이터 이동해야 합니다.PRAEFECT_INTERNAL_TOKEN
을 강력한 비밀로 교체하여 클러스터 내 Gitaly 노드와 통신할 때 Praefect에서 사용합니다. 이 토큰은PRAEFECT_EXTERNAL_TOKEN
과 다릅니다.GITALY_HOST_*
를 각 Gitaly 노드의 IP 또는 호스트 주소로 교체합니다.복제본 수를 늘리려면 클러스터에 더 많은 Gitaly 노드를 추가할 수 있습니다. 매우 큰 GitLab 인스턴스의 경우 추가적인 클러스터를 추가할 수도 있습니다.
가상 스토리지에 추가로 Gitaly 노드를 추가할 때 해당 가상 스토리지의 모든 리포지터리 이름은 고유해야 합니다. 또한 Praefect 구성에서 참조된 모든 Gitaly 노드 주소는 고유해야 합니다.# 스토리지 해시의 이름은 GitLab 서버의 git_data_dirs에서 설정된 리포지터리 이름 ('default') 및 Gitaly 노드('gitaly-1')의 gitaly['configuration'][:storage][INDEX][:name]와 일치해야 합니다. praefect['configuration'] = { # ... virtual_storage: [ { # ... name: 'default', node: [ { storage: 'gitaly-1', address: 'tcp://GITALY_HOST_1:8075', token: 'PRAEFECT_INTERNAL_TOKEN' }, { storage: 'gitaly-2', address: 'tcp://GITALY_HOST_2:8075', token: 'PRAEFECT_INTERNAL_TOKEN' }, { storage: 'gitaly-3', address: 'tcp://GITALY_HOST_3:8075', token: 'PRAEFECT_INTERNAL_TOKEN' }, ], }, ], }
-
/etc/gitlab/gitlab.rb
파일에 변경 사항을 저장하고 Praefect를 다시 구성합니다:gitlab-ctl reconfigure
-
다음을 위해:
- “배포 노드”:
-
/etc/gitlab/gitlab.rb
에서praefect['auto_migrate'] = true
로 설정하여 Praefect 데이터베이스 자동 마이그레이션을 다시 활성화합니다. -
데이터베이스 마이그레이션이 업그레이드 중에 자동으로 실행되지 않게하려면 다음을 실행합니다:
sudo touch /etc/gitlab/skip-auto-reconfigure
-
- 다른 노드: 설정을 그대로 두셔도 됩니다.
/etc/gitlab/skip-auto-reconfigure
는 필요하지 않지만,apt-get update
와 같은 명령을 실행할 때 GitLab가 자동으로 다시 구성되는 것을 방지하기 위해 추가 구성 변경을 수행하고 나서 매뉴얼으로 재구성을 실행할 수 있도록 설정해 두는 것이 좋습니다.
- “배포 노드”:
-
/etc/gitlab/gitlab.rb
파일에 변경 사항을 저장하고 Praefect를 다시 구성합니다:gitlab-ctl reconfigure
-
Praefect가 Prometheus 리스닝 주소를 업데이트했는지 확인하도록 하려면 Praefect를 다시 시작합니다:
gitlab-ctl restart praefect
-
Praefect가 PostgreSQL에 연결할 수 있는지 확인합니다:
sudo -u git /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-ping
확인이 실패하면 단계를 올바르게 수행했는지 확인하세요.
/etc/gitlab/gitlab.rb
을 수정한 경우sudo gitlab-ctl reconfigure
를 다시 실행한 다음sql-ping
명령을 시도하세요.
TLS 지원 활성화
Praefect는 TLS 암호화를 지원합니다. 안전한 연결을 위해 Praefect 인스턴스와 통신하려면 다음을 수행해야 합니다.
- Gitaly가 TLS로 구성되어 있고 GitLab 구성의 해당 리포지터리 항목의
gitaly_address
에tls://
URL 스키마를 사용합니다. - 이는 자동으로 제공되지 않으므로 고유한 인증서를 사용해야 합니다. 각 Praefect 서버의 해당하는 인증서를 해당 Praefect 서버에 설치해야 합니다.
또한 인증서 또는 해당 인증 기관은 GitLab 사용자 정의 인증서 구성 프로시저에서 설명된 절차에 따라 Gitaly 서버와 그와 통신하는 모든 Praefect 클라이언트에 설치되어 있어야 합니다(GitLab 사용자 정의 인증서 구성 참조).
다음을 주의하세요:
- 인증서에는 Praefect 서버에 액세스하는 데 사용하는 주소를 명시해야 합니다. 인증서에 호스트 이름 또는 IP 주소를 대체 이름으로 추가해야 합니다.
-
명령줄에서
Gitaly TLS
를 활성화한 상태에서dial-nodes
나list-untracked-repositories
와 같은 Praefect 하위 명령을 실행할 때,SSL_CERT_DIR
또는SSL_CERT_FILE
환경 변수를 설정하여 Gitaly 인증서를 신뢰할 수 있도록 해야 합니다. 예시:sudo SSL_CERT_DIR=/etc/gitlab/trusted-certs /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dial-nodes
-
Praefect 서버를 암호화되지 않은 수신 주소
listen_addr
와 암호화된 수신 주소tls_listen_addr
로 동시에 구성할 수 있습니다. 이를 통해 필요한 경우 암호화되지 않은 트래픽에서 암호화된 트래픽으로 점진적으로 전환할 수 있습니다.암호화되지 않은 수신기를 비활성화하려면 다음을 설정하세요:
praefect['configuration'] = { # ... listen_addr: nil, }
TLS로 Praefect를 구성합니다.
Linux 패키지 설치의 경우:
- Praefect 서버용 인증서를 생성합니다.
-
Praefect 서버에서
/etc/gitlab/ssl
디렉터리를 생성하고 키와 인증서를 해당 디렉터리에 복사합니다:sudo mkdir -p /etc/gitlab/ssl sudo chmod 755 /etc/gitlab/ssl sudo cp key.pem cert.pem /etc/gitlab/ssl/ sudo chmod 644 key.pem cert.pem
-
/etc/gitlab/gitlab.rb
를 편집하고 다음을 추가합니다:praefect['configuration'] = { # ... tls_listen_addr: '0.0.0.0:3305', tls: { # ... certificate_path: '/etc/gitlab/ssl/cert.pem', key_path: '/etc/gitlab/ssl/key.pem', }, }
-
파일을 저장하고 GitLab 재구성을 수행합니다.
-
Praefect 클라이언트(각 Gitaly 서버 포함)에게 인증서 또는 해당 인증 기관을
/etc/gitlab/trusted-certs
로 복사합니다:sudo cp cert.pem /etc/gitlab/trusted-certs/
-
Praefect 클라이언트(단, Gitaly 서버 제외)에서
/etc/gitlab/gitlab.rb
의git_data_dirs
를 다음과 같이 편집합니다:git_data_dirs({ "default" => { "gitaly_address" => 'tls://PRAEFECT_LOADBALANCER_HOST:3305', "gitaly_token" => 'PRAEFECT_EXTERNAL_TOKEN' } })
- 파일을 저장하고 GitLab 재구성을 수행합니다.
자체 컴파일 설치의 경우:
- Praefect 서버용 인증서를 생성합니다.
-
Praefect 서버에서
/etc/gitlab/ssl
디렉터리를 생성하고 키와 인증서를 해당 디렉터리에 복사합니다:sudo mkdir -p /etc/gitlab/ssl sudo chmod 755 /etc/gitlab/ssl sudo cp key.pem cert.pem /etc/gitlab/ssl/ sudo chmod 644 key.pem cert.pem
-
Praefect 클라이언트(각 Gitaly 서버 포함)에게 인증서 또는 해당 인증 기관을 시스템 신뢰 인증서로 복사합니다:
sudo cp cert.pem /usr/local/share/ca-certificates/praefect.crt sudo update-ca-certificates
-
Praefect 클라이언트(단, Gitaly 서버 제외)에서
/home/git/gitlab/config/gitlab.yml
의storages
를 다음과 같이 편집합니다:gitlab: repositories: storages: default: gitaly_address: tls://PRAEFECT_LOADBALANCER_HOST:3305
-
파일을 저장하고 GitLab 재시작을 수행합니다.
-
각 Gitaly 서버에 Praefect 서버 인증서를 또는 해당 인증 기관을 시스템 신뢰 인증서로 복사하여 Praefect 서버가 호출될 때 인증서를 신뢰할 수 있도록 설정합니다:
sudo cp cert.pem /usr/local/share/ca-certificates/praefect.crt sudo update-ca-certificates
-
/home/git/praefect/config.toml
을 편집하고 다음을 추가합니다:tls_listen_addr = '0.0.0.0:3305' [tls] certificate_path = '/etc/gitlab/ssl/cert.pem' key_path = '/etc/gitlab/ssl/key.pem'
- 파일을 저장하고 GitLab 재시작을 수행합니다.
서비스 검색
- GitLab 15.10에 도입됨.
필수 컴포넌트:
- DNS 서버.
GitLab은 Praefect 호스트 디렉터리을 검색하기 위해 서비스 검색을 사용합니다. 서비스 검색은 주기적으로 DNS A 또는 AAAA 레코드를 확인하고, 레코드에서 검색한 IP가 대상 노드의 주소로 사용됩니다. Praefect는 SRV 레코드를 통한 서비스 검색을 지원하지 않습니다.
기본적으로, 확인 사이의 최소 시간은 TTL과 관계없이 5분입니다. Praefect에서 이 간격을 사용자 정의하는 것을 지원하지 않습니다. 클라이언트가 업데이트를 받으면:
- 새 IP 주소에 대한 새로운 연결을 설정합니다.
- 기존 연결을 유지합니다.
- 제거된 IP 주소에 대한 연결을 종료합니다.
종료되지 않은 요청은 그 완료 시까지 처리됩니다. Workhorse는 10분의 제한시간을 가지며, 다른 클라이언트에는 우아한 시간 제한이 명시되어 있지 않습니다.
DNS 서버는 로드 밸런싱 대신 모든 IP 주소를 반환해야 합니다. 클라이언트는 요청을 라운드로빈 방식으로 IP 주소로 분산할 수 있습니다.
클라이언트 구성을 업데이트하기 전에 DNS 서비스 검색이 올바르게 작동하는지 확인하세요. 확인하는 데 dig
를 사용하는 것이 좋습니다.
서비스 디스커버리 구성
기본적으로 Praefect는 DNS 해결을 운영 체제에 위임합니다. 이러한 경우 Gitaly 주소는 다음 형식 중 하나로 설정할 수 있습니다.
dns:[호스트]:[포트]
-
dns:///[호스트]:[포트]
(슬래시 3개에 유의)
또한 다음 형식으로 권위있는 이름 서버를 지정할 수도 있습니다.
dns://[권위_호스트]:[권위_포트]/[호스트]:[포트]
- DNS 서비스 디스커버리 주소에 각 Praefect 노드의 IP 주소를 추가합니다.
-
Praefect 클라이언트(단 Gitaly 서버)에서 다음과 같이
/etc/gitlab/gitlab.rb
의git_data_dirs
를 편집합니다. Praefect 서비스 디스커버리 주소(예:praefect.service.consul
)로PRAEFECT_SERVICE_DISCOVERY_ADDRESS
를 대체합니다.git_data_dirs({ "default" => { "gitaly_address" => 'dns:PRAEFECT_SERVICE_DISCOVERY_ADDRESS:2305', "gitaly_token" => 'PRAEFECT_EXTERNAL_TOKEN' } })
- 파일을 저장하고 GitLab을 다시 구성하세요.
- DNS 서비스 디스커버리 서비스를 설치합니다. 모든 Praefect 노드를 해당 서비스에 등록합니다.
-
Praefect 클라이언트(단 Gitaly 서버)에서
/home/git/gitlab/config/gitlab.yml
을 다음과 같이 수정합니다.gitlab: repositories: storages: default: gitaly_address: dns:PRAEFECT_SERVICE_DISCOVERY_ADDRESS:2305
- 파일을 저장하고 GitLab을 다시 시작하세요.
Consul을 사용하여 서비스 디스커버리 구성
이미 아키텍처에 Consul 서버가 있다면, 각 Praefect 노드에 Consul 에이전트를 추가하고 praefect
서비스를 등록할 수 있습니다. 이렇게 하면 각 노드의 IP 주소가 praefect.service.consul
에 등록되어 서비스 디스커버리에서 찾을 수 있습니다.
요구 사항:
- Consul 서버 중 하나 이상이 Consul 에이전트를 유지합니다.
-
각 Praefect 서버에서
/etc/gitlab/gitlab.rb
에 다음을 추가합니다.consul['enable'] = true praefect['consul_service_name'] = 'praefect' # 여기에 주석 처리된 사항을 추가해야 합니다: # https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/8321 consul['monitoring_service_discovery'] = true praefect['configuration'] = { # ... # prometheus_listen_addr: '0.0.0.0:9652', }
- 파일을 저장하고 GitLab을 다시 구성하세요.
- 서비스 디스커버리에 사용하려면 각 Praefect 서버에서 위의 단계를 반복하세요.
-
Praefect 클라이언트(단 Gitaly 서버)에서 다음과 같이
/etc/gitlab/gitlab.rb
의git_data_dirs
를 수정합니다.CONSUL_SERVER
를 Consul 서버의 IP나 주소로 대체합니다. 기본 Consul DNS 포트는8600
입니다.git_data_dirs({ "default" => { "gitaly_address" => 'dns://CONSUL_SERVER:8600/praefect.service.consul:2305', "gitaly_token" => 'PRAEFECT_EXTERNAL_TOKEN' } })
- Praefect 클라이언트에서
dig
을 사용하여 각 IP 주소가praefect.service.consul
에 등록되었는지 확인합니다.dig A praefect.service.consul @CONSUL_SERVER -p 8600
명령을 사용합니다.CONSUL_SERVER
를 위에서 구성한 값으로 대체하고, 모든 Praefect 노드 IP 주소가 출력에 표시되어야 합니다. - 파일을 저장하고 GitLab을 다시 구성하세요.
Gitaly
이 단계를 완료하려면 다음이 필요합니다:
- 구성된 Praefect 노드
- Gitaly 노드로 구성할 GitLab이 설치된 3개(또는 그 이상)의 서버. 이러한 서버는 특정 노드여야 합니다. 이러한 노드에서 다른 서비스를 실행하지 마십시오.
Praefect 클러스터에 할당된 모든 Gitaly 서버를 구성해야 합니다. 구성은 표준 독립형 Gitaly 서버와 동일하지만 다음과 같은 점을 제외합니다.
- 리포지터리 이름은 Praefect에 노출되고 있습니다. GitLab이 아닙니다.
- 비밀 토큰이 Praefect과 공유되고 있습니다. GitLab이 아닙니다.
Praefect 클러스터의 모든 Gitaly 노드의 구성은 동일할 수 있습니다. 왜냐하면 Praefect가 올바른 작업을 라우팅하도록 의존하기 때문입니다.
특히 다음에 주의를 기울여야 합니다.
- 이 섹션에서 구성된
gitaly['configuration'][:auth][:token]
은 Praefect 노드의praefect['configuration'][:virtual_storage][<index>][:node][<index>][:token]
아래의token
값과 일치해야 합니다. 이 값을 이 문서에서는PRAEFECT_INTERNAL_TOKEN
플레이스홀더로 사용하고 있습니다. - 이 섹션에서 구성된
gitaly['configuration'][:storage]
의 물리적 리포지터리 이름은 Praefect 노드의praefect['configuration'][:virtual_storage]
아래의 물리적 리포지터리 이름과 일치해야 합니다. 이는 이전 섹션에서 설정되었습니다. 이 문서에서는 물리적 리포지터리 이름으로gitaly-1
,gitaly-2
,gitaly-3
을 사용합니다.
Gitaly 서버 구성에 대한 자세한 내용은 저희Gitaly 문서를 참조하세요.
-
Gitaly 노드에 SSH로 로그인하고 루트로 전환합니다.
sudo -i
-
/etc/gitlab/gitlab.rb
를 편집하여 Gitaly 노드에서 다른 모든 서비스를 비활성화합니다.# Gitaly 노드에서 다른 모든 서비스를 비활성화합니다 postgresql['enable'] = false redis['enable'] = false nginx['enable'] = false grafana['enable'] = false puma['enable'] = false sidekiq['enable'] = false gitlab_workhorse['enable'] = false prometheus_monitoring['enable'] = false gitlab_kas['enable'] = false # Gitaly 서비스만 활성화합니다 gitaly['enable'] = true # 필요한 경우 Prometheus 활성화 prometheus['enable'] = true # 'gitlab-ctl reconfigure' 중에 데이터베이스 연결을 방지하기 위해 데이터베이스 마이그레이션 비활성화 gitlab_rails['auto_migrate'] = false
-
네트워크 인터페이스에서 Gitaly의 수신 대기를 설정하여
/etc/gitlab/gitlab.rb
를 편집합니다.gitaly['configuration'] = { # ... # # Gitaly를 모든 네트워크 인터페이스에서 연결 수신하도록 설정 # 이 주소/포트에 대한 액세스를 제한하기 위해 방화벽을 사용합니다 listen_addr: '0.0.0.0:8075', # Gitaly에 대한 Prometheus 메트릭 액세스 활성화. 이 주소/포트에 제한된 접근을 해야합니다 prometheus_listen_addr: '0.0.0.0:9236', }
-
Gitaly의 강력한
auth_token
을 편집하여 클라이언트가 이 Gitaly 노드와 통신하기 위해 필요합니다. 일반적으로 이 토큰은 모든 Gitaly 노드에 대해 동일합니다.gitaly['configuration'] = { # ... auth: { # ... token: 'PRAEFECT_INTERNAL_TOKEN', }, }
-
git push
작업에 필요한 GitLab Shell 비밀 토큰을 구성합니다. 다음 중 하나를 수행하세요.-
방법 1:
- Gitaly 클라이언트의
/etc/gitlab/gitlab-secrets.json
을 해당 경로의 같은 위치에 있는 Gitaly 서버 및 다른 Gitaly 클라이언트로 복사합니다. - Gitaly 서버에서 GitLab을 다시 구성합니다.
- Gitaly 클라이언트의
-
방법 2:
-
/etc/gitlab/gitlab.rb
을 편집합니다. -
GITLAB_SHELL_SECRET_TOKEN
을 실제 비밀 토큰으로 대체합니다.
gitlab_shell['secret_token'] = 'GITLAB_SHELL_SECRET_TOKEN'
-
-
-
git push
작업에 필요한internal_api_url
을 구성합니다.# gitlab-shell API 콜백 URL을 구성합니다. 이를 설정하지 않으면 `git push`가 실패합니다. 프론트 도어 GitLab URL 또는 내부 로드 밸런서가 될 수 있습니다. # 예: 'https://gitlab.example.com', 'http://10.0.2.2' gitlab_rails['internal_api_url'] = 'https://gitlab.example.com'
-
/etc/gitaly/gitlab.rb
에서gitaly['configuration'][:storage]
를 설정하여 Git 데이터의 저장 위치를 구성합니다. 각 Gitaly 노드는 고유한 리포지터리 이름(예:gitaly-1
)을 가져야 합니다.각 Gitaly 노드에 대해
gitaly['configuration'][:storage]
를 고유하게 설정하는 대신, 모든 Gitaly 노드에 대한 구성을 모든 Gitaly 노드에 포함하는 것이 더 쉽습니다. Praefectvirtual_storage
구성은 각 리포지터리 이름(예:gitaly-1
)을 특정 노드에 매핑하며 요청은 그에 따라 라우팅됩니다. 이는 여러분의 Gitaly 노드의 모든 구성이 동일할 수 있다는 것을 의미합니다.# Praefect가 이전 단계에서 제공된 주소에 따라 요청만 라우팅하기 때문에 모든 노드의 데이터 디렉터리를 동일한 구성에 포함할 수 있습니다. gitaly['configuration'] = { # ... storage: [ { name: 'gitaly-1', path: '/var/opt/gitlab/git-data/repositories', }, { name: 'gitaly-2', path: '/var/opt/gitlab/git-data/repositories', }, { name: 'gitaly-3', path: '/var/opt/gitlab/git-data/repositories', }, ], }
-
변경 사항을
/etc/gitaly/gitlab.rb
에 저장하고 Gitaly을 다시 구성하세요.gitlab-ctl reconfigure
-
Gitaly가 Prometheus 수신 주소를 업데이트했는지 확인하려면 Gitaly을 다시 시작하세요.
gitlab-ctl restart gitaly
위의 단계는 각 Gitaly 노드에 대해 완료되어야 합니다!
모든 Gitaly 노드가 구성되면 Praefect 연결 확인기를 실행하여 Praefect가 Praefect 구성의 모든 Gitaly 서버에 연결할 수 있는지 확인합니다.
-
Praefect 노드에서 SSH로 로그인하고 Praefect 연결 확인기를 실행합니다.
sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml dial-nodes
로드 밸런서
장애 허용성이 있는 Gitaly 구성에서는 로드 밸런서가 필요하여 GitLab 응용 프로그램에서 Praefect 노드로의 내부 트래픽을 라우팅해야 합니다. 어떤 로드 밸런서를 사용하거나 정확한 구성 방법은 GitLab 설명서의 범위를 벗어납니다.
기존의 GitLab와 같이 여러분이 이미 선택한 로드 밸런서가 있다면 좋겠습니다. 예를 들어 HAProxy(오픈 소스), Google Internal Load Balancer, AWS Elastic Load Balancer, F5 Big-IP LTM, Citrix Net Scaler 등이 있습니다. 이 설명서는 구성해야 할 포트와 프로토콜을 개요합니다.
leastconn
로드 밸런싱 전략과 동등한 것을 사용해야 합니다.LB Port | Backend Port | Protocol |
---|---|---|
2305 | 2305 | TCP |
GitLab
이 섹션을 완료하려면:
Praefect 클러스터는 GitLab 응용 프로그램에게 저장 공간으로 노출되어야 합니다. 이는 git_data_dirs
를 업데이트함으로써 이루어집니다.
특별한 주의가 필요한 사항:
- 이 섹션에서
git_data_dirs
에 추가된 리포지터리 이름은 Praefect 노드의praefect['configuration'][:virtual_storage]
하위에 있는 리포지터리 이름과 일치해야 합니다. 이는 이 안내서의 Praefect 섹션에서 설정되었습니다. 이 문서에서는 Praefect 리포지터리 이름으로default
를 사용합니다.
-
GitLab 노드에 SSH로 로그인한 후 root 사용자로 로그인합니다:
sudo -i
-
/etc/gitlab/gitlab.rb
파일을 편집하여 현재 GitLab 인스턴스가 제공하는 실제 외부 엔드포인트에 의해 파일이 제공될 수 있도록external_url
을 구성합니다:GITLAB_SERVER_URL
을 현재 GitLab 인스턴스가 제공하는 실제 외부 엔드포인트로 대체해야 합니다.external_url 'GITLAB_SERVER_URL'
-
GitLab에서 구성된 클러스터에 연결되지 않은 기본 Gitaly 서비스를 비활성화합니다. GitLab이 구성된 클러스터에 연결되기 때문에 필요하지 않습니다.
기본 Gitaly 리포지터리에 기존 데이터가 저장되어 있는 경우, 먼저 데이터를 Gitaly 클러스터 리포지터리로 이관해야 합니다.gitaly['enable'] = false
-
/etc/gitlab/gitlab.rb
파일을 편집하여 Praefect 클러스터를 리포지터리 위치로 추가합니다.다음을 교체해야 합니다:
-
PRAEFECT_LOADBALANCER_HOST
를 로드 밸런서의 IP 주소 또는 호스트 이름으로. -
PRAEFECT_EXTERNAL_TOKEN
을 실제 시크릿으로.
TLS를 사용하는 경우:
-
gitaly_address
는tls://
로 시작해야 합니다. - 포트는
3305
로 변경해야 합니다.
git_data_dirs({ "default" => { "gitaly_address" => "tcp://PRAEFECT_LOADBALANCER_HOST:2305", "gitaly_token" => 'PRAEFECT_EXTERNAL_TOKEN' } })
-
-
/etc/gitlab/gitlab-secrets.json
을 Gitaly 클라이언트에서 Gitaly 서버 및 기타 Gitaly 클라이언트의 같은 경로로 복사합니다.- 또는
/etc/gitlab/gitlab.rb
파일을 편집하여 GitLab Shell 시크릿 토큰을 구성합니다.
gitlab_shell['secret_token'] = 'GITLAB_SHELL_SECRET_TOKEN'
- 또는
-
/etc/gitlab/gitlab.rb
파일을 편집하여 Prometheus 모니터링 설정을 추가합니다. 만약 Prometheus가 다른 노드에서 활성화된 상태라면 해당 노드에서 편집해야 합니다.다음을 교체해야 합니다:
-
PRAEFECT_HOST
를 Praefect 노드의 IP 주소 또는 호스트 이름으로. -
GITALY_HOST_*
를 각 Gitaly 노드의 IP 주소 또는 호스트 이름으로.
prometheus['scrape_configs'] = [ { 'job_name' => 'praefect', 'static_configs' => [ 'targets' => [ 'PRAEFECT_HOST:9652', # praefect-1 'PRAEFECT_HOST:9652', # praefect-2 'PRAEFECT_HOST:9652', # praefect-3 ] ] }, { 'job_name' => 'praefect-gitaly', 'static_configs' => [ 'targets' => [ 'GITALY_HOST_1:9236', # gitaly-1 'GITALY_HOST_2:9236', # gitaly-2 'GITALY_HOST_3:9236', # gitaly-3 ] ] } ]
-
-
변경 사항을
/etc/gitlab/gitlab.rb
에 저장하고 GitLab을 다시 구성합니다:gitlab-ctl reconfigure
- 각 Gitaly 노드에서 Git Hooks가 GitLab에 도달할 수 있는지 확인합니다. 각 Gitaly 노드에서 다음을 실행하십시오:
- GitLab 15.3 이상의 경우,
sudo /opt/gitlab/embedded/bin/gitaly check /var/opt/gitlab/gitaly/config.toml
을 실행합니다. - GitLab 15.2 이하의 경우,
sudo /opt/gitlab/embedded/bin/gitaly-hooks check /var/opt/gitlab/gitaly/config.toml
을 실행합니다.
- GitLab 15.3 이상의 경우,
-
GitLab이 Praefect에 도달할 수 있는지 확인합니다.
gitlab-rake gitlab:gitaly:check
-
Praefect 리포지터리가 새 리포지터리를 저장하도록 구성되었는지 확인합니다.
- 왼쪽 사이드바에서 아래쪽에 있는 관리 영역을 선택합니다.
- 왼쪽 사이드바에서 설정 > 리포지터리를 선택합니다.
- 리포지터리 스토리지 섹션을 펼칩니다.
이 가이드를 따르면
default
리포지터리가 100의 가중치를 가지고 모든 새 리포지터리를 저장할 것입니다. - README와 함께 새 프로젝트를 생성하여 모든 것이 제대로 작동하는지 확인합니다. 프로젝트를 만들고 README 파일이 있는지 확인하면 됩니다. 프로젝트가 생성되고 README 파일을 볼 수 있다면 문제 없이 작동합니다!
기존 GitLab 인스턴스에 TCP 사용하기
기존 Gitaly 인스턴스에 Gitaly 클러스터를 추가할 때, 기존 Gitaly 리포지터리는 TCP/TLS로 수신 대기해야 합니다. 만약 gitaly_address
가 지정되지 않았다면, Unix 소켓이 사용되어 클러스터와의 통신을 방해합니다.
예시:
git_data_dirs({
'default' => { 'gitaly_address' => 'tcp://old-gitaly.internal:8075' },
'cluster' => {
'gitaly_address' => 'tls://<PRAEFECT_LOADBALANCER_HOST>:3305',
'gitaly_token' => '<praefect_external_token>'
}
})
자세한 정보는 혼합 구성을 참조하세요. ### Grafana
Grafana는 GitLab에 포함되어 있으며 Praefect 클러스터를 모니터링하는 데 사용할 수 있습니다. 상세한 설명은 Grafana 대시보드 서비스를 참조하세요.
빠르게 시작하려면 다음을 수행하세요:
-
GitLab 노드(또는 Grafana가 활성화된 노드)로 SSH로 로그인하세요.
sudo -i
-
/etc/gitlab/gitlab.rb
을 편집하여 Grafana 로그인 양식을 활성화하세요.grafana['disable_login_form'] = false
-
변경 사항을
/etc/gitlab/gitlab.rb
에 저장하고 GitLab을 다시 구성하세요.gitlab-ctl reconfigure
-
Grafana 관리자 암호를 설정하세요. 이 명령은 새로운 암호를 입력하라는 프롬프트를 제공합니다.
gitlab-ctl set-grafana-password
-
웹 브라우저에서 GitLab 서버(
https://gitlab.example.com/-/grafana
와 같은)의/-/grafana
를 엽니다.설정한 암호와
admin
사용자 이름으로 로그인하세요. -
조회(Explore)로 이동하여
gitlab_build_info
를 쿼리하여 모든 기기에서 메트릭을 수신하는지 확인하세요.
축하합니다! 관찰 가능한 고장 내성 Praefect 클러스터를 구성했습니다.
복제 요인 구성
Praefect는 리포지터리당 복제 요인을 구성하는 것을 지원합니다. 특정 리포지터리 노드를 할당하여 리포지터리를 호스팅할 수 있습니다.
Praefect는 실제 복제 요인을 저장하지 않지만, 원하는 복제 요인이 충족되도록 충분한 리포지터리를 할당합니다. 나중에 리포지터리 노드가 가상 리포지터리에서 제거되면 해당 리포지터리에 할당된 리포지터리의 복제 요인은 그에 따라 감소합니다.
다음 중 하나를 구성할 수 있습니다:
- 새로 생성된 리포지터리에 적용되는 각 가상 리포지터리의 기본 복제 요인.
-
set-replication-factor
하위 명령을 사용하여 기존 리포지터리에 대한 복제 요인.
기본 복제 요인 구성
default_replication_factor
가 설정되지 않은 경우, 리포지터리는 항상 virtual_storages
에 정의된 모든 리포지터리 노드에 복제됩니다. 가상 리포지터리에 새 리포지터리 노드가 도입되면 새 리포지터리 및 기존 리포지터리가 자동으로 해당 노드로 복제됩니다.
많은 리포지터리 노드를 보유한 대규모 Gitaly 클러스터 배포의 경우, 리포지터리를 모든 리포지터리 노드에 복제하는 것은 종종 현명하지 않으며 문제를 야기할 수 있습니다. 일반적으로 복제 요인 3이 충분하며, 이는 더 많이 사용하는 리포지터리에 대해 복제 요인 3을 의미합니다. 더 높은 복제 요인은 주 리포지터리에 압력을 가중시킬 수 있습니다.
기본 복제 요인을 구성하려면 /etc/gitlab/gitlab.rb
파일에 구성을 추가하세요:
praefect['configuration'] = {
# ...
virtual_storage: [
{
# ...
name: 'default',
default_replication_factor: 3,
},
],
}
기존 리포지터리의 복제 요인 구성
set-replication-factor
하위 명령은 필요한 복제 요인에 도달하도록 자동으로 무작위 리포지터리 노드를 지정하거나 취소합니다. 리포지터리의 주 노드는 항상 먼저 지정되고 취소되지 않습니다.
sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml set-replication-factor -virtual-storage <가상-리포지터리> -repository <상대-경로> -replication-factor <복제-요인>
-
-virtual-storage
는 리포지터리가 위치한 가상 리포지터리입니다. -
-repository
는 리포지터리의 리포지터리 내 상대 경로입니다. -
-replication-factor
는 리포지터리의 원하는 복제 요인입니다. 최소 값은 주 리포지터리는 무조건 복제가 필요하기 때문에1
입니다. 최대 복제 요인은 가상 리포지터리의 리포지터리 수입니다.
성공하면 지정된 호스트 리포지터리가 출력됩니다. 예:
$ sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml set-replication-factor -virtual-storage default -repository @hashed/3f/db/3fdba35f04dc8c462986c992bcf875546257113072a909c162f7e470e581e278.git -replication-factor 2
current assignments: gitaly-1, gitaly-2
리포지터리 저장 권장 사항
필요한 리포지터리의 크기는 인스턴스마다 다를 수 있고 복제 요인에 따라 달라집니다. 리포지터리 저장의 중복을 구현할 수 있어야 합니다.
복제 요인:
-
1
: Gitaly 및 Gitaly 클러스터는 대략적으로 동일한 리포지터리 요구 사항을 가지고 있습니다. -
1
이상: 필요한 리포지터리의 양은사용 공간 * 복제 요인
입니다.사용 공간
에는 계획된 미래 성장을 포함해야 합니다.
리포지터리 확인
Praefect는 리포지터리에 대한 메타데이터를 데이터베이스에 저장합니다. 만일 리포지터리가 Praefect를 거치지 않고 디스크에서 수정된다면 메타데이터가 부정확해질 수 있습니다. 예를 들어 Gitaly 노드가 새 노드로 대체되는 것이 아니라 다시 구축되었다면, 리포지터리 확인이 이를 감지합니다.
메타데이터는 복제 및 라우팅 결정에 사용되므로 부정확성이 문제를 일으킬 수 있습니다. Praefect에는 주기적으로 배경 작업을 실행하여 메타데이터를 실제 디스크 상태와 비교하는 기능이 있습니다. 이 작업은 다음을 수행합니다:
- 건강한 리포지터리에서 확인해야 할 복제본의 일꾼을 구합니다. 복제본은 확인되지 않거나 구성된 검증 간격을 초과한 상태일 수 있습니다. 확인되지 않은 복제본을 먼저 우선순위를 두어 설정하고, 마지막 성공적인 확인 시간을 기준으로 가장 오래된 시간순으로 배치된 다른 복제본을 확인합니다.
- 해당 복제본이 각 리포지터리에 존재하는지 확인합니다. 만일:
- 복제본이 존재하는 경우, 마지막 성공적인 확인 시간을 업데이트합니다.
- 복제본이 존재하지 않는 경우, 해당 메타데이터 레코드를 제거합니다.
- 확인이 실패하면 작업을 다음 작업을 대기할 때 복제본은 다음 작업에서 다시 확인 대기 디렉터리에 기록됩니다.
작업은 확인해야 할 각 복제본에 대해 전용 확인 임대권을 획득합니다. 이렇게 함으로써 여러 작업자가 동시에 동일한 복제본을 확인하는 것을 피합니다. 작업자는 확인을 완료하면 임대를 해제합니다. 어떤 이유로 인해 작업자가 임대를 해제하지 않은 경우, Praefect에는 10초마다 기한이 만료된 임대를 해제하는 백그라운드 고루틴이 포함되어 있습니다.
작업자는 실행 전에 각 메타데이터 제거를 기록합니다. perform_deletions
키가 실제로 무효화된 메타데이터 레코드를 삭제하는지 여부를 나타냅니다. 예:
{
"level": "info",
"msg": "removing metadata records of non-existent replicas",
"perform_deletions": false,
"replicas": {
"default": {
"@hashed/6b/86/6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b.git": [
"praefect-internal-0"
]
}
}
}
검증 워커 구성
기본적으로 워커는 활성화되어 있으며 메타데이터 레코드를 일주일마다 확인합니다. 검증 간격은 유효한 Go duration string으로 구성할 수 있습니다.
메타데이터를 3일마다 검증하려면:
praefect['configuration'] = {
# ...
background_verification: {
# ...
verification_interval: '72h',
},
}
값이 0 이거나 0보다 작으면 백그라운드 검증기가 비활성화됩니다.
praefect['configuration'] = {
# ...
background_verification: {
# ...
verification_interval: '0',
},
}
삭제 활성화
- Introduced 및 GitLab 15.0에서 기본적으로 비활성화됨
- GitLab 15.9에서 기본적으로 활성화
gitaly_praefect_generated_replica_paths
feature flag가 활성화되어 있는 경우에만 삭제를 활성화해야 합니다. 피처 플래그는 GitLab 15.6에서 제거되어 삭제를 항상 활성화할 수 있게 되었습니다.기본적으로 워커는 유효하지 않은 메타데이터 레코드를 삭제합니다. 또한 삭제된 레코드를 로그에 남기고 Prometheus 메트릭을 출력합니다.
유효하지 않은 메타데이터 레코드를 삭제하지 않으려면 다음을 사용하세요:
praefect['configuration'] = {
# ...
background_verification: {
# ...
delete_invalid_records: false,
},
}
매뉴얼으로 검증 우선 순위 설정
일부 레플리카의 검증을 예정된 다음 검증 시간보다 우선적으로 설정할 수 있습니다. 예를 들어 디스크 장애 후 관리자가 디스크 내용이 변경되었을 수 있다는 것을 알고 있는 경우입니다. Praefect는 결국 레플리카를 다시 검증하지만 사용자들은 그 동안 오류를 경험할 수 있습니다.
일부 레플리카의 재검증을 매뉴얼으로 우선 순위로 설정하려면 praefect verify
하위 명령어를 사용하세요. 하위 명령어는 레플리카를 미검증 상태로 표시합니다. 미검증된 레플리카는 백그라운드 검증 워커에 의해 우선 순위로 설정됩니다. 레플리카를 검증하려면 검증 워커를 활성화해야 합니다.
특정 리포지터리의 레플리카를 우선으로 설정하려면:
sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml verify -repository-id=<repository-id>
가상 스토리지에 저장된 모든 레플리카를 우선으로 설정하려면:
sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml verify -virtual-storage=<virtual-storage>
스토리지에 저장된 모든 레플리카를 우선으로 설정하려면:
sudo /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml verify -virtual-storage=<virtual-storage> -storage=<storage>
결과에는 미검증으로 표시된 레플리카 수가 포함됩니다.
자동 장애 조치 및 주 선출 전략
Praefect는 정기적으로 각 Gitaly 노드의 상태를 확인하며, 현재 기본 Gitaly 노드가 불건전하다고 판명되면 자동으로 새로 선출된 주 Gitaly 노드로 장애 조치를 수행합니다.
리포지터리별 주 노드를 사용해야 합니다. 이것은 GitLab 14.0에서 유일하게 사용 가능한 선출 전략입니다.
리포지터리별 주 노드
Gitaly 클러스터는 각 리포지터리별로 별도로 주 Gitaly 노드를 선출합니다. 구성 가능한 복제 요소와 결합하면 저장 용량을 수평적으로 확장하고 쓰기 부하를 Gitaly 노드 간에 분산할 수 있습니다.
주 선출이 느리게 실행됩니다. 현재 주가 부적절한 경우 Praefect는 즉시 새 주 노드를 선출하지 않습니다. 현재 주가 사용 불가능한 동안 요청을 처리해야 하는 경우 새 주가 선출됩니다.
유효한 주 노드 후보는 다음과 같습니다:
- 건강합니다. Gitaly 노드는 최근 10초 동안
>=50%
Praefect 노드가 성공적으로 건강 확인한 Gitaly 노드로 간주됩니다. - 리포지터리의 최신 복사본을 완전히 가지고 있습니다.
여러 주 노드 후보가 있는 경우 Praefect는 다음과 같이 작동합니다:
- 무작위로 하나를 선택합니다.
- 리포지터리를 호스트로 할당된 Gitaly 노드를 승격하는 것을 우선적으로 고려합니다. 리포지터리에 할당된 Gitaly 노드가 주로 승격되며, 할당된 Gitaly 노드가 없으면 일시적으로 할당되지 않은 노드를 선출할 수 있습니다. 할당되지 않은 주는 할당되는 노드가 사용 가능해지면 주 지위에서 제거됩니다.
리포지터리에 유효한 주 후보가 없는 경우:
- 불건전한 주 노드가 해제되고 리포지터리에 주 노드가 없는 상태가 됩니다.
- 주 노드가 성공적으로 선출될 때까지 주를 필요로 하는 작업은 실패합니다.
리포지터리별 주 Gitaly 노드로 이전
새 Gitaly 클러스터는 즉시 per_repository
선출 전략을 사용할 수 있습니다.
기존 클러스터를 마이그레이션하려면:
-
Praefect 노드는 클러스터에 저장된 각 리포지터리의 데이터베이스 레코드를 기록하지 않았습니다.
per_repository
선출 전략이 구성되면 Praefect는 각 리포지터리의 데이터베이스 레코드가 있을 것으로 예상합니다. 백그라운드 데이터베이스 마이그레이션을 실행하여 누락된 리포지터리를 위한 데이터베이스 레코드가 생성됩니다. 마이그레이션하기 전에 Praefect의 로그를 확인하여 데이터베이스 마이그레이션이 실행되었는지 확인하세요.데이터베이스 마이그레이션을 위해 Praefect의 로그를 확인하세요.
virtual_storages
필드에 가상 스토리지의 이름과 누락된 데이터베이스 레코드가 있는지 여부가 포함됩니다.예를 들어,
default
가상 스토리지가 성공적으로 마이그레이션되었습니다:{"level":"info","msg":"repository importer finished","pid":19752,"time":"2021-04-28T11:41:36.743Z","virtual_storages":{"default":true}}
성공적으로 마이그레이션이 진행되지 않은 가상 스토리지는 다음과 같이 표시됩니다:
{"level":"info","msg":"repository importer finished","pid":19752,"time":"2021-04-28T11:41:36.743Z","virtual_storages":{"default":false}}
데이터베이스 마이그레이션은 Praefect가 시작될 때 실행됩니다. 데이터베이스 마이그레이션이 실패하면 Praefect 노드를 재시작하여 재시도할 수 있습니다.
-
서로 다른 선출 전략을 병행해서 실행하는 것은 리포지터리에 대해 서로 다른 주를 갖는 분리된 상태를 유발할 수 있습니다. 이를 방지하는 방법은 다음과 같습니다:
-
짧은 다운타임이 허용될 경우:
-
선출 전략 변경 전 Praefect 노드를 모두 중지합니다. Praefect 노드에서
gitlab-ctl stop praefect
를 실행하여 수행합니다. -
Praefect 노드에서
/etc/gitlab/gitlab.rb
에praefect['failover_election_strategy'] = 'per_repository'
로 선출 전략을 구성합니다. -
Praefect 노드를 다시 설정하고 시작하기 위해
gitlab-ctl reconfigure && gitlab-ctl start
를 실행합니다.
-
-
다운타임이 허용되지 않을 경우:
-
현재 주 노드를 확인하여 현재 주 Gitaly node인지 확인합니다.
-
Praefect 노드의
/etc/gitlab/gitlab.rb
에서 가상 스토리지의 구성에서 보조 Gitaly 노드를 주석 처리합니다. 이를 통해 구성된 Gitaly 노드가 하나만 존재하도록 하여 두 선출 전략 모두 같은 Gitaly 노드를 주로 선출하도록합니다. -
Praefect 노드에서
gitlab-ctl reconfigure
를 실행합니다. Praefect 프로세스가 모두 재시작되고 이전 프로세스가 종료될 때까지 기다립니다. 최대 1분이 소요될 수 있습니다. -
Praefect 노드의
/etc/gitlab/gitlab.rb
에서praefect['failover_election_strategy'] = 'per_repository'
로 선출 전략을 구성합니다. -
모든 Praefect 노드에서
gitlab-ctl reconfigure
를 실행합니다. 이전 프로세스가 모두 종료되고 새 프로세스가 시작될 때까지 기다립니다. 최대 1분이 소요될 수 있습니다. -
이전에 수행한 단계에서 주석 처리한 보조 Gitaly 노드 구성을 해제합니다.
-
모든 Praefect 노드에서
gitlab-ctl reconfigure
를 실행하여 Praefect 프로세스를 다시 설정하고 재시작합니다.
-
-