Skip to content
Blog

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:

  1. 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/).
  2. repositories/: Contains metadata pointers (links). A tag like v1.0.0 is simply a small text file containing a 64-character SHA-256 string pointing to a manifest blob inside blobs/.
  3. _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.

DriverTarget Use CaseKey Advantages
FilesystemLocal testing & single serversZero configuration; uses local disk or NFS
S3AWS & S3-compatible (MinIO, Ceph)High durability; infinite scale; multi-region
GCSGoogle Cloud Platform (GCP)Native IAM integration; high throughput
Azure BlobMicrosoft Azure cloudNative Managed Identity auth
In-MemoryUnit tests & integration testingUltra-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

  1. Enable Blob Descriptor Caching: Add cache.blobdescriptor: inmemory or configure a Redis cache server to prevent frequent object store lookups for layer metadata.
  2. Configure S3 Multipart Uploads: Set chunksize to 5-10 MB to accelerate large layer uploads.
  3. Set Up S3 Lifecycle Rules: Automatically expire incomplete multipart uploads in _uploads/ after 7 days to reclaim storage space.
  4. 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.