GitLab Container Virtual Registry with Docker Hardened Images

GitLab Container Virtual Registry provides a single, authenticated endpoint for pulling images from multiple registries while caching manifests and layers locally. It reduces repeated network downloads, centralizes upstream credentials, and makes it easier to adopt Docker Hardened Images without changing every team’s CI/CD configuration. The article recommends using it as an operational layer between pipelines and registries such as Docker Hub, dhi.io, MCR, and Quay.io.

The Container Image Management Problem

Platform teams often depend on several registries:

• Docker Hub for common base images
• dhi.io for Docker Hardened Images
• MCR for .NET and Azure tooling
• Quay.io for Red Hat ecosystem images
• Internal registries for proprietary images

This creates:

• Different authentication mechanisms and image paths
• Registry-specific CI/CD configuration
• Repeated credential-management work
• Slow builds caused by downloading identical images in every job

How Container Virtual Registry Works

• Pipelines pull through a GitLab URL such as: gitlab.com/virtual_registries/container/<id>/image
• GitLab checks configured upstreams in priority order.
• If the image is cached, GitLab serves it directly.
• If not, GitLab fetches it from the appropriate upstream, caches the manifest and layers, and returns it.
• Cache validity is configurable, with 24 hours presented as the default.
• Developers and pipeline authors do not need to know which upstream registry provides an image.

Benefits for Docker Hardened Images

Docker Hardened Images offer:

• Minimal attack surfaces
• Near-zero CVEs
• Software bills of materials (SBOMs)
• SLSA provenance

The virtual registry reduces the friction of adopting them by providing:

• Centralized authentication: Teams authenticate to GitLab while GitLab stores and uses the dhi.io credentials.
• Simpler CI/CD: Pipelines use one GitLab endpoint rather than configuring dhi.io separately.
• Gradual adoption: Teams can migrate incrementally while cached image paths reveal which variants are being used.
• Improved visibility: The cache provides an inventory of active dependencies, such as whether teams pull library/python:3.11 instead of a hardened alternative.
• An audit trail: Cached images help with compliance and understanding fleet-wide dependencies.

Setting Up the Registry

The article demonstrates setup with a Python client.

• Create a virtual registry under a GitLab top-level group:

  registry = client.create_virtual_registry(
      group_id="785414",
      name="platform-images",
      description="Cached container images for platform teams"
  )
  

• Add Docker Hub as an upstream, using a 24-hour cache period.

• Add dhi.io with a Docker username and access token:

  dhi_upstream = client.create_upstream(
      registry_id=registry["id"],
      url="https://dhi.io",
      name="Docker Hardened Images",
      username="your-docker-username",
      password="your-docker-access-token",
      cache_validity_hours=24
  )
  

• Add other sources such as:

  • https://mcr.microsoft.com for Microsoft images, with a 48-hour cache period
  • https://quay.io for Quay-hosted images, with a 24-hour cache period

Practical Recommendation

Use GitLab Container Virtual Registry as a centralized pull-through cache when multiple teams rely on several container registries. Configure Docker Hardened Images as an upstream, point pipelines to the GitLab virtual registry endpoint, and use the cache contents to monitor adoption, performance, and image dependencies.