gcrane-copy

Copy an image from source to target

$ gcrane [[cp|copy]] [source] [target]

$ gcrane copy [source] [target] [[-j|--jobs]] [nr_of_copies]

$ gcrane copy [source] [target] [[-r|--recursive]]

$ gcrane copy [[-h|--help]]

gcrane copy <src> <dst> [flags]
src: Source image or blob reference (e.g., gcr.io/my-project/my-image:tag)
dst: Destination image or blob reference (e.g., us-docker.pkg.dev/my-project/my-repo/my-image:newtag)

--allow-nondistributable-artifacts
    Allow copying of non-distributable artifacts, such as certain Windows base layers, which may not be universally supported by all registries.

--allow-missing-blobs
    Do not fail the copy operation if a referenced blob is missing from the source registry, allowing for partial copies in some scenarios.

--all
    When copying an image, copy all tags associated with the manifest list. When copying a repository, copy all tags from the source to the destination.

--recursive
    When operating in repository mode (with --repo), recursively copy all images and their associated tags within the source repository to the destination repository.

--dry-run
    Perform a dry run of the copy operation, showing what would be copied without making any actual changes to the registries.

--platform <platform>
    Specify a target platform (e.g., linux/amd64) to copy only the image for that specific platform from a multi-architecture manifest list.

--repo
    Enable repository mode, allowing you to copy all images and their tags from a source repository to a destination repository. Typically used with --all or --recursive.

--tags <tag1,tag2,...>
    A comma-separated list of specific tags to copy when operating in repository mode (requires --repo). Only images with these tags will be copied.

gcrane-copy is a powerful subcommand of the gcrane utility, specifically designed for efficient copying of container images and arbitrary OCI blobs between compatible registries, or within the same registry. It is highly optimized for Google Cloud's Container Registry (GCR) and Artifact Registry, providing robust authentication and authorization integration. Unlike traditional docker push/pull operations that often require local caching of images, gcrane-copy can perform server-side copies when supported by the registries involved. This capability significantly accelerates transfers and reduces local resource usage, particularly for large images. It serves as an invaluable tool for migrating images between projects, mirroring repositories for disaster recovery, or replicating artifacts across different environments without unnecessary intermediate downloads to your local machine. It supports various authentication methods and gracefully handles multi-architecture images.

gcrane-copy relies on gcrane being installed and properly configured, including authentication with the registries involved. While it prioritizes server-side copies for efficiency, this capability is dependent on the registries' support; cross-registry copies between different vendors often fallback to client-side streaming, which can consume significant local network bandwidth and time for very large images. Ensure you have appropriate read/write permissions for both source and destination registries.

gcrane-copy typically inherits authentication from your existing gcloud CLI configuration when interacting with Google Cloud registries. For other OCI-compatible registries, it can utilize standard Docker credential helpers, or you can provide credentials explicitly through flags like --username and --password.

A key advantage of gcrane-copy is its intelligent attempt to perform a server-side copy whenever possible. In this mode, image data is transferred directly between registries without being pulled down to your local machine, dramatically speeding up transfers and reducing local resource consumption. If server-side copy is not supported (e.g., for copies between registries from different vendors), it gracefully falls back to a client-side streamed copy, where the data flows through the gcrane client on your local machine.

gcrane is a specialized tool developed by Google, leveraging the robust go-containerregistry library (which also powers the more general-purpose crane CLI tool). Its development was driven by the need for more efficient, reliable, and deeply integrated image management within Google Container Registry and Artifact Registry. It offers an alternative to the standard docker CLI, providing enhanced performance for certain operations and seamless integration with Google Cloud's authentication mechanisms, quickly gaining popularity for its speed and server-side copying capabilities.

gcrane(1), crane(1), docker(1)