crane-flatten

Flatten an image

$ crane flatten

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

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

crane [GLOBAL_OPTIONS] flatten SOURCE_IMAGE_REFERENCE DESTINATION_IMAGE_REFERENCE

SOURCE_IMAGE_REFERENCE
    The reference to the source container image (e.g., myregistry/myimage:latest) to be flattened.

DESTINATION_IMAGE_REFERENCE
    The reference where the flattened image will be pushed (e.g., myregistry/myimage:flattened).

--allow-nondistributable-artifacts
    Allows pushing non-distributable layers, such as scratch-based layers. Defaults to false.

--insecure
    Permits insecure HTTP requests to registries, bypassing TLS certificate verification. Use with caution. Defaults to false.

--platform=/
    Specifies the target platform (e.g., linux/amd64, linux/arm64) for the image if it's a multi-platform image. Defaults to linux/amd64.

--registry-option==
    Provides registry-specific options in key=value format (e.g., gcr.io=allow-nondistributable-artifacts).

--user-agent=
    Sets the User-Agent string for registry requests.

The crane flatten command, part of the go-containerregistry project's
crane CLI tool, is designed to optimize container images by consolidating
all their distinct layers into a single, cohesive layer.

Container images are typically built as a series of read-only layers,
where each layer represents a change from the previous one. While this
layered approach offers efficient storage and caching during image builds,
it can sometimes lead to larger-than-necessary images, especially if files
are added and then removed in subsequent layers.

crane flatten addresses this by effectively 'squashing' all these
intermediate layers down to a single filesystem state. This process
can result in a smaller final image size, potentially reducing download
times and attack surface by eliminating unnecessary historical data or
intermediate build artifacts. It's particularly useful for creating
minimal base images (like 'scratch' based images) or for preparing images
for environments where a flattened structure is preferred for security or
simplicity reasons.

• Loss of History: Flattening an image removes the ability to inspect individual layers, making it harder to understand the image's build history or debug issues related to specific changes.
• Debugging Challenges: Without distinct layers, debugging an image that encounters issues can be more complex, as you lose the granular context of how the filesystem evolved.
• Potential Size Increase: In rare cases, if a layer adds a large file and a subsequent layer removes it, flattening might result in a larger image size compared to the original layered image, as the 'removed' data might still contribute to the single flattened layer's size if not properly optimized during the squashing process.
• Cache Invalidation: A flattened image will not benefit from Docker/container runtime layer caching, as there's only one layer to cache.

crane flatten is commonly used for:

• Creating truly minimal images (e.g., from FROM scratch) by removing all
  intermediate build artifacts and tools from the final image.
• Reducing the attack surface of an image by eliminating potentially vulnerable
  files that were only temporarily present in intermediate layers.
• Simplifying image structure for specific deployment scenarios or custom
  container runtimes that might prefer single-layer images.

Traditional container images are built as a union filesystem of multiple layers.
Each ADD, COPY, RUN instruction in a Dockerfile often creates a new layer.
This allows for efficient storage (sharing common base layers) and faster
builds (caching unchanged layers). A flattened image, on the other hand,
represents only the final state of the filesystem, as if all changes from
all layers were applied to a single base layer.

The crane tool is part of the go-containerregistry project, an open-source
library and command-line utility set developed by Google. It provides
efficient, low-level access and manipulation capabilities for container
images and registries, implemented purely in Go. The flatten subcommand
was introduced to address common needs in container image optimization,
especially in cloud-native build pipelines and environments where image size
and simplicity are critical considerations. Its development reflects the
ongoing evolution of best practices for container image management.

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