Freedom251 › Container Registries
Distribution Registry
What Distribution Registry is
Distribution Registry is an open-source registry for storing and delivering named container images and other content. Teams push images into it and pull tagged versions through its HTTP API V2. It implements OCI Distribution Specification 1.0.1 and supports OCI artifacts. Bundled storage drivers cover local filesystems, Amazon S3, Microsoft Azure Blob Storage, and Google Cloud Storage. TLS and basic authentication are built in, while externally accessible deployments should use TLS and access controls. Delegated authentication can connect a trusted token server or another third-party system for more detailed authorization. HTTP webhooks can react to manifest and layer pushes or pulls, and logging, reporting, and debug/vars metrics support monitoring. Notification queues are held in memory, so events may be lost if an instance disappears before delivery. The registry runs on Linux, macOS, Windows, through an API, or as a self-hosted service. It can operate in air-gapped networks when required images are transferred from a connected host. Production operation requires skills in availability, scalability, logging, monitoring, and security. The project is free and licensed under Apache.
Who it suits
It suits teams wanting control over image storage, distribution pipelines, or integration with in-house development workflows. It also fits CI/CD and isolated-network deployments.
What it does well
- Open-source Apache license
- Implements OCI Distribution Specification 1.0.1
- Supports local, S3, Azure, and Google Cloud storage
- Provides TLS, basic authentication, and delegated authentication
- Webhook notifications support CI/CD workflows
What to know first
- Notification queues can lose messages when instances fail
- New storage drivers are not currently accepted
- OSS and Swift storage drivers are unsupported
- Production operation requires specialized operational skills
Verdict
Distribution Registry provides a free, self-hosted foundation for OCI image storage and delivery. Its security and webhook features support controlled pipelines, while in-memory notifications and operational requirements deserve planning.
Facts from Distribution Registry's own pages
- Advanced access control
- Delegated authentication is supported, but requires implementing or using a third-party authentication system. · distribution.github.io, 10 Oct 2026
- Advanced authentication
- The Registry supports delegated authentication through a trusted token server for deployments needing more control over access control and authorization integration. · distribution.github.io, 11 Oct 2026
- Air-gapped use
- A Registry can run without internet connectivity, but images that are not local may need to be fetched on a connected host and migrated into the isolated network. · distribution.github.io, 11 Oct 2026
- API
- The documentation provides an HTTP API V2 specification for interacting with the registry. · distribution.github.io, 10 Oct 2026
- Authentication and transport security
- The Registry supports TLS and basic authentication; its deployment guide says externally accessible registries must be secured with TLS and should use access controls. · distribution.github.io, 10 Oct 2026
- Compatibility
- The Distribution Registry implements OCI Distribution Spec version 1.0.1. · distribution.github.io, 11 Oct 2026
- Driver limits
- New storage drivers are not currently being accepted, and the OSS and Swift drivers are no longer supported. · distribution.github.io, 10 Oct 2026
- Image workflows
- Users interact with a registry by pushing and pulling images, which are available in tagged versions. · distribution.github.io, 11 Oct 2026
- Integrations
- A typical CI/CD workflow can push a new image to the Registry after a successful build, then use a Registry notification to trigger deployment or notify other systems. · distribution.github.io, 11 Oct 2026
- Intended use
- The project is aimed at teams that want control over image storage, their distribution pipeline, or integration with in-house development workflows. · distribution.github.io, 10 Oct 2026
- License
- The Registry is open source under the permissive Apache license. · distribution.github.io, 11 Oct 2026
- Monitoring
- The Registry includes logging and reporting, and notification endpoint status and metrics are exposed through its debug/vars interface. · distribution.github.io, 10 Oct 2026
- Notification limitation
- Notification queues are in memory, so messages can be lost if a registry instance is lost before delivery. · distribution.github.io, 10 Oct 2026
- Notifications
- The Registry includes a notification system that calls webhooks in response to activity, along with logging and reporting. · distribution.github.io, 11 Oct 2026
- OCI compatibility
- The registry implements OCI Distribution Specification version 1.0.1. · distribution.github.io, 10 Oct 2026
- Operational requirements
- Production operation requires skills in availability, scalability, logging, monitoring, and security; familiarity with Docker and networking is also required. · distribution.github.io, 11 Oct 2026
- Purpose
- Distribution Registry is a stateless, highly scalable server-side application for storing and distributing container images and other content. · distribution.github.io, 11 Oct 2026
- Security
- The Registry natively supports TLS and basic authentication; externally accessible registries must first be secured using TLS. · distribution.github.io, 11 Oct 2026
- Storage
- The default storage driver is the local POSIX filesystem; supported cloud storage drivers include S3, Microsoft Azure, and Google Cloud Storage. · distribution.github.io, 11 Oct 2026
- Storage driver limitation
- Adding support for new storage drivers has been put on hold; the documentation suggests considering whether a desired driver is S3 compatible. · distribution.github.io, 11 Oct 2026
- Support
- The project directs users to its #distribution channel in CNCF Slack for help and its GitHub issue tracker to report bugs. · distribution.github.io, 10 Oct 2026
- Webhook notifications
- The registry can send HTTP webhook notifications for manifest and layer pushes and pulls. · distribution.github.io, 10 Oct 2026
Where Distribution Registry stands on Freedom251
- Container Registries#13 of 60