crane-append

Push image based on a base image

$ crane append [[-b|--base]] [image_name]

$ crane append [[-f|--new_layer]] [layer_name1 layer_name2 ...]

$ crane append [[-t|--new_tag]] [tag_name]

$ crane append [[-o|--output]] [path/to/tarball]

$ crane append --oci-empty-base

$ crane append --set-base-image-annotations

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

crane append [options] <base_image_ref> <layer_tarball_path> [...]

<base_image_ref>
    The reference to the existing OCI image (e.g., gcr.io/my-repo/my-image:latest) to which layers will be appended.

<layer_tarball_path>
    The path to one or more .tar.gz files containing the content of the new layers. Multiple paths can be provided.

--allow-nondistributable-artifacts
    Permits pushing non-distributable layers or artifacts, which might not be supported by all registries.

--entrypoint strings
    Sets a new entrypoint for the appended image. Can be provided as a comma-separated list (e.g., sh,-c,exec myapp).

--env strings
    Adds or updates environment variables in the image configuration (e.g., MY_VAR=value). Can be used multiple times.

-h, --help
    Displays help information for the append command.

--new_tag strings
    Specifies new tags for the resulting appended image (e.g., my-image:new-version). Can be used multiple times.

--o strings
    Overrides image configuration entries like Entrypoint or Cmd. For example, sh,-c,echo hello.

--preserve-original-entries
    When modifying image configuration, this flag ensures that original entries for fields like Entrypoint or Cmd are preserved if not explicitly overridden.

--repo string
    Specifies the target repository for the appended image if it differs from the base image's repository.

--squash
    Squashes the newly added layers into a single new layer, reducing the total number of layers in the resulting image.

--user string
    Sets the user or UID for the image (e.g., root or 1001).

--workdir string
    Sets the working directory for the image (e.g., /app).

The crane append command is a powerful subcommand of the crane utility, part of the go-containerregistry project. It enables users to non-destructively add one or more new layers, provided as .tar.gz archives, to an existing OCI (Open Container Initiative) image. This operation is performed directly against a container registry, meaning you don't need to pull the entire image or have a Docker daemon running locally. This makes it exceptionally efficient for CI/CD pipelines, allowing for quick modifications like adding configuration files, patches, or environment variables to an image without the overhead of a full rebuild. It supports pushing the modified image to a new tag or even a different repository. Beyond adding layers, it can also modify image metadata such as entrypoint, command, environment variables, user, and working directory.

The crane append command is not a standard Linux utility and requires the crane tool to be installed separately, typically via go install or pre-compiled binaries. It operates directly with container registries, necessitating proper authentication and permissions for both source and destination images. Layers must be provided in the OCI-compliant .tar.gz format. While powerful for incremental updates, misuse can lead to broken or incompatible image configurations. It is specifically designed for container image layers and not for general filesystem operations.

The layers provided to crane append must be in a specific .tar.gz format, representing a filesystem difference (a 'diff' layer). These can often be generated from a Docker container using docker export followed by compressing the output, or by manually creating a .tar.gz of the desired files.

Common applications include adding runtime configurations (e.g., config maps, secrets), applying security patches to existing base images, updating application binaries without rebuilding the entire stack, or injecting environment variables directly into an image. It's highly favored in environments where image immutability and rapid deployment are critical.

crane is a project from Google's go-containerregistry repository, designed to provide a suite of tools for direct interaction with container registries without relying on a full Docker daemon. It emerged around 2018-2019 to address challenges in CI/CD environments where fast, efficient, and daemon-less operations on container images were crucial. The append subcommand was developed to facilitate incremental updates and patches to existing images, avoiding the time-consuming process of rebuilding an entire image from a Dockerfile for minor changes. This makes it particularly valuable for optimizing build times and network bandwidth in automated pipelines.

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