Implement Registry Storage State Detection and Communication

Context

As part of the self-managed database rollout, we need a mechanism to determine the state of both the database and object storage currently configured. This information is crucial for automatic database enablement, particularly for distinguishing between fresh installations and those with existing metadata. See Enable the Container Registry Metadata Database... (omnibus-gitlab#8900) and Provide the container registry DB by default fo... (gitlab-org/charts/gitlab#5931 - closed)

Problem

The registry startup process performs various state checks, but these are in situ and not accessible outside the startup flow. We need a unified way to:

  • Detect metadata, namely tags, within the database
  • Detect if the database configured to be enabled or disabled
  • Detect metadata, namely lockfiles, within object storage
  • Make this information accessible to charts and omnibus tooling
  • Maintain consistency between startup and runtime checks

Impact

Improve the automation and reliability of container registry deployments by providing administrators with critical storage state information.

Proposal

We should determine which data to expose, we should coordinate with distribution, but a first pass would be something like this:

type StorageState struct {
    DatabaseConfigured      bool `json:"databaseConfigured"`
    DatabaseReachable      bool `json:"databaseReachable"`
    DatabaseHasMetadata    bool `json:"databasehasMetadata"`
    ObjectStorageConfigured bool `json:"objectStorageConfigured"`
    ObjectStorageReachable  bool `json:"objectStorageReachable"`
    ObjectStorageInUse      bool `json:"objectStorageInUse"`
}

Implementation Approaches

CLI Tooling

Extend the registry CLI with a command to check storage state, similar to other utility commands.

Pros
  • Consistent with existing tooling and patterns
  • Enables scripting and automation
  • Clear separation of concerns
  • Simple implementation path
  • Familiar to administrators
Cons
  • Requires CLI access
  • Not suitable for runtime monitoring
  • Limited integration options

New API Endpoint

Extend the GitLab V1 API with a new endpoint for the database status.

Pros
  • Real-time status availability
  • Native monitoring integration
  • Programmatic access
Cons
  • Additional security considerations
  • Increased API surface area
  • Extra authentication requirements

Status File

Implements storage state detection by periodically writing state information to a status file. This would be enabled/disabled via configuration changes to the registry.

Pros
  • Automatic periodic updates
  • Low implementation complexity

Cons:

  • Less flexible than other options
  • Potential stale data
  • Admins could disable this, reducing the reliability of state detection
  • Unclear where to write the file
Edited by Hayley Swimelar