GitLabコンテナレジストリの管理

GitLabコンテナレジストリを使用すると、すべてのプロジェクトが、Dockerイメージを保存するための独自のスペースを保持できます。

Distribution Registryの詳細については、以下を参照してください:

• 設定
• ストレージドライバー
• レジストリサーバーのデプロイ

このドキュメントは管理者向けガイドです。GitLabコンテナレジストリの使用方法については、ユーザードキュメントを参照してください。

コンテナレジストリを有効にする

コンテナレジストリを有効にするプロセスは、使用するインストールのタイプによって異なります。

Linuxパッケージインストール

Linuxパッケージを使用してGitLabをインストールした場合、コンテナレジストリはデフォルトで使用できるときと、そうでないときがあります。

組み込みのLet’s Encryptインテグレーションを使用している場合、コンテナレジストリは、GitLabドメインのポート5050で自動的に有効になって使用できるようになります。

そうでない場合、コンテナレジストリは有効になりません。有効にするには、次の手順に従います:

• GitLabドメイン用にコンテナレジストリを設定できます。
• または、別のドメイン用にコンテナレジストリを設定できます。

コンテナレジストリは、デフォルトでHTTPSで動作します。HTTPを使用できますが、推奨されておらず、このドキュメントでは扱いません。

Helmチャートによるインストール

Helmチャートによるインストールについては、Helmチャートに関するドキュメントのコンテナレジストリを使用するを参照してください。

自己コンパイルによるインストール

GitLabインストールを自分でコンパイルした場合は、次の手順に従います:

1. インストールするGitLabのバージョンに対応するイメージ（例: registry.gitlab.com/gitlab-org/build/cng/gitlab-container-registry:v3.15.0-gitlab）を使用して、レジストリをデプロイする必要があります。
2. インストールの完了後、レジストリを有効にするには、gitlab.ymlでレジストリの設定を構成する必要があります。
3. lib/support/nginx/registry-sslにあるサンプルNGINX設定ファイルを使用して、host、port、TLS証明書のパスに一致するようにレジストリを編集します。

gitlab.ymlの内容は次のとおりです:

registry:
  enabled: true
  host: <registry.gitlab.example.com>
  port: <5005>
  api_url: <http://localhost:5000/>
  key: <config/registry.key>
  path: <shared/registry>
  issuer: <gitlab-issuer>

各設定項目の意味は次のとおりです:

ソースからGitLabをインストールする場合、レジストリの初期化ファイルはGitLabに同梱されていません。したがって、設定を変更しても、GitLabを再起動してレジストリを再起動することはできません。それを行う方法については、アップストリームドキュメントをお読みください。

最低限必要な絶対条件として、レジストリの設定に、サービスとしてcontainer_registry、レルムとしてhttps://gitlab.example.com/jwt/authがあることを確認してください:

auth:
  token:
    realm: <https://gitlab.example.com/jwt/auth>
    service: container_registry
    issuer: gitlab-issuer
    rootcertbundle: /root/certs/certbundle

コンテナレジストリドメインの設定

レジストリの外部ドメインは、次のいずれかの方法で設定できます:

• 既存のGitLabドメインを使用します。レジストリはポートでリッスンし、GitLabのTLS証明書を再利用します。
• 完全に別のドメインとその新しいTLS証明書を使用します。

コンテナレジストリにはTLS証明書が必要なため、コストが考慮事項となる場合があります。

コンテナレジストリを初めて設定する前に、この点を考慮してください。

既存のGitLabドメインでコンテナレジストリを設定する

既存のGitLabドメインを使用するようにコンテナレジストリが設定されている場合、ポートでコンテナレジストリを公開できます。これにより、既存のGitLab TLS証明書を再利用できます。

GitLabドメインがhttps://gitlab.example.comで、外部へのポートが5050の場合、コンテナレジストリを設定するには、次のことを行います:

• Linuxパッケージインストールを使用している場合は、gitlab.rbを編集します。
• 自己コンパイルによるインストールを使用している場合は、gitlab.ymlを編集します。

レジストリがリッスンするポート（デフォルトでは5000）とは異なるポートを選択してください。そうしないと、競合が発生します。

registry_external_url '<https://registry-gitlab.example.com>'
registry_nginx['redirect_http_to_https'] = true
registry_nginx['listen_port'] = 5678

これで、ユーザーは次のコマンドを使用して、GitLab認証情報でコンテナレジストリにサインインできるはずです:

docker login <gitlab.example.com:5050>

独自のドメインでコンテナレジストリを設定する

独自のドメインを使用するようにレジストリが設定されている場合は、その特定のドメイン（例: registry.example.com）のTLS証明書が必要です。既存のGitLabドメインのサブドメインでホストされている場合は、ワイルドカード証明書が必要になる場合があります。たとえば、*.gitlab.example.comはregistry.gitlab.example.comに一致するワイルドカードであり、*.example.comとは異なります。

手動で生成されたSSL証明書（ここで説明しています）だけでなく、Let’s Encryptによって自動的に生成された証明書もLinuxパッケージのインストールでサポートされています。

https://registry.gitlab.example.comでコンテナレジストリにアクセスできるようにしたいとします。

registry_nginx['ssl_certificate'] = "/etc/gitlab/ssl/certificate.pem"
registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key"

これで、ユーザーはGitLab認証情報を使用して、コンテナレジストリにサインインできるはずです:

docker login <registry.gitlab.example.com>

