Artifact Registry ADR 010: データ保持

コンテキスト

Artifact Registry は、補完的な 2 つのメカニズムでデータを管理します。

1. 保持 (Retention): アーティファクトの最大寿命を設定する、時間ベースの有効期限切れ
2. クリーンアップ (Cleanup): データを削除する能動的なプロセス（ライフサイクルポリシー、ガベージコレクション）

これらのメカニズムは独立して動作します。保持はアーティファクトが削除対象となる時点を定義し、クリーンアップが削除を実行します。

削除の優先順位

複数のメカニズムが同じアーティファクトに適用される場合、次の優先順位によって動作が決まります。

すべての削除パスはソフト削除を経由します。これにより、削除トリガーにかかわらず一貫した復元期間が提供され、バグや誤設定された保持期間から保護されます。ガベージコレクションは、ソフト削除期間が満了した後にソフト削除されたアーティファクトを永久に削除します。

アーティファクト保持

保持は、アーティファクトがアクセスされずに存在できる最大時間を定義します。

デフォルト保持期間

365 日間使用されなかったアーティファクトは自動的に削除されます。このデフォルトは無制限なストレージ増加を防ぎ、より長い保持を必要とする顧客には（後述の）延長メカニズムで対応します。この Organization レベルのデフォルトは次のとおりです。

• タグやライフサイクルポリシーにかかわらず、すべてのアーティファクトに適用される
• 下限として機能する。ライフサイクルポリシーはより早く削除できるが、この上限を超えて保持を延長することはできない
• アーティファクトがダウンロードされるとリセットされる

Organization 管理者はデフォルトの期間を調整できます。明示的に変更されない限り、365 日という値が適用されます。

保持の延長

デフォルトでは、すべてのリポジトリは厳格な強制を通じて Organization の保持ポリシーに準拠しなければなりません。Organization Owner は、オプションで次を有効にできます。

• リポジトリレベルの例外: リポジトリが Organization のデフォルトを超えて保持を延長できるようにする
• 無期限保持: 重要なアーティファクトを無期限に保持できるようにする

これらのメカニズムは、複数年の保持が求められる規制業界（例: SOX や HIPAA）向けに設計されています。

ライフサイクルポリシー

ライフサイクルポリシーは、特定の条件に一致するアーティファクトを能動的に削除する、ユーザー定義のルールです。デフォルトの保持期間よりも積極的なクリーンアップを実行します。

• ライフサイクルポリシーは、保持期間が満了する前にアーティファクトを削除できる
• 保持は、ライフサイクルポリシーが見逃したり無視したりしたアーティファクトを削除する
• いずれのメカニズムも、破棄されたアーティファクトを復活させることはできない

サポートされる戦略

ライフサイクルポリシーは 保持セマンティクスのみ を使用します。パターンは保持対象を定義し、一致しないものはすべて削除対象となります。これにより、保持/期限切れのルールが競合する複雑さを回避します。これはコンテナレジストリのクリーンアップポリシーから得た 教訓 です。

アーティファクトのターゲティング

パターンマッチングは、アクセスルールや仮想リポジトリフィルターと共有する一貫したターゲティングモデルを使用します。各ポリシールールは パターン と ターゲットフィールド を指定します。利用可能なターゲットフィールドはアーティファクトの種類によって異なります。

ポリシーは、単一のルール内で複数のターゲットフィールドを組み合わせることができます（例: 名前が release-* に一致し、かつバージョンが v* に一致するアーティファクトを保持する）。ライフサイクルポリシー、アクセスルール、仮想リポジトリの許可/拒否フィルターで同じターゲティングモデルを使用することで、実装の再利用と一貫したユーザー体験を実現します。

ソフト削除

ソフト削除は常に有効であり、ユーザーが設定することはできません。すべての削除（手動、ライフサイクルポリシー、保持期限切れ）は、アーティファクトを即座に削除するのではなく、削除対象としてマークします。ユーザーはハード削除期間が満了するまで、ソフト削除されたアーティファクトを復元できます。これは GitLab のプロジェクト遅延削除から得た 教訓 です。そこではソフト削除をオプションにしたことで、誤って永久にデータが失われる事態が発生しました。

ソフト削除されたアーティファクトを UI に表示するかどうかは、保持の問題ではなく表示の問題です。

通知

Artifact Registry は、アーティファクトが削除に近づくとユーザーに通知します。

重要なアーティファクトをダウンロードしたり保持を延長したりする時間をユーザーに与えるため、保持期限切れの 30 日前までに最低限の事前通知を強制すべきです。正確な通知チャネルと表示場所は UX 設計時に定義します。

仮想リポジトリのキャッシュ

仮想リポジトリは、上流レジストリからパッケージをキャッシュします。キャッシュされたコンテンツには、ホスト型アーティファクトとは別の保持およびクリーンアップルールがあります。

キャッシュ有効性

各上流には、キャッシュされたメタデータをいつ更新する必要があるかを決定する、設定可能な有効期間があります。デフォルト: 24 時間。これは陳腐化を制御するもので、削除を制御するものではありません。

