GitLabシークレットマネージャー (OpenBao)

The GitLabシークレットマネージャーは、OpenBao（オープンソースのシークレット管理ソリューション）を使用します。OpenBaoは、GitLabのインスタンスで使用されるシークレットに対して、安全なストレージ、アクセス制御、およびライフサイクル管理を提供します。

GitLab CI/CDジョブで、GitLabシークレットマネージャーのシークレットを使用する場合は、GitLab Runner 19.0以降を使用する必要があります。

OpenBaoアーキテクチャ

OpenBaoは、既存のGitLabサービスと並行して動作するオプションコンポーネントとして、GitLabと統合されます。

• RailsバックエンドとRunnerは、ロードバランサーを介してOpenBao APIに接続します。
• OpenBaoはPostgreSQLにデータを保存します。Helmチャートは、OpenBaoが同じPostgreSQLインスタンス上の別個の論理データベースを使用するように設定します。Helmチャートのglobal.openbao.psqlを使用して接続を設定します。
• OpenBaoはシークレットストアからアンシールキーを取得します。
• OpenBaoは、HelmチャートによってマウントされたKubernetesシークレットからアンシールキーを読み取ります。
• OpenBaoは、監査ログが有効な場合にRailsバックエンドに監査ログを送信します。

flowchart TB
    SecretStore[Secret store]
    PostgreSQL[PostgreSQL]
    LB[Load balancer]
    OpenBao[OpenBao active node]
    Rails[Rails backend]
    Runner[GitLab Runner]
    Workhorse[Workhorse]

    Rails-- Write secrets and permissions -->LB
    Runner-- Get pipeline secrets -->LB
    LB-->OpenBao
    OpenBao-- Get unseal key -->SecretStore
    OpenBao-- Store -->PostgreSQL
    OpenBao-- Audit logs -->Workhorse
    Workhorse-->Rails

OpenBaoは、すべてのリクエストを処理する単一ノードで実行され、アクティブノードが失敗した場合は、オプションで複数のスタンバイノードが引き継ぎます。

OpenBaoをインストールする

前提条件:

• 管理者アクセス権。
• GitLab 19.0以降。
• Kubernetesクラスター。
• クラウドネイティブGitLabデプロイの場合、外部（Omnibus以外）のPostgreSQLインスタンス。外部のPostgreSQLインスタンスは、クラウドネイティブデプロイ用のGitLab Helmチャートで必要とされ、OpenBao固有のものではありません。OpenBaoは、そのインスタンス上で個別の論理データベースを使用します。

GitLabデプロイに基づいて、インストール方法を選択してください:

• Cloud Native GitLab: GitLabをKubernetesにデプロイする場合にこれを使用します。詳細については、OpenBao Helmチャートドキュメントを参照してください。
• Linux package: GitLabをLinuxパッケージで単一ノードまたは複数のノードにデプロイする場合にこれを使用します。詳細については、LinuxパッケージインスタンスへのOpenBaoのインストールを参照してください。

インストール後、GitLabシークレットマネージャーのユーザードキュメントに従ってOpenBaoが機能していることを確認してください。

サイジングの推奨事項

OpenBaoのリソース要件は、GitLabインスタンスのサイズとシークレットの使用パターンによって異なります。

これらの推奨事項は、検証済みの開始点です。デプロイをモニタリングし、実際の使用パターンに基づいてリソースを調整してください。要件は、シークレットをフェッチするCI/CDジョブの数、およびシークレットマネージャーが有効になっているグループとプロジェクトの数によって異なります。

ポッドのリソース

OpenBaoは、すべてのリクエストを処理する単一ノードで実行されます。追加のレプリカは、高可用性のフェイルオーバーのみを提供します。OpenBaoはPostgreSQLデータベースに接続されている場合、水平リードスケーラビリティ（HRS）をサポートしないため、スタンバイノードはリードトラフィックを処理しません。

シークレットフェッチレートの推定

適用される行を判断するには、1秒あたりのシークレットフェッチ数を推定します:

fetches/s = Git Pull RPS × adoption rate × 3

各項目の説明は以下のとおりです:

