Nydus OCI Compatibility: How Dragonfly Extends Open Container Initiative Standards

Nydus maintains full compatibility with OCI image and distribution specifications while extending them with additional manifest fields for RAFS bootstrap and data blobs, enabling seamless integration with standard container registries and runtimes.

Nydus, developed under the Dragonfly project (dragonflyoss/nydus), is a container image acceleration solution designed to work within the existing container ecosystem. The project achieves complete Nydus OCI compatibility by adhering to the Open Container Initiative (OCI) image and distribution specifications, allowing images to be stored in standard registries and executed by OCI-compliant runtimes without requiring infrastructure changes.

OCI Image Manifest Extensions

Nydus extends the OCI image manifest specification rather than replacing it. In docs/nydus-design.md, the architecture defines how Nydus images maintain OCI compatibility while adding performance optimizations.

Extended Manifest Structure with RAFS Bootstrap

According to the design documentation at docs/nydus-design.md#L9-L11, Nydus introduces an additional manifest file that stores pointers to the RAFS (Registry Acceleration File System) bootstrap and data blobs. This manifest sits alongside the standard OCI image manifest, ensuring that:

• Standard OCI tools can parse the image structure
• The RAFS metadata remains accessible to Nydus-aware runtimes
• Layer deduplication and chunk-level sharing remain intact

Artifact Type Identification

Nydus identifies its manifest format using the artifactType field specified in docs/nydus-design.md#L25-L32. The manifest declares:

application/vnd.nydus.image.manifest.v1+json

This MIME type allows OCI-aware tools to recognize Nydus images while still processing them as standard OCI artifacts. Container registries that support OCI image indexes can store and serve Nydus content without modification.

OCI Distribution Spec Compliance

Nydus maintains strict compliance with the OCI Distribution Specification, enabling seamless integration with existing container infrastructure.

Standard Registry Support

As documented in service/README.md#L22-L23, Nydus stores blobs in any OCI-compatible registry, including:

• Docker Hub
• Harbor
• GitHub Container Registry (GHCR)
• Amazon ECR
• Google Container Registry

Additionally, Nydus supports alternative storage backends that implement OCI distribution APIs, including object storage services (OSS, S3), network-attached storage (NAS), and local HTTP directories configured to mimic OCI registry endpoints.

Converting OCI Images to Nydus Format

The Nydus ecosystem provides tools that consume standard OCI images and produce Nydus-optimized versions while maintaining OCI compatibility.

Using nydusify for Registry Conversion

The nydusify tool, documented in docs/nydusify.md#L5-L9, accepts OCI images from remote registries or local OCI layouts and converts them to Nydus format:

# Convert an OCI image to Nydus and push to registry

nydusify \
  --source docker.io/library/alpine:3.18 \
  --target my-registry.example.com/alpine:nydus \
  --output-type tar

This process preserves the original OCI image layers while generating additional RAFS bootstrap and data blobs that enable lazy loading and chunk deduplication.

Using nydus-image for Local Conversion

For local image manipulation, nydus-image provides detailed control over the conversion process, as described in docs/nydus-image.md#L58-L66:

# Create a Nydus image from an OCI tarball

nydus-image create \
  --bootstrap /path/to/output/bootstrap \
  --blob-dir /path/to/blobs \
  /path/to/oci-layout.tar

This command generates the RAFS bootstrap and data blobs required for Nydus acceleration while maintaining compatibility with OCI distribution protocols.

Runtime Compatibility with OCI-Compliant Engines

Nydus images execute on standard container runtimes without requiring modifications to the underlying infrastructure, as confirmed in README.md#L41-L44.

Supported Runtimes

Nydus maintains compatibility with:

• containerd – With the nydus-snapshotter plugin for lazy pulling
• Docker – Via the nydus-snapshotter integration
• Kubernetes – Through CRI-compliant container runtime interfaces
• CRI-O – With snapshotter support enabled

These runtimes process Nydus images as standard OCI artifacts because the manifest structure satisfies OCI schema requirements. The Nydus daemon provides additional benefits such as on-demand chunk fetching, chunk-level deduplication, and faster container start-up without breaking OCI compliance.

Summary

• Nydus extends rather than replaces OCI specifications, maintaining full backward compatibility with existing container infrastructure.
• The application/vnd.nydus.image.manifest.v1+json artifact type allows OCI-aware tools to identify Nydus images while processing them as standard OCI artifacts.
• Nydus images store in any OCI-compatible registry (Docker Hub, Harbor, GHCR, S3, OSS) without requiring registry modifications.
• Conversion tools nydusify and nydus-image consume standard OCI images and produce Nydus-optimized versions that remain OCI-compliant.
• Container runtimes including containerd, Docker, Kubernetes, and CRI-O execute Nydus images without infrastructure changes, leveraging the nydus-snapshotter for lazy loading capabilities.

Frequently Asked Questions

Is Nydus a replacement for OCI images?

No, Nydus is not a replacement for OCI images. According to the source code in docs/nydus-design.md, Nydus augments OCI specifications by adding an extra manifest file that stores RAFS bootstrap and data blob pointers while maintaining the overall OCI Image Spec structure. Standard OCI tools can still parse, distribute, and verify Nydus images because the manifest satisfies OCI schema requirements.

Can Nydus images run on standard containerd without plugins?

Standard containerd requires the nydus-snapshotter plugin to leverage Nydus-specific features like lazy pulling and chunk-level deduplication. However, as noted in README.md#L41-L44, the images themselves remain OCI-compliant and can be processed by standard containerd in a fallback mode, though without the performance benefits. For full Nydus acceleration, the snapshotter must be installed and configured.

How does Nydus maintain OCI compatibility while adding deduplication?

Nydus maintains OCI compatibility by storing deduplication metadata in separate RAFS bootstrap and data blobs that are referenced through an extended manifest, as described in docs/nydus-design.md#L9-L11. The manifest uses the artifactType field with value application/vnd.nydus.image.manifest.v1+json to identify the format while keeping the overall structure compliant with OCI Image Spec. This allows registries to store Nydus blobs alongside standard OCI layers without modification.

Which registries support storing Nydus images?

According to service/README.md#L22-L23, Nydus images can be stored in any OCI-compatible registry, including Docker Hub, Harbor, GitHub Container Registry (GHCR), Amazon ECR, and Google Container Registry. Additionally, Nydus supports object storage services like OSS and S3, NAS, and local HTTP directories configured to mimic OCI distribution APIs. No registry modifications are required because Nydus conforms to standard OCI Distribution Spec protocols.

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