How to Convert Existing Container Images to Nydus Format Using Nydusify

Nydusify is a high-level CLI tool that orchestrates the conversion of standard OCI container images into Nydus format by driving the nydus-image builder layer-by-layer, optionally pushing blobs to remote storage backends, and generating a new image manifest that enables lazy loading and chunk deduplication.

Converting existing container images to Nydus format using nydusify allows you to leverage the dragonflyoss/nydus repository's high-performance image distribution capabilities without rebuilding images from scratch. The tool handles the entire transformation pipeline—from parsing source manifests to assembling RAFS (Registry Accelerated File System) bootstraps—making it the standard method for migrating workloads to the Nydus ecosystem.

Understanding the Nydusify Conversion Architecture

The conversion process relies on three primary components working in sequence. First, the CLI entry point in contrib/nydusify/cmd/nydusify.go parses flags such as --source, --target, and backend configurations, then validates archives via validateSourceAndTargetArchives and resolves target references through getTargetReference.

Second, the converter package (contrib/nydusify/pkg/converter/convert.go) implements the core converter.Convert function. This component iterates over each platform layer of the source image, invokes the nydus-image binary to create RAFS bootstraps and data blobs, and manages concurrent layer processing.

Third, backend helpers in contrib/nydusify/pkg/utils/backend.go (specifically utils.NewRegistryBackendConfig) generate JSON configurations for blob storage, supporting registry-native storage, OSS, S3, and local filesystem backends.

Basic Conversion Workflow

Simple Registry-to-Registry Conversion

The most common use case pulls an OCI image from a registry, converts it to Nydus format, and pushes the result back to the same or a different registry:

nydusify convert \
  --source <registry>/<repo>:<tag> \
  --target <registry>/<repo>:<tag>-nydus

This command processes every layer in the source image, generates corresponding Nydus bootstrap and blob files, and creates a new manifest referencing these artifacts. The resulting image tag <tag>-nydus can be consumed by containerd with the Nydus snapshotter.

Using Target Suffixes

Instead of specifying a full target reference, you can use --target-suffix to automatically append a string to the source tag:

nydusify convert \
  --source myregistry/app:1.2.3 \
  --target-suffix -nydus

Internally, nydusify calls getTargetReference to concatenate the source reference with the suffix, producing myregistry/app:1.2.3-nydus. This reduces CLI verbosity when batch-converting images with consistent naming conventions.

Advanced Conversion Scenarios

Converting from Local OCI Archives

For air-gapped environments or pre-downloaded images, convert directly from a local OCI archive file:

nydusify convert \
  --source myregistry/app:1.2.3 \
  --source-archive /tmp/app-oci.tar \
  --target myregistry/app:1.2.3-nydus

The validateSourceAndTargetArchives function in cmd/nydusify.go verifies the archive path exists before conversion begins. This workflow is essential for CI/CD pipelines that cache images as tarballs.

Exporting to Local OCI Archives

Conversely, you can convert and export the result to a local archive without pushing to a registry:

nydusify convert \
  --source myregistry/app:1.2.3 \
  --target myregistry/app:1.2.3-nydus \
  --target-archive /tmp/app-nydus.tar

The resulting tarball contains the Nydus image manifest, bootstrap, and blob layers, suitable for manual inspection or distribution via alternative channels.

Configuring External Object Storage Backends (OSS/S3)

For production deployments, store large data blobs in object storage while keeping the lightweight bootstrap in the registry. First, create a backend configuration JSON file.

For Alibaba Cloud OSS (oss-config.json):

{
  "endpoint": "region.aliyuncs.com",
  "scheme": "https",
  "access_key_id": "<your-id>",
  "access_key_secret": "<your-secret>",
  "bucket_name": "nydus-bucket",
  "object_prefix": "nydus/"
}

Then run:

nydusify convert \
  --source myregistry/app:1.2.3 \
  --target myregistry/app:1.2.3-nydus \
  --backend-type oss \
  --backend-config-file ./oss-config.json

The utils.NewRegistryBackendConfig helper in pkg/utils/backend.go constructs the appropriate backend configuration when --backend-type is omitted (defaulting to registry storage). For S3-compatible storage, use --backend-type s3 with a similar JSON structure containing endpoint, access_key_id, secret_access_key, bucket_name, and region.

Enabling Build Cache for Incremental Builds

Accelerate repeated conversions by caching layer artifacts:

nydusify convert \
  --source myregistry/app:1.2.3 \
  --target myregistry/app:1.2.3-nydus \
  --build-cache myregistry/cache:latest \
  --build-cache-tag v1