イミュータブルなアーティファクトを持つことが分かっているレジストリにリンクされた一部の上流では、ユーザーが指定しない限り、キャッシュ有効期間設定が自動的に無効化されます。

キャッシュ保持

7 日間使用されなかったキャッシュ済みアーティファクトは自動的に削除されます。キャッシュされたコンテンツは上流から再取得できるため、これはホスト型アーティファクトの保持よりも積極的です。

キャッシュ保持は Organization レベルで設定され、デフォルトで有効です。

監査ログの保持

監査ログは、セキュリティに関連する操作を記録します。

削除の監査エントリには、デバッグとコンプライアンス調査を支援するため、トリガー（手動、ライフサイクルポリシー、保持期限切れ、またはガベージコレクション）を記録しなければなりません。

バックグラウンドジョブが、保持期間を超えたログを削除します。

ガベージコレクション

ガベージコレクションは、Organization の重複排除されたストレージプール内の孤立したデータを削除します（ADR-002 を参照）。保持やライフサイクルポリシーとは異なり、ガベージコレクションは設定できません。

Blob クリーンアップ

各 Organization には独自の blob ストレージプールがあります。blob は、その Organization 内のどのアーティファクトからも参照されていない場合にのみ削除されます。

1. アーティファクトを削除すると、そのアタッチメントレコードが削除される
2. バックグラウンドジョブが、Organization 内でアタッチメント数がゼロの blob を見つける
3. ジョブが、blob レコードと物理ファイルの両方を削除する

孤立した blob は 24 時間以内に削除されます。この遅延は、トランザクションのロールバック、同時アップロード、バッチ操作に対応するためのものです。

ソフト削除の期限切れ

バックグラウンドジョブが、ソフト削除されたアーティファクトを 30 日後に永久に削除します。この期間は、復元時間とストレージコストのバランスを取ります。

安全な廃棄

すべての永久削除（blob クリーンアップ、ソフト削除の満了、保持期限切れ）は、Records Retention & Disposal ポリシーに従い、ストレージプロバイダーのセキュアな削除メカニズムに依存します。オブジェクトストレージの場合、これはプロバイダーの API（例: GCS や S3 のオブジェクト削除）を通じて物理ファイルが削除されることを意味します。データベースレコードは PostgreSQL からハード削除されます。削除自体の監査ログエントリは、この ADR で定義された監査ログ保持期間に従って保持されます。

バックアップ保持

Artifact Registry の PostgreSQL データベースとオブジェクトストレージのバックアップ保持はプラットフォームの責任であり、デプロイメントの標準的なバックアップポリシーに従います。

• GitLab.com (SaaS): GitLab の既存のデータベースおよびオブジェクトストレージのバックアップスケジュールに従う
• Dedicated/Self-Managed: バックアップ保持はデプロイメント管理者が設定する

バックアップには、保持ポリシー、ライフサイクルポリシー、またはガベージコレクションによってすでに削除されたアーティファクトが含まれている場合があります。バックアップからの復元により、以前に削除されたアーティファクトが再導入される場合があります。これは想定される動作であり、通常の保持/クリーンアップサイクルがそれらを再処理します。

ストレージクラスの遷移

ストレージクラス管理は プラットフォームの責任 です。Artifact Registry はストレージクラスを操作しません。デプロイメント管理者は、サポートされている場合に、ストレージプロバイダー側で移行を設定します。サービスは、ストレージクラスにかかわらず、アーティファクトを参照および操作できます。

ストレージクラスの移行は、保持やクリーンアップとは独立しています。

• Archive ストレージ内のアーティファクトも、保持上限とライフサイクルポリシーの対象となる
• ソフト削除されたアーティファクトは、ガベージコレクションまでストレージクラスを保持する
• 仮想リポジトリのキャッシュは、同じ移行スケジュールに従う

遷移スケジュール

オブジェクトは、現在のストレージクラスにかかわらず、アクセスされると即座に Standard ストレージに移行します。

プラットフォーム設定

デプロイメント管理者は、インフラレベルでストレージクラスの移行を有効にします。

GitLab.com の場合、GCS Autoclass は次を提供します。

• アクセスパターンに基づく自動移行
• 取り出し料金なし（Autoclass 料金に含まれる）
• 早期削除料金なし

横断的な懸念

マルチリージョンレプリケーション

保持ポリシー、ライフサイクルポリシー、またはガベージコレクションによってアーティファクトが削除された場合、その削除はすべてのレプリカに伝播されなければなりません。レプリケーションメカニズム（マルチリージョンレプリケーションであれ他の手法であれ、マルチリージョナリティの方向性 を参照）は、ストレージのドリフトや陳腐化したデータを避けるため、削除された blob とメタデータがすべてのレプリカから確実に削除されるようにしなければなりません。

エクスポートとインポート

GitLab のプロジェクトのエクスポート/インポートは、Artifact Registry に保存されたアーティファクトを参照する場合があります。エクスポート前に保持またはライフサイクルポリシーによってアーティファクトが削除されていた場合、エクスポートは欠落したアーティファクトを適切に処理すべきです（例: 失敗するのではなく、それらを除外して省略をログに記録する）。

サブスクリプションの期限切れ