コンテナレジストリをサイト全体で無効にする

これらの手順に従ってレジストリを無効にしても、既存のDockerイメージは削除されません。Dockerイメージの削除は、レジストリアプリケーション自体によって処理されます。

新しいプロジェクトのコンテナレジストリをサイト全体で無効にする

コンテナレジストリが有効になっている場合、すべての新しいプロジェクトで使用可能になります。この機能を無効にして、プロジェクトのオーナーがコンテナレジストリを自分で有効にできるようにするには、次の手順に従います。

トークンの持続時間を増やす

GitLabでは、コンテナレジストリのトークンは5分ごとに期限切れになります。トークンの持続時間を増やすには、次の手順に従います:

1. 左側のサイドバーの下部で、管理者を選択します。
2. 設定 > CI/CDを選択します。
3. コンテナレジストリを展開します。
4. **認証トークンの持続時間（分）**の値を更新します。
5. 変更を保存を選択します。

コンテナレジストリのストレージを設定する

ストレージドライバーを設定することにより、さまざまなストレージバックエンドを使用するようにコンテナレジストリを設定できます。デフォルトでは、GitLabコンテナレジストリは、ファイルシステムドライバー設定を使用するように設定されています。

サポートされているドライバーは次のとおりです:

ほとんどのS3互換サービス（MinIOなど）はコンテナレジストリで動作するはずですが、AWS S3のサポートのみが保証されています。サードパーティのS3実装の正しさは保証できないため、問題のデバッグは可能ですが、AWS S3バケットに対して問題を再現できない限り、レジストリにパッチを適用することはできません。

ファイルシステムを使用する

ファイルシステムにイメージを保存する場合は、以下の手順に従って、コンテナレジストリのストレージパスを変更できます。

このパスには、次のユーザーがアクセスできます:

• コンテナレジストリデーモンを実行しているユーザー。
• GitLabを実行しているユーザー。

GitLab、レジストリ、Webサーバーのすべてのユーザーがこのディレクトリにアクセスできる必要があります。

オブジェクトストレージを使用する

ローカルファイルシステムの代わりに、オブジェクトストレージにコンテナレジストリイメージを保存する場合は、サポートされているストレージドライバーのいずれかを設定できます。

詳細については、オブジェクトストレージを参照してください。

Linuxパッケージのインストールのオブジェクトストレージを設定する

コンテナレジストリのオブジェクトストレージを設定するには、次の手順に従います:

1. 使用するストレージドライバーを選択します。
2. 適切な設定で/etc/gitlab/gitlab.rbを編集します。
3. ファイルを保存して、GitLabを再設定し、変更を有効にします。

# Deprecated: Will be removed in GitLab 19.0
registry['storage'] = {
  's3' => {
    'accesskey' => '<s3-access-key>',
    'secretkey' => '<s3-secret-key-for-access-key>',
    'bucket' => '<your-s3-bucket>',
    'region' => '<your-s3-region>',
    'regionendpoint' => '<your-s3-regionendpoint>'
  }
}

# Beta: s3_v2 driver
registry['storage'] = {
  's3_v2' => {
    'accesskey' => '<s3-access-key>',
    'secretkey' => '<s3-secret-key-for-access-key>',
    'bucket' => '<your-s3-bucket>',
    'region' => '<your-s3-region>',
    'regionendpoint' => '<your-s3-regionendpoint>'
  }
}

registry['storage'] = {
  's3_v2' => {
    'accesskey' => '<s3-access-key>',
    'secretkey' => '<s3-secret-key-for-access-key>',
    'bucket' => '<your-s3-bucket>',
    'region' => '<your-s3-region>',
    'regionendpoint' => '<your-s3-regionendpoint>',
    'checksum_disabled' => true
  }
}

registry['storage'] = {
  's3_v2' => {  # Beta driver
    'accesskey' => '<s3-access-key>',
    'secretkey' => '<s3-secret-key-for-access-key>',
    'bucket' => '<your-s3-bucket>',
    'region' => '<your-s3-region>',
    'regionendpoint' => '<your-s3-vpc-endpoint>',
    'pathstyle' => false
  }
}

registry['storage'] = {
  's3' => {
    'accesskey' => '<s3-access-key>',
    'secretkey' => '<s3-secret-key-for-access-key>',
    'bucket' => '<your-s3-bucket>',
    'region' => '<your-s3-region>',
    'regionendpoint' => '<your-s3-regionendpoint>',
    'maxrequestspersecond' => 100
  }
}

# Deprecated: Will be removed in GitLab 19.0
registry['storage'] = {
  'azure' => {
    'accountname' => '<your_storage_account_name>',
    'accountkey' => '<base64_encoded_account_key>',
    'container' => '<container_name>'
  }
}

# Beta: azure_v2 driver
registry['storage'] = {
  'azure_v2' => {
    'credentials_type' => '<client_secret>',
    'tenant_id' => '<your_tenant_id>',
    'client_id' => '<your_client_id>',
    'secret' => '<your_secret>',
    'container' => '<your_container>',
    'accountname' => '<your_account_name>'
  }
}

registry['storage'] = {
  'gcs' => {
    'bucket' => '<your_bucket_name>',
    'keyfile' => '<path/to/keyfile>',
    # If you have the bucket shared with other apps beyond the registry, uncomment the following:
    # 'rootdirectory' => '/gcs/object/name/prefix'
  }
}

自己コンパイルによるインストール

