This epic tracks the comprehensive rollout of the Container Registry Metadata Database with online garbage collection for GitLab self-managed installations. The rollout follows a phased approach from dedicated environments through to full automation for all self-managed deployments. ### Overview The Container Registry Metadata Database enables online garbage collection, eliminating the need for maintenance windows during cleanup operations. This epic coordinates work across multiple domains: dedicated rollout, policy changes, code changes, self-managed automation, and monitoring. ### Rollout Strategy The rollout follows a dependency-driven approach, ensuring stability and reliability at each phase: - **Self-Managed Automation** - Provide database provisioning and migration tools - **Monitoring & Adoption** - Track migration statistics and user adoption rates - **Dedicated Environment Support** - Complete rollout in dedicated environments with Geo support and stability improvements - **Policy Changes** - Establish deprecation policies and default enablement strategies - **Code Modernization** - Implement database-native features and remove (or quarantine) legacy components ```mermaid gantt title Container Registry Metadata Database Rollout - Main Phases dateFormat YYYY-MM-DD axisFormat %Y-%m section Dedicated Dedicated Rollout :dedicated, after stab, 180d GEO Support :geo, 2025-08-22, 90d Stability and Reliability Improvements :stab, after stats, 180d GET Support :get, after geo, 60d section Self-Managed Automation Self-Managed Automation Work :automation, 2025-07-01, 2025-08-21 section Monitoring Improved Migration Statistics :stats, 2025-07-01, 2025-09-18 Low % Self-Managed Instances on Database :lowper, after stats, 180d High % Self-Managed Instances on Database :highper, after lowper, 400d section Policy Changes Deprecate Object Storage Metadata :osmd, 2025-08-22, 30d Enabled by Default :ebd, 2026-05-21, 30d Require the Database :obd, 2027-05-21, 30d section Code Changes Code Changes :code, 2025-07-01, 2027-06-21 ``` ### Success Criteria - [ ] Dedicated rollout completed with full Geo support - [ ] Database preconfigured in Omnibus and Charts deployments - [ ] Automatic database migrations implemented - [ ] High percentage of self-managed users migrated to database - [ ] Object storage metadata deprecated and removed ### This approach ensures a controlled, data-driven rollout that maintains system stability while progressively modernizing the container registry codebase. <details> <summary>Legacy Project Phase Breakdown</summary> #### Off by default (beta) * Users with existing non-database registry deployments may choose to manually migrate to the metadata database. * Users standing up a new deployment may **enable** the database from the start, avoiding the need to migrate. #### Bring Your Own Database **This is the current phase.** In this phase, we will have GA support for users who are willing and able to provide and administer their own database for container registry. In brief, this phase means the core user experience of the registry metadata database is stable and reliable, but is missing convience and quality of life features. Below, the goals and non goals for reaching this point are listed. The goals are what we need to have inplace to officially call this feature GA. The non goals are to clarify what will not be present or required at the start of GA support for bringing your own database, however, these features maybe added later. ##### Goals * Import Process is free of known bugs * Import Documentation Reflects known best practices and addresses feedback from the beta program * Registry API and online GC Operations are stable and reliable * Three step import for Charts deployments * Registry Database as an opt-In optional improvement ##### Non Goals * Automatic provisioning of the registry database * Automatic or Integrated registry database migrations * Automatic import of object storage data * Geo Support * Requiring usage of the database [Open Issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=created_date&state=opened&label_name%5B%5D=Container%20Registry%20Self-Managed%20Rollout%3A%3ABlocks%3A%3AOff%20by%20Default&first_page_size=20)\ [MRs](https://gitlab.com/groups/gitlab-org/-/merge_requests?scope=all&state=all&label_name%5B%5D=Container%20Registry%20Self-Managed%20Rollout%3A%3ABlocks%3A%3AOff%20by%20Default) #### On by default * Users with existing non-database registry deployments may choose to manually migrate to the metadata database. * Users standing up a new deployment may **disable** the database, choosing to migrate later. [Open Issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=created_date&state=opened&label_name%5B%5D=Container%20Registry%20Self-Managed%20Rollout%3A%3ABlocks%3A%3AOn%20by%20Default&first_page_size=20)\ [MRs](https://gitlab.com/groups/gitlab-org/-/merge_requests?scope=all&state=all&label_name%5B%5D=Container%20Registry%20Self-Managed%20Rollout%3A%3ABlocks%3A%3AOn%20by%20Default) #### Required Migration * Users with existing non-database registry deployments must migrate to the metadata database before upgrading * Users standing up a new deployment **must** use the database. * The enable/disable configuration for the database will be removed in GitLab 19. [Open Issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=created_date&state=opened&label_name%5B%5D=Container%20Registry%20Self-Managed%20Rollout%3A%3ABlocks%3A%3ARequired%20Migration&first_page_size=20)\ [MRs](https://gitlab.com/groups/gitlab-org/-/merge_requests?scope=all&state=all&label_name%5B%5D=Container%20Registry%20Self-Managed%20Rollout%3A%3ABlocks%3A%3ARequired%20Migration) #### Post-Deployment migrations Like GitLab Rails, the registry supports both regular schema and post-deployment migrations. For those concerned about downtime during upgrades, starting in GitLab 17.10, you can now skip post-deployment migrations during the upgrade process and apply them manually after the application starts. This helps prevent unexpected delays during upgrades caused by long-running PDMs, giving you more control over maintenance windows. Updated documentation: * Linux package installations: https://docs.gitlab.com/administration/packages/container_registry_metadata_database/#database-migrations * Helm chart installations: https://docs.gitlab.com/charts/charts/registry/metadata_database/#database-migrations #### New Features Enabled by the Database This phase runs concurrently with all other phases and indicates that we will make improvements to the registry that take advantage of the new database during the beta rollout. Not only will we add new features for SAAS and self-managed users, we will also begin looking towards the future where there is no filesystem metadata. This means that we will be take full advantage of the database and remove the large and significantly complex portion of the registry codebase dedicated to filesystem metadata once the rollout is complete. Removing this code allows us to refine our focus, increase the ease of onboarding new contributors to the registry codebase, and significantly reduce the size of the mental model needed to understand the registry on a deep level. [Open Issues](https://gitlab.com/groups/gitlab-org/-/issues/?sort=created_date&state=opened&label_name%5B%5D=Container%20Registry%20Self-Managed%20Rollout%3A%3AEnabled%20by%20Database&first_page_size=20)\ [MRs](https://gitlab.com/groups/gitlab-org/-/merge_requests?scope=all&state=all&label_name%5B%5D=Container%20Registry%20Self-Managed%20Rollout%3A%3AEnabled%20by%20Database) </details> <!-- triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION --> > [!important] > This page may contain information related to upcoming products, features and functionality. > It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. > Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc. <!-- triage-serverless v3 PLEASE DO NOT REMOVE THIS SECTION -->