ClickHouse

요약

ClickHouse는 오픈소스 칼럼 지향 데이터베이스 관리 시스템입니다. GitLab은 GitLab Duo, SDLC 트렌드, CI Analytics 등 고급 분석 기능을 지원하기 위해 ClickHouse를 보조 데이터 저장소로 사용합니다.

히스토리

GitLab 18.11에서 GitLab Self-Managed 대상으로 일반 공급(GA) 되었습니다.

ClickHouse는 오픈소스 칼럼 지향 데이터베이스 관리 시스템입니다. 대규모 데이터 세트에 걸쳐 효율적으로 필터링, 집계, 쿼리를 수행할 수 있습니다.

GitLab은 GitLab Duo, SDLC 트렌드, CI Analytics 등 고급 분석 기능을 지원하기 위해 ClickHouse를 보조 데이터 저장소로 사용합니다. GitLab은 이러한 기능을 지원하는 데이터만 ClickHouse에 저장합니다.

ClickHouse를 GitLab에 연결할 때는 ClickHouse Cloud를 사용하는 것을 권장합니다.

또는 직접 준비한 ClickHouse를 사용할 수도 있습니다. 자세한 내용은 GitLab Self-Managed를 위한 ClickHouse 권장 사항을 참고합니다.

ClickHouse로 사용할 수 있는 분석 기능#

ClickHouse를 구성하면 다음 분석 기능을 사용할 수 있습니다.

기능	설명
러너 플릿 대시보드	러너 사용률 지표와 작업(job) 대기 시간을 표시합니다. 프로젝트별로 러너 유형 및 작업 상태에 따른 작업 수와 실행된 러너 분(minute)을 담은 CSV 파일 내보내기를 제공합니다.
기여 분석	시간 경과에 따른 그룹 구성원 기여도(푸시 이벤트, 이슈, 머지 리퀘스트) 분석을 제공합니다. ClickHouse는 대규모 인스턴스에서 타임아웃 문제 발생 가능성을 줄여 줍니다.
GitLab Duo 및 SDLC 트렌드	GitLab Duo가 소프트웨어 개발 성과에 미치는 영향을 측정합니다. 개발 지표(배포 빈도, 리드 타임, 변경 실패율, 복구 시간)와 AI 관련 지표(GitLab Duo 시트 도입률, Code Suggestions 수락률, GitLab Duo Chat 사용률)를 함께 추적합니다.
AI 지표용 GraphQL API	`AiMetrics`, `AiUserMetrics`, `AiUsageData` 엔드포인트를 통해 GitLab Duo 및 SDLC 트렌드 데이터에 프로그래밍 방식으로 접근할 수 있도록 제공합니다. BI 도구 및 맞춤형 분석과 연동할 수 있도록 사전 집계된 지표와 원시 이벤트 데이터 내보내기를 제공합니다.

지원되는 ClickHouse 버전#

지원되는 ClickHouse 버전은 사용 중인 GitLab 버전에 따라 다릅니다.

GitLab 17.7 이상은 ClickHouse 23.x를 지원합니다. ClickHouse 24.x 또는 25.x를 사용하려면 우회 방법을 사용합니다.
GitLab 18.1 이상은 ClickHouse 23.x, 24.x, 25.x를 지원합니다.
GitLab 18.8 이상은 ClickHouse 23.x, 24.x, 25.x와 Replicated 데이터베이스 엔진을 지원합니다.
- 이전 버전의 클러스터에는 추가 권한(dictGet)이 필요합니다. 스니펫을 참고합니다.
GitLab 19.0 이상은 ClickHouse 25.x와 26.6 까지의 26.x를 지원합니다. ClickHouse 23.x 및 24.x에 대한 지원은 제거되었습니다.
ClickHouse 26.7 이상은 지원되지 않습니다. 임시 우회 방법은 ClickHouse 26.7 이상을 참고합니다.

ClickHouse Cloud는 항상 최신 안정 버전 GitLab 릴리스와 호환됩니다.

Warning

일부 ClickHouse 버전은 GitLab 통합에 영향을 미치는 하위 호환성이 깨지는 변경 사항을 도입합니다.

ClickHouse 25.12는 ALTER MODIFY COLUMN에 하위 호환성이 깨지는 변경 사항을 도입했습니다. 이로 인해 18.8 이전 버전의 GitLab ClickHouse 통합에서 마이그레이션 프로세스가 중단됩니다. GitLab을 18.8 이상으로 업그레이드해야 합니다.
ClickHouse 26.7은 GitLab 이 아직 충족하지 못하는 AggregatingMergeTree 테이블에 대한 검증을 추가했으며, 이로 인해 마이그레이션이 Code: 36(BAD_ARGUMENTS) 오류와 함께 실패합니다. 임시 우회 방법은 ClickHouse 26.7 이상을 참고합니다.

ClickHouse 설정#

운영 요구 사항에 따라 배포 유형을 선택합니다.

ClickHouse Cloud(권장): 자동 업그레이드, 백업, 스케일링을 제공하는 완전 관리형 서비스입니다.
GitLab Self-Managed 용 ClickHouse(BYOC): 인프라와 구성을 완전히 직접 제어합니다.

ClickHouse 인스턴스를 설정한 후:

GitLab 데이터베이스와 사용자를 생성합니다.
GitLab 연결을 구성합니다.
연결을 확인합니다.
ClickHouse 마이그레이션을 실행합니다.
Analytics 용 ClickHouse를 활성화합니다.

ClickHouse Cloud 설정#

사전 요구 사항:

ClickHouse Cloud 계정을 보유하고 있어야 합니다.
GitLab 인스턴스에서 ClickHouse Cloud 로의 네트워크 연결을 활성화해야 합니다.
GitLab 인스턴스의 관리자여야 합니다.

ClickHouse Cloud를 설정하려면:

ClickHouse Cloud에 로그인합니다.
New Service를 선택합니다.
서비스 티어를 선택합니다.
- Development: 테스트 및 개발 환경용입니다.
- Production: 고가용성이 필요한 프로덕션 워크로드용입니다.
클라우드 제공업체와 리전을 선택합니다. 최적의 성능을 위해 GitLab 인스턴스와 가까운 리전을 선택합니다.
서비스 이름과 설정을 구성합니다.
Create Service를 선택합니다.
프로비저닝이 완료되면 서비스 대시보드에서 연결 정보를 기록해 둡니다.
- 호스트
- 포트(GitLab 이 사용하는 HTTPS 연결은 8443, clickhouse-client가 사용하는 TLS를 적용한 네이티브 TCP는 9440)
- 사용자 이름
- 비밀번호

Note

ClickHouse Cloud는 버전 업그레이드와 보안 패치를 자동으로 처리합니다. Enterprise Edition(EE) 고객은 업그레이드 발생 시점을 직접 제어하도록 일정을 예약해, 업무 시간 중 예기치 않은 서비스 중단을 피할 수 있습니다. 자세한 내용은 ClickHouse 업그레이드를 참고합니다.

ClickHouse Cloud 서비스를 생성한 후에는 GitLab 데이터베이스와 사용자를 생성합니다.

GitLab Self-Managed 용 ClickHouse 설정(BYOC)#

사전 요구 사항:

ClickHouse 인스턴스가 설치되어 실행 중이어야 합니다. ClickHouse가 설치되어 있지 않다면 다음을 참고합니다.
- ClickHouse 공식 설치 가이드.
- GitLab Self-Managed를 위한 ClickHouse 권장 사항.
지원되는 ClickHouse 버전을 사용해야 합니다.
GitLab 인스턴스에서 ClickHouse 로의 네트워크 연결을 활성화해야 합니다.
ClickHouse와 GitLab 인스턴스 양쪽의 관리자여야 합니다.

Warning

GitLab Self-Managed 용 ClickHouse를 사용하는 경우, 버전 업그레이드·보안 패치·백업의 계획과 실행은 직접 담당해야 합니다. 자세한 내용은 ClickHouse 업그레이드를 참고합니다.

고가용성 구성#

다중 노드 고가용성(HA) 구성을 위해 GitLab은 ClickHouse의 Replicated 테이블 엔진을 지원합니다.

사전 요구 사항:

여러 노드로 구성된 ClickHouse 클러스터가 있어야 합니다. 최소 3개 노드를 권장합니다.
remote_servers 구성 섹션에서 클러스터를 정의합니다.
ClickHouse 구성에서 다음 매크로를 설정합니다.
- cluster
- shard
- replica

HA를 위해 데이터베이스를 구성할 때는 반드시 ON CLUSTER 절과 함께 구문을 실행해야 합니다.

자세한 내용은 ClickHouse Replicated 데이터베이스 엔진 문서를 참고합니다.

로드 밸런서 구성#

GitLab 애플리케이션은 HTTP/HTTPS 인터페이스를 통해 ClickHouse 클러스터와 통신합니다. HA 배포에서는 HTTP 프록시나 로드 밸런서를 사용해 ClickHouse 클러스터 노드 사이에 요청을 분산합니다.

권장 로드 밸런서 옵션:

chproxy - 캐싱과 라우팅이 내장된 ClickHouse 전용 HTTP 프록시입니다.
HAProxy - 범용 TCP/HTTP 로드 밸런서입니다.
NGINX - 로드 밸런싱 기능을 갖춘 웹 서버입니다.
클라우드 제공업체의 로드 밸런서(AWS Application Load Balancer, GCP Load Balancer, Azure Load Balancer)입니다.

기본 chproxy 구성 예시:

server:
  http:
    listen_addr: ":8080"

clusters:
  - name: "clickhouse_cluster"
    nodes: [
      "http://ch-node1:8123",
      "http://ch-node2:8123",
      "http://ch-node3:8123"
    ]

users:
  - name: "gitlab"
    password: "your_secure_password"
    to_cluster: "clickhouse_cluster"
    to_user: "gitlab"

로드 밸런서를 사용할 때는 GitLab 이 개별 ClickHouse 노드가 아니라 로드 밸런서 URL에 연결하도록 구성합니다.

자세한 내용은 chproxy 문서를 참고합니다.

GitLab Self-Managed 용 ClickHouse 인스턴스를 구성한 후에는 GitLab 데이터베이스와 사용자를 생성합니다.

ClickHouse 설치 확인#

데이터베이스를 구성하기 전에 ClickHouse가 설치되어 접근 가능한 상태인지 확인합니다.

ClickHouse가 실행 중인지 확인합니다.
```
clickhouse-client --query "SELECT version()"
```
ClickHouse가 실행 중이면 버전 번호(예: 24.3.1.12)가 표시됩니다.
자격 증명으로 연결할 수 있는지 확인합니다.
```
clickhouse-client --host your-clickhouse-host --port 9440 --secure --user default --password 'your-password'
```
[!note] 아직 TLS를 구성하지 않았다면, 초기 테스트용으로 --secure 플래그 없이 9000 포트를 사용합니다.