ストレージドライバーの設定は、Dockerレジストリをデプロイしたときに作成されたレジストリ設定YAMLファイルで行います。

s3ストレージドライバーの例:

storage:
  s3:
    accesskey: '<s3-access-key>'                # Not needed if IAM role used
    secretkey: '<s3-secret-key-for-access-key>' # Not needed if IAM role used
    bucket: '<your-s3-bucket>'
    region: '<your-s3-region>'
    regionendpoint: '<your-s3-regionendpoint>'
  cache:
    blobdescriptor: inmemory
  delete:
    enabled: true

<your-s3-bucket>は、既存のバケットの名前である必要があり、サブディレクトリを含めることはできません。

ダウンタイムなしでオブジェクトストレージに移行する

コンテナレジストリを停止せずにストレージを移行するには、コンテナレジストリを読み取り専用モードに設定します。大規模なインスタンスでは、コンテナレジストリをしばらくの間、読み取り専用モードにする必要があります。この間、コンテナレジストリからプルすることはできますが、プッシュすることはできません。

1. オプション。移行するデータ量を減らすには、ガベージコレクションツールをダウンタイムなしで実行します。

2. この例では、awsコマンドラインインターフェースを使用します。以前にコマンドラインインターフェースを設定していない場合は、sudo aws configureを実行して、認証情報を設定する必要があります。管理者以外のユーザーはコンテナレジストリフォルダーにアクセスできない可能性が高いため、sudoを使用するようにしてください。認証情報の設定を確認するには、lsを実行して、すべてのバケットをリストします。

   sudo aws --endpoint-url <https://your-object-storage-backend.com> s3 ls

   AWSをバックエンドとして使用している場合、--endpoint-urlは必要ありません。

3. たとえば、awsコマンドラインインターフェースcpまたはsyncコマンドを使用して、初期データをS3バケットにコピーします。dockerフォルダーをバケット内のトップレベルフォルダーとして保持する必要があります。

   sudo aws --endpoint-url <https://your-object-storage-backend.com> s3 sync registry s3://mybucket

   大量のデータがある場合は、並行同期操作を実行することにより、パフォーマンスを向上させることができる場合があります。

4. 最終的なデータ同期を行うには、コンテナレジストリをread-onlyモードにして 、GitLabを再設定します。

5. 最初のデータ読み込み以降に行われた変更をS3バケットに同期し、移行先のバケットには存在するが移行元には存在しないファイルを削除します:

   sudo aws --endpoint-url <https://your-object-storage-backend.com> s3 sync registry s3://mybucket --delete --dryrun

   コマンドが期待どおりに動作することを確認したら、--dryrunフラグを削除してコマンドを実行します。

   --deleteフラグは、移行先には存在するが移行元には存在しないファイルを削除します。移行先と移行元を入れ替えると、レジストリ内のすべてのデータが削除されます。

6. 次の2つのコマンドから返されるファイル数を確認して、すべてのコンテナレジストリファイルがオブジェクトストレージにアップロードされていることを確認します:

   sudo find registry -type f | wc -l

   sudo aws --endpoint-url <https://your-object-storage-backend.com> s3 ls s3://<mybucket> --recursive | wc -l

   これらのコマンドの出力は、_uploadsディレクトリとそのサブディレクトリの内容を除いて一致するはずです。

7. ストレージにS3バケットを使用するようにレジストリを設定します。

8. 変更を有効にするには、レジストリをread-writeモードに戻し、GitLabを再設定します。

Azureオブジェクトストレージに移行する

registry['storage'] = {
  'azure' => {
    'accountname' => '<your_storage_account_name>',
    'accountkey' => '<base64_encoded_account_key>',
    'container' => '<container_name>',
    'trimlegacyrootprefix' => true
  }
}

storage:
  azure:
    accountname: <your_storage_account_name>
    accountkey: <base64_encoded_account_key>
    container: <container_name>
    trimlegacyrootprefix: true

デフォルトでは、Azure Storageドライバーはcore.windows.netレルムを使用します。azureセクションでrealmに別の値を設定できます（たとえば、Azure Government Cloudの場合はcore.usgovcloudapi.net）。

ストレージドライバーのリダイレクトを無効にする

デフォルトでは、リモートバックエンドで設定されたレジストリにアクセスするユーザーは、ストレージドライバーのデフォルトバックエンドにリダイレクトされます。たとえば、s3ストレージドライバーを使用してレジストリを設定できます。このストレージドライバーは、リクエストをリモートS3バケットにリダイレクトして、GitLabサーバーの負荷を軽減します。

ただし、この動作は、パブリックサーバーに通常アクセスできない内部ホストで使用されるレジストリに対しては望ましくありません。リダイレクトとプロキシダウンロードを無効にするには、次のようにdisableフラグをtrueに設定します。これにより、すべてのトラフィックが常にレジストリサービスを通過するようになります。その結果、セキュリティが向上しますが（ストレージバックエンドが公開されないため、攻撃されにくくなります）、パフォーマンスが低下します（すべてのトラフィックがサービスを経由してリダイレクトされます）。

暗号化されたS3バケット

デフォルトでSSE-S3またはSSE-KMS暗号化が有効になっているS3バケットに対して、AWS KMSによるサーバー側の暗号化を使用できます。カスタマーマスターキー（CMK）とSSE-C暗号化は、リクエストごとに暗号化キーを送信する必要があるため、サポートされていません。