The converter.Opt struct in cmd/nydusify.go passes cache parameters to converter.Convert, which checks for existing layer blobs before re-converting unchanged content. This is particularly effective in CI environments where base images change infrequently.

Chunk Deduplication with Chunk-Dict

Reduce storage footprint across multiple images by referencing a shared chunk dictionary:

nydusify convert \
  --source myregistry/app:1.2.3 \
  --target myregistry/app:1.2.3-nydus \
  --chunk-dict bootstrap=/path/to/dict.boot

The chunk dictionary (dict.boot) contains pre-computed chunk hashes. During conversion, nydusify identifies duplicate chunks between the source image and the dictionary, referencing existing blobs instead of creating new ones. This is documented in the chunk-deduplication documentation and handled within the converter package.

Prefetch Optimization Patterns

Improve container startup latency by pre-fetching critical files:

cat prefetch.txt | nydusify convert \
  --source myregistry/app:1.2.3 \
  --target myregistry/app:1.2.3-nydus \
  --prefetch-patterns

The prefetch.txt file contains absolute paths (one per line) that the Nydus runtime should fetch immediately upon image mount. The converter passes these patterns to nydus-image, which embeds them in the RAFS metadata for runtime optimization.

Reverse Conversion (Experimental)

Convert Nydus images back to standard OCI format:

nydusify convert \
  --source myregistry/app:1.2.3-nydus \
  --target myregistry/app:1.2.3-oci \
  --reverse

The --reverse flag triggers converter.ReverseConvert (implemented in contrib/nydusify/pkg/converter/reverse.go), which reconstructs standard OCI layers from Nydus RAFS metadata and data blobs. Note that this feature is experimental and may not support all Nydus features.

Key Source Files and Implementation Details

Understanding the codebase helps troubleshoot complex conversions:

File	Purpose	Key Functions
contrib/nydusify/cmd/nydusify.go	CLI entry point and flag parsing	getTargetReference, validateSourceAndTargetArchives, converter.Convert invocation
contrib/nydusify/pkg/converter/convert.go	Core conversion logic	Convert (loops layers, calls nydus-image), manifest assembly
contrib/nydusify/pkg/converter/reverse.go	Experimental reverse conversion	ReverseConvert
contrib/nydusify/pkg/utils/backend.go	Backend configuration helpers	NewRegistryBackendConfig
docs/nydusify.md	User-facing documentation	Flag reference and examples

The conversion flow in converter.Convert handles platform-specific layers concurrently, invokes the nydus-image binary for RAFS creation, and manages blob upload to the configured backend (registry, OSS, S3, or localfs).

Summary

• Nydusify is the official CLI tool for converting existing container images to Nydus format, orchestrating the nydus-image builder and backend storage operations.
• The conversion process supports multiple workflows: registry-to-registry, local archive import/export, and external object storage backends (OSS/S3) for blob separation.
• Performance optimizations include build caching (--build-cache), chunk deduplication (--chunk-dict), and prefetch patterns to reduce startup latency.
• The tool is implemented in contrib/nydusify/cmd/nydusify.go with core logic in pkg/converter, supporting experimental reverse conversion back to OCI format.

Frequently Asked Questions

What is the difference between nydusify and nydus-image?

Nydusify is a high-level CLI tool that orchestrates the entire conversion workflow, including pulling source images, managing layers, and pushing results to registries. Nydus-image is the low-level binary that performs the actual RAFS (Registry Accelerated File System) bootstrap and data blob creation for individual layers. Nydusify invokes nydus-image internally during the conversion process.

Can I convert images without pushing to a registry?

Yes, you can use the --target-archive flag to export the converted Nydus image to a local OCI archive file instead of pushing to a registry. For example: nydusify convert --source myregistry/app:1.2.3 --target myregistry/app:1.2.3-nydus --target-archive /tmp/app-nydus.tar. This is useful for offline distribution or local testing.

How does the build cache improve conversion performance?

The build cache (--build-cache flag) stores previously converted layer artifacts in a specified registry repository. When converting images that share layers with previous builds (such as updated versions of the same base image), nydusify checks the cache repository for existing blobs before re-converting unchanged layers. This significantly reduces conversion time and computational overhead in CI/CD pipelines.

Is reverse conversion from Nydus to OCI fully supported?

Reverse conversion is currently experimental and available via the --reverse flag. It triggers the converter.ReverseConvert function in contrib/nydusify/pkg/converter/reverse.go, which reconstructs standard OCI layers from Nydus RAFS metadata. However, this feature may not support all Nydus-specific optimizations (such as certain chunking strategies or compression formats), so it should be used with caution in production environments.

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