はじめに
前回の記事ではGitLab Container Registryの基本的な設定と利用方法を解説しました。
今回は、GitLabに保存したイメージの公開範囲を制御したり、ガベージコレクションでストレージ利用を最適化するなど、運用で役立つ実践的な設定方法を紹介します。
可視性の設定
GitLabにおける「可視性（Visibility）」とは、プロジェクトや関連リソースに誰がアクセスできるかを制御する仕組みを指します。例えば、「公開」に設定すればGitLabのアカウントがないユーザーも含めて誰でも閲覧可能になり、「非公開」に設定すれば招待されたメンバーしか利用できません。
GitLabではこの可視性をプロジェクト単位とレジストリ単位の両方で設定することができます。つまり、ソースコードとコンテナイメージで異なる公開範囲を持たせることが可能です。両者を組み合わせることで「コードは公開するが、イメージは限定公開」といった柔軟な運用が可能となります。
以下ではまずプロジェクトの可視性について整理し、その後にContainer Registry特有の可視性設定を紹介します。
プロジェクトの可視性
プロジェクト全体の可視性は [設定] > [一般] > [可視性、プロジェクトの機能、権限] で変更可能です。
| 可視性レベル | アクセス可能ユーザー | 利用用途 |
|---|---|---|
| 公開 | 全てのユーザー（非ログインユーザーを含む） | OSS公開、社外への配布 |
| 内部 | GitLabにログイン済みのユーザー全員 | 社内全体で共有 |
| 非公開 | プロジェクトのメンバーのみ | 機密性の高いプロジェクト |
レジストリの可視性
各プロジェクトに紐づくコンテナレジストリも独自に公開範囲を設定可能です。
選択肢は以下の2種類です：
- アクセスできる人すべて（Everyone With Access、デフォルト）: プロジェクトの可視性に従い、アクセス権を持つすべてのユーザーが利用可能
- プロジェクトメンバーのみ（Only Project Members）: 招待されたメンバーのみ利用可能
イメージの可視性はプロジェクト設定画面の[一般]を選択し、[コンテナレジストリ]の欄で設定することができます。
このプロジェクト可視性とレジストリ可視性を組み合わせることで、コンテナイメージに対する実際のアクセス範囲が決まります。
可視性の組み合わせとユースケース例
| プロジェクト可視性 | レジストリ可視性 | イメージ取得可能ユーザー | 主なユースケース |
|---|---|---|---|
| 公開 | アクセスできる人すべて | 誰でも（非ログインユーザー含む） | OSSライブラリの公式コンテナイメージ、学習教材用のサンプルアプリイメージ |
| 公開 | プロジェクトメンバーのみ | プロジェクトメンバーのみ | ソースコードはGitLab上で公開しつつ、商用サービス向けのビルド済み実行イメージは顧客限定で配布 |
| 内部 | アクセスできる人すべて | 社内ユーザー全員（Guest 以上） | 社内共通のベースイメージ配布（Python/Java ランタイムなど） |
| 内部 | プロジェクトメンバーのみ | プロジェクトメンバーのみ | 特定部門やチーム限定のアプリイメージ |
| 非公開 | アクセスできる人すべて | プロジェクトメンバー（Reporter 以上） | 社外非公開の業務システム、クライアント案件専用イメージ |
| 非公開 | プロジェクトメンバーのみ | プロジェクトメンバー（Reporter 以上） | 高度なセキュリティが求められる分野のイメージ（金融・医療・政府系など） |
※公開設定を選ぶ場合は、情報漏洩が起きないように権限やイメージの内容を十分確認してください。
ガベージコレクション
GitLabのレジストリでイメージタグを削除しても、ストレージ容量はすぐには解放されません。タグが外れたイメージは「未タグ付き（Untagged）」として残るためです。
この問題を解決するのが ガベージコレクション（GC） です。
ガベージコレクションはGitLabの管理者がサーバー上でCLIコマンド（gitlab-ctl registry-garbage-collect）を実行することで動作します。
CI/CDで頻繁にイメージをビルド・pushする環境では、レジストリに不要なイメージが蓄積しやすいため、定期的にガベージコレクションを実施することでストレージを効率的に利用できます。
前提
- gitlab-ctl registry-garbage-collectはメタデータをオブジェクトストレージに保存している場合のみ有効。
- メタデータデータベース方式（GitLabの新しいレジストリ方式）を有効にしている場合、このコマンドは使えず、代わりにオンラインGCが利用可能。
- この機能はSelf-Managed版（Omnibus / Helm）限定 であり、GitLab.com（SaaS）では利用不可。
未参照レイヤーと未タグ付きマニフェストの違い
ガベージコレクションが扱う対象は2種類あります。
未参照レイヤー（unreferenced layers）
- どのイメージマニフェストからも参照されていないレイヤー
- デフォルトのガベージコレクションで削除対象になる
- pullできず、純粋に不要なデータ
未タグ付きマニフェスト（untagged manifests）
- タグは削除されたが、ダイジェスト（@sha256:…）を指定すればpull可能
- 再タグ付けも可能で、再びGitLab UIやAPIに表示される
- デフォルトでは削除されず、ガベージコレクション実行コマンド（gitlab-ctl registry-garbage-collect）に-m オプションを付けた場合のみ削除される
このため -m を付けると「未タグ付きイメージ」も消えるため、過去のdigest pullや再利用ができなくなります。実行前に十分注意してください。
基本の実行方法
ガベージコレクションは、GitLabサーバー上でgitlab-ctl registry-garbage-collectコマンドを実行して行います。
# 未参照レイヤーを削除
$ sudo gitlab-ctl registry-garbage-collectデフォルトでは未参照レイヤーのみ削除され、未タグ付きのマニフェストは残ります。
未タグ付きイメージも含めて完全に削除したい場合は、同じコマンドに -m オプションを指定して実行します。
# 未タグ付きイメージも含め削除
$ sudo gitlab-ctl registry-garbage-collect -m※-mは破壊的な操作で元に戻せません。実行前に必ずバックアップを取得することを推奨します。
レジストリのダウンタイムと回避方法
gitlab-ctl registry-garbage-collectコマンドでガベージコレクションを行うと、処理前にレジストリが停止し、終了後に再起動されます。つまり、基本的にダウンタイムが発生することとなります。
停止を避けたい場合は、レジストリを「読み取り専用モード」に切り替え、GitLabに含まれるregistryバイナリ（通常は/opt/gitlab/embedded/bin/registry）を直接実行してガベージコレクションを行います。
- /etc/gitlab/gitlab.rbに以下を設定し gitlab-ctl reconfigureを実行
registry['storage'] = {
'filesystem' => { 'rootdirectory' => "<レジストリのストレージパス>" },
'maintenance' => { 'readonly' => { 'enabled' => true } }
}- ガベージコレクションを実行
# 未参照レイヤーのみ削除
$ sudo /opt/gitlab/embedded/bin/registry garbage-collect /var/opt/gitlab/registry/config.yml
# 未タグ付きも削除
$ sudo /opt/gitlab/embedded/bin/registry garbage-collect -m /var/opt/gitlab/registry/config.yml- 読み取り専用モードをfalseに戻して再度 gitlab-ctl reconfigureを実行
registry['storage'] = {
'filesystem' => { 'rootdirectory' => "<レジストリのストレージパス>" },
'maintenance' => { 'readonly' => { 'enabled' => false } }
}ガベージコレクション実行中でもイメージのpullは可能ですがpushは不可となります。
まとめ
今回は、GitLab Container Registryを実務で活用するための応用設定として「可視性の制御」と「ガベージコレクション」を紹介しました。特にガベージコレクションはストレージ効率を維持する上で重要ですが、Self-Managed版限定の管理者作業であり、ダウンタイムやオプション指定に注意が必要です。
2回にわたり解説したとおり、GitLabはソースコード管理だけでなく、コンテナイメージの管理機能も備えています。コードとイメージを一元管理することで、CI/CD環境をシンプルかつ効率的に構成できます。
次回からはGitLab CI/CD編として、レジストリと連携したパイプライン構築について解説していきます。