• Git Pull RPSは、GitLabインスタンスのピークGitプルスループットです。これは、既存の環境モニタリングから測定できます。ピークトラフィックメトリクスの抽出を参照してください。
• adoption rateは、シークレットマネージャーを使用するCI/CDジョブの割合（たとえば、5％の場合は0.05、20％の場合は0.20、50％の場合は0.50）です。
• 3は、シークレットマネージャーを使用するジョブごとにフェッチされるシークレットの想定平均数です。

Select the row where Secret fetches/sが結果を満たすか、わずかに超える行を選択します。たとえば、20%の採用率で20 GitプルRPSを測定したデプロイの場合: 20 × 0.20 × 3 = 12 fetches/s。Use at least the Up to 12 row。

デプロイ後、推定値を実際の使用量と比較して検証します。モニタリングクエリを使用してリソース使用量を測定し、しきい値を超えた場合は次の行にスケールすることで、リソースを増やしてください。

リソースの計算方法

CPUは、CI/CDジョブがシークレットをフェッチする頻度によって決定されます。シークレット書き込み操作（シークレットの作成または更新）は、パイプラインのボリュームに比べて頻度が低く、CPU負荷にはほとんど影響しません。この表では、各CI/CDジョブがGitクローンから始まるため、Gitクローンレート（Git Pull RPS）をCIジョブレートのプロキシとして使用します。式の詳細については、シークレットフェッチレートの推定を参照してください。CPU制限をCPUリクエストの2倍に設定します。これにより、起動時とプロビジョニング時の急増に対するバーストヘッドルームが提供され、安定状態でのノードの過剰な予約を防ぎます。

メモリはOpenBaoネームスペースの数によって決定され、これはシークレットマネージャーが有効になっているGitLabグループとプロジェクトの数に対応します。1ネームスペースあたり約5 MB、さらに1 GBの安全マージン（最低2 GB）を割り当てます。メモリ制限をメモリリクエスト（保証されたQoSクラス）と等しく設定します。OpenBaoは、メモリ制限を超えると、正常な低下なしにすぐにクラッシュします。

Replicasは、高可用性のフェイルオーバーのみを提供します。すべてのデプロイに2つのレプリカを使用します。OpenBaoはPostgreSQLストレージバックエンドでの水平リードスケーラビリティ（HRS）をサポートしないため、追加のレプリカはスループットのメリットを提供しません。

データベースリソース

OpenBaoは、PostgreSQL上の独立した論理データベースにデータを保存します。GitLabデータベースと同じPostgreSQLサーバーに配置できます。リファレンスアーキテクチャのPostgreSQL推奨事項を超える追加のデータベースコンピューティング能力は必要ありません。

データベース接続プール

OpenBao Helmチャートは、これらのPostgreSQL接続プールデフォルト値を設定します:

モニタリングでデータベース接続の待機時間が観測されない限り、これらの値を増やさないでください。

データベースストレージ

データベースストレージの要件は、主にシークレットの総数に依存します。そのメタデータと保存されたバージョンを含む各シークレットは、約13 KBのストレージを必要とします。

すべてのリファレンスアーキテクチャの階層で、ストレージの増加は無視できます。5〜10 GBのデータベースストレージを割り当てることで、十分なヘッドルームが確保されます。

GitLabシークレットマネージャーを有効にする

シークレットマネージャーがインスタンスで有効になっている場合、特定のグループとプロジェクトでそれを有効にできます。

前提条件:

• 管理者アクセス権。
• OpenBaoがインストールされ、設定されている必要があります。

シークレットマネージャーをインスタンスに対して有効にするには:

1. 右上隅で、管理者を選択します。
2. 左側のサイドバーで、設定 > 一般を選択します。
3. GitLabシークレットマネージャーを展開する。
4. Secrets Manager切替をオンにします。

OpenBaoのデプロイをモニタリングする

次のクエリを使用して、デプロイが適切にサイジングされていることを確認し、スケーリングが必要な時期を検出してください。

CPU使用率

OpenBao CPU使用量を測定するには:

sum(rate(container_cpu_usage_seconds_total{container="openbao-server"}[5m]))

結果はCPUコア単位です。サイジング表のCPUリクエスト値と比較するために、1,000を掛けてミリコアに変換します。CPU使用率がCPUリクエストの50％を常に超える場合は、サイジング表の次の行にスケールすることを検討してください。

メモリ使用率

