Gitaly TLS 지원
GitLab v19.4요약
Gitaly는 TLS 암호화를 지원합니다. Gitaly는 GitLab과의 TLS 연결에서 서버 인증서와 동일한 인증서를 클라이언트 인증서로 제공합니다. 인증서는 자동으로 제공되지 않으므로 직접 준비해야 합니다. 또한 인증서(또는 그 인증 기관)는 다음 모두에 설치해야 합니다.
Gitaly는 TLS 암호화를 지원합니다. 보안 연결을 수신하는 Gitaly 인스턴스와 통신하려면
GitLab 구성에서 해당 스토리지 항목의 gitaly_address에 tls:// URL 스킴을
사용합니다.
Gitaly는 GitLab과의 TLS 연결에서 서버 인증서와 동일한 인증서를 클라이언트 인증서로 제공합니다. 클라이언트 인증서를 검증해 GitLab 접근을 허용하는 리버스 프록시(예: NGINX)와 결합하면 상호 TLS 인증 전략의 일부로 활용할 수 있습니다.
인증서는 자동으로 제공되지 않으므로 직접 준비해야 합니다. 각 Gitaly 서버에 해당하는 인증서는 그 Gitaly 서버에 설치해야 합니다.
또한 인증서(또는 그 인증 기관)는 다음 모두에 설치해야 합니다.
- Gitaly 서버.
- 해당 서버와 통신하는 Gitaly 클라이언트.
로드 밸런서를 사용한다면 ALPN TLS 확장으로 HTTP/2를 협상할 수 있어야 합니다.
인증서 요구 사항#
- 인증서에는 Gitaly 서버에 접근할 때 사용하는 주소가 명시되어야 합니다. 호스트명 또는 IP 주소를 Subject Alternative Name으로 인증서에 추가해야 합니다.
- Gitaly 서버는 암호화되지 않은 수신 주소
listen_addr과 암호화된 수신 주소tls_listen_addr을 동시에 구성할 수 있습니다. 이를 통해 필요하다면 암호화되지 않은 트래픽에서 암호화된 트래픽으로 점진적으로 전환할 수 있습니다. - 인증서의 Common Name 필드는 무시됩니다.
TLS로 Gitaly 구성#
히스토리
- GitLab 17.11에서 최소 TLS 버전 구성 옵션이 도입되었습니다.
TLS 지원을 구성하기 전에 Gitaly를 구성합니다.
TLS 지원 구성 절차는 설치 유형에 따라 다릅니다.
-
Gitaly 서버용 인증서를 생성합니다.
-
Gitaly 클라이언트에서 인증서(또는 그 인증 기관)를
/etc/gitlab/trusted-certs로 복사합니다.sudo cp cert.pem /etc/gitlab/trusted-certs/ -
Gitaly 클라이언트에서
/etc/gitlab/gitlab.rb의gitlab_rails['repositories_storages']를 다음과 같이 편집합니다.gitlab_rails['repositories_storages'] = { 'default' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, 'storage1' => { 'gitaly_address' => 'tls://gitaly1.internal:9999' }, 'storage2' => { 'gitaly_address' => 'tls://gitaly2.internal:9999' }, } -
파일을 저장하고 GitLab을 재구성합니다.
-
Gitaly 서버에서
/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 /etc/gitlab/ssl/cert.pem sudo chmod 600 /etc/gitlab/ssl/key.pem # For Linux package installations, 'git' is the default username. Modify the following command if it was changed from the default sudo chown -R git /etc/gitlab/ssl -
Gitaly 서버와 클라이언트가 자기 자신이나 다른 Gitaly 서버를 호출할 때 인증서를 신뢰하도록, 모든 Gitaly 서버 인증서(또는 그 인증 기관)를 모든 Gitaly 서버와 클라이언트의
/etc/gitlab/trusted-certs로 복사합니다.sudo cp cert1.pem cert2.pem /etc/gitlab/trusted-certs/ -
/etc/gitlab/gitlab.rb를 편집해 다음을 추가합니다.gitaly['configuration'] = { # ... tls_listen_addr: '0.0.0.0:9999', tls: { certificate_path: '/etc/gitlab/ssl/cert.pem', key_path: '/etc/gitlab/ssl/key.pem', ## Optionally configure the minimum TLS version Gitaly offers to clients. ## ## Default: "TLS 1.2" ## Options: ["TLS 1.2", "TLS 1.3"]. # # min_version: "TLS 1.2" }, } -
파일을 저장하고 GitLab을 재구성합니다.
-
Gitaly 클라이언트(예: Rails 애플리케이션)에서
sudo gitlab-rake gitlab:gitaly:check를 실행해 Gitaly 서버에 연결되는지 확인합니다. -
Gitaly 연결 유형 관찰로 Gitaly 트래픽이 TLS로 제공되는지 확인합니다.
-
선택 사항. 다음과 같이 보안을 강화합니다.
/etc/gitlab/gitlab.rb의gitaly['configuration'][:listen_addr]을 주석 처리하거나 삭제해 TLS가 아닌 연결을 비활성화합니다.- 파일을 저장합니다.
- GitLab을 재구성합니다.
-
Gitaly 서버용 인증서를 생성합니다.
-
Gitaly 클라이언트에서 인증서를 시스템 신뢰 인증서로 복사합니다.
sudo cp cert.pem /usr/local/share/ca-certificates/gitaly.crt sudo update-ca-certificates -
Gitaly 클라이언트에서
/home/git/gitlab/config/gitlab.yml의storages를 편집해gitaly_address가 TLS 주소를 사용하도록 변경합니다. 예를 들면 다음과 같습니다.gitlab: repositories: storages: default: gitaly_address: tls://gitaly1.internal:9999 gitaly_token: AUTH_TOKEN_1 storage1: gitaly_address: tls://gitaly1.internal:9999 gitaly_token: AUTH_TOKEN_1 storage2: gitaly_address: tls://gitaly2.internal:9999 gitaly_token: AUTH_TOKEN_2 -
파일을 저장하고 GitLab을 재시작합니다.
-
Gitaly 서버에서
/etc/default/gitlab을 생성하거나 편집해 다음을 추가합니다.export SSL_CERT_DIR=/etc/gitlab/ssl -
Gitaly 서버에서
/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 /etc/gitlab/ssl/cert.pem sudo chmod 600 /etc/gitlab/ssl/key.pem # Set ownership to the same user that runs Gitaly sudo chown -R git /etc/gitlab/ssl -
Gitaly 서버가 자기 자신이나 다른 Gitaly 서버를 호출할 때 인증서를 신뢰하도록, 모든 Gitaly 서버 인증서(또는 그 인증 기관)를 시스템 신뢰 인증서 폴더로 복사합니다.
sudo cp cert.pem /usr/local/share/ca-certificates/gitaly.crt sudo update-ca-certificates -
/home/git/gitaly/config.toml을 편집해 다음을 추가합니다.tls_listen_addr = '0.0.0.0:9999' [tls] certificate_path = '/etc/gitlab/ssl/cert.pem' key_path = '/etc/gitlab/ssl/key.pem' -
파일을 저장하고 GitLab을 재시작합니다.
-
Gitaly 연결 유형 관찰로 Gitaly 트래픽이 TLS로 제공되는지 확인합니다.
-
선택 사항. 다음과 같이 보안을 강화합니다.
/home/git/gitaly/config.toml의listen_addr을 주석 처리하거나 삭제해 TLS가 아닌 연결을 비활성화합니다.- 파일을 저장합니다.
- GitLab을 재시작합니다.
인증서 업데이트#
최초 구성 이후 Gitaly 인증서를 업데이트하려면 다음 단계를 따릅니다.
/etc/gitlab/ssl 디렉터리 아래의 SSL 인증서 내용이 변경되었지만 /etc/gitlab/gitlab.rb의 구성은
바뀌지 않았다면, GitLab을 재구성해도 Gitaly에는 영향이 없습니다. 이 경우 Gitaly 프로세스가 인증서를
읽도록 Gitaly를 직접 재시작해야 합니다.
sudo gitlab-ctl restart gitaly
/etc/gitlab/gitlab.rb 파일을 변경하지 않은 채 /etc/gitlab/trusted-certs의 인증서를 변경하거나 업데이트했다면 다음을 수행해야 합니다.
-
신뢰 인증서의 심볼릭 링크가 갱신되도록 GitLab을 재구성합니다.
-
Gitaly 프로세스가 인증서를 읽도록 Gitaly를 직접 재시작합니다.
sudo gitlab-ctl restart gitaly
/etc/gitlab/ssl 디렉터리 아래의 SSL 인증서 내용이 변경되었다면, Gitaly 프로세스가 인증서를 읽도록
GitLab을 재시작해야 합니다.
/usr/local/share/ca-certificates의 인증서를 변경하거나 업데이트했다면 다음을 수행해야 합니다.
sudo update-ca-certificates를 실행해 시스템의 신뢰 인증서 목록을 갱신합니다.- Gitaly 프로세스가 인증서를 읽도록 GitLab을 재시작합니다.
Gitaly 연결 유형 관찰#
제공되는 Gitaly 연결 유형을 관찰하는 방법은 관련 문서를 참고합니다.