SSE-S3の場合は、レジストリ設定のencryptオプションを有効にする必要があります。これ行う方法は、GitLabをインストールした方法によって異なります。インストール方法に応じて、次の手順に従ってください。

ストレージの制限

ストレージの制限がなければ、ユーザーは任意のサイズのDockerイメージを無制限にアップロードできます。この設定は、将来のリリースで設定可能になるはずです。

レジストリの内部ポートを変更する

レジストリサーバーはデフォルトでポート5000のlocalhostでリッスンします。これは、レジストリサーバーが接続を受け入れるアドレスです。次の例では、レジストリのポートを5010に設定します。

プロジェクトごとにコンテナレジストリを無効にする

GitLabインスタンスでレジストリが有効になっているが、プロジェクトに必要ない場合は、プロジェクトの設定からレジストリを無効にすることができます。

GitLabを認証エンドポイントとして外部コンテナレジストリを使用する

外部コンテナレジストリを使用すると、コンテナレジストリに関連付けられている一部の機能が使用できなくなったり、固有のリスクが発生したりする場合があります。

インテグレーションを機能させるには、JSON Webトークンを使用してGitLabで認証するように外部レジストリを設定する必要があります。外部レジストリのランタイム設定には、次のエントリが必ず含まれている必要があります:

auth:
  token:
    realm: https://<gitlab.example.com>/jwt/auth
    service: container_registry
    issuer: gitlab-issuer
    rootcertbundle: /root/certs/certbundle

これらのエントリがない場合、レジストリログインはGitLabで認証できません。また、GitLabは、registry.example.com/group/project/image-name:tagやregistry.example.com/group/project/my/image-name:tagなど、プロジェクト階層下のネストされたイメージ名を認識せず、registry.example.com/group/project:tagのみを認識します。

Linuxパッケージインストール

GitLabを外部コンテナレジストリの認証エンドポイントとして使用できます。

1. /etc/gitlab/gitlab.rbを開き、必要な設定を行います:

   gitlab_rails['registry_enabled'] = true
   gitlab_rails['registry_api_url'] = "https://<external_registry_host>:5000"
   gitlab_rails['registry_issuer'] = "gitlab-issuer"

   • gitlab_rails['registry_enabled'] = trueは、GitLabコンテナレジストリ機能と認証エンドポイントを有効にするために必要です。これを有効にしても、GitLabにバンドルされているコンテナレジストリサービスは起動しません。
   • gitlab_rails['registry_api_url'] = "http://<external_registry_host>:5000"は、レジストリがインストールされているホストと一致するように変更する必要があります。また、外部レジストリがTLSを使用するように設定されている場合は、httpsを指定する必要があります。

2. GitLabと外部コンテナレジストリが安全に通信するには、証明書とキーのペアが必要です。証明書とキーのペアを作成して、公開証明書（rootcertbundle）を使用して外部コンテナレジストリを設定し、秘密キーを使用してGitLabを設定する必要があります。そうするには、/etc/gitlab/gitlab.rbに次のコードを追加します:

   # registry['internal_key'] should contain the contents of the custom key
   # file. Line breaks in the key file should be marked using `\n` character
   # Example:
   registry['internal_key'] = "---BEGIN RSA PRIVATE KEY---\nMIIEpQIBAA\n"
   
   # Optionally define a custom file for a Linux package installation to write the contents
   # of registry['internal_key'] to.
   gitlab_rails['registry_key_path'] = "/custom/path/to/registry-key.key"

   再設定が実行されるたびに、registry_key_pathで指定されたファイルには、internal_keyで指定されたコンテンツが入力されます。ファイルが指定されていない場合、Linuxパッケージのインストールでは、デフォルトで/var/opt/gitlab/gitlab-rails/etc/gitlab-registry.keyになり、そのファイルに入力されます。

3. GitLabコンテナレジストリページに表示されるコンテナレジストリURLを変更するには、次のように設定します:

   gitlab_rails['registry_host'] = "<registry.gitlab.example.com>"
   gitlab_rails['registry_port'] = "5005"

4. ファイルを保存して、GitLabを再設定し、変更を有効にします。

自己コンパイルによるインストール

1. /home/git/gitlab/config/gitlab.ymlを開き、registryの下の設定を編集します:

   ## Container registry
   
   registry:
     enabled: true
     host: "<registry.gitlab.example.com>"
     port: "5005"
     api_url: "https://<external_registry_host>:5000"
     path: /var/lib/registry
     key: </path/to/keyfile>
     issuer: gitlab-issuer

   これらのパラメータの意味については、こちらをご覧ください。

2. ファイルを保存して、GitLabを再起動し、変更を有効にします。

コンテナレジストリ通知を設定する

レジストリで発生するイベントに応じてWebhook通知を送信するようにコンテナレジストリを設定できます。

コンテナレジストリ通知設定のオプションの詳細については、Dockerレジストリ通知のドキュメントを参照してください。

コンテナレジストリに複数のエンドポイントを設定できます。

notifications:
  endpoints:
    - name: <alistener>
      disabled: false
      url: https://<my.listener.com>/event
      headers: <http.Header>
      timeout: 500
      threshold: 5 # DEPRECATED: use `maxretries` instead.
      maxretries: 5
      backoff: 1000

クリーンアップポリシーを実行する

前提要件:

• Sidekiqとは異なるノードでコンテナレジストリが実行される分散アーキテクチャを使用している場合は、外部Sidekiqを使用する場合のコンテナレジストリの設定の手順に従います。