데이터베이스와 사용자 생성#

필요한 사용자와 데이터베이스 객체를 생성하려면:

안전한 비밀번호를 생성하고 저장해 둡니다.
다음 위치에 로그인합니다.
- ClickHouse Cloud의 경우 ClickHouse SQL 콘솔
- GitLab Self-Managed 용 ClickHouse의 경우 clickhouse-client
PASSWORD_HERE 부분을 생성한 비밀번호로 바꿔서 다음 명령을 실행합니다.

CREATE DATABASE gitlab_clickhouse_main_production;
CREATE USER gitlab IDENTIFIED WITH sha256_password BY 'PASSWORD_HERE';
CREATE ROLE gitlab_app;
GRANT SELECT, INSERT, ALTER, CREATE, UPDATE, DROP, TRUNCATE, OPTIMIZE, dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app;
GRANT SELECT ON information_schema.* TO gitlab_app;
GRANT gitlab_app TO gitlab;

CLUSTER_NAME_HERE 부분을 클러스터 이름으로 바꿉니다.

CREATE DATABASE gitlab_clickhouse_main_production ON CLUSTER CLUSTER_NAME_HERE ENGINE = Replicated('/clickhouse/databases/{cluster}/gitlab_clickhouse_main_production', '{shard}', '{replica}');
CREATE USER gitlab IDENTIFIED WITH sha256_password BY 'PASSWORD_HERE' ON CLUSTER CLUSTER_NAME_HERE;
CREATE ROLE gitlab_app ON CLUSTER CLUSTER_NAME_HERE;
GRANT SELECT, INSERT, ALTER, CREATE, UPDATE, DROP, TRUNCATE, OPTIMIZE, dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app ON CLUSTER CLUSTER_NAME_HERE;
GRANT SELECT ON information_schema.* TO gitlab_app ON CLUSTER CLUSTER_NAME_HERE;
GRANT gitlab_app TO gitlab ON CLUSTER CLUSTER_NAME_HERE;

GitLab 연결 구성#

GitLab에 ClickHouse 자격 증명을 제공하려면:

/etc/gitlab/gitlab.rb 파일을 편집합니다.
```
gitlab_rails['clickhouse_databases']['main']['database'] = 'gitlab_clickhouse_main_production'
gitlab_rails['clickhouse_databases']['main']['url'] = 'https://your-clickhouse-host:port'
gitlab_rails['clickhouse_databases']['main']['username'] = 'gitlab'
gitlab_rails['clickhouse_databases']['main']['password'] = 'PASSWORD_HERE' # replace with the actual password
```
URL을 다음과 같이 바꿉니다.
- ClickHouse Cloud의 경우: https://your-service.clickhouse.cloud:8443
- GitLab Self-Managed 용 ClickHouse의 경우: https://your-clickhouse-host:8443
- 로드 밸런서를 사용하는 GitLab Self-Managed 용 ClickHouse HA의 경우: https://your-load-balancer:8080(또는 사용 중인 로드 밸런서 URL)
파일을 저장하고 GitLab을 재구성합니다.
```
sudo gitlab-ctl reconfigure
```

ClickHouse 비밀번호를 Kubernetes Secret으로 저장합니다.

kubectl create secret generic gitlab-clickhouse-password --from-literal="main_password=PASSWORD_HERE"

Helm 값을 내보냅니다.

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml 파일을 편집합니다.
```
global:
  clickhouse:
    enabled: true
    main:
      username: gitlab
      password:
        secret: gitlab-clickhouse-password
        key: main_password
      database: gitlab_clickhouse_main_production
      url: 'https://your-clickhouse-host:port'
```
URL을 다음과 같이 바꿉니다.
- ClickHouse Cloud의 경우: https://your-service.clickhouse.cloud:8443
- GitLab Self-Managed 용 ClickHouse 단일 노드의 경우: https://your-clickhouse-host:8443
- 로드 밸런서를 사용하는 GitLab Self-Managed 용 ClickHouse HA의 경우: https://your-load-balancer:8080(또는 사용 중인 로드 밸런서 URL)

파일을 저장하고 새 값을 적용합니다.

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Note

프로덕션 배포에서는 ClickHouse 인스턴스에 TLS/SSL을 구성하고 https:// URL을 사용합니다. GitLab Self-Managed 설치의 경우 네트워크 보안 문서를 참고합니다.

연결 확인#

연결이 정상적으로 설정되었는지 확인하려면:

Rails 콘솔에 로그인합니다.
다음 명령을 실행합니다.
```
ClickHouse::Client.select('SELECT 1', :main)
```
성공하면 명령이 [{"1"=>1}]를 반환합니다.

연결에 실패하면 다음을 확인합니다.

ClickHouse 서비스가 실행 중이고 접근 가능한지 확인합니다.
GitLab에서 ClickHouse 로의 네트워크 연결을 확인합니다. 방화벽과 보안 그룹이 연결을 허용하는지 점검합니다.
연결 URL(호스트, 포트, 프로토콜)이 올바른지 확인합니다.
자격 증명이 올바른지 확인합니다.
HA 클러스터 배포의 경우: 로드 밸런서가 올바르게 구성되어 요청을 라우팅하는지 확인합니다.

ClickHouse 마이그레이션 실행#

Note

이 단계는 필수입니다. 건너뛰면 Analytics 대시보드에 데이터가 표시되지 않고 "Failed to fetch data" 오류가 나타납니다.

필요한 데이터베이스 객체를 생성하려면 다음을 실행합니다.

sudo gitlab-rake gitlab:clickhouse:migrate

마이그레이션은 GitLab-Migrations 차트를 통해 자동으로 실행됩니다.

또는 Toolbox Pod에서 다음 명령을 실행해 마이그레이션을 수행할 수도 있습니다.

gitlab-rake gitlab:clickhouse:migrate

Analytics 용 ClickHouse 활성화#

GitLab 인스턴스가 ClickHouse에 연결되면 ClickHouse를 사용하는 기능을 활성화할 수 있습니다.

사전 요구 사항:

인스턴스에 대한 관리자 권한이 있어야 합니다.
ClickHouse 연결이 구성되고 확인되어 있어야 합니다.
마이그레이션이 성공적으로 완료되어 있어야 합니다.

Analytics 용 ClickHouse를 활성화하려면:

왼쪽 사이드바 하단에서 Admin을 선택합니다.
Settings > General을 선택합니다.
ClickHouse를 확장합니다.
Enable ClickHouse for Analytics를 선택합니다.
Save changes를 선택합니다.

Analytics 용 ClickHouse 비활성화#

Analytics 용 ClickHouse를 비활성화하려면:

사전 요구 사항:

인스턴스에 대한 관리자 권한이 있어야 합니다.

비활성화하려면:

왼쪽 사이드바 하단에서 Admin을 선택합니다.
Settings > General을 선택합니다.
ClickHouse를 확장합니다.
Enable ClickHouse for Analytics 확인란의 선택을 해제합니다.
Save changes를 선택합니다.

Note

Analytics 용 ClickHouse를 비활성화하면 GitLab 이 ClickHouse에 쿼리를 보내지 않게 되지만, ClickHouse 인스턴스의 데이터는 삭제되지 않습니다. ClickHouse에 의존하는 Analytics 기능은 대체 데이터 소스로 전환되거나 사용할 수 없게 됩니다.

ClickHouse 업그레이드#

ClickHouse Cloud#

ClickHouse Cloud는 버전 업그레이드와 보안 패치를 자동으로 처리하므로 수동 개입이 필요하지 않습니다.

업그레이드 일정과 점검 기간에 대한 정보는 ClickHouse Cloud 업그레이드를 참고합니다.

Note

ClickHouse Cloud는 예정된 업그레이드를 사전에 알려 줍니다. 새 기능과 변경 사항을 계속 확인하려면 ClickHouse Cloud 변경 이력을 검토합니다.

GitLab Self-Managed 용 ClickHouse(BYOC)#

GitLab Self-Managed 용 ClickHouse를 사용하는 경우, 버전 업그레이드의 계획과 실행은 직접 담당해야 합니다.

사전 요구 사항:

ClickHouse 인스턴스에 대한 관리자 권한이 있어야 합니다.
업그레이드 전 데이터를 백업해야 합니다. 재해 복구를 참고합니다.

업그레이드하기 전에:

ClickHouse 릴리스 노트를 검토해 호환성이 깨지는 변경 사항이 있는지 확인합니다.
사용 중인 GitLab 버전과의 호환성을 확인합니다.
프로덕션이 아닌 환경에서 업그레이드를 테스트합니다.
예상되는 다운타임을 계획하거나, HA 클러스터의 경우 롤링 업그레이드 전략을 사용합니다.

ClickHouse를 업그레이드하려면:

단일 노드 배포의 경우 ClickHouse 업그레이드 문서를 따릅니다.
HA 클러스터 배포의 경우 다운타임을 최소화하기 위해 롤링 업그레이드를 수행합니다.
- 한 번에 노드 하나씩 업그레이드합니다.
- 해당 노드가 클러스터에 다시 합류할 때까지 기다립니다.
- 다음 노드로 넘어가기 전에 클러스터 상태를 확인합니다.

Warning

ClickHouse 버전이 항상 사용 중인 GitLab 버전과 호환되는 상태를 유지하도록 합니다. 버전이 호환되지 않으면 인덱싱이 중단되고 기능이 실패할 수 있습니다. 자세한 내용은 지원되는 ClickHouse 버전을 참고합니다.

자세한 업그레이드 절차는 업데이트에 대한 ClickHouse 문서를 참고합니다.

운영#

마이그레이션 상태 확인#

사전 요구 사항:

인스턴스에 대한 관리자 권한이 있어야 합니다.

ClickHouse 마이그레이션 상태를 확인하려면:

왼쪽 사이드바 하단에서 Admin을 선택합니다.
Settings > General을 선택합니다.
ClickHouse를 확장합니다.
사용 가능한 경우 Migration status 섹션을 확인합니다.

또는 Rails 콘솔을 사용해 대기 중인 마이그레이션을 확인할 수도 있습니다.

# Sign in to Rails console
# Run this to check migrations
ClickHouse::MigrationSupport::Migrator.new(:main).pending_migrations

실패한 마이그레이션 재시도#

ClickHouse 마이그레이션이 실패하면:

로그에서 오류 세부 정보를 확인합니다. ClickHouse 관련 오류는 GitLab 애플리케이션 로그에 기록됩니다.
근본 원인(예: 메모리 부족, 연결 문제)을 해결합니다.

마이그레이션을 다시 시도합니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:clickhouse:migrate

# For self-compiled installations
bundle exec rake gitlab:clickhouse:migrate RAILS_ENV=production

Note

