zstd `compression-level` should cover level mapping

[polarathene]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

I can't find what I'm looking for

Description

The docs communicate support for zstd compression when building with the compression-level range matching that of standard zstd, however a custom mapping since support was introduced in 2022 reveals that is not the case (the docs do link to the Go library used for zstd with the 4 supported levels documented at the README, but the approximated zstd levels documented do not align with what BuildKit is using).

Full details: moby/buildkit#6291 (comment)

Location

https://docs.docker.com/build/exporters/#compression

Suggestion

A table like this may help (or a link to my comment on the related buildkit GH discussions):

compression-level	klauspost/compress/zstd level	Approx zstd compression level
0-2	Fastest	1
3-6 (default)	Default	3
7-8	Better	7
9+	Best	11

NOTE: The mapping may no longer be accurate, the Go library's README hasn't updated that section since Dec 2020.

Additionally it would be very helpful to communicate zstd:chunked support. AFAIK this is not supported (pull or build) with Docker or BuildKit, only the fallback to zstd via backwards-compatibility.

Some resources online seem to imply that zstd:chunked is supported in a meaningful way beyond zstd pull support, but if the additional optimizations are not supported like with Podman, this should be clarified so that the information is easier to discover and confirm.

[github-actions]

❌ The agent team encountered an error. Please check the workflow logs for details.

[github-actions]

✅ The agent team has created a PR to address this issue. Please review when ready.