A container registry is a service that stores, versions and distributes container images over HTTPS. In container-based cloud infrastructure, it is the central exchange point between building and running software: a build pipeline pushes a new image to the registry, and every host, cluster node or developer machine that needs it pulls the image from there.
Modern registries implement the OCI Distribution Specification, which grew out of the Docker Registry HTTP API version 2. Because the protocol is standardized, the same tools such as Docker, Podman, containerd and Kubernetes can work with public, private and self-hosted registries in the same way.
How a container registry stores images
A registry does not store an image as one file. It stores content-addressed blobs, each identified by a cryptographic digest such as sha256:..., and a manifest that lists which blobs make up the image: one configuration blob and a set of compressed file system layers.
Because blobs are addressed by their hash, identical layers are stored only once and shared by every image that uses them. When a client pushes an image, it first asks which layers already exist and uploads only the missing ones; when it pulls, it downloads only layers it does not already have locally.
For images built for several processor architectures, the registry also stores an image index, sometimes called a manifest list. The index points to one manifest per platform, such as linux/amd64 and linux/arm64, and the client automatically selects the manifest matching its own platform.
Repositories, tags and digests
Images in a registry are organized into repositories, usually one per application or component, often grouped under a namespace for a team or organization. Each image is then addressed by a tag or a digest within its repository.
| Part | Example | Meaning | Mutable |
|---|---|---|---|
| Registry host | registry.example.com | Server that stores the image | Not applicable |
| Namespace and repository | shop/checkout | Collection of versions of one image | Not applicable |
| Tag | :2.4.1 or :latest | Human-readable label for a manifest | Yes, can be moved |
| Digest | @sha256: followed by 64 hex characters | Hash of the exact manifest | No, fixed by content |
The difference between tags and digests is critical in operations. A tag can be reassigned to a different image at any time, so latest or even 2.4 may point to new content tomorrow. A digest always identifies the same bytes, which makes it the reliable choice for production deployments and audits.
Many registries offer tag immutability as a setting, which prevents an existing tag from being overwritten. This protects release tags such as 2.4.1 from accidental or malicious replacement. A common convention combines both approaches: immutable version tags for releases, plus a moving tag such as stable that only marks which release a team currently recommends.
Types of container registries
Registries differ in who can access them and who operates them. Most organizations use more than one type, for example a public registry for base images and a private registry for their own applications.
| Type | Operated by | Strengths | Considerations |
|---|---|---|---|
| Public registry | Community or vendor | Large catalog of base images | Pull rate limits, trust in publishers |
| Cloud provider registry | Cloud platform | Integrated identity and networking | Ties images to one provider |
| Self-hosted registry | Own team | Full control, works offline | Operation, storage and upgrades |
| Pull-through cache or mirror | Own team or platform | Faster pulls, fewer external requests | Cache invalidation and storage |
| Universal artifact repository | Own team or vendor | Images plus packages in one place | Broader scope, more configuration |
Because the OCI format can carry more than container images, registries increasingly store other OCI artifacts as well, such as Helm charts, signatures and software bills of materials. These attach to images and travel through the same distribution path.
Security and governance functions
A registry is a critical point in the software supply chain: whatever it serves is what production runs. Mature registries therefore add controls on top of plain storage.
| Feature | Risk addressed | How it works |
|---|---|---|
| Access control | Unauthorized push or pull | Per-repository permissions and tokens |
| Vulnerability scanning | Known flaws in packages | Image layers checked against vulnerability databases |
| Image signing | Tampered or substituted images | Signatures verified before deployment |
| Retention policies | Unbounded storage growth | Old or untagged images removed by rules |
| Replication | Regional outage and slow pulls | Images copied to registries in other regions |
Deleting tags alone does not free space. The underlying blobs remain until garbage collection removes those no longer referenced by any manifest, a process that some self-hosted registries run only in a read-only maintenance window.
Operational pitfalls
The registry often becomes a hidden single point of failure. If it is unreachable, new deployments and autoscaling stop, because new nodes cannot pull images, even though running containers keep working.
- Deploying the latest tag makes rollbacks and audits unreliable; use versioned tags or digests.
- Relying directly on public registries exposes builds to rate limits and outages; mirror critical base images.
- Embedding secrets in image layers leaks them to anyone who can pull the image.
- Skipping retention rules lets storage costs grow with every build.
- Large images slow every pull; multi-stage builds and slim base images reduce layer size.
For clusters, registry credentials must be provided to the nodes, in Kubernetes typically as an image pull secret. Expired or missing credentials show up as image pull errors that stop pods from starting, a common cause of failed deployments.
In everyday language
A container registry works like a warehouse for ready-to-ship software packages. When a new version of an application is built, it is packed and placed on a labeled shelf in the warehouse.
Any server that needs to run the application simply orders the package by its label and receives an exact copy. Everyone gets the same package, and the warehouse keeps older versions in case they are needed again.
Seen in the real world
A software company runs about 60 microservices on several Kubernetes clusters. Its build pipeline creates a new image for every merged change and pushes it to a private registry, tagged with the version number and the commit identifier.
Deployment manifests reference each image by digest, so a cluster always runs exactly the image that passed testing. The registry scans every new image and blocks promotion to production when it finds a critical vulnerability, and a pull-through cache mirrors the public base images the teams depend on.
When a public registry suffers a multi-hour outage, the company’s builds and deployments continue without interruption from the mirror. A retention rule keeps the last 20 versions of each service plus all released tags, which keeps registry storage stable at a few hundred gigabytes despite thousands of builds per month.