crane-rebase

Rebase image

$ crane rebase

$ crane rebase --new_base [image_name]

$ crane rebase --old_base [image_name]

$ crane rebase [[-t|--tag]] [tag_name]

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

crane rebase --image {image_name} --base {base_image} --output {output_image}

--base
    The target base image to rebase onto (e.g., 'ubuntu:latest'). This should be a valid image reference in a container registry.

--image
    The image to rebase. This must be a valid image reference in a container registry.

--output
    The name of the rebased image to push to the registry. This should be a valid image reference, including registry and tag (e.g., 'myregistry.example.com/myorg/rebased-image:latest').

--platform
    The target platform for the image rebase. If not specified defaults to the platform where the command is running (example: linux/amd64).

--digest
    Use the image digest instead of tag if available. Useful for immutable image references.

--insecure
    Allow insecure (HTTP) connections to the registry. Use with caution.

--username
    Username for registry authentication.

--password
    Password for registry authentication.

The crane rebase command allows you to efficiently rebase a Docker image onto a new base image in a container registry without re-uploading unchanged layers. It achieves this by analyzing the image's layers and comparing them to the target base image. Only the layers that differ are uploaded, significantly reducing the time and bandwidth required for image updates, especially when applying security patches or upgrading the base operating system.

This command primarily focuses on optimizing the update process for existing images in container registries. It is an efficient tool for managing image dependencies and performing base image updates without incurring the full cost of rebuilding and pushing entire images. Using crane rebase saves time, reduces network transfer costs and avoids unnecessary rebuilds.

crane rebase relies on the assumption that layers which have the same content identifier (digest) are identical. Ensure that the base image layers are built in a manner that preserves layer hashes when content remains unchanged. Authentication is often required to pull and push images. The command might not work as expected if the base image has significant structural changes compared to the original image.

By default, crane uses the Docker configuration file (usually located at ~/.docker/config.json) for authentication. You can also provide credentials via the --username and --password flags. Proper authentication is essential to pull and push images to private registries.

While crane rebase optimizes the upload process, it does not actively optimize the layer structure itself. For optimal image size and performance, consider best practices for Dockerfile layering during the initial image build.

crane is part of the GoogleContainerTools suite and represents a modern, container-native approach to image manipulation. It was designed to be lightweight, performant, and specifically tailored to container workflows. crane rebase likely evolved as a solution to address the inefficiencies of rebuilding and re-uploading entire images for minor updates, particularly in cloud-native environments where images are frequently deployed and updated. The command has seen increased adoption as organizations seek more efficient ways to manage their container images and reduce associated costs.

crane copy(1), crane manifest(1), crane push(1), docker push(1), docker pull(1)