Expose registry `/gitlab/v1/admin/db/migration/status` endpoint

Endpoint

GET /gitlab/v1/admin/db/migrations/status

Description:

This API will return a detailed summary of the migration status for the Container Registry. It includes:

  • The version of the container registry
  • The count of applied schema migrations.
  • The count of pending schema migrations (with distinctions between post-deployment and non-post-deployment).
  • The count of active, paused, failed, and completed background migrations.

The response is intended for via Gitlab rails to help communicate to GitLab administrators the status of migrations related to the Container Registry in the Health Check Section

Authentication

This endpoint is accessible only through Gitlab rails which should only be able to call the endpoint once a user accessing the Health Check Section has been authenticated as an administrator. To gate the endpoint on the registry side we will need a dedicated token that can be minted by Gitlab rails alone for administrators and can be verified by registry. Similar to the v2/catalog endpoint token that is created for admins in: https://gitlab.com/gitlab-org/gitlab/-/blob/669500433f9a4ba36ee97c1f98d97529c2557f07/app/services/auth/container_registry_authentication_service.rb#L185 , we want to issue an admin token for migrations. The proposed token is exactly the same as the catalog token but with the access.name attribute as migrations rather than catalog:

Proposed Admin Token spec

{
  "auth_type": "...",
  "access": [
    {
      "type": "registry",
      "name": "migrations",
      "actions": [
        "*"
      ],
    }
  ],
  "jti": "2f7be39f-4572-4321-9f0b-56fa5c334a35",
  "aud": "container_registry",
  "sub": "admin_user",
  "iss": "...",
  "iat": 1691301347,
  "nbf": 1691301342,
  "exp": 1691302247
}
  • access:
    • The type is set to "admin", indicating this token is for admin-level operations.
    • The name is set to "container_registry_migrations", which indicates that this token is specifically for accessing migration-related operations for the Container Registry.
    • The actions array contains "read", meaning the token allows the holder to read migration status.
    • The meta field includes role: "administrator", specifying that the user is an administrator.
    • sub: Refers to the admin user ("admin_user" is a placeholder for the actual admin user identifier).

Response

The response will be a JSON object containing the status of both schema migrations and background migrations.

{
  "version": "v4.13.0-gitlab",
  "schema_migrations": {
    "applied": 15,                      // Count of applied schema migrations
    "pending": 2,                       // Total count of pending schema migrations
    "pending_post_deployment": 1,       // Pending post-deployment schema migrations
    "pending_non_post_deployment": 1    // Pending non-post-deployment schema migrations
  },
  "background_migrations": {
    "active": 2,                        // Count of active background migrations
    "paused": 1,                        // Count of paused background migrations
    "failed": 0,                        // Count of failed background migrations
    "completed": 12                     // Count of completed background migrations
  }
}

To be able to expose such an endpoint we will need to:

  • Determine state (applied/not-applied) and count of schema migrations: This can be done by comparing the list of in memory migrations to the ones in the database schema migration table. We can further differentiate between which are post deploy migrations and which are not based on the PostDeployment attribute of the in memory migrations)

  • Determine the states (active, paused, failed, completed ) and count of each background migration: This can be done by querying the background_migrations registry table.

  • Expose the API endpoint on the /gitlab/v1/... endpoint path with token verification for the new token type

Edited by SAhmed