Better documentation for "squash"

[PAStheLoD]

Hello,

It would be very useful to have a better explanation of what steps to take exactly to get a "squashed" image. (Since --squash is removed.)

The error message is very vague: You should squash inside build using a multi-stage Dockerfile for efficiency.

Since ADD/COPY cannot copy multiple source directories in one step users need to use use more than one COPY steps, which will result in multiple layers. (As far as I understand.)

Thanks for considering!

[dockertopia]

@docker/build In this page https://docs.docker.com/engine/reference/commandline/build/ squash is stated as a experimental option. Was this removed?

[jedevc]

The flag has been deprecated for docker buildx build: https://github.com/docker/buildx/blob/441853f189fa51a83d7e241aaa5684a21c8288ab/commands/build.go#L526

but it does still seem to work for docker build (with and without buildkit): https://github.com/moby/moby/blob/51c7992928fb83ecfb4b62fc6cd51c76090e3042/api/server/backend/build/backend.go#L80-L89

@PAStheLoD, you can get a more efficient result using the new COPY --link syntax, which I think should result in a image with a single layer, or you could copy all the contents to a "staging" stage using multiple COPYs, and then copy from the "staging" stage to the final stage.

I'm not quite sure where we would add docs for this, it feels like something to maybe cover in the dockerfile best practices doc, but we're currently attempting to split that up, and there's a lot of build documentation in flux atm - maybe something to cover in what will be our new "using build cache" page, since squashing is related to ordering layers, and etc.

[PAStheLoD]

I used a handy tool wagoodman/dive to see what COPY --link does, and it ends up with one layer per COPY instruction.

We're using a distroless image so we end up adding a few .so files in /lib/x86_64-linux-gnu/ and /usr/lib/x86_64-linux-gnu/, and in /app, and ... I'm not sure how to handle that with a "staging" stage. I tried a few foo/bar-type super example Dockerfiles, but I just end up with /foo instead of /lib/foo, if that makes sense :)

(Maybe simply doing an export-import might be the easiest/fastest anyway, as these images/layers are very small.)

I'm not quite sure where we would add docs for this

I think almost anywhere is fine, Google/StackOverflow/blogs will pick it up.

Thanks for the quick response!

[dockertopia]

@jedevc without additional context I thought of cache as well, thinking if we're providing instructions on how to organize layers in order for cache optimization, that "squashing" could be mentioned in that area. We can additional cross-reference to this content from best practices or creating images (etc.). So that mean including this in WIP documentation. For now what could be the short-term way of addressing this? You said it is deprecated, but also that it works in both backends. Should I just add a deprecation notice?

[jedevc]

CC @thaJeztah - not sure what the intended future of the --squash option is :tada:

I assume that if buildx replaces build at some point, --squash will be fully gone, so is there any danger in marking the option as deprecated? If we are intending to keep supporting it, then buildx should probably implement it as well for consistency.

[AdrianBalcan]

This is confusing!! I spend too much time trying to make docker buildx --squash work, exactly as the documentation suggests.

In my opinion, is that --squash can be useful in some scenarios (eg. at the build stage for specific layer commits) to reduce the infrastructure complexity.

[bzip2]

If you run e.g.:

FROM scratch COPY --from=source_image / /

and set environment variables, endpoints, etc, would that acccomplish the same thing as squashing?

@jedevc: I'd suggest removing the --squash flag from the reference docs AND turning the warning into an error. It's totally understandable that the docs are in flux, but I wish I had known a long time ago that there's no way to squash with buildx. The flag is not deprecated (still working, discouraged, to be removed in the future) so the reference page is misleading, and the warning misled me twice (I missed it for a while, then looked for what it suggested).