Add some docs about build-arg's impact on the cache #18161
Conversation
| In this example, the cache miss will occur on line 3 because the value of | ||
| an environment variable (which is saved in the resulting image) is changed | ||
| as we change the `CONT_IMG_VER` build arg value. | ||
|
|
There was a problem hiding this comment.
Should we mention that in this case, the value is persisted in the final image, because it is now used in an ENV? Possibly general knowledge, but may something that trip users.
Edit: ignore, was reading to fast, it is mentioned in the text 😊
|
Ignore my previous comment, lol. Thanks @duglin, LGTM! ping @SvenDowideit @moxiegirl PTAL |
| @@ -1135,6 +1135,38 @@ corresponding `ARG` instruction in the Dockerfile. | |||
| To use these, simply pass them on the command line using the `--build-arg | |||
| <varname>=<value>` flag. | |||
|
|
|||
| ### Impact on build caching | |||
There was a problem hiding this comment.
@duglin thanks for the contribution. A few tweaks...
Impact on build caching
ARG variables are not persisted into the built image as ENV variables are.
However, ARG variables do impact the build cache in similar ways. If a
Dockerfile defines an ARG variable its value is different from a previous
build, then a "cache miss" occurs upon its first usage, not its declaration.
For example, consider this Dockerfile:
1 FROM ubuntu
2 ARG CONT_IMG_VER
3 RUN echo $CONT_IMG_VER
If you specify --build-arg CONT_IMG_VER=<value> on the command line the
specification on line 3 does not cause a cache miss; Line 3 does cause a cache
miss. The definition on line 2 has no impact on the resulting image. The RUN
on line 3 executes a command and in doing so defines a set of environment
variables, including CONT_IMG_VER. At that point, the ARG variable may
impact the resulting image, so a cache miss occurs.
Consider another example under the same command line:
1 FROM ubuntu
2 ARG CONT_IMG_VER
3 ENV CONT_IMG_VER $CONT_IMG_VER
4 RUN echo $CONT_IMG_VER
In this example, the cache miss occurs on line 3. The miss happens because the variable's value the ENV references the ARG variable and that variable is changed through the command line. In this example, the ENV command causes the image to include value.
|
@moxiegirl ok picked up your edits - made a few minor tweaks due to missing words, but otherwise just copy-n-pasted. PTAL |
| In this example, the cache miss occurs on line 3. The miss happens because | ||
| the variable's value in the `ENV` references the `ARG` variable and that | ||
| variable is changed through the command line. In this example, the `ENV` | ||
| command causes the image to include value. |
There was a problem hiding this comment.
looks like this is missing a word: "to include value", the value perhaps?
Closes moby#18017 Signed-off-by: Doug Davis <dug@us.ibm.com>
|
Thanks @duglin, LGTM counting @moxiegirl's example as the second LGTM 😇 |
Add some docs about build-arg's impact on the cache
|
@duglin Thank you! My mom is visiting so I was trying to talk and write at the same time. Have a Happy Thanksgiving! |
Closes #18017
Signed-off-by: Doug Davis dug@us.ibm.com