Container Registry Metadata Database: Knowledge Transfer Resources

A streamlined compilation of documentation, blog posts, demos, and technical resources for understanding and implementing the Container Registry metadata database feature.

Blog Posts and Articles

Next-generation GitLab container registry goes GA

URL: https://about.gitlab.com/blog/next-generation-gitlab-container-registry-goes-ga/
Official GA announcement for GitLab 17.3. Covers beta program results, storage cost savings, zero-downtime garbage collection, and roadmap including protected repositories and immutable tags.

GitLab's next-generation container registry is now available

URL: https://about.gitlab.com/blog/gitlabs-next-generation-container-registry-is-now-available/
Beta program announcement explaining why the legacy registry had limitations and documenting that offline garbage collection on GitLab.com would have taken 64 days. Introduces the new PostgreSQL-backed system.

Introducing the next generation of the GitLab.com Container Registry

URL: https://about.gitlab.com/blog/next-generation-container-registry/
GitLab.com Phase 2 migration announcement explaining the PostgreSQL backend and automatic online garbage collector that removes untagged images after 24 hours.

Announcing an exciting update to the GitLab.com Container Registry

URL: https://about.gitlab.com/blog/gitlab-com-container-registry-update/
Original announcement explaining the core problem with Docker Distribution's design and introducing the PostgreSQL solution with phased migration approach.

GitLab Package roadmap for 2024

URL: https://about.gitlab.com/blog/gitlab-package-roadmap-for-2024/
Strategic overview of Package stage direction, including 2024 focus on making container registry GA for self-managed with performance/reliability improvements.

Demo Videos and Presentations

Ops Showcase: Moving to Next-Generation Container Registry with Minimal Downtime

Video: https://youtu.be/aZdyYrKdtxk
Issue: gitlab-org/ci-cd/section-showcases#44 (closed)
Demonstrates the 3-step import process for migrating to metadata database with minimal downtime. Technical focus for Ops teams.

Cloud Native Talks: Container Registries Are Not Just for Containers

Event: https://community.cncf.io/events/details/cncf-malaga-presents-cloud-native-talks-container-registries-are-not-just-for-containers/
Explains what a container image is and how the registry API works using Docker and manual HTTP requests. Technical overview suitable for education.

Architecture and Design Documentation

Container Registry Metadata Database Architecture Blueprint

URL: https://docs.gitlab.com/ee/architecture/blueprints/container_registry_metadata_database
Comprehensive technical overview of the metadata database design explaining rationale and architecture decisions. Essential for understanding the "why" behind the feature.

Container Registry Self-Managed Database Rollout

URL: https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/container_registry_metadata_database_self_managed_rollout/
Design document for bringing metadata database to self-managed users. Documents strategy to unify registry experience across GitLab.com and self-managed.

Database Development Guidelines

URL: https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs-gitlab/database-dev-guidelines.md
Best practices for database development in the registry.

Database Migrations Guide

URL: https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs-gitlab/database-migrations.md
How to create and manage database migrations in the registry.

Push/Pull Request Flow

URL: https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs-gitlab/push-pull-request-flow.md
Documents how clients interact with the registry.

Authentication Flow

URL: https://gitlab.com/gitlab-org/container-registry/-/blob/master/docs-gitlab/auth-request-flow.md
JWT token authentication with metadata database.

Administration Documentation

Container Registry Metadata Database (Omnibus)

URL: https://docs.gitlab.com/ee/administration/packages/container_registry_metadata_database/
Complete guide for enabling and managing metadata database. Covers prerequisites, one-step vs three-step import methods, online garbage collection, external database configuration, backup considerations, and troubleshooting.

Container Registry Metadata Database (New Install)

URL: https://docs.gitlab.com/ee/administration/packages/container_registry_metadata_database_new_install
Guide for enabling metadata database on new registries with default database configuration for GitLab 17.3+.

Container Registry Metadata Database (Helm Charts)

URL: https://docs.gitlab.com/charts/charts/registry/metadata_database/
Kubernetes-specific deployment guide with database configuration YAML, load balancing, online GC settings, and Redis cache configuration.

Container Registry Administration

URL: https://docs.gitlab.com/ee/administration/packages/container_registry
General overview of container registry features, garbage collection (legacy vs online), and storage configuration.