마이그레이션은 멱등성을 갖도록 설계되어 있어 안전하게 재시도할 수 있습니다. 마이그레이션이 중간에 실패하면 다시 실행할 때 중단된 지점부터 재개하거나 이미 완료된 단계를 건너뜁니다.

ClickHouse Rake 작업#

GitLab은 ClickHouse 데이터베이스를 관리하기 위한 여러 Rake 작업을 제공합니다.

다음 Rake 작업을 사용할 수 있습니다.

작업	설명
`sudo gitlab-rake gitlab:clickhouse:migrate`	대기 중인 모든 ClickHouse 마이그레이션을 실행해 데이터베이스 스키마를 생성하거나 업데이트합니다.
`sudo gitlab-rake gitlab:clickhouse:drop`	모든 ClickHouse 데이터베이스를 삭제합니다. 모든 데이터가 삭제되므로 각별히 주의해서 사용합니다.
`sudo gitlab-rake gitlab:clickhouse:create`	ClickHouse 데이터베이스가 존재하지 않으면 생성합니다.
`sudo gitlab-rake gitlab:clickhouse:setup`	데이터베이스를 생성하고 모든 마이그레이션을 실행합니다. `create` 작업과 `migrate` 작업을 함께 실행하는 것과 동일합니다.
`sudo gitlab-rake gitlab:clickhouse:schema:dump`	현재 데이터베이스 스키마를 백업이나 버전 관리를 위해 파일로 덤프합니다.
`sudo gitlab-rake gitlab:clickhouse:schema:load`	덤프 파일에서 데이터베이스 스키마를 불러옵니다.

Note

셀프 컴파일 설치의 경우 sudo gitlab-rake 대신 bundle exec rake를 사용하고, 명령 끝에 RAILS_ENV=production을 추가합니다.

일반적인 작업 예시#

ClickHouse 연결과 스키마 확인#

ClickHouse 연결이 정상 작동하는지 확인하려면:

# For installations that use the Linux package
sudo gitlab-rake gitlab:clickhouse:info

# For self-compiled installations
bundle exec rake gitlab:clickhouse:info RAILS_ENV=production

이 작업은 ClickHouse 연결과 구성에 대한 디버깅 정보를 출력합니다.

모든 마이그레이션 재실행#

대기 중인 모든 마이그레이션을 실행하려면:

# For installations that use the Linux package
sudo gitlab-rake gitlab:clickhouse:migrate

# For self-compiled installations
bundle exec rake gitlab:clickhouse:migrate RAILS_ENV=production

데이터베이스 초기화#

Warning

이 작업은 ClickHouse 데이터베이스의 모든 데이터를 삭제합니다. 개발 환경이나 문제 해결 시에만 사용합니다.

데이터베이스를 삭제하고 다시 생성하려면:

# For installations that use the Linux package
sudo gitlab-rake gitlab:clickhouse:drop
sudo gitlab-rake gitlab:clickhouse:setup

# For self-compiled installations
bundle exec rake gitlab:clickhouse:drop RAILS_ENV=production
bundle exec rake gitlab:clickhouse:setup RAILS_ENV=production

환경 변수#

환경 변수를 사용해 Rake 작업의 동작을 제어할 수 있습니다.

환경 변수	데이터 유형	설명
`VERBOSE`	Boolean	마이그레이션 중 상세 출력을 보려면 `true`로 설정합니다. 예: `VERBOSE=true sudo gitlab-rake gitlab:clickhouse:migrate`

성능 튜닝#

Note

사용자 수에 따른 리소스 크기 산정과 배포 권장 사항은 시스템 요구 사항을 참고합니다.

ClickHouse 아키텍처와 성능 튜닝에 대한 정보는 아키텍처에 대한 ClickHouse 문서를 참고합니다.

재해 복구#

백업과 복원#

GitLab 애플리케이션을 업그레이드하기 전에 전체 백업을 수행해야 합니다. ClickHouse 데이터는 GitLab 백업 도구에 포함되지 않습니다.

백업 및 복원 전략은 선택한 배포 방식에 따라 달라집니다.

ClickHouse Cloud#

ClickHouse Cloud는 다음을 자동으로 수행합니다.

백업과 복원을 관리합니다.
매일 백업을 생성하고 보관합니다.

별도의 추가 구성은 필요하지 않습니다.

자세한 내용은 ClickHouse Cloud 백업을 참고합니다.

GitLab Self-Managed 용 ClickHouse#

직접 ClickHouse 인스턴스를 관리하는 경우, 데이터 안전을 위해 정기적으로 백업을 수행해야 합니다.

초기 전체 백업(예: metrics, logs 같은 시스템 테이블 제외)을 오브젝트 스토리지 버킷(예: AWS S3)에 수행합니다.
이 초기 전체 백업 이후에는 증분 백업을 수행합니다.

이 방식은 전체 백업마다 데이터가 중복되지만, 데이터를 복원하는 가장 쉬운 방법입니다.

또는 clickhouse-backup을 사용할 수도 있습니다. 이는 예약 실행, 원격 스토리지 관리 등 추가 기능과 함께 유사한 기능을 제공하는 서드파티 도구입니다.

모니터링#

GitLab 통합의 안정성을 보장하려면 ClickHouse 클러스터의 상태와 성능을 모니터링해야 합니다.

ClickHouse Cloud#

ClickHouse Cloud는 보안 API 엔드포인트를 통해 지표를 노출하는 네이티브 Prometheus 통합을 제공합니다.

API 자격 증명을 생성한 후에는 ClickHouse Cloud에서 지표를 수집하도록 컬렉터를 구성할 수 있습니다. 예를 들어 Prometheus 배포가 있습니다.

GitLab Self-Managed 용 ClickHouse#

ClickHouse는 Prometheus 형식 지표를 노출할 수 있습니다. 이를 활성화하려면:

config.xml의 prometheus 섹션을 구성해 전용 포트(기본값 9363)로 지표를 노출합니다.

<prometheus>
    <endpoint>/metrics</endpoint>
    <port>9363</port>
    <metrics>true</metrics>
    <events>true</events>
    <asynchronous_metrics>true</asynchronous_metrics>
</prometheus>

http://<clickhouse-host>:9363/metrics를 수집하도록 Prometheus 또는 이와 호환되는 서버를 구성합니다.

모니터링할 지표#

GitLab 기능에 영향을 줄 수 있는 문제를 감지하려면 다음 지표에 대한 알림을 설정해야 합니다.

지표 이름	설명	알림 임계값(권장)
`ClickHouse_Metrics_Query`	현재 실행 중인 쿼리 수입니다. 갑자기 급증하면 성능 병목을 나타낼 수 있습니다.	기준선 편차(예: `> 100`)
`ClickHouseProfileEvents_FailedSelectQuery`	실패한 select 쿼리 수입니다.	기준선 편차(예: `> 50`)
`ClickHouseProfileEvents_FailedInsertQuery`	실패한 insert 쿼리 수입니다.	기준선 편차(예: `> 10`)
`ClickHouse_AsyncMetrics_ReadonlyReplica`	레플리카가 읽기 전용 모드로 전환되었는지 나타냅니다(주로 ZooKeeper 연결 끊김으로 발생).	`> 0`(즉시 조치 필요)
`ClickHouse_ProfileEvents_NetworkErrors`	네트워크 오류(연결 재설정/타임아웃)입니다. 빈번하게 발생하면 GitLab 백그라운드 작업이 실패할 수 있습니다.	비율 `> 0`

생존 확인(Liveness check)#

ClickHouse가 로드 밸런서 뒤에서 사용 가능한 경우, HTTP /ping 엔드포인트로 생존 상태를 확인할 수 있습니다. 예상되는 응답은 HTTP 코드 200과 함께 Ok 입니다.

보안과 감사#

데이터 보안을 보장하고 감사 가능성을 확보하려면 다음 보안 사례를 적용합니다.

네트워크 보안#

TLS 암호화: ClickHouse 서버가 연결을 검증하도록 TLS 암호화를 사용하게 구성합니다.

GitLab에서 연결 URL을 구성할 때는 이를 지정하기 위해 https:// 프로토콜(예: https://clickhouse.example.com:8443)을 사용해야 합니다.
IP 허용 목록: ClickHouse 포트(기본값 8443 또는 9440)에 대한 접근을 GitLab 애플리케이션 노드와 승인된 다른 네트워크로만 제한합니다.

감사 로깅#

GitLab 애플리케이션은 개별 ClickHouse 쿼리에 대한 별도의 감사 로그를 유지하지 않습니다. 데이터 접근(누가 언제 무엇을 조회했는지)에 대한 특정 요구 사항을 충족해야 한다면, ClickHouse 쪽에서 로깅을 활성화할 수 있습니다.

ClickHouse Cloud#

ClickHouse Cloud에서는 쿼리 로깅이 기본적으로 활성화되어 있습니다. system.query_log 테이블을 쿼리해 이 로그에 접근할 수 있습니다.

GitLab Self-Managed 용 ClickHouse#

셀프 매니지드 인스턴스에서는 서버 구성에서 query_log 구성 파라미터가 활성화되어 있는지 확인합니다.

config.xml 또는 users.xml에 query_log 섹션이 있는지 확인합니다.

<query_log>
    <database>system</database>
    <table>query_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <ttl>event_date + INTERVAL 30 DAY</ttl>  <!-- Keep only 30 days -->
</query_log>

활성화하면 실행된 모든 쿼리가 system.query_log 테이블에 기록되어 감사 추적이 가능해집니다.

쿼리를 사용자에게 귀속시키기#

GitLab은 ClickHouse로 보내는 모든 쿼리에 log_comment 설정으로 주석을 달며, 이는 system.query_log의 log_comment 열에 저장됩니다. 이 주석을 사용해 로깅된 쿼리를 해당 쿼리를 발생시킨 요청에 귀속시킬 수 있습니다. 이 주석은 다음을 포함할 수 있는 JSON 객체입니다.

user_id: 요청을 발생시킨 사용자의 숫자 ID입니다.
root_namespace_id: 루트 네임스페이스의 숫자 ID입니다.
organization_id: 요청이 속한 조직의 숫자 ID입니다.
correlation_id: 다른 GitLab 로그에서도 사용되는 요청 상관관계 ID입니다.
application: web, sidekiq, console, test 중 하나입니다.
feature_category: 요청의 기능 카테고리입니다.

백그라운드 워커가 발생시키는 쿼리는 사용자나 네임스페이스 컨텍스트 없이 실행되므로, 해당 쿼리의 log_comment 에는 보통 correlation_id, application, feature_category만 포함됩니다.

예를 들어, 쿼리와 이를 발생시킨 사용자의 감사 추적을 구성하려면 다음과 같이 합니다.

SELECT JSONExtractInt(log_comment, 'user_id') AS user_id,
       JSONExtractString(log_comment, 'correlation_id') AS correlation_id,
       query,
       event_time
FROM system.query_log
WHERE type = 'QueryFinish' AND log_comment != ''
ORDER BY event_time DESC
LIMIT 20

