データレプリケーションのセットアップ

GitLab OrbitはClickHouse内のGitLabデータベースのコピーからGitLabデータを読み取ります。GitLabデータベース自体からは読み取りません。Siphonがそのコピーを最新の状態に保ちます。

SiphonはKubernetes上で3つのデプロイとして動作します。

前提条件:

• GitLab Self-Managed上のGitLab Orbitの前提条件。
• GitLab向けにセットアップされたClickHouseインスタンス（GitLab ClickHouseマイグレーション適用済み）。詳細については、ClickHouseを参照してください。
• GitLab PostgreSQLサーバーへのスーパーユーザーアクセス。
• PostgreSQLの再起動1回分のメンテナンスウィンドウ。
• Helm 3およびクラスターへのkubectlアクセス。

次の順序でレプリケーションをセットアップします。

1. PostgreSQLで論理レプリケーションを有効にする。
2. SiphonのPostgreSQLユーザーを作成する。
3. パブリケーションと権限を作成する。
4. SiphonのClickHouseユーザーを作成する。
5. パスワードをSiphonで利用可能にする。
6. Siphonをインストールする。

PostgreSQLで論理レプリケーションを有効にする

wal_levelがlogicalでない場合、Siphon producerは起動時に停止します。wal_level、max_replication_slots、max_wal_sendersへの変更はすべて、リロードではなくPostgreSQLの完全な再起動が必要です。また、gitlab-ctl reconfigureはPostgreSQLを再起動しません。

SiphonのPostgreSQLユーザーを作成する

Siphonは3つのロールを使用します。スーパーユーザーとして作成してください。ロールがREPLICATIONを付与できるのは、そのロール自身がすでにREPLICATION属性を持っている場合のみです。GitLabアプリケーションロールはこの属性を持っていません。

スーパーユーザーとしてgitlabhq_productionに接続し、次を実行します。

CREATE USER siphon WITH PASSWORD '<your_password>'
  NOSUPERUSER NOCREATEDB NOCREATEROLE NOINHERIT;
CREATE USER siphon_replicator WITH REPLICATION LOGIN PASSWORD '<your_password>'
  NOSUPERUSER NOCREATEDB NOCREATEROLE NOINHERIT;
CREATE USER siphon_snapshot WITH PASSWORD '<your_password>'
  NOSUPERUSER NOCREATEDB NOCREATEROLE NOINHERIT;

3つのロールは同じパスワードを使用できます。

この手順のvaluesファイルでは、Siphonはすべての接続にsiphon_replicatorとして接続します。他の2つのロールが存在するのは、次のステップのRakeタスクがそれらに読み取りアクセスも付与するためです。スプリットユーザーセットアップでは、後でこれらを使用できます。

パブリケーションと権限を作成する

GitLabにはSiphon向けにPostgreSQLを準備するRakeタスクが同梱されています。このタスクは冪等であり、次を作成します。

• パブリケーション。
• Siphonがパブリケーションにテーブルを追加するために呼び出すヘルパー関数。
• すべてのGitLabスキーマへの読み取りアクセス。

GitLab 19.2.2以降にはこのタスクが含まれています。

このタスクはsiphon_publication_main_1という名前のパブリケーションを作成し、siphonロールにpublic.siphon_alter_publicationへのEXECUTE権限を付与します。producerはsiphon_replicator接続でこの関数を呼び出すため、siphon_replicatorにも同じEXECUTE権限を付与してください。スーパーユーザーとして次を実行します。

GRANT EXECUTE ON FUNCTION public.siphon_alter_publication(text, text, integer)
  TO siphon_replicator;

パブリケーションはproducerが起動するまで空です。その後、Siphonは同じ関数を通じてパブリケーションにテーブルを追加します。

SiphonのClickHouseユーザーを作成する

SiphonはGitLabがすでに使用しているデータベースに書き込みます。GitLab ClickHouseマイグレーションがターゲットテーブルを作成するため、Siphonにはスキーマ権限は不要です。

管理者としてClickHouseに接続し、次を実行します。

