diff --git a/engine/userguide/eng-image/dockerfile_best-practices.md b/engine/userguide/eng-image/dockerfile_best-practices.md index c00def11c5..6b9fb0c4db 100644 --- a/engine/userguide/eng-image/dockerfile_best-practices.md +++ b/engine/userguide/eng-image/dockerfile_best-practices.md @@ -99,9 +99,19 @@ If containers depend on each other, you can use [Docker container networks](http ### Minimize the number of layers -You need to find the balance between readability (and thus long-term -maintainability) of the `Dockerfile` and minimizing the number of layers it -uses. Be strategic and cautious about the number of layers you use. +Prior to Docker 17.05, and even more, prior to Docker 1.10, it was important +to minimize the number of layers in your image. The following improvements have +mitigated this need: + +- In Docker 1.10 and higher, only `RUN`, `COPY`, and `ADD` instructions create + layers. Other instructions create temporary intermediate images, and no longer + directly increase the size of the build. + +- Docker 17.05 and higher add support for + [multi-stage builds](multistage-build.md), which allow you to copy only the + artifacts you need into the final image. This allows you to include tools and + debug information in your intermediate build stages without increasing the + size of the final image. ### Sort multi-line arguments @@ -192,10 +202,10 @@ LABEL com.example.release-date="2015-02-12" LABEL com.example.version.is-production="" ``` -An image can have more than one label. To specify multiple labels, Docker -recommends combining labels into a single `LABEL` instruction where possible. -Each `LABEL` instruction produces a new layer which can result in an inefficient -image if you use many labels. This example results in a single image layer. +An image can have more than one label. Prior to Docker 1.10, it was recommended +to combine all labels into a single `LABEL` instruction, to prevent extra layers +from being created. This is no longer necessary, but combining labels is still +supported. ```conf # Set multiple labels on one line