시스템 요구 사항#

권장 시스템 요구 사항은 사용자 수에 따라 달라집니다.

배포 결정 매트릭스 빠른 참조#

사용자 수	기본 권장 사항	대응 AWS ARM 인스턴스	대응 GCP ARM 인스턴스	대응 Azure ARM 인스턴스	배포 유형
1K	ClickHouse Cloud Basic	-	-	-	관리형
2K	ClickHouse Cloud Basic	`m8g.xlarge`	`c4a-standard-4`	`Standard_D4ps_v6`	관리형 또는 단일 노드
3K	ClickHouse Cloud Scale	`m8g.2xlarge`	`c4a-standard-8`	`Standard_D8ps_v6`	관리형 또는 단일 노드
5K	ClickHouse Cloud Scale	`m8g.4xlarge`	`c4a-standard-16`	`Standard_D16ps_v6`	관리형 또는 단일 노드
10K	ClickHouse Cloud Scale	`m8g.4xlarge`	`c4a-standard-16`	`Standard_D16ps_v6`	관리형 또는 단일 노드/HA
25K	GitLab Self-Managed 용 ClickHouse 또는 ClickHouse Cloud Scale	`m8g.8xlarge` 또는 3×`m8g.4xlarge`	`c4a-standard-32` 또는 3×`c4a-standard-16`	`Standard_D32ps_v6` 또는 3x`Standard_D16ps_v6`	관리형 또는 단일 노드/HA
50K	GitLab Self-Managed 용 ClickHouse 고가용성(HA) 또는 ClickHouse Cloud Scale	3×`m8g.4xlarge`	3×`c4a-standard-16`	3x`Standard_D16ps_v6`	관리형 또는 HA 클러스터

사용자 1천 명#

권장: 운영 복잡도 없이 비용 효율이 좋은 ClickHouse Cloud Basic을 사용합니다.

사용자 2천 명#

권장: 운영 복잡도 없이 최상의 가치를 제공하는 ClickHouse Cloud Basic을 사용합니다.

GitLab Self-Managed 용 ClickHouse 배포에 대한 대체 권장 사항:

AWS: m8g.xlarge(vCPU 4개, 16GB)
GCP: c4a-standard-4 또는 n4-standard-4(vCPU 4개, 16GB)
Azure: Standard_D4ps_v6(vCPU 4개, 16GB)
스토리지: 저~중 성능 티어로 20GB

사용자 3천 명#

권장: ClickHouse Cloud Scale

GitLab Self-Managed 용 ClickHouse 배포에 대한 대체 권장 사항:

AWS: m8g.2xlarge(vCPU 8개, 32GB)
GCP: c4a-standard-8 또는 n4-standard-8(vCPU 8개, 32GB)
Azure: Standard_D8ps_v6(vCPU 8개, 32GB)
스토리지: 중간 성능 티어로 100GB

Note

이 규모에서는 HA 배포가 비용 효율적이지 않습니다.

사용자 5천 명#

권장: ClickHouse Cloud Scale

GitLab Self-Managed 용 ClickHouse 배포에 대한 대체 권장 사항:

AWS: m8g.4xlarge(vCPU 16개, 64GB)
GCP: c4a-standard-16 또는 n4-standard-16(vCPU 16개, 64GB)
Azure: Standard_D16ps_v6(vCPU 16개, 64GB)
스토리지: 고성능 티어로 100GB
배포: 단일 노드 권장

사용자 1만 명#

권장: ClickHouse Cloud Scale

GitLab Self-Managed 용 ClickHouse 배포에 대한 대체 권장 사항:

AWS: m8g.4xlarge(vCPU 16개, 64GB)
GCP: c4a-standard-16 또는 n4-standard-16(vCPU 16개, 64GB)
Azure: Standard_D16ps_v6(vCPU 16개, 64GB)
스토리지: 고성능 티어로 200GB
HA 옵션: 중요 워크로드에는 3노드 클러스터가 실행 가능한 선택지가 됩니다

사용자 2만 5천 명#

권장: ClickHouse Cloud Scale 또는 GitLab Self-Managed 용 ClickHouse. 이 규모에서는 두 옵션 모두 경제적으로 타당합니다.

GitLab Self-Managed 용 ClickHouse 배포에 대한 권장 사항:

단일 노드:
- AWS: m8g.8xlarge(vCPU 32개, 128GB)
- GCP: c4a-standard-32 또는 n4-standard-32(vCPU 32개, 128GB)
- Azure: Standard_D32ps_v6(vCPU 32개, 128GB)
HA 배포:
- AWS: m8g.4xlarge × 3(각 vCPU 16개, 64GB)
- GCP: c4a-standard-16 × 3 또는 n4-standard-16 × 3(각 vCPU 16개, 64GB)
- Azure: Standard_D16ps_v6 × 3(각 vCPU 16개, 64GB)
스토리지: 노드당 고성능 티어로 400GB

사용자 5만 명#

권장: GitLab Self-Managed 용 ClickHouse HA 또는 ClickHouse Cloud Scale. 이 규모에서는 셀프 매니지드 옵션이 비용 면에서 약간 더 효율적입니다.

GitLab Self-Managed 용 ClickHouse 배포에 대한 권장 사항:

단일 노드:
- AWS: m8g.8xlarge(vCPU 32개, 128GB)
- GCP: c4a-standard-32 또는 n4-standard-32(vCPU 32개, 128GB)
- Azure: Standard_D32ps_v6(vCPU 32개, 128GB)
HA 배포(권장):
- AWS: m8g.4xlarge × 3(각 vCPU 16개, 64GB)
- GCP: c4a-standard-16 × 3 또는 n4-standard-16 × 3(각 vCPU 16개, 64GB)
- Azure: Standard_D16ps_v6 × 3(각 vCPU 16개, 64GB)
스토리지: 노드당 고성능 티어로 1000GB

GitLab Self-Managed 용 ClickHouse 배포의 HA 고려 사항#

HA 구성은 사용자 1만 명 이상에서만 비용 효율적입니다.

최소 구성: 쿼럼을 위한 ClickHouse 노드 3개.
ClickHouse Keeper: 코디네이션용 노드 3개(같은 위치에 배치하거나 분리 가능).
로드 밸런서: 쿼리 분산을 위해 권장됩니다.
네트워크: 노드 간 저지연 연결이 매우 중요합니다.

용어집#

클러스터(Cluster): 데이터를 저장하고 처리하기 위해 함께 동작하는 노드(서버) 집합입니다.
MergeTree: MergeTree는 높은 데이터 수집 속도와 대용량 데이터를 처리하도록 설계된 ClickHouse의 테이블 엔진입니다. 칼럼 기반 저장, 맞춤형 파티셔닝, 희소 기본 인덱스, 백그라운드 데이터 병합 지원 등의 기능을 제공하는 ClickHouse의 핵심 저장 엔진입니다.
파트(Parts): 테이블 데이터의 일부를 저장하는, 디스크상의 물리적 파일입니다. 파트는 파티션 키를 사용해 생성되는 테이블 데이터의 논리적 구분 단위인 파티션과는 다릅니다.
레플리카(Replica): ClickHouse 데이터베이스에 저장된 데이터의 사본입니다. 중복성과 신뢰성을 위해 동일한 데이터의 레플리카를 원하는 수만큼 둘 수 있습니다. 레플리카는 ReplicatedMergeTree 테이블 엔진과 함께 사용되며, 이를 통해 ClickHouse가 여러 서버에 걸쳐 데이터 사본을 동기화된 상태로 유지할 수 있습니다.
샤드(Shard): 데이터의 부분 집합입니다. ClickHouse는 항상 데이터에 대해 최소 하나의 샤드를 가집니다. 데이터를 여러 서버에 분할하지 않으면 데이터는 하나의 샤드에 저장됩니다. 단일 서버의 용량을 초과하는 경우, 데이터를 여러 서버에 샤딩해 부하를 분산할 수 있습니다.
TTL(Time To Live): TTL은 일정 기간이 지나면 칼럼/행을 자동으로 이동, 삭제, 롤업하는 ClickHouse 기능입니다. 더 이상 자주 접근할 필요가 없는 데이터를 삭제, 이동, 보관할 수 있어 스토리지를 더 효율적으로 관리할 수 있습니다.

문제 해결#

GitLab 18.0.0 이하에서의 데이터베이스 스키마 마이그레이션#

Warning

GitLab 18.0.0 이하에서는 ClickHouse 24.x 및 25.x를 대상으로 데이터베이스 스키마 마이그레이션을 실행할 때 다음과 같은 오류 메시지와 함께 실패할 수 있습니다.

Code: 344. DB::Exception: Projection is fully supported in ReplacingMergeTree with deduplicate_merge_projection_mode = throw. Use 'drop' or 'rebuild' option of deduplicate_merge_projection_mode

모든 마이그레이션을 실행하지 않으면 ClickHouse 통합이 동작하지 않습니다.

이 문제를 우회해 마이그레이션을 실행하려면:

Rails 콘솔에 로그인합니다.

다음 명령을 실행합니다.

ClickHouse::Client.execute("INSERT INTO schema_migrations (version) VALUES ('20231114142100'), ('20240115162101')", :main)

데이터베이스를 다시 마이그레이션합니다.
```
sudo gitlab-rake gitlab:clickhouse:migrate
```

이번에는 데이터베이스 마이그레이션이 성공적으로 완료됩니다.

데이터베이스 딕셔너리 읽기 지원#

GitLab 18.8부터 GitLab은 데이터 비정규화를 위해 ClickHouse Dictionaries를 사용하기 시작합니다. 18.8 이전 버전의 GRANT 구문은 gitlab 사용자에게 딕셔너리를 쿼리할 권한을 부여하지 않았으므로, 수동으로 수정하는 단계가 필요합니다.

다음 위치에 로그인합니다.
- ClickHouse Cloud의 경우 ClickHouse SQL 콘솔
- GitLab Self-Managed 용 ClickHouse의 경우 clickhouse-client
PASSWORD_HERE 부분을 생성한 비밀번호로 바꿔서 다음 명령을 실행합니다.

GRANT dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app;

CLUSTER_NAME_HERE 부분을 클러스터 이름으로 바꿉니다.

GRANT dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app ON CLUSTER CLUSTER_NAME_HERE;

권한을 부여하지 않으면 ClickHouse 마이그레이션(CreateNamespaceTraversalPathsDict)이 다음 오류와 함께 실패합니다.

DB::Exception: gitlab: Not enough privileges.

권한을 부여한 후에는 마이그레이션을 안전하게 재시도할 수 있습니다(이상적으로는 분산 마이그레이션 잠금이 해제될 때까지 1~2시간 기다립니다).

ClickHouse CI 작업 데이터 구체화 뷰의 데이터 불일치#

