From e7f9c01bce9a4e7cbeccbb3d68d7bb9776a55573 Mon Sep 17 00:00:00 2001 From: Misty Stanley-Jones Date: Fri, 20 Oct 2017 15:59:04 -0700 Subject: [PATCH] Clarify label and layer guidance (#4992) --- .../eng-image/dockerfile_best-practices.md | 24 +++++++++++++------ 1 file changed, 17 insertions(+), 7 deletions(-) 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