Key Features of Nydus Container Image Service: A Technical Deep Dive

Nydus container image service enables sub-second container startup by serving filesystems on-demand via the RAFS format, supporting chunk-level deduplication, multiple storage backends, and POSIX-compliant access through FUSE, Virtio-FS, or in-kernel EROFS.

Nydus is an open-source container image service hosted in the dragonflyoss/nydus repository that reimagines how container filesystems are stored and delivered. Unlike traditional OCI images that require full downloads before container startup, Nydus uses the Remote-Accessible File System (RAFS) format to enable lazy loading and efficient storage, making it a drop-in replacement for OCI images in modern container runtimes.

Core Architecture

RAFS Format

At the heart of Nydus container image service lies the RAFS (Remote-Accessible File System) format. This format stores container filesystems in a way that separates metadata from data blobs, enabling efficient remote access. The metadata structures defined in rafs/src/metadata/* provide fast lookup capabilities and support the chunk-level deduplication that makes Nydus storage-efficient.

Daemon Architecture

The nydusd daemon serves RAFS images through a finite-state-machine (FSM) framework implemented in service/src/daemon.rs. This architecture makes it easy to add new backends, metrics, or hot-upgrade logic. The core filesystem service in service/src/fs_service.rs translates FUSE, Virtio-FS, or EROFS requests into blob reads against various storage backends.

Key Features of Nydus Container Image Service

On-Demand Loading

Nydus implements on-demand loading (also called lazy loading), where image layers are fetched chunk-by-chunk only when a file is actually accessed. According to the README.md (lines 41-42), this reduces startup latency and network traffic, allowing containers to start in milliseconds instead of seconds.

Chunk-Level Deduplication

The service eliminates storage waste through chunk deduplication, where identical chunks are stored once and referenced from multiple layers or images (README.md, line 42). Additionally, the chunk dictionary feature allows new images to reuse existing chunk dictionaries, dramatically shrinking new blobs. This is documented in docs/nydus-image.md (lines 44-49) and implemented in the builder core.

Multiple Storage Backends

nydusd supports reading blobs from diverse storage systems without code changes. As documented in docs/nydusd.md (lines 15-22), supported backends include:

• localfs: Local filesystem storage
• OSS: Alibaba Cloud Object Storage Service
• registry: Standard OCI/Docker registry
• localdisk: Raw block device access
• P2P: Dragonfly peer-to-peer CDN

POSIX Compatibility

Nydus exposes a full POSIX-compliant filesystem view through multiple interfaces:

• FUSE: Userspace filesystem implementation for broad compatibility
• Virtio-FS: High-performance virtualization filesystem
• EROFS: In-kernel read-only filesystem for maximum performance (README.md, line 45)

This ensures existing Linux workloads run unchanged, and overlay-fs can be stacked on top if needed.

Data Analyzability and Pre-fetching

The service records access patterns to enable intelligent pre-fetching, I/O amplification detection, and abnormal-behavior analytics (README.md, line 44). This provides visibility for performance tuning and security auditing, allowing operators to optimize container startup based on actual workload patterns.

Security Features

Nydus provides optional per-chunk encryption and on-the-fly digest validation (configurable) as documented in docs/nydusd.md (lines 27-30). This guarantees data-at-rest protection and end-to-end integrity checks, ensuring that image contents cannot be tampered with during distribution.

Runtime Integration and Ecosystem

Containerd Snapshotter and Other Runtimes

Nydus container image service integrates seamlessly with major container runtimes through dedicated plugins:

• containerd snapshotter: Enables native containerd support for lazy-loading Nydus images
• Docker graph driver: Direct Docker integration
• CRI-O/Podman plugins: Support for alternative Kubernetes runtimes
• Kata Containers: Integration for virtualized containers

These integrations allow Nydus to work across Kubernetes, Docker, containerd, and Kata environments without application changes.

Image Conversion with Nydusify

The contrib/nydusify/ utilities provide automated conversion from standard OCI images to Nydus format. These tools handle the complexity of chunking, deduplication, and metadata generation, making it easy to adopt Nydus in existing CI/CD pipelines that currently produce OCI images.

Practical Implementation Examples

Building a Nydus Image

Convert a local directory into a Nydus image using the nydus-image CLI:

# Convert a local directory into a Nydus image (metadata + data blobs)

nydus-image create -t dir-rafs \
    -D ./output \
    ./my-app

This produces output/<meta-hash> (bootstrap) and one or more output/<data-hash> blobs. The builder implements feature flags in builder/src/core/feature.rs to control options like chunk-TOC and encryption.

Running the Nydus Daemon

Configure and launch nydusd with a local filesystem backend:

# Create a simple localfs config

cat > /etc/nydus/nydusd-config.localfs.json <<EOF
{
  "device": {
    "backend": { "type": "localfs", "config": { "dir": "/var/lib/nydus/blobs" } },
    "cache":   { "type": "blobcache", "config": { "work_dir": "/var/lib/nydus/cache" } }
  },
  "mode": "direct"
}
EOF

# Launch the daemon

sudo nydusd \
  --config /etc/nydus/nydusd-config.localfs.json \
  --mountpoint /mnt/nydus \
  --bootstrap /path/to/bootstrap \
  --log-level info

Any process accessing /mnt/nydus sees the container root filesystem with on-demand loading enabled. The daemon's FSM-based lifecycle is implemented in service/src/daemon.rs.

Inspecting Images with nydusctl

Use the CLI client to inspect bootstrap metadata:

# Show bootstrap information (metadata, chunk layout, etc.)

nydusctl inspect --bootstrap /path/to/bootstrap

This tool is useful for debugging and verifying integrity. The implementation resides in src/bin/nydusctl/main.rs.

Kubernetes Integration

Enable Nydus in containerd for Kubernetes workloads:

# /etc/containerd/config.toml

[plugins."io.containerd.grpc.v1.cri".containerd]
  snapshotter = "nydus"

After restarting containerd, pulling an image with a Nydus layer automatically uses the nydusd daemon to serve the root filesystem via lazy loading.

Summary

• On-demand loading fetches data chunks only when accessed, reducing startup latency from seconds to milliseconds.
• Chunk-level deduplication and chunk dictionaries minimize storage and bandwidth usage across images.
• Multiple backend support (localfs, OSS, registry, P2P) provides deployment flexibility for any infrastructure.
• POSIX compatibility via FUSE, Virtio-FS, and EROFS ensures existing workloads run without modification.
• Runtime integration with containerd, Docker, Kubernetes, and Kata Containers enables transparent adoption.
• Security features include per-chunk encryption and integrity validation for end-to-end protection.

Frequently Asked Questions

What is the RAFS format in Nydus container image service?

RAFS (Remote-Accessible File System) is the core storage format used by Nydus to containerize filesystems. It separates metadata from data blobs, storing filesystem structures in a bootstrap file while content-addressable chunks reside in separate blob files. This separation enables lazy loading and deduplication, as implemented in rafs/src/metadata/*.

How does Nydus container image service achieve faster container startup times?

Nydus reduces startup latency through on-demand loading (lazy loading), where image layers are fetched chunk-by-chunk only when files are actually accessed. According to the README.md (lines 41-42), this allows containers to start in milliseconds instead of seconds by eliminating the need to download entire image layers before container execution begins.

What storage backends does Nydus container image service support?

The nydusd daemon supports diverse storage systems without code changes. As documented in docs/nydusd.md (lines 15-22), supported backends include localfs (local filesystem), OSS (Alibaba Cloud Object Storage), registry (standard OCI/Docker registries), localdisk (raw block devices), and P2P (Dragonfly peer-to-peer CDN).

How does Nydus container image service integrate with Kubernetes?

Nydus provides a containerd snapshotter plugin that enables native lazy-loading support in Kubernetes environments. By configuring the snapshotter in /etc/containerd/config.toml and using the nydusd daemon, containers automatically benefit from on-demand image loading without application changes. Nydus also integrates with Docker via a graph driver and supports CRI-O, Podman, and Kata Containers for comprehensive runtime coverage.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}