GitLab 18.5 이하에서는 Sidekiq 워커가 네트워크 타임아웃 이후 재시도할 때 ClickHouse 테이블(ci_finished_pipelines, ci_finished_builds 등)에 중복 데이터가 삽입될 수 있었습니다. 이 문제로 인해 구체화 뷰(materialized view)가 러너 플릿 대시보드를 포함한 분석 대시보드에서 잘못된 집계 지표를 표시했습니다.

이 문제는 GitLab 18.9에서 수정되었으며 18.6, 18.7, 18.8에 백포트되었습니다. 이 문제를 해결하려면 GitLab 18.6 이상으로 업그레이드합니다.

기존에 중복 데이터가 있는 경우, 영향을 받은 구체화 뷰를 재구성하는 수정 사항이 이슈 586319에서 GitLab 18.10을 목표로 계획되어 있습니다. 도움이 필요하면 GitLab 지원팀에 문의합니다.

ClickHouse 26.7 이상#

ClickHouse 26.7은 정렬 키에도 속하지 않고 집계 상태 칼럼(AggregateFunction 또는 SimpleAggregateFunction)도 아닌 칼럼을 가진 AggregatingMergeTree 테이블을 거부합니다. 일부 GitLab 테이블이 이런 구조를 가지고 있어 마이그레이션이 실패합니다.

Code: 36. DB::Exception: Column(s) purchase_id, add_on_name of the AggregatingMergeTree table are neither part of the sorting key nor aggregate measures (AggregateFunction or SimpleAggregateFunction). ... (BAD_ARGUMENTS)

기존 설치에는 영향이 없습니다. 새로 설치하거나, 새 레플리카를 추가하거나, 처음부터 구성한 환경에서는 실패합니다.

ClickHouse 26.6 이하를 사용합니다. 26.7 이상을 반드시 실행해야 한다면 /etc/clickhouse-server/users.d/compatibility.xml에서 compatibility를 26.6으로 설정합니다.

<clickhouse>
    <profiles>
        <default>
            <compatibility>26.6</compatibility>
        </default>
    </profiles>
</clickhouse>

ClickHouse는 users.d를 자동으로 다시 불러오므로 재시작이 필요하지 않습니다. 이 설정은 프로필 에서만 동작하므로 ALTER USER ... SETTINGS compatibility는 효과가 없습니다. users.d는 26.7에서 추가된 모든 설정의 기본값을 되돌리므로, GitLab 이 26.7 지원을 시작하면 이 파일을 제거합니다.

Warning

compatibility 설정의 대안으로 서버 merge_tree 설정인 allow_dimensions_outside_sorting_key 를 사용해서는 안 됩니다. 26.7 이전 서버는 Code: 115(UNKNOWN_SETTING) 오류와 함께 시작에 실패합니다.

ClickHouse

GitLab v19.4

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

원문 보기

번역일: 2026-09-18

요약

히스토리

GitLab 18.11에서 GitLab Self-Managed 대상으로 일반 공급(GA) 되었습니다.

ClickHouse는 오픈소스 칼럼 지향 데이터베이스 관리 시스템입니다. 대규모 데이터 세트에 걸쳐 효율적으로 필터링, 집계, 쿼리를 수행할 수 있습니다.

ClickHouse를 GitLab에 연결할 때는 ClickHouse Cloud를 사용하는 것을 권장합니다.

또는 직접 준비한 ClickHouse를 사용할 수도 있습니다. 자세한 내용은 GitLab Self-Managed를 위한 ClickHouse 권장 사항을 참고합니다.

ClickHouse로 사용할 수 있는 분석 기능#

ClickHouse를 구성하면 다음 분석 기능을 사용할 수 있습니다.

기능	설명
러너 플릿 대시보드	러너 사용률 지표와 작업(job) 대기 시간을 표시합니다. 프로젝트별로 러너 유형 및 작업 상태에 따른 작업 수와 실행된 러너 분(minute)을 담은 CSV 파일 내보내기를 제공합니다.
기여 분석	시간 경과에 따른 그룹 구성원 기여도(푸시 이벤트, 이슈, 머지 리퀘스트) 분석을 제공합니다. ClickHouse는 대규모 인스턴스에서 타임아웃 문제 발생 가능성을 줄여 줍니다.
GitLab Duo 및 SDLC 트렌드	GitLab Duo가 소프트웨어 개발 성과에 미치는 영향을 측정합니다. 개발 지표(배포 빈도, 리드 타임, 변경 실패율, 복구 시간)와 AI 관련 지표(GitLab Duo 시트 도입률, Code Suggestions 수락률, GitLab Duo Chat 사용률)를 함께 추적합니다.
AI 지표용 GraphQL API	`AiMetrics`, `AiUserMetrics`, `AiUsageData` 엔드포인트를 통해 GitLab Duo 및 SDLC 트렌드 데이터에 프로그래밍 방식으로 접근할 수 있도록 제공합니다. BI 도구 및 맞춤형 분석과 연동할 수 있도록 사전 집계된 지표와 원시 이벤트 데이터 내보내기를 제공합니다.

지원되는 ClickHouse 버전#

지원되는 ClickHouse 버전은 사용 중인 GitLab 버전에 따라 다릅니다.

GitLab 17.7 이상은 ClickHouse 23.x를 지원합니다. ClickHouse 24.x 또는 25.x를 사용하려면 우회 방법을 사용합니다.
GitLab 18.1 이상은 ClickHouse 23.x, 24.x, 25.x를 지원합니다.
GitLab 18.8 이상은 ClickHouse 23.x, 24.x, 25.x와 Replicated 데이터베이스 엔진을 지원합니다.
- 이전 버전의 클러스터에는 추가 권한(dictGet)이 필요합니다. 스니펫을 참고합니다.
GitLab 19.0 이상은 ClickHouse 25.x와 26.6 까지의 26.x를 지원합니다. ClickHouse 23.x 및 24.x에 대한 지원은 제거되었습니다.
ClickHouse 26.7 이상은 지원되지 않습니다. 임시 우회 방법은 ClickHouse 26.7 이상을 참고합니다.

ClickHouse Cloud는 항상 최신 안정 버전 GitLab 릴리스와 호환됩니다.

Warning

일부 ClickHouse 버전은 GitLab 통합에 영향을 미치는 하위 호환성이 깨지는 변경 사항을 도입합니다.

ClickHouse 25.12는 ALTER MODIFY COLUMN에 하위 호환성이 깨지는 변경 사항을 도입했습니다. 이로 인해 18.8 이전 버전의 GitLab ClickHouse 통합에서 마이그레이션 프로세스가 중단됩니다. GitLab을 18.8 이상으로 업그레이드해야 합니다.
ClickHouse 26.7은 GitLab 이 아직 충족하지 못하는 AggregatingMergeTree 테이블에 대한 검증을 추가했으며, 이로 인해 마이그레이션이 Code: 36(BAD_ARGUMENTS) 오류와 함께 실패합니다. 임시 우회 방법은 ClickHouse 26.7 이상을 참고합니다.

ClickHouse 설정#

운영 요구 사항에 따라 배포 유형을 선택합니다.

ClickHouse Cloud(권장): 자동 업그레이드, 백업, 스케일링을 제공하는 완전 관리형 서비스입니다.
GitLab Self-Managed 용 ClickHouse(BYOC): 인프라와 구성을 완전히 직접 제어합니다.

ClickHouse 인스턴스를 설정한 후:

GitLab 데이터베이스와 사용자를 생성합니다.
GitLab 연결을 구성합니다.
연결을 확인합니다.
ClickHouse 마이그레이션을 실행합니다.
Analytics 용 ClickHouse를 활성화합니다.

ClickHouse Cloud 설정#

사전 요구 사항:

ClickHouse Cloud 계정을 보유하고 있어야 합니다.
GitLab 인스턴스에서 ClickHouse Cloud 로의 네트워크 연결을 활성화해야 합니다.
GitLab 인스턴스의 관리자여야 합니다.

ClickHouse Cloud를 설정하려면:

ClickHouse Cloud에 로그인합니다.
New Service를 선택합니다.
서비스 티어를 선택합니다.
- Development: 테스트 및 개발 환경용입니다.
- Production: 고가용성이 필요한 프로덕션 워크로드용입니다.
클라우드 제공업체와 리전을 선택합니다. 최적의 성능을 위해 GitLab 인스턴스와 가까운 리전을 선택합니다.
서비스 이름과 설정을 구성합니다.
Create Service를 선택합니다.
프로비저닝이 완료되면 서비스 대시보드에서 연결 정보를 기록해 둡니다.
- 호스트
- 포트(GitLab 이 사용하는 HTTPS 연결은 8443, clickhouse-client가 사용하는 TLS를 적용한 네이티브 TCP는 9440)
- 사용자 이름
- 비밀번호

Note

ClickHouse Cloud 서비스를 생성한 후에는 GitLab 데이터베이스와 사용자를 생성합니다.

GitLab Self-Managed 용 ClickHouse 설정(BYOC)#

사전 요구 사항:

ClickHouse 인스턴스가 설치되어 실행 중이어야 합니다. ClickHouse가 설치되어 있지 않다면 다음을 참고합니다.
- ClickHouse 공식 설치 가이드.
- GitLab Self-Managed를 위한 ClickHouse 권장 사항.
지원되는 ClickHouse 버전을 사용해야 합니다.
GitLab 인스턴스에서 ClickHouse 로의 네트워크 연결을 활성화해야 합니다.
ClickHouse와 GitLab 인스턴스 양쪽의 관리자여야 합니다.

Warning

고가용성 구성#

다중 노드 고가용성(HA) 구성을 위해 GitLab은 ClickHouse의 Replicated 테이블 엔진을 지원합니다.

사전 요구 사항:

여러 노드로 구성된 ClickHouse 클러스터가 있어야 합니다. 최소 3개 노드를 권장합니다.
remote_servers 구성 섹션에서 클러스터를 정의합니다.
ClickHouse 구성에서 다음 매크로를 설정합니다.
- cluster
- shard
- replica

HA를 위해 데이터베이스를 구성할 때는 반드시 ON CLUSTER 절과 함께 구문을 실행해야 합니다.

자세한 내용은 ClickHouse Replicated 데이터베이스 엔진 문서를 참고합니다.

로드 밸런서 구성#

권장 로드 밸런서 옵션:

chproxy - 캐싱과 라우팅이 내장된 ClickHouse 전용 HTTP 프록시입니다.
HAProxy - 범용 TCP/HTTP 로드 밸런서입니다.
NGINX - 로드 밸런싱 기능을 갖춘 웹 서버입니다.
클라우드 제공업체의 로드 밸런서(AWS Application Load Balancer, GCP Load Balancer, Azure Load Balancer)입니다.

기본 chproxy 구성 예시:

server:
  http:
    listen_addr: ":8080"

