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 image_name [options]

image_name
    The name of the container image to mutate. This can include the registry and tag (e.g., docker.io/library/nginx:latest).

--append path=file
    Appends a file to the image at the specified path.

--env key=value
    Sets an environment variable in the image configuration.

--expose port
    Exposes a port from the image.

--label key=value
    Adds a label to the image.

--remove path
    Removes a file or directory from the image.

--config file
    Specifies a configuration file with multiple mutation instructions.

--user user
    Sets the user context of the container. Should be either user ID or username.

--cmd cmd
    Sets the CMD instruction for the image.

--entrypoint entrypoint
    Sets the ENTRYPOINT instruction for the image.

The crane mutate command is a part of the crane tool, which provides functionalities to manipulate container images.

Specifically, crane mutate allows you to alter a container image in-place, without needing to rebuild it from scratch.

This is particularly useful for making small modifications such as updating metadata, adding or removing files, modifying environment variables, or changing labels.

Instead of rebuilding an entire image, crane mutate operates directly on the image layers, drastically reducing the time needed for simple image updates, improving deployment cycles and efficiency.

It simplifies tasks such as updating configuration files within an image, patching vulnerabilities, or customizing images for specific environments.

Modifying images with crane mutate can potentially invalidate existing image signatures or break applications that rely on specific image contents. Always test mutated images thoroughly before deploying them in production. Changing the image configuration may require corresponding changes in orchestration and deployment systems.

Example 1:
Add file `/app/config.json` to an image:
crane mutate my-image:latest --append /app/config.json=config.json

Example 2:
Set environment variable `API_KEY` in an image:
crane mutate my-image:latest --env API_KEY=secret

crane and its mutate subcommand are relatively recent additions to the container tooling landscape. They emerged to address the need for more efficient ways to modify container images without requiring full rebuilds. Its development focuses on providing a streamlined and lightweight approach to image manipulation, filling a gap in existing container workflows.

The tool is actively developed and sees increasing adoption for tasks related to patching, customization, and optimization of container images.

crane(1), docker(1), skopeo(1)