クリーンアップポリシーを作成したら、すぐに実行してコンテナレジストリのストレージ容量を削減できます。スケジュールされたクリーンアップを待つ必要はありません。

特定のプロジェクトで使用されるコンテナレジストリのディスク容量を削減するために、管理者は次のことを行えます:

1. プロジェクトごとのディスク容量使用量を確認して、クリーンアップが必要なプロジェクトを特定します。
2. GitLab Railsコンソールを使用してクリーンアップポリシーを実行し、イメージタグを削除します。
3. ガベージコレクションを実行して、参照されていないレイヤーとタグ付けされていないマニフェストを削除します。

プロジェクトごとのレジストリディスク容量使用量

各プロジェクトで使用されるディスク容量を確認するには、GitLab Railsコンソールで次のスクリプトを実行します:

projects_and_size = [["project_id", "creator_id", "registry_size_bytes", "project path"]]
# You need to specify the projects that you want to look through. You can get these in any manner.
projects = Project.last(100)

registry_metadata_database = ContainerRegistry::GitlabApiClient.supports_gitlab_api?

if registry_metadata_database
  projects.each do |project|
    size = project.container_repositories_size
    if size > 0
      projects_and_size << [project.project_id, project.creator&.id, size, project.full_path]
    end
  end
else
  projects.each do |project|
    project_layers = {}

    project.container_repositories.each do |repository|
      repository.tags.each do |tag|
        tag.layers.each do |layer|
          project_layers[layer.digest] ||= layer.size
        end
      end
    end

    total_size = project_layers.values.compact.sum
    if total_size > 0
      projects_and_size << [project.project_id, project.creator&.id, total_size, project.full_path]
    end
  end
end

# print it as comma separated output
projects_and_size.each do |ps|
   puts "%s,%s,%s,%s" % ps
end

クリーンアップポリシーを実行してイメージタグを削除するには、GitLab Railsコンソールで次のコマンドを実行します:

# Numeric ID of the project whose container registry should be cleaned up
P = <project_id>

# Numeric ID of a user with Developer, Maintainer, or Owner role for the project
U = <user_id>

# Get required details / objects
user    = User.find_by_id(U)
project = Project.find_by_id(P)
policy  = ContainerExpirationPolicy.find_by(project_id: P)

# Loop through each container repository
project.container_repositories.find_each do |repo|
  puts repo.attributes

  # Start the tag cleanup
  puts Projects::ContainerRepository::CleanupTagsService.new(container_repository: repo, current_user: user, params: policy.attributes.except("created_at", "updated_at")).execute
end

スケジュールに従ってクリーンアップを実行することもできます。

すべてのプロジェクトのクリーンアップポリシーをインスタンス全体で有効にするには、コンテナレジストリがあるが、クリーンアップポリシーが無効になっているすべてのプロジェクトを見つける必要があります:

# Find all projects where Container registry is enabled, and cleanup policies disabled

projects = Project.find_by_sql ("SELECT * FROM projects WHERE id IN (SELECT project_id FROM container_expiration_policies WHERE enabled=false AND id IN (SELECT project_id FROM container_repositories))")

# Loop through each project
projects.each do |p|

# Print project IDs and project full names
    puts "#{p.id},#{p.full_name}"
end

コンテナレジストリのメタデータデータベース

メタデータデータベースは、オンラインガベージコレクションなど、多くの新しいレジストリ機能を有効にするほか、多くのレジストリ操作の効率を向上させます。詳細については、コンテナレジストリのメタデータデータベースのページを参照してください。

コンテナレジストリのガベージコレクション

前提要件:

• LinuxパッケージまたはGitLab Helmチャートを使用して、GitLabをインストールしている必要があります。

コンテナレジストリはかなりの量のストレージ容量を使用する可能性があるため、ストレージの使用量を削減することをおすすめします。リストされているオプションの中で最も効果的なのはタグの削除です。ただし、タグを削除するだけではイメージレイヤーは削除されず、基盤となるイメージマニフェストのタグが削除されたままになります。

より効果的に容量を解放するために、コンテナレジストリには、参照されていないレイヤーと（オプションで）タグ付けされていないマニフェストを削除できるガベージコレクターがあります。

ガベージコレクターを開始するには、次のgitlab-ctlコマンドを実行します:

sudo gitlab-ctl registry-garbage-collect

ガベージコレクションの実行に必要な時間は、コンテナレジストリのデータサイズに比例します。

コンテンツアドレス可能なレイヤーについて理解する

初めてイメージをビルドする次の例を考えてみましょう:

# This builds a image with content of sha256:<111111...>
docker build -t <my.registry.com>/<my.group>/<my.project>:latest .
docker push <my.registry.com>/<my.group>/<my.project>:latest

次に、latestを新しいバージョンで上書きします:

# This builds a image with content of sha256:<222222...>
docker build -t <my.registry.com>/<my.group>/<my.project>:latest .
docker push <my.registry.com>/<my.group>/<my.project>:latest

これで、latestタグはsha256:<222222...>のマニフェストを指します。レジストリのアーキテクチャにより、latestタグを介して直接アクセスできなくなったとしても、イメージ<my.registry.com>/<my.group>/<my.project>@sha256:<111111...>をプルすると、このデータにアクセスできます。

参照されていないレイヤーを削除する