Using Geo with Container Registry

URL: https://docs.gitlab.com/ee/administration/packages/container_registry/using_geo_with_the_container_registry
Geo setup with metadata database including separate database/storage requirements per site and replication configuration.

Container Registry Troubleshooting (Admin)

URL: https://docs.gitlab.com/administration/packages/container_registry_troubleshooting/
Debug server, Prometheus metrics, certificate issues, AWS S3 errors, and IPv6 problems.

Container Registry Troubleshooting (User)

URL: https://docs.gitlab.com/user/packages/container_registry/troubleshoot_container_registry/
Common user-facing issues and resolutions.

User-Facing Documentation

Delete Container Registry Images

URL: https://docs.gitlab.com/ee/user/packages/container_registry/delete_container_registry_images.md#garbage-collection
Explains online garbage collection as a metadata database feature with automatic cleanup behavior.

Protected Container Tags

URL: https://docs.gitlab.com/ee/user/packages/container_registry/protected_container_tags
Feature enabled by metadata database allowing regex-based protection rules with role-based permissions.

Immutable Container Tags

URL: https://docs.gitlab.com/ee/user/packages/container_registry/immutable_container_tags
Beta feature preventing tag modification/deletion, requires metadata database.

Reduce Container Registry Storage

URL: https://docs.gitlab.com/ee/user/packages/container_registry/reduce_container_registry_storage.md#view-container-registry-usage
Storage usage visibility and cleanup policies enabled by metadata database.

Technical Issues and Feedback

Feedback Issue: Next Generation Container Registry Rollout

URL: gitlab#423459
Real-world import times from various registry sizes (100 GiB to 609 TiB) with downtime windows, total import times, and storage backend comparisons. Critical data for planning migrations.

Design: In Place Migration Procedure

URL: #884 (closed)
Technical design of the 3-step import process.

Operational Readiness Review

URL: #1537
Production readiness assessment for the metadata database feature.

Post-Deployment Migrations

URL: #1516 (closed)
Database schema migration strategy separated from import process.

Migration Decoupling

URL: #1521 (closed)
Separating import from schema migrations for operational flexibility.

Include a Default Database for Container Registry

URL: gitlab#480742 (closed)
Automatic database provisioning for GitLab 17.8+ simplifying systems administration.

Backup and Restore Not Considering Metadata Database

URL: gitlab#532507
Known limitation requiring manual backup procedures until automated backup integration is complete.

Key Epics

Release Container Registry with Metadata Database and Online GC (Self-Managed)

URL: &5521
Main rollout epic tracking the entire journey from beta to required migration.

Dedicated: Container Registry Metadata Database Rollout

URL: gitlab-com/gl-infra/gitlab-dedicated&723
GitLab Dedicated-specific rollout currently in 180-day rollout phase.

Geo Support for Next Generation Container Registry

URL: &15325
Tracking Geo-specific implementation and testing.

Test and Improve Container Registry Offline Migration Tool

URL: &8602
Ongoing improvements to migration tooling.

Additional Resources

Stage Direction - Package

URL: https://about.gitlab.com/direction/package/
Product direction page with mission to eliminate artifact management complexity and competitive positioning.

Package: Container Registry Group Handbook

URL: https://handbook.gitlab.com/handbook/engineering/development/ops/package/container-registry/
Team structure, working agreements, and project ownership.

GitLab Environment Toolkit (GET) Support

URL: https://gitlab.com/gitlab-org/gitlab-environment-toolkit/-/issues/877
GET integration for automated database provisioning, critical for GitLab Dedicated automation.

GitLab.com Production Runbooks

URL: https://runbooks.gitlab.com/registry/gitlab-registry/
SRE operational runbooks including database connection pool management, index bloat, load balancing, and online GC operations.

Quick Reference: Key Requirements

Minimum Version: GitLab 17.5+ (18.3+ recommended)
Database: PostgreSQL 12+
Status: GA, opt-in (off by default)
Migration: One-step or three-step process
Import Speed: 2-4 TB per hour reported
GC Behavior: Online, unreferenced content deleted after 24 hours
Backup: Manual backup required (not in standard GitLab backup)
Geo: Requires separate database per site
Legacy Deprecation: Target GitLab 19.0