crane-mutate

New annotations to set (default [])

$ crane mutate [[-a|--annotation]]/[[-l|--label]] [annotation/label]

$ crane mutate [--append]/[--cmd]/[--entrypoint]/[[-e|--env]]/[--exposed-ports] [var1 var2 ...]

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

$ crane mutate --set-platform [platform_name]

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

$ crane mutate [[-u|--user]] [username]

$ crane mutate [[-w|--workdir]] [path/to/workdir]

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

crane mutate original_image_ref [flags]

--add-layer
    Adds a new layer to the image from a local tarball (e.g., 'crane save' output or a custom tarball).

--cmd '["cmd","arg"]'
    Sets the default command (CMD) for the image. Must be a JSON array string.

--config-file
    Applies multiple mutations from a YAML or JSON configuration file. This is a powerful way to define complex changes.

--delete-layer
    Deletes a layer from the image identified by its digest (e.g., 'sha256:...').

--entrypoint '["cmd","arg"]'
    Sets the entrypoint for the image. Must be a JSON array string.

--env
    Sets or overrides an environment variable in the image configuration. Can be specified multiple times.

--label
    Sets or overrides an image label. Can be specified multiple times.

--new-tag
    Applies a new tag to the mutated image. The mutated image is pushed to the original repository with this new tag.

--os
    Sets the operating system (e.g., 'linux', 'windows') in the image configuration.

--os-feature
    Sets an OS feature (e.g., 'windows.servercore'). Can be specified multiple times.

--os-version
    Sets the OS version string in the image configuration.

--output
    Writes the mutated image to a local OCI layout path instead of pushing it back to a registry.

--platform
    When mutating a multi-platform (manifest list) image, specifies the target platform (e.g., 'linux/amd64', 'windows/arm64') to mutate.

--user
    Sets the user or UID/GID that the container will run as.

--working-dir
    Sets the working directory for the container.

The crane mutate command, part of the go-containerregistry (crane) utility, allows for efficient modification of container image metadata and content directly within a container registry without requiring a full image pull or a local Docker daemon. It enables users to alter various aspects of an image, such as environment variables, labels, entrypoints, working directories, or even add/delete layers. This capability is particularly valuable in CI/CD pipelines for post-processing images, re-tagging, or applying patches without incurring the overhead of rebuilding or transferring large image blobs locally. It manipulates the image manifest and configuration, then pushes the updated manifest back to the registry, often resulting in a new image digest.

The crane mutate command requires direct network access to the container registry and appropriate authentication credentials. When mutating an image, a new manifest is typically pushed, potentially with a new digest. If you specify --new-tag, it will overwrite any existing image at that tag. Exercise caution, especially in production environments, as unintended changes or tag overwrites can occur. It's crucial to understand that 'mutate' doesn't *change* the existing image in-place, but rather creates a modified *version* of it.

crane is a standalone Go binary. It can be installed by downloading pre-built releases from its GitHub repository (github.com/google/go-containerregistry/pkg/crane) or via go install if you have the Go toolchain configured.

crane mutate uses standard OCI registry authentication mechanisms, typically reading credentials from your Docker configuration file (~/.docker/config.json) or environment variables (e.g., DOCKER_USERNAME, DOCKER_PASSWORD).

Common use cases for crane mutate include:
- Adding security scan results as image labels.
- Changing the entrypoint or CMD of a base image for specific deployments.
- Stripping sensitive environment variables post-build.
- Re-tagging an image with new version identifiers without a full re-push.
- Applying patches (e.g., adding a security fix layer) without rebuilding the entire application.

The crane utility, including its mutate subcommand, is part of the go-containerregistry (pkg/crane) project, developed primarily by Google. It emerged as a lightweight, Go-based tool for interacting with OCI (Open Container Initiative) compatible container registries without the need for a full Docker daemon. Its development aimed to provide more granular control and scripting capabilities for registry operations, particularly valuable in cloud-native build pipelines and CI/CD workflows where fast, direct registry interaction is crucial. The 'mutate' subcommand was introduced to address the need for modifying image metadata and layers post-build, offering a powerful alternative to re-building an entire image for minor configuration changes.

crane(1), crane push(1), crane pull(1), crane config(1), skopeo(1), docker(1)