イメージレイヤーは、コンテナレジストリストレージの大部分を占めています。イメージマニフェストがレイヤーを参照していない場合、レイヤーは参照されていないと見なされます。参照されていないレイヤーは、コンテナレジストリのガベージコレクターのデフォルトのターゲットです。

設定ファイルのデフォルトの場所を変更しなかった場合は、次のコマンドを実行します:

sudo gitlab-ctl registry-garbage-collect

コンテナレジストリconfig.ymlの場所を変更した場合は、次のコマンドを実行します:

sudo gitlab-ctl registry-garbage-collect /path/to/config.yml

タグ付けされていないマニフェストと参照されていないレイヤーをすべて削除して、追加の容量を回復することもできます。

タグ付けされていないマニフェストと参照されていないレイヤーを削除する

デフォルトでは、コンテナレジストリのガベージコレクターはタグ付けされていないイメージを無視し、ユーザーはタグ付けされていないイメージをダイジェストでプルし続けることができます。また、ユーザーは将来、イメージに再度タグ付けして、GitLab UIとAPIで再び表示できるようにすることもできます。

タグ付けされていないイメージと、これらのイメージによって排他的に参照されるレイヤーに関心がない場合は、それらをすべて削除できます。registry-garbage-collectコマンドで-mフラグを使用します:

sudo gitlab-ctl registry-garbage-collect -m

タグ付けされていないイメージの削除について迷っている場合は、続行する前にレジストリデータをバックアップしてください。

ダウンタイムなしでガベージコレクションを実行する

コンテナレジストリをオンラインに保ちながらガベージコレクションを実行するには、レジストリを読み取り専用モードにし、組み込みのgitlab-ctl registry-garbage-collectコマンドをバイパスします。

コンテナレジストリが読み取り専用モードの場合、イメージをプルできますが、プッシュすることはできません。コンテナレジストリは、ガベージコレクションの全期間にわたって読み取り専用のままでなければなりません。

デフォルトでは、レジストリストレージパスは/var/opt/gitlab/gitlab-rails/shared/registryです。

読み取り専用モードを有効にするには、次の手順に従います:

1. /etc/gitlab/gitlab.rbで、読み取り専用モードを指定します:

   registry['storage'] = {
     'filesystem' => {
       'rootdirectory' => "<your_registry_storage_path>"
     },
     'maintenance' => {
       'readonly' => {
         'enabled' => true
       }
     }
   }

2. 保存してGitLabを再設定します:

   sudo gitlab-ctl reconfigure

   このコマンドは、コンテナレジストリを読み取り専用モードに設定します。

3. 次に、ガベージコレクションコマンドの1つをトリガーします:

   # Remove unreferenced layers
   sudo /opt/gitlab/embedded/bin/registry garbage-collect /var/opt/gitlab/registry/config.yml
   
   # Remove untagged manifests and unreferenced layers
   sudo /opt/gitlab/embedded/bin/registry garbage-collect -m /var/opt/gitlab/registry/config.yml

   このコマンドは、ガベージコレクションを開始します。完了までの時間は、レジストリデータサイズに比例します。

4. 完了したら、/etc/gitlab/gitlab.rbで、読み取り/書き込みモードに戻します:

   registry['storage'] = {
     'filesystem' => {
       'rootdirectory' => "<your_registry_storage_path>"
     },
     'maintenance' => {
       'readonly' => {
         'enabled' => false
       }
     }
   }

5. 保存してGitLabを再設定します:

   sudo gitlab-ctl reconfigure

スケジュールに従ってガベージコレクションを実行する

理想的には、レジストリが使用されていないときに、レジストリのガベージコレクションを週に1回定期的に実行する必要があります。最も簡単な方法は、週に1回定期的に実行される新しいcrontabジョブを追加することです。

/etc/cron.d/registry-garbage-collectの下にファイルを作成します:

SHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin

# Run every Sunday at 04:05am
5 4 * * 0  root gitlab-ctl registry-garbage-collect

タグ付けされていないマニフェストと参照されていないレイヤーを削除するには、-mフラグを追加することをおすすめします。

ガベージコレクションを停止する

ガベージコレクションを停止することを想定している場合は、ダウンタイムなしでガベージコレクションを実行するで説明されているように、ガベージコレクションを手動で実行する必要があります。その後、Control+Cを押して、ガベージコレクションを停止できます。

そうしないと、gitlab-ctlを中断すると、レジストリサービスがダウン状態になる可能性があります。この場合、gitlab-ctlコマンドでレジストリサービスを再び起動できるようにするために、システムでガベージコレクションプロセス自体を見つける必要があります。

また、プロセスのマークフェーズ中に進行状況や結果を保存する方法はありません。blobが削除され始めると初めて、永続的な処理が行われます。

継続的なゼロダウンタイムのガベージコレクション

メタデータデータベースに移行すると、ガベージコレクションのスケジュールを設定したり、読み取り専用モードを要求したりすることなく、バックグラウンドでガベージコレクションを実行できます。

コンポーネントごとのスケーリング

このセクションでは、コンポーネントごとにレジストリトラフィックが増加するに伴い、パフォーマンス上のボトルネックが発生する可能性について簡単に説明します。各サブセクションは、小さいレジストリワークロードに役立つものから大きいワークロードに役立つものへと至る、おおまかな推奨事項順に記載されています。レジストリはリファレンスアーキテクチャに含まれておらず、シート数または1秒あたりのリクエスト数を対象にしたスケーリングガイドはありません。

データベース