CREATE USER siphon IDENTIFIED WITH sha256_password BY '<your_password>';
CREATE ROLE siphon_app;
GRANT SELECT, INSERT, dictGet ON gitlab_clickhouse_main_production.* TO siphon_app;
GRANT siphon_app TO siphon;

dictGet権限は必須です。これがないと、プローブはメトリクスエンドポイントをスクレイピングするだけなので、ポッドはヘルスチェックを通過します。障害はconsumerログにパーミッションエラーとして現れます。ディクショナリに基づくすべてのテーブルは空のままになります。

systemデータベースを制限するマネージドClickHouseの場合は、次も実行します。

GRANT SELECT ON system.tables, system.columns TO siphon_app;

パスワードをSiphonで利用可能にする

SiphonはKubernetes Secretに基づく環境変数から両方のパスワードを読み取ります。Secretを作成する前にネームスペースが存在している必要があります。次のセクションのvaluesファイルは、Siphonネームスペース内にsiphon-secretsという名前のSecretが1つあり、次のキーを持つことを想定しています。

すでに運用しているシークレットマネージャーに値を保管することをお勧めします。External Secrets Operatorなどのツールを使用してクラスターに同期してください。平文を他の場所に保存しないでください。

Siphonをインストールする

configMode: splitを使用すると、SiphonはGitLabに同梱されているイメージからポッド起動時にテーブルリストを構築します。リストはGitLabのバージョンと一致し、手動での更新は不要です。

global.gitlabVersionはgitlab-siphon-tablesイメージのタグであり、レプリケートされるテーブルセットをGitLabのバージョンに固定します。タグはv19.2.0-eeから始まります。タグが存在しないとポッドが起動できなくなるため、インストール前にコンテナレジストリでタグが存在することを確認してください。

1. 次の内容をsiphon-values.yamlとして保存し、プレースホルダーを置き換えます。

   configMode: split
   
   global:
     # Tag of the gitlab-siphon-tables image.
     # Must match your GitLab version exactly, patch level included.
     gitlabVersion: v19.2.2-ee
   
   image:
     repository: registry.gitlab.com/gitlab-org/analytics-section/siphon
     tag: 0.0.124-beta
   
   siphonConnectionConfigMap:
     create: true
     data:
       prometheus:
         port: 8080
       connection:
         queueing:
           driver: nats
           url: nats://nats.nats.svc.cluster.local:4222
           stream_name: siphon_stream_main_db
           nats_config:
             replicas: 1
             max_age_seconds: 1296000
         clickhouse:
           host: <clickhouse_host>
           # Native protocol, not the HTTP port GitLab uses.
           port: 9000
           ssl: false
           username: siphon
           password: "${CLICKHOUSE_SIPHON_PASSWORD}"
           database: gitlab_clickhouse_main_production
         databases:
           main:
             host: <postgresql_host>
             port: 5432
             database: gitlabhq_production
             user: siphon_replicator
             password: "${SIPHON_DB_PASSWORD}"
             ssl_mode: require
             advisory_lock_id: 1
             application_name: siphon_main_1
             advisory_lock_timeout_ms: 100
             advisory_lock_timeout_fuzziness_ms: 50
             lock_timeout_ms: 500
             lock_timeout_fuzziness_ms: 300
       overrides:
         siphon_main_1:
           database_ref: main
   
   siphonLayoutConfigMap:
     create: true
     data:
       stream_name: siphon_stream_main_db
       refresh_mode: inline
       partitions_monitoring_interval_in_seconds: 3600
       max_column_size_in_bytes: 10485760
       producers:
         main:
           - siphon_main_1
       consumers:
         - siphon_consumer_1
       reconcilers:
         - siphon_reconciler_1
       # Point the producer at the publication the Rake task created. Without this
       # override, the producer derives the name from the application identifier
       # and tries to create its own.
       replication_overrides:
         siphon_main_1:
           publication_name: siphon_publication_main_1
       # GitLab splits its schema three ways even on one database. Map ci and sec onto main.
       database_mapping:
         ci: main
         sec: main
   
   deployments:
     postgres-producer:
       configMode: split
       split:
         role: producer
       envFromSecrets:
         - {name: SIPHON_DB_PASSWORD, secretName: siphon-secrets, secretKey: pg-password}
         - {name: CLICKHOUSE_SIPHON_PASSWORD, secretName: siphon-secrets, secretKey: ch-siphon-password}
     clickhouse-consumer:
       configMode: split
       split:
         role: consumer
       envFromSecrets:
         - {name: SIPHON_DB_PASSWORD, secretName: siphon-secrets, secretKey: pg-password}
         - {name: CLICKHOUSE_SIPHON_PASSWORD, secretName: siphon-secrets, secretKey: ch-siphon-password}
     reconciler:
       configMode: split
       split:
         role: reconciler
       envFromSecrets:
         - {name: SIPHON_DB_PASSWORD, secretName: siphon-secrets, secretKey: pg-password}
         - {name: CLICKHOUSE_SIPHON_PASSWORD, secretName: siphon-secrets, secretKey: ch-siphon-password}

