<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Collaborate/take over this issue](https://contributors.gitlab.com/manage-issue?action=work&projectId=278964&issueIid=458440) </details> <!--IssueSummary end--> <!-- * Use this issue template for suggesting new docs or updates to existing docs. Note: Doc work as part of feature development is covered in the Feature Request template. * For issues related to features of the docs.gitlab.com site, see https://gitlab.com/gitlab-org/gitlab-docs/issues/ * For information about documentation content and process, see https://docs.gitlab.com/ee/development/documentation/ --> ### Problem to solve <!-- Include the following detail as necessary: * What product or feature(s) affected? * What docs or doc section affected? Include links or paths. * Is there a problem with a specific document, or a feature/process that's not addressed sufficiently in docs? * Any other ideas or requests? --> #### What product or feature(s) affected? ~"Category:Geo Replication" ~"Category:Container Registry" #### What docs or doc section affected? https://docs.gitlab.com/ee/administration/geo/replication/container_registry.html #### Is there a problem with a specific document, or a feature/process that's not addressed sufficiently in docs? The current Geo documentation for container registry does not address the new [metadata database](https://docs.gitlab.com/ee/administration/packages/container_registry.html#container-registry-metadata-database), which is currently being rolled out to self-managed: https://gitlab.com/groups/gitlab-org/-/epics/5521+ ### Further details <!-- * Any concepts, procedures, reference info we could add to make it easier to successfully use GitLab? * Include use cases, benefits, and/or goals for this work. * If adding content: What audience is it intended for? (What roles and scenarios?) For ideas, see personas at https://handbook.gitlab.com/handbook/product/personas/ or the persona labels at https://gitlab.com/groups/gitlab-org/-/labels?subscribed=&search=persona%3A --> This documentation should address: - setting up a secondary site for a primary site which is already using the registry metadata database - migrating both sides of an existing geo site to the new registry database - general setup guidelines #### Impact Enable geo-distributed GitLab deployments to use the new container registry metadata database, ensuring consistent replication across sites while maintaining data integrity. ### Proposal <!-- Further specifics for how can we solve the problem. --> #### Setting up a secondary site for a primary site which is already using the registry metadata database All that needs to be done in this instance is for the new secondary site to come up with the database already enabled. The key here is to avoid syncing from a primary using the database to a secondary, which is not because database backed registries have more API endpoints than object storage metadata registries and therefore cannot be synced in this direction. #### Migrating an Existing Geo deployment This would require breaking replication, and migrating each site independently before reconnecting them. Migration documentation can be found for [charts](https://docs.gitlab.com/charts/charts/registry/index.html#database) and [omnibus](https://docs.gitlab.com/ee/administration/packages/container_registry_metadata_database.html) #### General Setup Guidelines For the container registry database, there needs to be a 1:1 relationship between databases and backend object storage for registry blobs. If each site has its own object storage for registry, each site needs a separate database. If each site uses the same object storage for both registries, then there should be a single database for that object storage. ### Who can address the issue <!-- What if any special expertise is required to resolve this issue? --> The expertise required for this is both Geo and container registry. ### Other links/references <!-- E.g. related GitLab issues/MRs -->