1. 別個のデータベースに移行する: データベースの負荷が増加するにつれて、レジストリのメタデータデータベースを別個の物理データベースに移動して、垂直方向にスケールしてください。別個のデータベースを使用すると、レジストリによって生成されるトラフィックを分離しながら、レジストリデータベースで使用できるリソースの量を増やすことができます。
2. HA PostgreSQLサードパーティソリューションに移行する: Praefectと同様に、評価の高いプロバイダーまたはソリューションに移行すると、HAが実現し、マルチノードレジストリデプロイが簡単になります。レジストリはネイティブのPostgresパーティション、トリガー、および関数を多用するため、これらをサポートするプロバイダーを選択する必要があります。

レジストリサーバー

1. 別個のノードに移行する: 別個のノードへの移行は、垂直方向にスケールして、コンテナレジストリのサーバープロセスで使用できるリソースを増やす方法の1つです。
2. ロードバランサーの背後で複数のレジストリノードを実行する: レジストリは1つの大きなノードで大量のトラフィックを処理できますが、レジストリは通常、複数のデプロイで水平にスケールするように設計されています。複数の小さなノードを設定すると、オートスケールなどの手法も有効になります。

Redisキャッシュ

Redisキャッシュを有効にすると、パフォーマンスが向上するだけでなく、リポジトリの名前変更などの機能も有効になります。

1. Redisサーバー: 単一のRedisインスタンスがサポートされています。これは、Redisキャッシュのメリットを利用する最も簡単な方法です。
2. Redis Sentinel: Redis Sentinelもサポートされており、キャッシュをHAにすることができます。
3. Redis Cluster: Redis Clusterは、デプロイの拡大に合わせて、さらにスケールするために使用することもできます。

ストレージ

1. ローカルファイルシステム: ローカルファイルシステムはデフォルトであり、比較的高いパフォーマンスを発揮しますが、マルチノードデプロイや大量のレジストリデータには適していません。
2. オブジェクトストレージ: オブジェクトストレージを使用して、大量のレジストリデータの実用的なストレージを実現します。オブジェクトストレージは、マルチノードレジストリデプロイにも適しています。

オンラインガベージコレクション

1. デフォルトを調整する: オンラインガベージコレクションがレビューキューを確実にクリアしない場合は、gc設定セクションのmanifestsおよびblobsセクションでinterval設定を調整できます。デフォルトは5sですが、たとえば500msのように、ミリ秒単位で設定することもできます。
2. レジストリサーバーで水平にスケールする: マルチノードデプロイでレジストリアプリケーションを水平方向にスケールしている場合、設定を変更する必要なしに、オンラインガベージコレクションは自動的にスケールします。

別々のノードでGitLabとレジストリを設定する（Linuxパッケージインストール）

デフォルトでは、GitLabパッケージは、両方のサービスが同じノードで実行されることを前提としています。サービスを別々のノードで実行するには、個別の設定必要です。

設定オプション

次の設定オプションは、それぞれのノードの/etc/gitlab/gitlab.rbで設定する必要があります。

レジストリノードの設定

GitLabノードの設定

ノードをセットアップする

別々のノードでGitLabとコンテナレジストリを設定するには、次の手順に従います:

1. レジストリノードで、次の設定を使用して/etc/gitlab/gitlab.rbを編集します:

   # Registry server details
   # - IP address: 10.30.227.194
   # - Domain: registry.example.com
   
   # Disable unneeded services
   gitlab_workhorse['enable'] = false
   puma['enable'] = false
   sidekiq['enable'] = false
   postgresql['enable'] = false
   redis['enable'] = false
   gitlab_kas['enable'] = false
   gitaly['enable'] = false
   nginx['enable'] = false
   
   # Configure registry settings
   registry['enable'] = true
   registry['registry_http_addr'] = '0.0.0.0:5000'
   registry['token_realm'] = 'https://<gitlab.example.com>'
   registry['http_secret'] = '<6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b>'
   
   # Configure GitLab Rails settings
   gitlab_rails['registry_issuer'] = 'omnibus-gitlab-issuer'
   gitlab_rails['registry_key_path'] = '/etc/gitlab/gitlab-registry.key'

2. GitLabノードで、次の設定を使用して/etc/gitlab/gitlab.rbを編集します:

   # GitLab server details
   # - IP address: 10.30.227.149
   # - Domain: gitlab.example.com
   
   # Configure GitLab URL
   external_url 'https://<gitlab.example.com>'
   
   # Configure registry settings
   gitlab_rails['registry_enabled'] = true
   gitlab_rails['registry_api_url'] = '<http://10.30.227.194:5000>'
   gitlab_rails['registry_host'] = '<registry.example.com>'
   gitlab_rails['registry_port'] = 5000
   gitlab_rails['registry_issuer'] = 'omnibus-gitlab-issuer'
   gitlab_rails['registry_key_path'] = '/etc/gitlab/gitlab-registry.key'

3. 両方のノード間で/etc/gitlab/gitlab-secrets.jsonファイルを同期します:

   1. ファイルをGitLabノードからレジストリノードにコピーします。
   2. ファイルの権限が正しいことを確認します。
   3. 両方のノードでsudo gitlab-ctl reconfigureを実行します。

コンテナレジストリのアーキテクチャ

ユーザーは、独自のDockerイメージをコンテナレジストリに保存できます。レジストリはクライアントに面しているため、レジストリはWebサーバーまたはロードバランサー（LB）に直接公開されます。

