crane-export

Write tarball to stdout

$ crane export [image_name] -

$ crane export [image_name] [path/to/tarball]

$ crane export - [path/to/filename]

crane export [flags] <image-reference> <output-path>

image-reference
    The reference to the container image in a remote registry (e.g., gcr.io/google-containers/ubuntu:latest or myregistry.com/myimage:v1.0).

output-path
    The local filesystem path where the image tarball will be saved (e.g., ubuntu.tar). This file will contain all layers and metadata for the specified image.

-platform string
    Specifies the platform for the image to pull and export (e.g., linux/amd64, linux/arm64). This is crucial for multi-architecture images to ensure the correct variant is exported.

-type string
    Defines the format of the exported tarball. Supported types are docker (default) and oci. docker format is compatible with docker load, while oci adheres to the Open Container Initiative image format specification.

-compress
    If this flag is present, the output tarball will be compressed using gzip, potentially reducing its file size.

-allow-nondistributable-artifacts
    Allows pulling of non-distributable artifacts, which might be subject to license restrictions or specific registry configurations.

-insecure
    Allows communication with registries over plain HTTP or disables TLS certificate validation for HTTPS connections. Use with caution as it compromises security.

-plain-http
    Forces communication with registries using plain HTTP, completely bypassing TLS/SSL encryption.

-verbose
    Enables verbose logging output, providing more detailed information about the operation's progress and actions.

crane export is a utility from the go-containerregistry project that allows users to pull a container image from a remote registry and save it to a local tarball.

This tarball can then be used to load the image into a container runtime (like Docker or containerd) or for offline transfer. It serves as a lightweight and fast alternative to tools like docker save or skopeo copy, especially useful in CI/CD pipelines or environments where a Docker daemon is not available or desired. It efficiently handles image layers and manifests, supporting multi-platform images and allowing the user to specify the desired output format.

Exporting very large images can consume significant disk space and network bandwidth.
The compatibility of the exported tarball with various container runtimes depends on the --type flag chosen; older runtimes might not fully support the oci format.
crane export requires an active network connection to the image registry for the operation to succeed. It does not support exporting an image from a local cache without prior network retrieval.

The --type flag offers flexibility in the format of the exported tarball:
• docker: This is the default type and generates a tarball compatible with the docker load command. It often contains multiple image manifests and layers, making it suitable for direct import into a Docker daemon.
• oci: This type generates a tarball that adheres to the Open Container Initiative (OCI) image format specification. OCI-compliant tarballs are designed for broader compatibility with modern container runtimes and tools that support OCI standards, offering a more standardized and portable format.

For images that support multiple architectures (e.g., linux/amd64, linux/arm64), using the --platform flag is essential. Without it, crane might select a default platform based on the system it's running on, or an arbitrary choice from the manifest list. Explicitly specifying the platform ensures that the exact architecture you intend to export is pulled and saved into the tarball.

The crane utility is an integral part of the go-containerregistry project, an open-source collection of Go libraries and tools developed by Google. Conceived to provide a lightweight, fast, and daemonless approach to interacting with OCI-compliant container registries, crane (and thus crane export) emerged as a preferred tool in CI/CD pipelines, scripting, and environments where direct Docker daemon dependency is undesirable. Its development emphasizes efficiency and programmatic control over container images and registries.

docker save(1), skopeo copy(1), crane(1), ctr(1)