2. チャートをインストールします。

   helm repo add siphon https://gitlab.com/api/v4/projects/76780115/packages/helm/stable
   helm repo update
   
   helm upgrade --install siphon siphon/siphon \
     --version 1.18.0 \
     --namespace siphon \
     --create-namespace \
     --values siphon-values.yaml

   これらのコマンドは直接Helmインストールのリファレンスです。ネームスペース名とデプロイ方法は独自のツールに合わせて調整してください。

3. 3つのデプロイがすべて実行中であることを確認します。

   kubectl -n siphon get pods

出力には、Running状態のpostgres-producer、clickhouse-consumer、reconcilerポッドが一覧表示されます。

Siphonはvaluesファイルを変更してもポッドを再起動しません。変更を適用するには、デプロイを再起動します。

kubectl -n siphon rollout restart deployment

Valuesファイルの設定

大きな行のオブジェクトストレージ

ストリームに収まらない大きな行はオブジェクトストアに送られます。前述のvaluesファイルはオブジェクトストアを設定していないため、SiphonはNATS JetStreamオブジェクトストアを使用し、認証情報は不要です。

外部バケットを使用するには、queueingの下にidentifier、type、bucket_nameを含むobject_storage_configを追加し、すべてのSiphonポッドにバケットの認証情報を付与します。type: s3の場合、SiphonはAWS SDKの標準チェーンに従うため、AWS_REGIONを設定し、インスタンスロールをアタッチするか、envとenvFromSecretsを通じてAWS_ACCESS_KEY_IDとAWS_SECRET_ACCESS_KEYを渡します。S3互換サービスの場合は、AWS_ENDPOINT_URL_S3も設定します。Google Cloud Storageの場合は、アプリケーションデフォルト認証情報でtype: gcsを使用します。

レプリケーションを確認する

最初のコピーは一度に1つのテーブルを処理し、各テーブルのマージ中はレプリケーションを一時停止します。そのため、所要時間はデータ量ではなくテーブル数に依存します。GitLab 19.2.2インスタンスは60以上のテーブルをレプリケートします。以下のチェックはレプリケーションが実行中であることを確認するものです。最初のコピーが完了したことを確認するものではありません。

1. SiphonがPostgreSQLを読み取っていることを確認します。スロットがアクティブであり、GitLabへの書き込み後にconfirmed_flush_lsnが進んでいる必要があります。

   SELECT slot_name, active, wal_status, confirmed_flush_lsn
   FROM pg_replication_slots
   WHERE slot_name = 'siphon_main_1_slot';

2. ClickHouseに行が届いていることを確認します。

   SELECT count() FROM gitlab_clickhouse_main_production.siphon_namespaces FINAL;
   SELECT count() FROM gitlab_clickhouse_main_production.siphon_projects FINAL;

   PostgreSQLの同じテーブルとカウントを比較してください。テーブルはReplacingMergeTreeであり、バックグラウンドマージが完了するまで更新された行が複数回現れるため、FINALが必要です。テーブルが最初の書き込み時にプレースホルダー行を受け取ることがあるため、ClickHouseのカウントは通常わずかに多くなります。

次のステップ

• GitLab Orbitをセットアップする