%%{init: { "fontFamily": "GitLab Sans" }}%%
flowchart LR
    accTitle: Container registry authentication flow
    accDescr: Shows how users authenticate with the container registry with GitLab API to push and pull Docker images

    A[User] --->|1: Docker loginon port 443| C{Frontend loadbalancer}
    C --->|2: connection attemptwithout token fails| D[Container registry]
    C --->|5: connect with token succeeds| D[Container registry]
    C --->|3: Dockerrequests token| E[API frontend]
    E --->|4:API returnssigned token| C

    linkStyle 1 stroke-width:4px,stroke:red
    linkStyle 2 stroke-width:4px,stroke:green

認証フローには、次の手順が含まれます:

1. ユーザーはクライアントでdocker login registry.gitlab.exampleを実行します。このリクエストは、ポート443でWebサーバー（またはLB）に到達します。
2. Webサーバーは、レジストリのバックエンドプールに接続します（デフォルトではポート5000）。ユーザーが有効なトークンを持っていないため、レジストリは401 Unauthorized HTTPコードと、トークンを取得するためのURLを返します。このURLは、レジストリ設定のtoken_realmによって定義され、GitLab APIを指します。
3. DockerクライアントはGitLab APIに接続して、トークンを取得します。
4. APIはレジストリキーでトークンに署名して、Dockerクライアントに送信します。
5. Dockerクライアントは、APIから受信したトークンを使用して再度ログインします。これで、認証されたクライアントはDockerイメージをプッシュおよびプルできるようになりました。

参照: https://distribution.github.io/distribution/spec/auth/token/

GitLabとコンテナレジストリ間の通信

コンテナレジストリはユーザーを内部的に認証できないため、GitLabを介して認証情報を検証します。レジストリとGitLab間の接続は、TLSで暗号化されています。

GitLabは秘密キーを使用してトークンに署名し、レジストリは証明書によって提供される公開キーを使用して署名を検証します。

デフォルトでは、自己署名証明書とキーのペアがすべてのインストールに対して生成されます。レジストリ設定のinternal_key設定を使用して、この動作をオーバーライドできます。

次の手順は、通信フローについて説明しています:

1. GitLabは、レジストリの秘密キーを使用してレジストリを操作します。レジストリリクエストが送信されると、有効期間の短い（10分）ネームスペース制限トークンが生成され、秘密キーで署名されます。
2. レジストリは、署名が、設定で指定されたレジストリ証明書と一致することを検証し、操作を許可します。
3. GitLabは、Sidekiqを介してバックグラウンドジョブを処理します。このとき、レジストリともやり取りします。これらのジョブはレジストリと直接通信して、イメージの削除を処理します。

サードパーティレジストリから移行する

GitLabでの外部コンテナレジストリの使用は、GitLab 15.8で非推奨となり、GitLab 16.0でサポートが終了しました。詳細については、非推奨に関する通知を参照してください。

このインテグレーションはGitLab 16.0で無効になっていませんが、問題のデバッグと修正のサポートは提供されなくなりました。また、このインテグレーションの開発は終了し、新機能で強化されなくなりました。新しいGitLabコンテナレジストリバージョンがGitLab Self-Managedで利用可能になった後（エピック5521を参照）、サードパーティレジストリ機能は完全に削除される可能性があります。GitLabコンテナレジストリのみがサポートされる予定です。

このセクションでは、サードパーティレジストリからGitLabコンテナレジストリに移行するための管理者向けガイダンスを提供します。使用しているサードパーティコンテナレジストリがここにリストされていない場合は、フィードバックイシューでユースケースについて説明してください。

以下のすべての手順については、まずテスト環境で試してみる必要があります。本番環境でレプリケートする前に、すべてが期待どおりに動作し続けることを確認してください。

Docker Distribution Registry

Docker Distribution RegistryはCNCFに寄贈され、現在はDistribution Registryとして知られています。このレジストリは、GitLabコンテナレジストリの基盤となるオープンソースの実装です。GitLabコンテナレジストリは、サポートされているすべてのストレージバックエンドを含む、Distribution Registryによって提供される基本機能と互換性があります。GitLabコンテナレジストリに移行するには、このページの手順に従い、Distribution Registryと同じストレージバックエンドを使用します。GitLabコンテナレジストリでは、Distribution Registryに使用しているのと同じ設定を使用できるはずです。

コンテナイメージ削除の最大再試行回数

コンテナイメージを削除するときにエラーが発生する可能性があります。そのため、エラーが一時的な問題ではないことを確認するために、削除が再試行されます。削除は最大10回再試行され、再試行間にはバックオフ遅延が適用されます。この遅延により、再試行の間隔を長くして、一時的なエラーを解決できるようにします。

また、再試行の最大回数を設定すると、再試行間で解決されていない永続的なエラーがあるかどうかを検出するのに役立ちます。削除が再試行の最大回数を超えると、コンテナリポジトリのstatusがdelete_failedに設定されます。このステータスになると、リポジトリは削除を再試行しなくなります。

delete_failedステータスのコンテナリポジトリを調査し、問題の解決を試みてください。問題が解決したら、リポジトリのステータスをdelete_scheduledに戻して、イメージが再び削除されるようにすることができます。リポジトリのステータスを更新するには、Railsコンソールから次のスクリプトを実行します:

container_repository = ContainerRepository.find(<id>)
container_repository.update(status: 'delete_scheduled')