【Docker】Dockerfile 之 ARG（二）

參考教程：https://docs.docker.com/engine/reference/builder/

環境

1. virtual box 6.1
2. centos 7.8
3. docker 19.03

ARG

使用 ARG 變量

You can use an ARG or an ENV instruction to specify variables that are available to the RUN instruction. Environment variables defined using the ENV instruction always override an ARG instruction of the same name. Consider this Dockerfile with an ENV and ARG instruction.

您可以使用 ARG 或 ENV 指令來指定可用於 RUN 指令的變量。使用 ENV 指令定義的環境變量始終會覆蓋同名的 ARG 指令。考慮這個帶有 ENV 和 ARG 指令的 Dockerfile。

FROM ubuntu
ARG CONT_IMG_VER
ENV CONT_IMG_VER=v1.0.0
RUN echo $CONT_IMG_VER

Then, assume this image is built with this command:
然后，假定此鏡像是使用以下命令構建的：

$ docker build --build-arg CONT_IMG_VER=v2.0.1 .

In this case, the RUN instruction uses v1.0.0 instead of the ARG setting passed by the user:v2.0.1 This behavior is similar to a shell script where a locally scoped variable overrides the variables passed as arguments or inherited from environment, from its point of definition.

在這種情況下，RUN 指令使用 v1.0.0 而不是用戶傳遞的 ARG 值：v2.0.1。這種行為類似於 shell 腳本，其中局部作用域的變量覆蓋了傳遞的變量。從其定義的角度出發，還是從環境繼承而來的。

Using the example above but a different ENV specification you can create more useful interactions between ARG and ENV instructions:

使用上面的示例但使用不同的 ENV 規范，您可以在 ARG 和 ENV 指令之間創建更有用的交互：

FROM ubuntu
ARG CONT_IMG_VER
ENV CONT_IMG_VER=${CONT_IMG_VER:-v1.0.0}
RUN echo $CONT_IMG_VER

Unlike an ARG instruction, ENV values are always persisted in the built image. Consider a docker build without the --build-arg flag:

與 ARG 指令不同， ENV 值始終保留在生成的鏡像中。考慮一個沒有 --build-arg 標志的 docker build：

$ docker build .

Using this Dockerfile example, CONT_IMG_VER is still persisted in the image but its value would be v1.0.0 as it is the default set in line 3 by the ENV instruction.

使用此 Dockerfile 示例，CONT_IMG_VER 仍保留在鏡像中，但其值將為 v1.0.0，因為它是 ENV 指令在第 3 行中設置的默認值。

The variable expansion technique in this example allows you to pass arguments from the command line and persist them in the final image by leveraging the ENV instruction. Variable expansion is only supported for a limited set of Dockerfile instructions.

在此示例中，變量擴展技術使您可以從命令行傳遞參數，並利用 ENV 指令將其保留在最終鏡像中。僅有限的一組 Dockerfile 指令支持變量擴展。

預定義的變量

Docker has a set of predefined ARG variables that you can use without a corresponding ARG instruction in the Dockerfile.

Docker 有一組預定義的 ARG 變量，您可以在 Dockerfile 中使用它們而無需相應的 ARG 指令。

• HTTP_PROXY
• http_proxy
• HTTPS_PROXY
• https_proxy
• FTP_PROXY
• ftp_proxy
• NO_PROXY
• no_proxy

To use these, simply pass them on the command line using the flag:

要使用這些，只需使用以下標志在命令行中傳遞它們：

--build-arg <varname>=<value>

By default, these pre-defined variables are excluded from the output of docker history. Excluding them reduces the risk of accidentally leaking sensitive authentication information in an HTTP_PROXY variable.

默認情況下，這些預定義變量從 docker history 輸出中排除。排除它們會降低意外泄露敏感身份驗證信息到 HTTP_PROXY 變量中的風險。

For example, consider building the following Dockerfile using --build-arg HTTP_PROXY=http://user:[e-mail].

例如，考慮使用 --build-arg HTTP_PROXY=http://user:[e-mail] 構建以下Dockerfile。

FROM ubuntu
RUN echo "Hello World"