clusters:
  - name: "clickhouse_cluster"
    nodes: [
      "http://ch-node1:8123",
      "http://ch-node2:8123",
      "http://ch-node3:8123"
    ]

users:
  - name: "gitlab"
    password: "your_secure_password"
    to_cluster: "clickhouse_cluster"
    to_user: "gitlab"

로드 밸런서를 사용할 때는 GitLab 이 개별 ClickHouse 노드가 아니라 로드 밸런서 URL에 연결하도록 구성합니다.

자세한 내용은 chproxy 문서를 참고합니다.

GitLab Self-Managed 용 ClickHouse 인스턴스를 구성한 후에는 GitLab 데이터베이스와 사용자를 생성합니다.

ClickHouse 설치 확인#

데이터베이스를 구성하기 전에 ClickHouse가 설치되어 접근 가능한 상태인지 확인합니다.

ClickHouse가 실행 중인지 확인합니다.
```
clickhouse-client --query "SELECT version()"
```
ClickHouse가 실행 중이면 버전 번호(예: 24.3.1.12)가 표시됩니다.
자격 증명으로 연결할 수 있는지 확인합니다.
```
clickhouse-client --host your-clickhouse-host --port 9440 --secure --user default --password 'your-password'
```
[!note] 아직 TLS를 구성하지 않았다면, 초기 테스트용으로 --secure 플래그 없이 9000 포트를 사용합니다.

데이터베이스와 사용자 생성#

필요한 사용자와 데이터베이스 객체를 생성하려면:

안전한 비밀번호를 생성하고 저장해 둡니다.
다음 위치에 로그인합니다.
- ClickHouse Cloud의 경우 ClickHouse SQL 콘솔
- GitLab Self-Managed 용 ClickHouse의 경우 clickhouse-client
PASSWORD_HERE 부분을 생성한 비밀번호로 바꿔서 다음 명령을 실행합니다.

CREATE DATABASE gitlab_clickhouse_main_production;
CREATE USER gitlab IDENTIFIED WITH sha256_password BY 'PASSWORD_HERE';
CREATE ROLE gitlab_app;
GRANT SELECT, INSERT, ALTER, CREATE, UPDATE, DROP, TRUNCATE, OPTIMIZE, dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app;
GRANT SELECT ON information_schema.* TO gitlab_app;
GRANT gitlab_app TO gitlab;

CLUSTER_NAME_HERE 부분을 클러스터 이름으로 바꿉니다.

CREATE DATABASE gitlab_clickhouse_main_production ON CLUSTER CLUSTER_NAME_HERE ENGINE = Replicated('/clickhouse/databases/{cluster}/gitlab_clickhouse_main_production', '{shard}', '{replica}');
CREATE USER gitlab IDENTIFIED WITH sha256_password BY 'PASSWORD_HERE' ON CLUSTER CLUSTER_NAME_HERE;
CREATE ROLE gitlab_app ON CLUSTER CLUSTER_NAME_HERE;
GRANT SELECT, INSERT, ALTER, CREATE, UPDATE, DROP, TRUNCATE, OPTIMIZE, dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app ON CLUSTER CLUSTER_NAME_HERE;
GRANT SELECT ON information_schema.* TO gitlab_app ON CLUSTER CLUSTER_NAME_HERE;
GRANT gitlab_app TO gitlab ON CLUSTER CLUSTER_NAME_HERE;

GitLab 연결 구성#

GitLab에 ClickHouse 자격 증명을 제공하려면:

/etc/gitlab/gitlab.rb 파일을 편집합니다.
```
gitlab_rails['clickhouse_databases']['main']['database'] = 'gitlab_clickhouse_main_production'
gitlab_rails['clickhouse_databases']['main']['url'] = 'https://your-clickhouse-host:port'
gitlab_rails['clickhouse_databases']['main']['username'] = 'gitlab'
gitlab_rails['clickhouse_databases']['main']['password'] = 'PASSWORD_HERE' # replace with the actual password
```
URL을 다음과 같이 바꿉니다.
- ClickHouse Cloud의 경우: https://your-service.clickhouse.cloud:8443
- GitLab Self-Managed 용 ClickHouse의 경우: https://your-clickhouse-host:8443
- 로드 밸런서를 사용하는 GitLab Self-Managed 용 ClickHouse HA의 경우: https://your-load-balancer:8080(또는 사용 중인 로드 밸런서 URL)
파일을 저장하고 GitLab을 재구성합니다.
```
sudo gitlab-ctl reconfigure
```

ClickHouse 비밀번호를 Kubernetes Secret으로 저장합니다.

kubectl create secret generic gitlab-clickhouse-password --from-literal="main_password=PASSWORD_HERE"

Helm 값을 내보냅니다.

helm get values gitlab > gitlab_values.yaml

gitlab_values.yaml 파일을 편집합니다.
```
global:
  clickhouse:
    enabled: true
    main:
      username: gitlab
      password:
        secret: gitlab-clickhouse-password
        key: main_password
      database: gitlab_clickhouse_main_production
      url: 'https://your-clickhouse-host:port'
```
URL을 다음과 같이 바꿉니다.
- ClickHouse Cloud의 경우: https://your-service.clickhouse.cloud:8443
- GitLab Self-Managed 용 ClickHouse 단일 노드의 경우: https://your-clickhouse-host:8443
- 로드 밸런서를 사용하는 GitLab Self-Managed 용 ClickHouse HA의 경우: https://your-load-balancer:8080(또는 사용 중인 로드 밸런서 URL)

파일을 저장하고 새 값을 적용합니다.

helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab

Note

프로덕션 배포에서는 ClickHouse 인스턴스에 TLS/SSL을 구성하고 https:// URL을 사용합니다. GitLab Self-Managed 설치의 경우 네트워크 보안 문서를 참고합니다.

연결 확인#

연결이 정상적으로 설정되었는지 확인하려면:

Rails 콘솔에 로그인합니다.
다음 명령을 실행합니다.
```
ClickHouse::Client.select('SELECT 1', :main)
```
성공하면 명령이 [{"1"=>1}]를 반환합니다.

연결에 실패하면 다음을 확인합니다.

ClickHouse 서비스가 실행 중이고 접근 가능한지 확인합니다.
GitLab에서 ClickHouse 로의 네트워크 연결을 확인합니다. 방화벽과 보안 그룹이 연결을 허용하는지 점검합니다.
연결 URL(호스트, 포트, 프로토콜)이 올바른지 확인합니다.
자격 증명이 올바른지 확인합니다.
HA 클러스터 배포의 경우: 로드 밸런서가 올바르게 구성되어 요청을 라우팅하는지 확인합니다.

ClickHouse 마이그레이션 실행#

Note

이 단계는 필수입니다. 건너뛰면 Analytics 대시보드에 데이터가 표시되지 않고 "Failed to fetch data" 오류가 나타납니다.

필요한 데이터베이스 객체를 생성하려면 다음을 실행합니다.

sudo gitlab-rake gitlab:clickhouse:migrate

마이그레이션은 GitLab-Migrations 차트를 통해 자동으로 실행됩니다.

또는 Toolbox Pod에서 다음 명령을 실행해 마이그레이션을 수행할 수도 있습니다.

gitlab-rake gitlab:clickhouse:migrate

Analytics 용 ClickHouse 활성화#

GitLab 인스턴스가 ClickHouse에 연결되면 ClickHouse를 사용하는 기능을 활성화할 수 있습니다.

사전 요구 사항:

인스턴스에 대한 관리자 권한이 있어야 합니다.
ClickHouse 연결이 구성되고 확인되어 있어야 합니다.
마이그레이션이 성공적으로 완료되어 있어야 합니다.

Analytics 용 ClickHouse를 활성화하려면:

왼쪽 사이드바 하단에서 Admin을 선택합니다.
Settings > General을 선택합니다.
ClickHouse를 확장합니다.
Enable ClickHouse for Analytics를 선택합니다.
Save changes를 선택합니다.

Analytics 용 ClickHouse 비활성화#

Analytics 용 ClickHouse를 비활성화하려면:

사전 요구 사항:

인스턴스에 대한 관리자 권한이 있어야 합니다.

비활성화하려면:

왼쪽 사이드바 하단에서 Admin을 선택합니다.
Settings > General을 선택합니다.
ClickHouse를 확장합니다.
Enable ClickHouse for Analytics 확인란의 선택을 해제합니다.
Save changes를 선택합니다.

Note

ClickHouse 업그레이드#

ClickHouse Cloud#

ClickHouse Cloud는 버전 업그레이드와 보안 패치를 자동으로 처리하므로 수동 개입이 필요하지 않습니다.

업그레이드 일정과 점검 기간에 대한 정보는 ClickHouse Cloud 업그레이드를 참고합니다.

Note

ClickHouse Cloud는 예정된 업그레이드를 사전에 알려 줍니다. 새 기능과 변경 사항을 계속 확인하려면 ClickHouse Cloud 변경 이력을 검토합니다.

GitLab Self-Managed 용 ClickHouse(BYOC)#

GitLab Self-Managed 용 ClickHouse를 사용하는 경우, 버전 업그레이드의 계획과 실행은 직접 담당해야 합니다.

사전 요구 사항:

ClickHouse 인스턴스에 대한 관리자 권한이 있어야 합니다.
업그레이드 전 데이터를 백업해야 합니다. 재해 복구를 참고합니다.

업그레이드하기 전에:

ClickHouse 릴리스 노트를 검토해 호환성이 깨지는 변경 사항이 있는지 확인합니다.
사용 중인 GitLab 버전과의 호환성을 확인합니다.
프로덕션이 아닌 환경에서 업그레이드를 테스트합니다.
예상되는 다운타임을 계획하거나, HA 클러스터의 경우 롤링 업그레이드 전략을 사용합니다.

ClickHouse를 업그레이드하려면:

단일 노드 배포의 경우 ClickHouse 업그레이드 문서를 따릅니다.
HA 클러스터 배포의 경우 다운타임을 최소화하기 위해 롤링 업그레이드를 수행합니다.
- 한 번에 노드 하나씩 업그레이드합니다.
- 해당 노드가 클러스터에 다시 합류할 때까지 기다립니다.
- 다음 노드로 넘어가기 전에 클러스터 상태를 확인합니다.

Warning

자세한 업그레이드 절차는 업데이트에 대한 ClickHouse 문서를 참고합니다.

운영#

마이그레이션 상태 확인#

사전 요구 사항:

인스턴스에 대한 관리자 권한이 있어야 합니다.

ClickHouse 마이그레이션 상태를 확인하려면:

왼쪽 사이드바 하단에서 Admin을 선택합니다.
Settings > General을 선택합니다.
ClickHouse를 확장합니다.
사용 가능한 경우 Migration status 섹션을 확인합니다.

또는 Rails 콘솔을 사용해 대기 중인 마이그레이션을 확인할 수도 있습니다.