OpenBaoメモリ使用量を測定するには:

sum(container_memory_working_set_bytes{container="openbao-server"})

結果はバイト単位です。メモリは、グループとプロジェクトがシークレットマネージャーを有効にすると、1ネームスペースあたり約5 MBずつ増加します。再起動後、OpenBaoがデータベースからネームスペースのメタデータを読み込むと、メモリは安定します。

正しいメモリリクエストを計算するには、シークレットマネージャーが有効になっているグループとプロジェクトを数え、5 MBを掛けてから1 GBを追加します。結果が現在のメモリリクエストを超える場合は、ポッドのリソースを更新してください。メモリがアクティブなプロビジョニングなしに持続的な上昇傾向を示す場合、潜在的な問題について調査してください。

CPUスロットリング

レイテンシーに影響を与える可能性のあるCPUスロットリングを検出するには:

sum(rate(container_cpu_cfs_throttled_periods_total{container="openbao-server"}[5m]))
/
sum(rate(container_cpu_cfs_periods_total{container="openbao-server"}[5m]))

スロットル比率が0.25（25％）を超える場合、現在のワークロードに対してCPU制限が低すぎることを示します。OpenBaoがスロットルされると、CPU時間を待機しているgoroutineがシークレットフェッチレイテンシーの増加を引き起こします。

ヘルスチェックエンドポイント

OpenBaoは、モニタリング用のヘルスチェックエンドポイントを提供します:

• <your-openbao-url>/v1/sys/health: OpenBaoのヘルスステータスを返します。
• <your-openbao-url>/v1/sys/seal-status: シールステータスを返します。

これらのエンドポイントをモニタリングシステムと統合できます。

バックアップと復元

OpenBaoは、PostgreSQL上の独立した論理データベースにデータを保存します。シークレットが復元されることを確実にするため、このデータベースを通常のGitLabバックアップと共にバックアップしてください。

OpenBao固有の詳細なバックアップおよび復元手順については、OpenBaoバックアップドキュメントを参照してください。

リカバリーキー管理

OpenBaoのリカバリーキーの管理に関する情報（保存、表示、ルートトークン生成への使用を含む）については、リカバリーキー管理を参照してください。

高可用性

OpenBaoは単一ノードのアクティブノードアーキテクチャを使用します。1つのノードがすべてのリクエストを処理し、アクティブノードが失敗した場合は、スタンバイノードが自動フェイルオーバーを提供します。

フェイルオーバー

スタンバイノードは起動時にすべてのネームスペースメタデータを読み込むため、アクティブへのプロモーションに追加の初期化は必要ありません。ネームスペースの数はフェイルオーバー時間に影響しません。

本番環境デプロイの場合:

• 冗長性のために少なくとも2つのOpenBaoレプリカを実行します。
• 高可用性のPostgreSQLバックエンドを使用します。
• モニタリングクエリを使用してモニタリングとアラートを実装します。

アップグレード時のダウンタイム

OpenBaoはゼロダウンタイムのアップグレードをサポートしていません。アップグレード中、OpenBaoは起動時に各ネームスペースを順次初期化します。シークレットマネージャーが有効になっているすべてのグループまたはプロジェクトは1つのネームスペースとしてカウントされます。

アップグレードには、1,000ネームスペースあたり約11秒と、ベースラインとして5秒かかります。

OpenBaoがオンデマンドのネームスペース読み込みを実装すると、アップグレードのダウンタイムは大幅に短縮されます。詳細については、イシュー595721を参照してください。

Geoデプロイ

OpenBaoはGeoデプロイをサポートしています。OpenBaoはプライマリとセカンダリ両方のGeoサイトにデプロイされますが、プライマリサイトのみがアクティブなOpenBaoノードを実行します。

GeoにおけるOpenBaoの動作

プライマリサイトでは、OpenBaoは書き込み可能なPostgreSQLデータベースに接続されたアクティブノードとして実行されます。セカンダリサイトでは、OpenBaoはPostgreSQLリードレプリカに接続されたスタンバイモードで実行されます。

PostgreSQLストリーミングレプリケーションは、すべてのOpenBaoデータ（シークレット、ポリシー、認証設定）をプライマリからセカンダリサイトに自動的に転送します。