In this case, the value of the HTTP_PROXY variable is not available in the docker history and is not cached. If you were to change location, and your proxy server changed to http://user:[e-mail], a subsequent build does not result in a cache miss.

在這種情況下，docker_history 中沒有 HTTP_PROXY 變量的值，也不被緩存。如果要更改位置，並且您的代理服務器已更改為 http://user:[e-mail]，則后續的構建不會導致高速緩存未命中。

If you need to override this behaviour then you may do so by adding an ARG statement in the Dockerfile as follows:

如果您需要覆蓋此行為，則可以通過在 Dockerfile 中添加 ARG 語句來做到這一點，如下所示：

FROM ubuntu
ARG HTTP_PROXY
RUN echo "Hello World"

When building this Dockerfile, the HTTP_PROXY is preserved in the docker history, and changing its value invalidates the build cache.

構建此 Dockerfile 時，HTTP_PROXY 保留在 docker history 中，並且更改其值會使構建緩存無效。

對構建緩存的影響

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 whose value is different from a previous build, then a “cache miss” occurs upon its first usage, not its definition. In particular, all RUN instructions following an ARG instruction use the ARG variable implicitly (as an environment variable), thus can cause a cache miss. All predefined ARG variables are exempt from caching unless there is a matching ARG statement in the Dockerfile.

ARG 變量不會像 ENV 變量那樣持久保存到構建的鏡像中。但是，ARG 變量確實以類似的方式影響構建緩存。如果 Dockerfile 定義了一個值與先前版本不同的 ARG 變量，則首次使用時會發生“緩存未命中”，而不是其定義。尤其是，緊跟在 ARG 指令之后的所有 RUN 指令都隱式地使用 ARG 變量（作為環境變量），因此可能導致高速緩存未命中。除非在 Dockerfile 中有匹配的 ARG 語句，否則所有預定義的 ARG 變量均免於緩存。

For example, consider these two Dockerfile:

例如，考慮以下兩個 Dockerfile：

FROM ubuntu
ARG CONT_IMG_VER
RUN echo $CONT_IMG_VER

FROM ubuntu
ARG CONT_IMG_VER
RUN echo hello

If you specify --build-arg CONT_IMG_VER=<value> on the command line, in both cases, the specification on line 2 does not cause a cache miss; line 3 does cause a cache miss.ARG CONT_IMG_VER causes the RUN line to be identified as the same as running CONT_IMG_VER=<value> echo hello, so if the <value> changes, we get a cache miss.

如果在命令行上指定 --build-arg CONT_IMG_VER = <value>，則在兩種情況下，第 2 行的規范都不會導致高速緩存未命中。第 3 行確實會導致緩存未命中。ARG CONT_IMG_VER 會導致 RUN 行被標識為與運行 CONT_IMG_VER = <value> echo hello 相同，因此，如果 <value> 發生更改，我們將得到緩存未命中。

Consider another example under the same command line:

考慮同一命令行下的另一個示例：

FROM ubuntu
ARG CONT_IMG_VER
ENV CONT_IMG_VER=$CONT_IMG_VER
RUN echo $CONT_IMG_VER

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 the value.

在此示例中，高速緩存未命中發生在第 3 行。之所以發生未命中，是因為 ENV 中的變量值引用了 ARG 變量，並且該變量通過命令行進行了更改。在這個例子中，ENV 命令使鏡像包含該值。

If an ENV instruction overrides an ARG instruction of the same name, like this Dockerfile:

如果 ENV 指令覆蓋了同名的 ARG 指令，例如 Dockerfile：

FROM ubuntu
ARG CONT_IMG_VER
ENV CONT_IMG_VER=hello
RUN echo $CONT_IMG_VER

Line 3 does not cause a cache miss because the value of CONT_IMG_VER is a constant (hello). As a result, the environment variables and values used on the RUN (line 4) doesn’t change between builds.

第 3 行不會導致緩存未命中，因為 CONT_IMG_VER 的值是一個常量（hello）。因此，RUN（第4行）中使用的環境變量和值在構建之間不會更改。

總結

介紹了 Dockerfile 中 ARG 指令的使用方式，預定義的變量和對緩存的影響。