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 [OPTIONS] <SOURCE_IMAGE> <NEW_BASE_IMAGE> <TARGET_IMAGE>

SOURCE_IMAGE
    The full reference of the existing container image to be rebased (e.g., myregistry/myimage:mytag).

NEW_BASE_IMAGE
    The full reference of the new base image that the source image will be rebased onto (e.g., gcr.io/distroless/static:latest).

TARGET_IMAGE
    The full reference where the rebased image will be pushed (e.g., myregistry/myimage:newtag).

-u, --username USERNAME
    Username for authenticating with container registries.

-p, --password PASSWORD
    Password for authenticating with container registries.

--insecure
    Allow insecure HTTP connections or skip certificate verification for registry communication.

--platform PLATFORM
    Specify the target platform for the image in the format os/arch[/variant] (e.g., linux/amd64). Can be specified multiple times for multi-platform images.

--allow-unverified-base
    Permit the new base image to be referenced by tag without requiring a digest, potentially leading to non-reproducible rebases if the base tag changes.

--allow-nondistributable-artifacts
    Allow pushing/pulling images that contain layers marked as non-distributable. Use with caution as these layers might not be transferable between all registries.

The crane rebase command is a powerful utility from the go-containerregistry project, designed to efficiently update the base layer of an existing container image without requiring a full rebuild of the application layers. Traditional methods of updating a base image often involve rebuilding the entire Dockerfile, which can be time-consuming and generate new, potentially larger, image layers.

crane rebase works by inspecting the layers of the source image and comparing them with the layers of a specified new base image. It intelligently identifies the common layers and replaces the old base layers with the new ones, effectively "rebasing" the image. The unique application layers of the original image are then appended on top of the new base. This process primarily manipulates image manifests and layer pointers, making it significantly faster and more network-efficient than a full image build and push, especially when dealing with frequent security updates to common base images like Alpine or Debian.

This tool is particularly valuable in CI/CD pipelines for maintaining up-to-date and secure container images with minimal overhead.

• Layer Compatibility: crane rebase expects a certain level of commonality between the old and new base images. If the new base image fundamentally changes its lower layers, the rebase operation might fail or produce unexpected results.


• No Application Changes: This command only modifies the base layers and manifest pointers. It does not re-execute any Dockerfile instructions above the base or rebuild application layers. Any changes required in the application's configuration or dependencies due to the new base must be handled by a full image rebuild.


• Registry Access: Proper authentication and network connectivity to both the source and target registries (and the new base image's registry) are crucial for successful operation.


• Digest Pinning: For reproducible builds, it's recommended to use digest-pinned image references for the NEW_BASE_IMAGE instead of tags, unless --allow-unverified-base is explicitly used.

When crane rebase is executed, it performs the following conceptual steps:

• Fetch Manifests: It pulls the manifests for the SOURCE_IMAGE and the NEW_BASE_IMAGE from their respective registries.


• Layer Comparison: It compares the ordered list of layer digests (diff IDs) from the SOURCE_IMAGE with those of the NEW_BASE_IMAGE. The command identifies the longest common sequence of layers between the original base of the SOURCE_IMAGE and the NEW_BASE_IMAGE.


• Manifest Modification: It constructs a new image manifest. The new manifest starts with the layers of the NEW_BASE_IMAGE, followed by the unique layers from the SOURCE_IMAGE that were built on top of its old base. This effectively swaps out the base layers.


• Push New Image: The modified manifest is then pushed to the TARGET_IMAGE location. Importantly, only the manifest itself and any new layers are pushed; existing layers (if common across images) are typically not re-uploaded, making the operation very efficient.

crane rebase is invaluable in several scenarios:

• Security Patching: Regularly updating application images to the latest patched versions of their base images (e.g., debian:stable-slim to debian:stable-slim-YYYYMMDD) to incorporate security fixes without rebuilding the application itself.


• Base Image Upgrades: Moving to a newer, compatible version of a base image (e.g., distroless/static to a newer digest) when no application-specific changes are required for the upgrade.


• Reduced CI/CD Times: Dramatically cuts down the time required for image updates in automated pipelines, as it avoids the lengthy docker build and subsequent docker push for every base image change.


• Minimizing Storage and Network Traffic: By avoiding full rebuilds and re-uploads of unchanged layers, it conserves registry storage and reduces network bandwidth consumption.

The crane tool is part of the go-containerregistry project, an open-source library and suite of command-line tools developed primarily by Google to interact with OCI (Open Container Initiative) image registries and images. The project's goal is to provide a robust, performant, and idiomatic Go API for managing container images, along with powerful CLI utilities like crane.

crane rebase emerged as a specific solution to a common operational challenge: efficiently updating container images to incorporate security patches or newer versions of their base images without incurring the significant time and resource costs of a full image rebuild. It addresses the need for faster, more agile image maintenance in modern CI/CD pipelines, where minimizing build times and network traffic is paramount. Its development reflects the increasing maturity and sophistication of container image management practices.

docker(1), skopeo(1), buildah(1), podman(1), oras(1)