両方のGitLabインスタンス（プライマリとセカンダリ）は、プライマリOpenBao URLに接続します。セカンダリOpenBaoデプロイはスタンバイのままとなり、セカンダリPostgreSQLデータベースがGeoフェイルオーバー中に書き込み可能になると、アクティブにプロモートされます。

セカンダリサイトでは、OpenBaoはfailed to acquire lockおよびcannot execute INSERT in a read-only transactionエラーをログに記録します。これらのエラーは想定される動作です。OpenBaoは読み取り専用データベースでHAリーダーロックを取得できません。

セカンダリサイトにOpenBaoをインストールする

前提条件:

• Geoが設定されている必要があります。詳細については、Geoの設定を参照してください。
• OpenBaoは、セカンダリにデプロイする前に、プライマリサイトにインストールされ、動作している必要があります。詳細については、OpenBaoのインストールを参照してください。

1. セカンダリOpenBaoは、レプリケートされたデータを復号化するために、プライマリと同じアンシールキーを使用する必要があります。プライマリクラスターからセカンダリクラスターへgitlab-openbao-unseal Kubernetesシークレットをコピーします:

   kubectl --namespace gitlab get secret gitlab-openbao-unseal -o yaml

   エクスポートされたシークレットをセカンダリクラスターに適用します。詳細については、シークレットをバックアップするを参照してください。

2. DNSレコードを更新して、フェイルオーバー中にプライマリドメインがセカンダリサイトを指すように計画している場合、事前にOpenBaoを適切に設定することをお勧めします。Helmチャートを設定し、urlとjwt_audienceをプライマリOpenBao URLに設定します:

   global:
     openbao:
       enabled: true
       url: https://openbao.<primary-domain>
       jwt_audience: https://openbao.<primary-domain>

   チャート設定オプションの詳細については、Geo設定を参照してください。

3. セカンダリサイトにGitLab Helmチャートをデプロイします。OpenBaoポッドが起動し、スタンバイモードのままになります。これは想定される動作です。

4. セカンダリクラスターでOpenBaoポッドが実行されていることを確認します:

   kubectl --namespace gitlab get pods -l app=openbao

   すべてのポッドがRunning状態である必要があります。セカンダリポッドにはopenbao-active: "true"ラベルがありません。これは想定される動作です。

5. アクティブサービスにセカンダリクラスター上のエンドポイントがないことを確認します:

   kubectl --namespace gitlab get endpoints gitlab-openbao-active

   セカンダリにエンドポイントがないことは想定される動作です。

6. CIパイプラインを実行してシークレットマネージャーをテストし、セカンダリサイトでシークレットマネージャー変数を使用します。

トラブルシューティング

シークレットマネージャーを使用する際に、次の問題が発生する可能性があります。

Geoデプロイのトラブルシューティングを行う

遅いシークレット操作の診断

CI/CDジョブがシークレットのフェッチに時間がかかったり、シークレット操作がタイムアウトしたりする場合に、このセクションを使用してください。

レイテンシーが上昇していることを確認する

次のクエリを使用して、平均要求レイテンシーをミリ秒単位で測定します。このクエリは、低トラフィックデプロイを含む、あらゆるトラフィックレベルで機能します:

rate(openbao_core_handle_request_sum[5m])
/
rate(openbao_core_handle_request_count[5m])

通常の負荷では、すべてのリクエストタイプにおける平均レイテンシーは通常3〜7ミリ秒です。平均レイテンシーが継続的に20ミリ秒を超える場合は、調査してください。

OpenBaoがリクエストをアクティブに処理している場合は、P99レイテンシーに次のクエリを使用します:

openbao_core_handle_request{quantile="0.99"}

通常のP99は10ミリ秒未満です。概要ウィンドウに最近の観測値がないため、OpenBaoがアイドル状態のとき、このクエリはNaNを返します。その場合はレートベースのクエリを使用してください。

潜在的な問題を特定する

PostgreSQLのレイテンシーが高い場合は、接続プールが飽和状態にあるかどうかを確認してください。すべての接続がビジー状態の場合、追加のリクエストがキューに入れられ、レイテンシーを引き起こします。接続プール設定については、Database resourcesを参照してください。PostgreSQLモニタリングまたはOpenBaoログで接続数を確認します。