# Sign in to Rails console
# Run this to check migrations
ClickHouse::MigrationSupport::Migrator.new(:main).pending_migrations

실패한 마이그레이션 재시도#

ClickHouse 마이그레이션이 실패하면:

로그에서 오류 세부 정보를 확인합니다. ClickHouse 관련 오류는 GitLab 애플리케이션 로그에 기록됩니다.
근본 원인(예: 메모리 부족, 연결 문제)을 해결합니다.

마이그레이션을 다시 시도합니다.

# For installations that use the Linux package
sudo gitlab-rake gitlab:clickhouse:migrate

# For self-compiled installations
bundle exec rake gitlab:clickhouse:migrate RAILS_ENV=production

Note

ClickHouse Rake 작업#

GitLab은 ClickHouse 데이터베이스를 관리하기 위한 여러 Rake 작업을 제공합니다.

다음 Rake 작업을 사용할 수 있습니다.

작업	설명
`sudo gitlab-rake gitlab:clickhouse:migrate`	대기 중인 모든 ClickHouse 마이그레이션을 실행해 데이터베이스 스키마를 생성하거나 업데이트합니다.
`sudo gitlab-rake gitlab:clickhouse:drop`	모든 ClickHouse 데이터베이스를 삭제합니다. 모든 데이터가 삭제되므로 각별히 주의해서 사용합니다.
`sudo gitlab-rake gitlab:clickhouse:create`	ClickHouse 데이터베이스가 존재하지 않으면 생성합니다.
`sudo gitlab-rake gitlab:clickhouse:setup`	데이터베이스를 생성하고 모든 마이그레이션을 실행합니다. `create` 작업과 `migrate` 작업을 함께 실행하는 것과 동일합니다.
`sudo gitlab-rake gitlab:clickhouse:schema:dump`	현재 데이터베이스 스키마를 백업이나 버전 관리를 위해 파일로 덤프합니다.
`sudo gitlab-rake gitlab:clickhouse:schema:load`	덤프 파일에서 데이터베이스 스키마를 불러옵니다.

Note

셀프 컴파일 설치의 경우 sudo gitlab-rake 대신 bundle exec rake를 사용하고, 명령 끝에 RAILS_ENV=production을 추가합니다.

일반적인 작업 예시#

ClickHouse 연결과 스키마 확인#

ClickHouse 연결이 정상 작동하는지 확인하려면:

# For installations that use the Linux package
sudo gitlab-rake gitlab:clickhouse:info

# For self-compiled installations
bundle exec rake gitlab:clickhouse:info RAILS_ENV=production

이 작업은 ClickHouse 연결과 구성에 대한 디버깅 정보를 출력합니다.

모든 마이그레이션 재실행#

대기 중인 모든 마이그레이션을 실행하려면:

# For installations that use the Linux package
sudo gitlab-rake gitlab:clickhouse:migrate

# For self-compiled installations
bundle exec rake gitlab:clickhouse:migrate RAILS_ENV=production

데이터베이스 초기화#

Warning

이 작업은 ClickHouse 데이터베이스의 모든 데이터를 삭제합니다. 개발 환경이나 문제 해결 시에만 사용합니다.

데이터베이스를 삭제하고 다시 생성하려면:

# For installations that use the Linux package
sudo gitlab-rake gitlab:clickhouse:drop
sudo gitlab-rake gitlab:clickhouse:setup

# For self-compiled installations
bundle exec rake gitlab:clickhouse:drop RAILS_ENV=production
bundle exec rake gitlab:clickhouse:setup RAILS_ENV=production

환경 변수#

환경 변수를 사용해 Rake 작업의 동작을 제어할 수 있습니다.

환경 변수	데이터 유형	설명
`VERBOSE`	Boolean	마이그레이션 중 상세 출력을 보려면 `true`로 설정합니다. 예: `VERBOSE=true sudo gitlab-rake gitlab:clickhouse:migrate`

성능 튜닝#

Note

사용자 수에 따른 리소스 크기 산정과 배포 권장 사항은 시스템 요구 사항을 참고합니다.

ClickHouse 아키텍처와 성능 튜닝에 대한 정보는 아키텍처에 대한 ClickHouse 문서를 참고합니다.

재해 복구#

백업과 복원#

GitLab 애플리케이션을 업그레이드하기 전에 전체 백업을 수행해야 합니다. ClickHouse 데이터는 GitLab 백업 도구에 포함되지 않습니다.

백업 및 복원 전략은 선택한 배포 방식에 따라 달라집니다.

ClickHouse Cloud#

ClickHouse Cloud는 다음을 자동으로 수행합니다.

백업과 복원을 관리합니다.
매일 백업을 생성하고 보관합니다.

별도의 추가 구성은 필요하지 않습니다.

자세한 내용은 ClickHouse Cloud 백업을 참고합니다.

GitLab Self-Managed 용 ClickHouse#

직접 ClickHouse 인스턴스를 관리하는 경우, 데이터 안전을 위해 정기적으로 백업을 수행해야 합니다.

초기 전체 백업(예: metrics, logs 같은 시스템 테이블 제외)을 오브젝트 스토리지 버킷(예: AWS S3)에 수행합니다.
이 초기 전체 백업 이후에는 증분 백업을 수행합니다.

이 방식은 전체 백업마다 데이터가 중복되지만, 데이터를 복원하는 가장 쉬운 방법입니다.

또는 clickhouse-backup을 사용할 수도 있습니다. 이는 예약 실행, 원격 스토리지 관리 등 추가 기능과 함께 유사한 기능을 제공하는 서드파티 도구입니다.

모니터링#

GitLab 통합의 안정성을 보장하려면 ClickHouse 클러스터의 상태와 성능을 모니터링해야 합니다.

ClickHouse Cloud#

ClickHouse Cloud는 보안 API 엔드포인트를 통해 지표를 노출하는 네이티브 Prometheus 통합을 제공합니다.

API 자격 증명을 생성한 후에는 ClickHouse Cloud에서 지표를 수집하도록 컬렉터를 구성할 수 있습니다. 예를 들어 Prometheus 배포가 있습니다.

GitLab Self-Managed 용 ClickHouse#

ClickHouse는 Prometheus 형식 지표를 노출할 수 있습니다. 이를 활성화하려면:

config.xml의 prometheus 섹션을 구성해 전용 포트(기본값 9363)로 지표를 노출합니다.

<prometheus>
    <endpoint>/metrics</endpoint>
    <port>9363</port>
    <metrics>true</metrics>
    <events>true</events>
    <asynchronous_metrics>true</asynchronous_metrics>
</prometheus>

http://<clickhouse-host>:9363/metrics를 수집하도록 Prometheus 또는 이와 호환되는 서버를 구성합니다.

모니터링할 지표#

GitLab 기능에 영향을 줄 수 있는 문제를 감지하려면 다음 지표에 대한 알림을 설정해야 합니다.

지표 이름	설명	알림 임계값(권장)
`ClickHouse_Metrics_Query`	현재 실행 중인 쿼리 수입니다. 갑자기 급증하면 성능 병목을 나타낼 수 있습니다.	기준선 편차(예: `> 100`)
`ClickHouseProfileEvents_FailedSelectQuery`	실패한 select 쿼리 수입니다.	기준선 편차(예: `> 50`)
`ClickHouseProfileEvents_FailedInsertQuery`	실패한 insert 쿼리 수입니다.	기준선 편차(예: `> 10`)
`ClickHouse_AsyncMetrics_ReadonlyReplica`	레플리카가 읽기 전용 모드로 전환되었는지 나타냅니다(주로 ZooKeeper 연결 끊김으로 발생).	`> 0`(즉시 조치 필요)
`ClickHouse_ProfileEvents_NetworkErrors`	네트워크 오류(연결 재설정/타임아웃)입니다. 빈번하게 발생하면 GitLab 백그라운드 작업이 실패할 수 있습니다.	비율 `> 0`

생존 확인(Liveness check)#

보안과 감사#

데이터 보안을 보장하고 감사 가능성을 확보하려면 다음 보안 사례를 적용합니다.

네트워크 보안#

TLS 암호화: ClickHouse 서버가 연결을 검증하도록 TLS 암호화를 사용하게 구성합니다.

GitLab에서 연결 URL을 구성할 때는 이를 지정하기 위해 https:// 프로토콜(예: https://clickhouse.example.com:8443)을 사용해야 합니다.
IP 허용 목록: ClickHouse 포트(기본값 8443 또는 9440)에 대한 접근을 GitLab 애플리케이션 노드와 승인된 다른 네트워크로만 제한합니다.

감사 로깅#

ClickHouse Cloud#

ClickHouse Cloud에서는 쿼리 로깅이 기본적으로 활성화되어 있습니다. system.query_log 테이블을 쿼리해 이 로그에 접근할 수 있습니다.

GitLab Self-Managed 용 ClickHouse#

셀프 매니지드 인스턴스에서는 서버 구성에서 query_log 구성 파라미터가 활성화되어 있는지 확인합니다.

config.xml 또는 users.xml에 query_log 섹션이 있는지 확인합니다.

<query_log>
    <database>system</database>
    <table>query_log</table>
    <partition_by>toYYYYMM(event_date)</partition_by>
    <flush_interval_milliseconds>7500</flush_interval_milliseconds>
    <ttl>event_date + INTERVAL 30 DAY</ttl>  <!-- Keep only 30 days -->
</query_log>

활성화하면 실행된 모든 쿼리가 system.query_log 테이블에 기록되어 감사 추적이 가능해집니다.

쿼리를 사용자에게 귀속시키기#

user_id: 요청을 발생시킨 사용자의 숫자 ID입니다.
root_namespace_id: 루트 네임스페이스의 숫자 ID입니다.
organization_id: 요청이 속한 조직의 숫자 ID입니다.
correlation_id: 다른 GitLab 로그에서도 사용되는 요청 상관관계 ID입니다.
application: web, sidekiq, console, test 중 하나입니다.
feature_category: 요청의 기능 카테고리입니다.

예를 들어, 쿼리와 이를 발생시킨 사용자의 감사 추적을 구성하려면 다음과 같이 합니다.

SELECT JSONExtractInt(log_comment, 'user_id') AS user_id,
       JSONExtractString(log_comment, 'correlation_id') AS correlation_id,
       query,
       event_time
FROM system.query_log
WHERE type = 'QueryFinish' AND log_comment != ''
ORDER BY event_time DESC
LIMIT 20

시스템 요구 사항#

권장 시스템 요구 사항은 사용자 수에 따라 달라집니다.

배포 결정 매트릭스 빠른 참조#

