crane-push

Push local image to remote registry

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

$ crane push [path/to/tarball] [image_name] --image-refs [path/to/filename]

$ crane push [path/to/tarball] [image_name] --index

$ crane push [[-h|--help]]

crane push [options] SOURCE DESTINATION

SOURCE: Path to a local OCI image layout directory or a tarball containing an OCI layout/Docker image. E.g., /path/to/my-image-oci-layout or my-image.tar
DESTINATION: Full registry path to the image, including repository and tag. E.g., registry.example.com/my-repo/my-image:latest

--insecure
    Allows connections to registries over HTTP or skips certificate validation for HTTPS, useful for local or insecure registries.

--tag <tag>
    Adds an additional tag to the pushed image. This option can be specified multiple times to add multiple tags.

--allow-nondistributable-artifacts
    Allows pushing layers that might be marked as non-distributable by their original source (e.g., Windows base layers).

--platform <platform>
    When pushing an OCI layout containing multiple platforms, this option filters which specific platform(s) to push (e.g., linux/amd64). Can be specified multiple times.

--config <path>
    Specifies a path to a JSON file containing the image configuration to use, overriding the default configuration from the source image.

--compress-level <int>
    Sets the compression level for pushed blobs (layers). A value of -1 uses the default, 0 for no compression, and 1-9 for increasing compression (default is often 5).

--verbose, -v
    Enables verbose logging, providing more detailed output about the push process.

crane is an open-source, daemon-less tool developed by Google, written in Go, for managing container images and registries. It provides various subcommands to inspect, modify, and transfer container images directly, without requiring a local Docker daemon.

The crane push command is specifically designed to upload a container image manifest and its associated layers (blobs) from a local source (typically an OCI image layout directory or a tarball) to a remote container registry. It serves as a lightweight and efficient alternative to docker push, particularly useful in automated CI/CD pipelines where a full Docker daemon might be undesirable or unavailable.

crane push supports pushing multi-architecture images (manifest lists) and optimizes transfers by only pushing layers that do not already exist in the target registry, ensuring efficiency and reducing bandwidth usage. It can handle images from various local formats, including OCI layouts and Docker image tarballs.

Authentication: crane typically relies on standard Docker credential helpers (e.g., ~/.docker/config.json) or environment variables (e.g., DOCKER_USERNAME, DOCKER_PASSWORD) for registry authentication. Ensure credentials are configured before pushing.

Source Format: crane push expects the source image to be in an OCI image layout directory or a compatible tarball. It does not directly push images from a local docker images list without first converting or saving them (e.g., using crane save or docker save).

Network Access: Requires direct network connectivity to the target container registry and necessary firewall permissions.

crane supports several authentication mechanisms for interacting with private registries: It first checks for credentials in the standard Docker configuration file (~/.docker/config.json). Alternatively, it can leverage environment variables like DOCKER_USERNAME and DOCKER_PASSWORD, or prompt interactively if no credentials are found and the registry requires authentication. For cloud provider registries (e.g., AWS ECR, GCP GCR), it often integrates with their respective credential helpers.

The primary source format for crane push is the OCI (Open Container Initiative) image layout. This is a standardized on-disk format for container images, providing a structured directory that contains the image manifest, configuration, and layers (blobs). This layout can be generated by tools like crane save, skopeo, or even docker save (which outputs a similar tarball format that crane can often interpret).

crane originated from the go-containerregistry library developed by Google. Its inception was driven by the increasing need for a lightweight, programmatic, and daemon-less method for interacting with container registries. This became particularly crucial in cloud-native environments and CI/CD pipelines where the overhead and dependencies of a full Docker daemon were undesirable. The crane push command, as a core functionality, reflects this design philosophy, offering a direct and efficient way to upload container images, distinguishing itself as a robust tool within the Kubernetes and container ecosystem.

docker push(1), crane pull(1), crane copy(1), oras push(1), skopeo copy(1)