ClickHouseインテグレーションガイドライン

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated
ステータス: ベータ版（Beta）は、GitLab Self-ManagedとGitLab Dedicatedで利用可能です

このエピックで、GitLab Self-ManagedのClickHouseサポートに関する計画の詳細をご覧ください。

GitLab DedicatedのClickHouseサポートに関する詳細は、GitLab DedicatedのClickHouseを参照してください。

ClickHouseは、オープンソースのカラム型データベース管理システムです。大規模なデータセット全体で、効率的にフィルタリング、集計、クエリを実行できます。

ClickHouseは、GitLabのセカンダリデータストアです。特定のデータのみがClickHouseに保存され、GitLab DuoとSDLCトレンドやCI分析などの高度な分析機能に使用されます。

ClickHouseをGitLabに接続する方法は2つあります:

推奨。ClickHouse Cloudを使用する。
独自のClickHouseを持ち込む。詳細については、GitLab Self-Managedに関するClickHouseの推奨事項を参照してください。

サポートされているClickHouseバージョン

最初のGitLabバージョン	ClickHouseバージョン	コメント
17.7.0	23.x（24.x、25.x）	ClickHouse 24.xおよび25.xを使用するには、回避策セクションを参照してください。
18.1.0	23.x、24.x、25.x
18.5.0	23.x、24.x、25.x	`Replicated`データベースエンジンに対する試験的なサポート。

ClickHouse Cloudがサポートされています。互換性は通常、最新の主要なGitLabリリースおよび新しいバージョンで保証されています。

ClickHouseの設定

ClickHouseをGitLabと組み合わせて設定するには、次の手順を実行します:

ClickHouseを実行および構成する

ホストされているサーバーでClickHouseを実行すると、インスタンスで毎月実行されるビルドの数、選択したハードウェア、ClickHouseをホストするデータセンターの選択など、さまざまなデータポイントがリソース消費に影響を与える可能性があります。いずれにせよ、コストはそれほど大きくならないはずです。

必要なユーザーとデータベースオブジェクトを作成するには:

安全なパスワードを生成して保存します。
ClickHouse SQLコンソールにサインインします。

次のコマンドを実行します。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 ON gitlab_clickhouse_main_production.* TO gitlab_app;
GRANT SELECT ON information_schema.* TO gitlab_app;
GRANT gitlab_app TO gitlab;

ClickHouseへのGitLab接続を構成する

ClickHouse認証情報をGitLabに提供するには:

/etc/gitlab/gitlab.rbを編集します:

gitlab_rails['clickhouse_databases']['main']['database'] = 'gitlab_clickhouse_main_production'
gitlab_rails['clickhouse_databases']['main']['url'] = 'https://example.com/path'
gitlab_rails['clickhouse_databases']['main']['username'] = 'gitlab'
gitlab_rails['clickhouse_databases']['main']['password'] = 'PASSWORD_HERE' # replace with the actual password

ファイルを保存して、GitLabを再設定します:
```
sudo gitlab-ctl reconfigure
```

ClickHouseのパスワードをKubernetesシークレットとして保存します:

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: default
      password:
        secret: gitlab-clickhouse-password
        key: main_password
      database: gitlab_clickhouse_main_production
      url: 'http://example.com'

ファイルを保存して、新しい値を適用します:
```
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
```

接続が正常に設定されたことを確認するには:

Railsコンソールにサインインします
次のコマンドを実行します:
```
ClickHouse::Client.select('SELECT 1', :main)
```
成功した場合、コマンドは[{"1"=>1}]を返します

ClickHouse移行の実行

必要なデータベースオブジェクトを作成するには、次を実行します:

sudo gitlab-rake gitlab:clickhouse:migrate

移行は、GitLab-移行チャートを使用して自動的に実行されます。

または、Toolboxポッドで次のコマンドを実行して、移行を実行することもできます:

gitlab-rake gitlab:clickhouse:migrate

分析にClickHouseを有効にする

GitLabインスタンスがClickHouseに接続されたので、ClickHouseを分析用に有効にすることで、ClickHouseを使用する機能を有効にできます。

`Replicated`データベースエンジン

マルチノード、高可用性設定の場合、GitLabはClickHouseのReplicatedテーブルエンジンをサポートします。

前提要件:

クラスターは、remote_servers構成セクションで定義する必要があります。
次のマクロを構成する必要があります:
- cluster
- shard
- replica

データベースを構成する際は、ON CLUSTER句でステートメントを実行する必要があります。次の例では、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 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アプリケーションは、HTTP/HTTPSインターフェースを介してClickHouseクラスターと通信します。chproxyなど、ClickHouseクラスターへのリクエストのロードバランシングにHTTPプロキシを使用することを検討してください。

トラブルシューティング

GitLab 18.0.0以前のデータベーススキーマ移行

GitLab 18.0.0以前では、ClickHouseのデータベーススキーマ移行を実行すると、次のエラーメッセージが表示されて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
```

今回は、データベースの移行が正常に完了するはずです。