사용자 수	기본 권장 사항	대응 AWS ARM 인스턴스	대응 GCP ARM 인스턴스	대응 Azure ARM 인스턴스	배포 유형
1K	ClickHouse Cloud Basic	-	-	-	관리형
2K	ClickHouse Cloud Basic	`m8g.xlarge`	`c4a-standard-4`	`Standard_D4ps_v6`	관리형 또는 단일 노드
3K	ClickHouse Cloud Scale	`m8g.2xlarge`	`c4a-standard-8`	`Standard_D8ps_v6`	관리형 또는 단일 노드
5K	ClickHouse Cloud Scale	`m8g.4xlarge`	`c4a-standard-16`	`Standard_D16ps_v6`	관리형 또는 단일 노드
10K	ClickHouse Cloud Scale	`m8g.4xlarge`	`c4a-standard-16`	`Standard_D16ps_v6`	관리형 또는 단일 노드/HA
25K	GitLab Self-Managed 용 ClickHouse 또는 ClickHouse Cloud Scale	`m8g.8xlarge` 또는 3×`m8g.4xlarge`	`c4a-standard-32` 또는 3×`c4a-standard-16`	`Standard_D32ps_v6` 또는 3x`Standard_D16ps_v6`	관리형 또는 단일 노드/HA
50K	GitLab Self-Managed 용 ClickHouse 고가용성(HA) 또는 ClickHouse Cloud Scale	3×`m8g.4xlarge`	3×`c4a-standard-16`	3x`Standard_D16ps_v6`	관리형 또는 HA 클러스터

사용자 1천 명#

권장: 운영 복잡도 없이 비용 효율이 좋은 ClickHouse Cloud Basic을 사용합니다.

사용자 2천 명#

권장: 운영 복잡도 없이 최상의 가치를 제공하는 ClickHouse Cloud Basic을 사용합니다.

GitLab Self-Managed 용 ClickHouse 배포에 대한 대체 권장 사항:

AWS: m8g.xlarge(vCPU 4개, 16GB)
GCP: c4a-standard-4 또는 n4-standard-4(vCPU 4개, 16GB)
Azure: Standard_D4ps_v6(vCPU 4개, 16GB)
스토리지: 저~중 성능 티어로 20GB

사용자 3천 명#

권장: ClickHouse Cloud Scale

GitLab Self-Managed 용 ClickHouse 배포에 대한 대체 권장 사항:

AWS: m8g.2xlarge(vCPU 8개, 32GB)
GCP: c4a-standard-8 또는 n4-standard-8(vCPU 8개, 32GB)
Azure: Standard_D8ps_v6(vCPU 8개, 32GB)
스토리지: 중간 성능 티어로 100GB

Note

이 규모에서는 HA 배포가 비용 효율적이지 않습니다.

사용자 5천 명#

권장: ClickHouse Cloud Scale

GitLab Self-Managed 용 ClickHouse 배포에 대한 대체 권장 사항:

AWS: m8g.4xlarge(vCPU 16개, 64GB)
GCP: c4a-standard-16 또는 n4-standard-16(vCPU 16개, 64GB)
Azure: Standard_D16ps_v6(vCPU 16개, 64GB)
스토리지: 고성능 티어로 100GB
배포: 단일 노드 권장

사용자 1만 명#

권장: ClickHouse Cloud Scale

GitLab Self-Managed 용 ClickHouse 배포에 대한 대체 권장 사항:

AWS: m8g.4xlarge(vCPU 16개, 64GB)
GCP: c4a-standard-16 또는 n4-standard-16(vCPU 16개, 64GB)
Azure: Standard_D16ps_v6(vCPU 16개, 64GB)
스토리지: 고성능 티어로 200GB
HA 옵션: 중요 워크로드에는 3노드 클러스터가 실행 가능한 선택지가 됩니다

사용자 2만 5천 명#

권장: ClickHouse Cloud Scale 또는 GitLab Self-Managed 용 ClickHouse. 이 규모에서는 두 옵션 모두 경제적으로 타당합니다.

GitLab Self-Managed 용 ClickHouse 배포에 대한 권장 사항:

단일 노드:
- AWS: m8g.8xlarge(vCPU 32개, 128GB)
- GCP: c4a-standard-32 또는 n4-standard-32(vCPU 32개, 128GB)
- Azure: Standard_D32ps_v6(vCPU 32개, 128GB)
HA 배포:
- AWS: m8g.4xlarge × 3(각 vCPU 16개, 64GB)
- GCP: c4a-standard-16 × 3 또는 n4-standard-16 × 3(각 vCPU 16개, 64GB)
- Azure: Standard_D16ps_v6 × 3(각 vCPU 16개, 64GB)
스토리지: 노드당 고성능 티어로 400GB

사용자 5만 명#

권장: GitLab Self-Managed 용 ClickHouse HA 또는 ClickHouse Cloud Scale. 이 규모에서는 셀프 매니지드 옵션이 비용 면에서 약간 더 효율적입니다.

GitLab Self-Managed 용 ClickHouse 배포에 대한 권장 사항:

단일 노드:
- AWS: m8g.8xlarge(vCPU 32개, 128GB)
- GCP: c4a-standard-32 또는 n4-standard-32(vCPU 32개, 128GB)
- Azure: Standard_D32ps_v6(vCPU 32개, 128GB)
HA 배포(권장):
- AWS: m8g.4xlarge × 3(각 vCPU 16개, 64GB)
- GCP: c4a-standard-16 × 3 또는 n4-standard-16 × 3(각 vCPU 16개, 64GB)
- Azure: Standard_D16ps_v6 × 3(각 vCPU 16개, 64GB)
스토리지: 노드당 고성능 티어로 1000GB

GitLab Self-Managed 용 ClickHouse 배포의 HA 고려 사항#

HA 구성은 사용자 1만 명 이상에서만 비용 효율적입니다.

최소 구성: 쿼럼을 위한 ClickHouse 노드 3개.
ClickHouse Keeper: 코디네이션용 노드 3개(같은 위치에 배치하거나 분리 가능).
로드 밸런서: 쿼리 분산을 위해 권장됩니다.
네트워크: 노드 간 저지연 연결이 매우 중요합니다.

용어집#

클러스터(Cluster): 데이터를 저장하고 처리하기 위해 함께 동작하는 노드(서버) 집합입니다.
MergeTree: MergeTree는 높은 데이터 수집 속도와 대용량 데이터를 처리하도록 설계된 ClickHouse의 테이블 엔진입니다. 칼럼 기반 저장, 맞춤형 파티셔닝, 희소 기본 인덱스, 백그라운드 데이터 병합 지원 등의 기능을 제공하는 ClickHouse의 핵심 저장 엔진입니다.
파트(Parts): 테이블 데이터의 일부를 저장하는, 디스크상의 물리적 파일입니다. 파트는 파티션 키를 사용해 생성되는 테이블 데이터의 논리적 구분 단위인 파티션과는 다릅니다.
레플리카(Replica): ClickHouse 데이터베이스에 저장된 데이터의 사본입니다. 중복성과 신뢰성을 위해 동일한 데이터의 레플리카를 원하는 수만큼 둘 수 있습니다. 레플리카는 ReplicatedMergeTree 테이블 엔진과 함께 사용되며, 이를 통해 ClickHouse가 여러 서버에 걸쳐 데이터 사본을 동기화된 상태로 유지할 수 있습니다.
샤드(Shard): 데이터의 부분 집합입니다. ClickHouse는 항상 데이터에 대해 최소 하나의 샤드를 가집니다. 데이터를 여러 서버에 분할하지 않으면 데이터는 하나의 샤드에 저장됩니다. 단일 서버의 용량을 초과하는 경우, 데이터를 여러 서버에 샤딩해 부하를 분산할 수 있습니다.
TTL(Time To Live): TTL은 일정 기간이 지나면 칼럼/행을 자동으로 이동, 삭제, 롤업하는 ClickHouse 기능입니다. 더 이상 자주 접근할 필요가 없는 데이터를 삭제, 이동, 보관할 수 있어 스토리지를 더 효율적으로 관리할 수 있습니다.

문제 해결#

GitLab 18.0.0 이하에서의 데이터베이스 스키마 마이그레이션#

Warning

Code: 344. DB::Exception: Projection is fully supported in ReplacingMergeTree with deduplicate_merge_projection_mode = throw. Use 'drop' or 'rebuild' option of deduplicate_merge_projection_mode

모든 마이그레이션을 실행하지 않으면 ClickHouse 통합이 동작하지 않습니다.

이 문제를 우회해 마이그레이션을 실행하려면:

Rails 콘솔에 로그인합니다.

다음 명령을 실행합니다.

ClickHouse::Client.execute("INSERT INTO schema_migrations (version) VALUES ('20231114142100'), ('20240115162101')", :main)

데이터베이스를 다시 마이그레이션합니다.
```
sudo gitlab-rake gitlab:clickhouse:migrate
```

이번에는 데이터베이스 마이그레이션이 성공적으로 완료됩니다.

데이터베이스 딕셔너리 읽기 지원#

다음 위치에 로그인합니다.
- ClickHouse Cloud의 경우 ClickHouse SQL 콘솔
- GitLab Self-Managed 용 ClickHouse의 경우 clickhouse-client
PASSWORD_HERE 부분을 생성한 비밀번호로 바꿔서 다음 명령을 실행합니다.

GRANT dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app;

CLUSTER_NAME_HERE 부분을 클러스터 이름으로 바꿉니다.

GRANT dictGet ON gitlab_clickhouse_main_production.* TO gitlab_app ON CLUSTER CLUSTER_NAME_HERE;

권한을 부여하지 않으면 ClickHouse 마이그레이션(CreateNamespaceTraversalPathsDict)이 다음 오류와 함께 실패합니다.

DB::Exception: gitlab: Not enough privileges.

권한을 부여한 후에는 마이그레이션을 안전하게 재시도할 수 있습니다(이상적으로는 분산 마이그레이션 잠금이 해제될 때까지 1~2시간 기다립니다).

ClickHouse CI 작업 데이터 구체화 뷰의 데이터 불일치#

이 문제는 GitLab 18.9에서 수정되었으며 18.6, 18.7, 18.8에 백포트되었습니다. 이 문제를 해결하려면 GitLab 18.6 이상으로 업그레이드합니다.

ClickHouse 26.7 이상#

Code: 36. DB::Exception: Column(s) purchase_id, add_on_name of the AggregatingMergeTree table are neither part of the sorting key nor aggregate measures (AggregateFunction or SimpleAggregateFunction). ... (BAD_ARGUMENTS)

기존 설치에는 영향이 없습니다. 새로 설치하거나, 새 레플리카를 추가하거나, 처음부터 구성한 환경에서는 실패합니다.

ClickHouse 26.6 이하를 사용합니다. 26.7 이상을 반드시 실행해야 한다면 /etc/clickhouse-server/users.d/compatibility.xml에서 compatibility를 26.6으로 설정합니다.

<clickhouse>
    <profiles>
        <default>
            <compatibility>26.6</compatibility>
        </default>
    </profiles>
</clickhouse>

Warning