Container Registry Storage Backends and On-Disk Layout
Deep dive into OCI registry storage drivers (filesystem, S3, GCS, Azure Blob), content-addressable layer blob storage, and the /var/lib/registry directory layout.
Published on • November 18, 2026
AI Assistant

Container registries are responsible for storing and serving gigabytes or terabytes of container image layers, manifests, and index artifacts. To achieve scalable, durable storage across single-node deployments and global multi-region clusters, the OCI Distribution project (formerly Docker Distribution) decouples registry logic from storage engines using a Storage Driver Interface.
In this deep dive, we will explore the internal on-disk layout of a container registry (/var/lib/registry), how content-addressable storage works, and how to configure cloud storage backends like AWS S3, Google Cloud Storage, and Azure Blob Storage.
The Storage Driver Architecture
+-----------------------------------------------------------------------------------+
| OCI Registry Engine (Distribution Core API) |
+-----------------------------------------------------------------------------------+
|
Storage Driver Abstraction Layer
|
+-----------------+-----------+-----------+------------------+
| | | |
v v v v
+----------+ +---------------+ +----------------------+ +---------------+
| Local | | AWS S3 | | Google Cloud Storage | | Azure Blob |
| File | | Object Store | | (GCS) | | Storage |
| System | +---------------+ +----------------------+ +---------------+
+----------+
The storage engine relies on Content-Addressable Storage (CAS). Layer files are named and retrieved according to their SHA-256 hash. If 50 different images use the exact same Ubuntu base layer (sha256:7f8a91b...), the storage backend stores only one copy of that blob!
On-Disk Directory Structure (/var/lib/registry)
When using the default filesystem storage driver, the registry organizes files under /var/lib/registry/docker/registry/v2/:
/var/lib/registry/docker/registry/v2/
├── blobs/
│ └── sha256/
│ ├── 4c/
│ │ └── 4c0f3f20865ebd3757f4.../data <-- Actual compressed layer blob
│ └── 7f/
│ └── 7f8a91b2c3d4e5f678.../data
└── repositories/
└── myorg/
└── myapp/
├── _manifests/
│ ├── revisions/
│ │ └── sha256/
│ │ └── a91b2c3.../link <-- Points to manifest blob in blobs/
│ └── tags/
│ └── v1.0.0/
│ ├── current/link <-- Points to active revision
│ └── index/
└── _uploads/ <-- Ephemeral upload buffers
Key Components Explained:
blobs/sha256/: The deduplicated data store. Contains all layer archives and manifest JSON files, indexed by their first two SHA-256 hexadecimal characters (e.g.4c/,7f/).repositories/: Contains metadata pointers (links). A tag likev1.0.0is simply a small text file containing a 64-character SHA-256 string pointing to a manifest blob insideblobs/._uploads/: Temporary staging area for active chunked layer pushes before SHA-256 validation completes.
Supported Registry Storage Drivers
While local filesystem storage works for single-node setups, production registries use cloud object stores for high availability and unlimited durability.
| Driver | Target Use Case | Key Advantages |
|---|---|---|
| Filesystem | Local testing & single servers | Zero configuration; uses local disk or NFS |
| S3 | AWS & S3-compatible (MinIO, Ceph) | High durability; infinite scale; multi-region |
| GCS | Google Cloud Platform (GCP) | Native IAM integration; high throughput |
| Azure Blob | Microsoft Azure cloud | Native Managed Identity auth |
| In-Memory | Unit tests & integration testing | Ultra-fast; lost on container stop |
Configuring Cloud Storage Backends
1. AWS S3 Backend Configuration
To store registry layers directly in an AWS S3 bucket (or S3-compatible MinIO instance):
# config.yml
version: 0.1
log:
level: info
storage:
s3:
region: us-east-1
bucket: my-company-docker-registry
encrypt: true
secure: true
v4auth: true
chunksize: 5242880 # 5MB chunk size for multipart uploads
cache:
blobdescriptor: inmemory
http:
addr: :5000
Deploying via Docker environment variables:
docker run -d \
-p 5000:5000 \
--name cloud-registry \
-e REGISTRY_STORAGE=s3 \
-e REGISTRY_STORAGE_S3_REGION=us-east-1 \
-e REGISTRY_STORAGE_S3_BUCKET=my-company-docker-registry \
-e REGISTRY_STORAGE_S3_ENCRYPT=true \
registry:2
2. Google Cloud Storage (GCS) Backend Configuration
storage:
gcs:
bucket: my-gcp-container-registry-bucket
keyfile: /etc/registry/gcp-sa-key.json
Performance & Optimization Tips
- Enable Blob Descriptor Caching: Add
cache.blobdescriptor: inmemoryor configure a Redis cache server to prevent frequent object store lookups for layer metadata. - Configure S3 Multipart Uploads: Set
chunksizeto 5-10 MB to accelerate large layer uploads. - Set Up S3 Lifecycle Rules: Automatically expire incomplete multipart uploads in
_uploads/after 7 days to reclaim storage space. - Use Cloud CDN for Pull Acceleration: Put CloudFront or Cloud CDN in front of S3/GCS buckets to speed up container pulls across geographically distributed Kubernetes clusters.
Summary
Decoupling registry logic from content-addressable storage engines allows OCI registries to scale effortlessly from local development disks to global cloud object stores.