Artifact Registry はプレミアム SKU のアドオンです。顧客の サブスクリプションが期限切れ になると、データは既存の ソフト削除 と ガベージコレクション メカニズムを再利用する 4 つのフェーズのライフサイクルに従います。

namespace の slug（registry handle）はこれらのフェーズに従い、ハード削除時に永久に廃止されます。ソフト削除期間内の再取得を含む slug 固有のセマンティクスについては、ADR-015: Slug Policy (internal) を参照してください。

通知は、通知 セクションで定義されたフレームワークと同じものに従います。

• サブスクリプション期限切れ時: 14 日後に書き込みブロックへ移行予定
• 書き込みブロックフェーズ終了の 14 日前: まもなくソフト削除予定
• ソフト削除期間終了の 14 日前: まもなく永久削除予定

このタイムラインは、既存の GitLab アドオンの前例よりも寛大です。GitLab Duo アドオンは、期限切れ後にシート割り当てを 28 日間保持 してから削除しますが、機能は即座に利用できなくなります。標準的な GitLab サブスクリプションの期限切れ では、即座に無料ティアにダウングレードされます。Artifact Registry の延長されたタイムラインは、2 つの要因を反映しています。第 1 に、（GitLab Duo のような）ステートレスな機能とは異なり、Artifact Registry は再作成できない顧客データを保存しており、読み取りアクセスを失うと本番デプロイが壊れる可能性があります。第 2 に、GitLab のコアプラットフォームとは異なり、Artifact Registry にはフォールバックできる無料ティアがありません。期限切れは、機能低下した体験ではなく、アクセスの完全な喪失を意味します。

このセクションは、非自発的な期限切れ（更新の失効）を対象としています。顧客が能動的にオプトアウトし、退出のタイムラインを自ら制御する意図的なキャンセルは、別のオフボーディングパスを必要とする場合があります。これは #593942 で追跡されています。

依存機能

CI パイプライン、マージリクエスト、その他の GitLab の機能は、Artifact Registry が管理するアーティファクトを参照する場合があります。保持またはライフサイクルポリシーがこれらのアーティファクトを削除した場合、参照を保持しているサービスまたはアプリケーション が、欠落したアーティファクトを適切に処理する責任を負います。

• 削除されたアーティファクトへのリンクは、汎用的なエラーではなく、明確なメッセージを表示すべき
• 削除されたアーティファクトに対する API レスポンスは、適切なステータスコードを返すべき
• ソフト削除されたアーティファクトは、ハード削除まで（「削除予定」インジケーター付きで）解決可能であり続けるべき

Artifact Registry は、アーティファクトが削除されても、依存する機能に能動的に通知しません。依存サービスは、クエリ時に参照を解決し、欠落したアーティファクトをそれに応じて処理します。イベント駆動のアプローチ（例: 関心のあるサブスクライバー向けに削除イベントを発行する）は将来の改善候補ですが、この ADR のスコープ外です。

帰結

ポジティブ

• 予測可能なコスト: デフォルトの有効期限切れが、無制限なストレージ増加を防ぐ
• 自動的なコスト最適化: ストレージクラスの移行が、手動の介入なしに古いアーティファクトのコストを削減する
• 柔軟性: Organization とリポジトリのオーバーライドが、多様なニーズに対応する
• 復元能力: ソフト削除が、誤った削除から保護する
• コンプライアンスサポート: 設定可能な保持が、規制要件を満たす
• キャッシュ効率: TTL ベースの管理が、鮮度とストレージのバランスを取る

ネガティブ

• オンボーディングの摩擦: ユーザーは、予期しない削除を避けるために、デフォルトの有効期限切れを理解する必要がある
• 複雑さ: 複数の保持レベル（Organization、リポジトリ、ルール）には明確なドキュメントが必要
• バックグラウンド負荷: クリーンアップジョブが追加のリソースを消費する

検討した代替案

公開前の明示的なポリシーを必須にする

ユーザーは、アーティファクトを公開する前にライフサイクルポリシーを設定しなければなりません。

トレードオフ: 偶発的なストレージ増加を防ぎますが、オンボーディングの摩擦が増え、採用を妨げる可能性があります。

デフォルトで無期限保持

明示的に削除されない限り、アーティファクトは永久に存続します。

却下した理由: 無制限なストレージ増加とコストの予期しない急増を招きます。ほとんどのユーザーはクリーンアップポリシーの設定を忘れ、結果として陳腐化したアーティファクトが蓄積されます。

参考文献

• ADR-001: アンカーポイントとしての組織

• ADR-007: データベーススキーマ - ライフサイクルポリシーと blob クリーンアップ
• GitLab 監査イベントドキュメント
• GCS Autoclass - 自動ストレージクラス移行
• GCS Storage Classes - Standard、Nearline、Coldline、Archive
• Records Retention & Disposal - 記録の保持とセキュアな廃棄に関する GitLab のセキュリティポリシー
• Data Retention Guidelines for Feature Development - 新機能におけるデータ保持に関するアーキテクチャガイドライン
• Competitive analysis (internal)

ページのソースコードを見る - ページの編集 - please contribute.