惠州房地产网站开发,网站对比app还有优势吗,农家乐网站源码,泉州网站建设方案维护目录 1. 背景2. 参考3. 原文3.1 Dockerfile 支持的指令3.2 Dockerfile格式3.3 Parser指令syntaxescape 3.4 环境变量替换3.5 docker构建忽略文件3.6 Shell 和 exec 格式Exec 格式Shell 格式使用不同的 shell 3.7 FROM指令了解ARG和FROM如何交互 3.8 RUN指令RUN指令缓存失效RUN … 目录 1. 背景2. 参考3. 原文3.1 Dockerfile 支持的指令3.2 Dockerfile格式3.3 Parser指令syntaxescape 3.4 环境变量替换3.5 docker构建忽略文件3.6 Shell 和 exec 格式Exec 格式Shell 格式使用不同的 shell 3.7 FROM指令了解ARG和FROM如何交互 3.8 RUN指令RUN指令缓存失效RUN --mountRUN --mounttypebind选项RUN --mounttypecache选项RUN --mounttypetmpfs选项RUN --mounttypesecret选项RUN --mounttypessh选项RUN --networkRUN --networkdefault选项RUN --networknone选项RUN --networkhost选项RUN --security选项 3.9 CMD指令3.10 LABEL指令3.11 MAINTAINER指令 (不建议)3.12 EXPOSE指令3.13 ENV指令3.14 ADD指令Adding private Git repositories私有git仓库ADD --keep-git-dir选项ADD --checksum选项ADD --chown --chmod选项ADD --link选项ADD --exclude选项 3.15 COPY指令COPY --chown --chmod选项**COPY** --link选项COPY --parents选项COPY --exclude选项 3.16 ENTRYPOINT指令Exec 格式的 ENTRYPOINT 示例Shell 格式 ENTRYPOINT 示例理解 CMD 和 ENTRYPOINT 是如何作用的 3.17 VOLUME指令关于指定卷的说明 3.18 USER指令3.19 WORKDIR指令3.20 ARG指令默认值范围使用ARG变量预定义ARG全局范围的ARGSBuildKit内置生成参数对构建缓存的影响 3.21 ONBUILD指令3.22 STOPSIGNAL指令3.23 HEALTHCHECK指令3.24 SHELL指令3.25 Here-Documents用法示例运行多行脚本示例创建实时文件 3.26 Dockerfile 示例 1. 背景
记录了Dockerfile 的构建镜像的知识。
2. 参考
链接: docker官方文档-Dockerfile reference链接: 关于制作Docker镜像| Dockerfile快速开始链接: Dockerfile的COPY --link链接: Docker笔记-08 Docker BuildKit
3. 原文
Docker可以通过从Dockerfile中读取指令来自动构建镜像。Dockerfile是一个文本文件它包含用户在命令行上调用用以组装镜像的所有命令。以下介绍可以在Dockerfile中使用的指令。
3.1 Dockerfile 支持的指令
指令说明ADD添加本地或远程的文件和目录。ARG构建时使用的变量。CMD容器启动时默认执行的命令。可作为ENTRYPOINT的参数使用COPY复制文件和目录ENTRYPOINT指定默认可执行文件。ENV设置环境变量。EXPOSE描述容器内应用程序正在侦听哪些端口。FROM从基础镜像产生一个新构建阶段。HEALTHCHECK启动时检查容器的健康状况。LABEL向镜像添加元数据标签。MAINTAINER指定镜像的作者。ONBUILD指定在镜像被用于构建时的指令。RUN构建中执行命令。SHELL设置镜像的默认shell。STOPSIGNAL指定退出容器的系统调用信号。USER设置用户和组ID。VOLUME创建卷挂载。WORKDIR更改工作目录。
3.2 Dockerfile格式
以下是Dockerfile的格式
第1行 # 注释第2行指令 参数
“指令”不区分大小写。但习惯将它们大写以便更容易地将它们与参数区分开。 Docker按顺序运行Dockerfile中的指令。Dockerfile必须以FROM指令开头。但它可以在Parser指令、注释和全局ARG之后三项都是可选项用法详见下。FROM指令指定构建的父镜像。FROM前面能有一个或多个ARG指令这些指令声明的参数将用在Dockerfile中FROM行中。
BuildKit将以#开头的行视为注释除非该行是有效的Parser指令。行中其他任何位置的#标记都被视为参数。这允许以下语句
第1个# 注释第2个# 参数
在执行Dockerfile指令之前注释行将被删除。在shell执行echo命令之前将删除以下示例中的注释。 上下两个指令执行效果相同 注释不支持换行符。
关于空白的注释 为了向后兼容注释#和指令如RUN之前的前导空格将被忽略但不鼓励使用。在这些情况下不会保留前导空格因此以下示例是等效的 然而指令参数中的空白并没有被忽略。以下示例按指定打印带有前导空格的hello-world
3.3 Parser指令
Parser指令是可选的并影响Dockerfile中后续行的处理方式。Parser指令不会向构建中添加层也不会显示为构建步骤。Parser指令被写成一种特殊类型的注释形式格式为# 指令值。单个指令只能使用一次。
一旦处理了注释、空行或构建器指令BuildKit就不再查找Parser指令。相反它将任何格式化为Parser指令的内容视为注释并且不尝试验证它是否可能是Parser指令。因此所有Parser指令都必须位于Dockerfile的顶部。
Parser指令不区分大小写但它们习惯写成小写。在任何Parser指令后面都包含一个空行也是惯例。Parser指令中不支持换行符。
由于这些规则以下示例全部无效
使用换行符 使用两次 在构建指令后面被当作注释 在注释后面被当作注释 因为不能识别 unknowndirectivevalue被认定为注释导致下一行正确的Parser指令syntaxvalue也被当作注释 Parser指令中允许使用非换行空格。因此以下行的处理方式完全相同造成重复使用多次 支持的两种Parser指令:
syntaxescape
syntax
使用syntax指令来声明用于构建的Dockerfile语法版本。如果未指定BuildKit将使用Dockerfile前端的捆绑版本。通过声明语法版本您可以自动使用最新的Dockerfile版本而无需升级BuildKit或Docker Engine甚至无需使用自定义Dockerfile实现。
使用说明:
docker/dockerfile:1持续使用1.x.x的最新版本
# syntaxdocker/dockerfile:1docker/dockerfile:1.2 持续使用1.2.x的最新版本不会使用如1.3.0版本
# syntaxdocker/dockerfile:1.2docker/dockerfile:1.2.1 指定版本不会更新
# syntaxdocker/dockerfile:1.2.1escape
escape指令设置用于对Dockerfile中的字符进行转义的字符。如果未指定则默认转义符为 \。
转义符既用于转义一行中的字符也用于转义换行符。这允许Dockerfile指令跨越多行。请注意无论转义解析器指令是否包含在Dockerfile中转义都不会在RUN命令中执行除非在行的末尾。
将转义符设置为 在Windows上特别有用因为 \ 是Windows目录路径分隔符。 使用 与Windows PowerShell一致
请看以下在Windows上容易出错的示例。第二行末尾的第二个 \ 将被解释为转义换行符而不是第一个 \ 的转义目标。类似地第三行末尾的 \ 实际也被认为是换行符的转义符。 这个结果导致第二行和第三行被认为是一条指令。 上述问题的一个解决方案是使用 / 作为COPY指令和dir的目标。然而这种语法往好了说是令人困惑的因为它对Windows上的路径来说不是自然的往坏了说是容易出错的因为并非Windows上的所有命令都支持 / 作为路径分隔符。
通过添加escape解析器指令# escape以下Dockerfile使用自然语义处理在Windows上的文件路径结果如预期的那样 结果
3.4 环境变量替换
环境变量用ENV声明也可以在某些指令中用作变量被Dockerfile解析。转义也被处理以便在指令中包含类似变量的语法。
环境变量在Dockerfile中用 $variable_name 或 ${variable_name} 表示。它们被同等对待大括号语法通常用于解决没有空格的变量名的问题比如${foo}_bar。
${variable_name} 语法还支持下列中标准bash修饰符
${variable:-word} 表示如果设置了变量则结果将是该值。若没有设置变量那个么word将是结果。${variable:word} 表示如果设置了变量则word将是结果否则结果为空字符串。
在Dockerfile语法的预发布版本中当在Dockerfile中使用 # syntaxdocker/dokerfile upstream:master 的syntax语法指令时支持以下变量替换
${variable#pattern} 从variable开头查找从variable中移除最短的匹配pattern ${variable##pattern} 从variable开头查找从variable中移除最长的匹配pattern ${variable%pattern} 从variable尾部查找从variable中移除最短的匹配pattern ${variable%pattern} 从variable尾部查找从variable中移除最长的匹配pattern ${variable/pattern/replacement} 从variable开头查找从variable中查找第一个pattern并用replacement替换 ${variable//pattern/replacement} 从variable开头查找从variable中查找全部pattern并用replacement替换 在任何情况下Word都可以是任何字符串包括其他环境变量。
pattern是 glob 匹配模式 使用匹配任意单个字符和* 匹配任意数量的字符包括零。如果匹配原始含义和 *需要使用反斜杠转义\和\* 进行转义
也可以通过在变量前添加 \ 来转义整个变量名例如$foo 或 ${foo} 将分别转换为 $foo和 ${foo} 原始含义。
举个例子 (转换结果显示在 # 后面): Dockerfile中的以下列表中指令支持环境变量
ADDCOPYENVEXPOSEFROMLABELSTOPSIGNALVOLUMEWORKDIRONBUILD (需要与上面中的指令结合使用)
也可以将环境变量放在RUN、CMD和ENTRYPOINT指令一起使用但在这些情况下变量替换由shell处理而不是由构建器处理。需要注意使用exec格式的指令不会自动调用shell命令执行。详见变量替换。
如果您想用shell处理合理的方式是使用shell格式 或者在 exec格式中直接执行shell 例如: RUN [ “sh”, “-c”, “echo $HOME” ].
环境变量替换会贯彻整条指令同一条指令中每个变量使用相同的值。如果更改了变量的值那么仅会在后续指令中生效。看以下示例
第1行赋值环境变量 abchello第2行重新赋abcbye同时使用变量赋值给变量def这时变量def的值是第1行定义的“hello”第3行再次使用变量abc赋值给变量ghi这时变量的ghi的值是第2行定义的“bye”
3.5 docker构建忽略文件
您可以使用.dockerignore文件从构建上下文中排除需要忽略的文件和目录。有关详细信息请参阅.dockerignore文件。
文件格式如下 build客户端在上下文的根目录下查找.dokerignore如果存在那么与.dokerignore文件中匹配的文件和目录会在送往builder服务端之前移除。注意被排除的文件和目录的也是在上下文的根目录下开始查找。
如果有多个Dockerfile文件每个可以对应各自的.dockerignore文件。格式为: Dockerfile名称.dokerignore 。例如
build.Dockerfile 对应 build.Dockerfile.dockerignorelint.Dockerfile 对应 lint.Dockerfile.dockerignoretest.Dockerfile 对应 test.Dockerfile.dockerignore
3.6 Shell 和 exec 格式
RUN、CMD和ENTRYPOINT指令都有两种可用的格式
exec 格式指令 [“executable”,“param1”,“param2”]shell 格式指令 command param1 param2
exec格式可以避免shell字符串转换并使用特定的shell命令或任何其他可执行文件调用。它使用JSON数组语法其中数组中的每个元素都是一个命令、标志或参数。
shell格式更为宽松强调易用性、灵活性和可读性。shell格式自动使用shell命令而exec格式则不会。
Exec 格式
exec格式被解析为JSON数组这意味着您必须在单词周围使用双引号“而不是单引号。 exec格式主要用于定义ENTRYPOINT指令并与CMD指令结合使用用来设置容器运行时重写的默认参数。有关详细信息请参见ENTRYPOINT
变量替换
使用exec表单不会自动调用shell命令。这意味着正常的shell处理如变量替换不会发生。例如RUN[“echo”“ H O M E ” ] 不会处理 HOME”]不会处理 HOME”]不会处理HOME的变量替换。
如果要进行shell处理则使用shell格式或直接使用exec格式执行shell例如RUN[“sh”、“-c”、“echo$HOME”]。当使用exec格式并直接执行shell时就像shell格式的情况一样是shell在执行环境变量替换而不是构建器。
反斜杠
In exec form, you must escape backslashes. This is particularly relevant on Windows where the backslash is the path separator. The following line would otherwise be treated as shell form due to not being valid JSON, and fail in an unexpected way:
在exec格式中必须转义反斜杠。这在反斜杠是路径分隔符的Windows上尤其重要。下面的例子中由于不是有效的JSON行将被视为shell格式导致意外失败
正确的方式见下
Shell 格式
与exec格式不同使用shell格式的指令总是使用shell命令。shell格式不使用JSON数组格式而是一个常规字符串。shell格式字符串允许您使用转义符默认为反斜杠对换行符进行转义以将单个指令延续到下一行将较长的命令拆分为多行。例如 它等同于下面的行 当然也可以用于heredocs分解shell命令 heredocs可以参见Here-Documents
使用不同的 shell
可以使用SHELL命令更改默认shell 更多信息, 详见下面的 SHELL指令
3.7 FROM指令
命令格式 FROM指令初始化一个新的构建阶段并为后续指令设置基础镜像。因此有效的Dockerfile必须以FROM指令开头。设置的镜像可以是任何有效的镜像。 ARG是Dockerfile中FROM之前的唯一指令。请见下了解ARG和FROM如何交互。 FROM可以在单个Dockerfile中多次出现用于创建多个镜像或者将一个构建阶段用作另一个的依赖项。只需在每条新的FROM指令之前记下提交输出的最后一个镜像ID即可。每个FROM指令都会清除先前指令创建的任何状态。 FROM指令可以选择使用AS name定义一个名称作为新的构建阶段的指定名称。该名称可以在随后的FROM和 COPY --FROMname 指令中使用引用在此阶段构建的镜像。 TAG或digest也是可选的。如果省略其中任何一个那么构建器默认采用latest的TAG。如果建器找不到对应的TAG则返回一个错误。
- -platform是可选标志可以指定一个镜像的平台假如FROM指令引用了一个多平台镜像。例如linux/amd64、linux/arm64或windows/amd64。默认情况下会使用构建请求的目标平台。全局构建参数可以用这个标志的值例如 automatic platform ARGs 允许您将阶段强制到本地构建平台 --platform$BUILDPORM并使用它交叉编译到构建阶段内的目标平台。
了解ARG和FROM如何交互
FROM指令支持由出现在第一个FROM之前的任何ARG指令声明的变量。 在FROM之前声明的ARG是在构建阶段之外的因此不能在FROM之后的任何指令中使用。要使用在第一个FROM之前声明的ARG的默认值请在构建阶段内使用没有值的ARG指令
3.8 RUN指令
RUN指令将执行一系列命令在当前镜像的顶部创建一个新层。添加的层将在Dockerfile的下一步中使用。RUN有两种形式 Shell格式是最常用的可以使用 escapes或heredocs将较长的指令分解为多行。 RUN指令的可选项包括:
RUN指令缓存失效
RUN指令的缓存在下一次构建过程中不会自动失效。RUN apt-get dist-upgrade -y等指令的缓存将在下一次构建过程中重复使用。RUN指令可以通过使用 --no-cache 标志不使用缓存例如docker build --no-cacher。
有关更多信息请参阅Dockerfile最佳实践指南。
RUN指令的缓存可以通过ADD和COPY指令失效。
ADD和COPY在功能上相似。COPY支持基础复制从构建上下文或多阶段构建中的一个阶段将文件复制到容器中。ADD支持从远程HTTPS和Git URL获取文件以及在从构建上下文添加文件时自动解压tar文件的功能。
RUN --mount
RUN --mount允许创建构建期间可以访问的文件系统挂载。这可用于
创建到主机文件系统或其他构建阶段的bind挂载访问构建密钥或ssh-agent使用持久化包管理缓存加快构建速度
支持的挂载类型包括
类型描述bind (default)绑定挂载上下文目录只读模式。cache挂载临时目录缓存编译器和包管理器的目录。tmpfs在构建容器中挂载tmpfs。secret允许构建容器访问安全文件如私钥等而无需将它们预制到镜像中ssh允许构建容器通过SSH代理访问SSH密钥并支持密码口令。
RUN --mounttypebind选项
这种挂载类型允许将文件或目录绑定到构建容器中。默认情况下挂载模式是只读。
类型描述target挂载目标路径.source挂载源路径默认路径为根.from源路径的出处构建阶段或镜像像名称。默认为构建上下文。rw,readwrite允许在挂载上写入写入数据会被丢弃
示例参考Docker笔记-08 Docker BuildKit
以下摘自Dockerfile命令详解之 RUN二RUN --mounttypebind
由于RUN指令是容器构建阶段生效运行所以挂载的目录也仅仅在构建阶段可以访问。由于不同的RUN指令会创建新的层所以只有同一个RUN指令中才可以访问挂载的目录。仅支持挂载上下文或者引用的镜像中存在的目录不能挂载宿主机上的目录或者上下文以及镜像中不存在的目录就算挂载上也没有任何意义。
RUN --mounttypecache选项
这种挂载类型允许构建容器挂载临时目录缓存编译器和包管理器的目录。
类型描述id可选ID用于标识单独/不同缓存的缓存。默认为目标的值。。target挂载目标路径ro,readonly设置挂载目录只读sharing值shared、private、locked。shared表示缓存可以被并发写入private表示如果有多个写入者的情况下创建一个新的挂载locked表示串行写入不允许并发写入from指定构建的缓存挂载基础默认是空目录sourcefrom指定的基础镜像的子路径默认是from的根mode八进制中新缓存目录的文件模式。默认0755.uid新缓存目录的用户ID。默认为0。gid新缓存目录的组ID。默认为0。
以下摘自Dockerfile命令详解之 RUN三RUN --mounttypecache
由于RUN指令是容器构建阶段生效运行所以缓存目录也仅仅在构建阶段可以访问。由于不同的RUN指令会创建新的层所以只有同一个RUN指令中才可以访问挂在过来的缓存目录。缓存目录可能会被Docker的GC清理cache类型的挂载方式是为了提高构建效率但是如果多个镜像进行构建的时候需要大量覆盖缓存中的文件那么使用这种方式并不明智。这种缓存主要用于多次构建都没有重大修改的情况
缓存目录的内容在构建器调用之间保持不变而不会使指令缓存失效。缓存挂载只能用于提高性能。您的构建应该可以使用缓存目录中的任何内容与其同时另一个构建可能会覆盖文件或者如果需要更多的存储空间GC可能会对其进行清理。
示例缓存Go包 示例缓存apt包 apt需要对其数据进行独占访问因此缓存使用shareinglocked选项这将确保使用相同缓存挂载的多个并行构建相互等待而不会同时访问相同的缓存文件。在这种情况下如果您希望每个构建都创建另一个缓存目录也可以使用sharingprivate。
说明apt命令需要对/etc/apt, /etc/cache, /var/cache/apt, /var/lib/apt进行读写操作
其它示例参考Docker笔记-08 Docker BuildKit
RUN --mounttypetmpfs选项
此挂载类型允许在构建容器中挂载tmpfs。
类型描述target挂载目标目录size指定挂载文件系统大小上限.
示例参考Docker笔记-08 Docker BuildKit
RUN --mounttypesecret选项
这种挂载类型允许构建容器时访问私钥等安全文件而无需将它们预装到镜像中。
类型描述idID。默认为目标路径的名称。target挂载目标目录。默认是 /run/secrets/ idrequired如果设置为true则当机密不可用时指令会出错。默认为falsemode八进制中机密文件的文件模式。默认0400。uid机密文件的用户ID。默认为0。gid机密文件的组ID。默认为0。
举例访问S3
RUN --mounttypessh选项
这种挂载类型允许构建容器通过SSH代理访问SSH密钥并支持密码口令。
类型描述idSSH代理套接字或密钥的ID。默认为“default”。target挂载目标路径. 默认是 /run/buildkit/ssh_agent.${N}.required如果设置为true则当Key不可用时指令会出错。默认为falsemode八进制套接字的文件模式。默认0600uid用户ID. 默认是 0。gid组ID. 默认是 0。
举例访问gitlab 其它示例参考Dockerfile 使用 SSH docker build
RUN --network
RUN --network允许控制命令在哪个网络环境中运行。 支持的网络类型包括
类型描述default (default)运行在默认网络中。none运行在none网络中。host运行在host网络中。
RUN --networkdefault选项
不提供标志该命令在构建的默认网络中运行。
RUN --networknone选项
该命令在没有网络访问的情况下运行lo仍然可用但与该进程隔离
示例: 隔离外部影响 pip安装tarfile中提供的包tarfile可以由早期的构建阶段控制。
RUN --networkhost选项
该命令在主机的网络环境中运行类似于docker build --networkhost但基于每条指令
警告 --networkhost的使用受network.host权限保护它需要在启动buildkitd daemon时使用 --allow-insecure-entitlement network.host标志或直接在buildkitd配置中添加并且在构建请求中添加 --allow network.host标志。
RUN --security选项
注意 还不能在稳定语法版本中使用请使用 docker/dockerfile:1-labs 版本
默认的安全模式是sandbox。在 --securityinsecurity的情况下构建器运行命令在没有沙箱sandbox的不安全模式下这允许控制运行提升权限例如containerd。这相当于运行docker run --privileged。
警告
为了使用此功能它需要在启动buildkitd daemon时使用 –allow-insecure-entitlement security.insecure标志或直接在buildkitd配置中添加并且在构建请求中添加 –allow security.insecure标志。
默认沙箱模式可以通过 --securitysandbox激活它没有选项。
示例检查权限
3.9 CMD指令
CMD指令设置从镜像运行容器时要执行的命令。
您可以使用shell或exec格式指定CMD指令
exec格式CMD[“可执行文件”、“param1”、“param2”]exec格式CMD[“param1”“param2”]作为ENTRYPOINT指令的默认参数shell格式CMD命令param1 param2
Dockerfile中只能有一条CMD指令。如果列出多个CMD则只有最后一个CMD生效。
CMD的目的是为正在执行的容器提供默认值。这些默认值可以包括可执行文件也可以省略可执行文件ENTRYPOINT指令的参数如果是这种情况还必须指定ENTRYPOINT指令。
如果您希望容器每次都运行相同的可执行文件那么您应该考虑将ENTRYPOINT与CMD结合使用。请参见ENTRYPOINT。一旦用户在docker运行时指定了的参数ENTRYPOINT的参数那么它们将覆盖CMD中设置的默认值但仍使用默认ENTRYPOINT的设置。
如果CMD用于作为ENTRYPOINT指令的默认参数那么CMD和ENTRYPOINT指令都应以exec格式指定。
注意
不要混淆RUN和CMD。RUN实际运行一个命令并且提交结果CMD在构建时不执行任何操作而是为镜像计划执行的命令。
3.10 LABEL指令
LABEL指令将元数据添加到镜像中。LABEL是一个键值对。若要在LABEL值中包含空格请像在命令行语法中一样使用引号和反斜杠。一些用法示例
一个镜像可以有多个标签。可以在一行上指定多个标签。在Docker 1.10之前这能减少了最终镜像的大小但现在已经不是这样了。您仍然可以选择在一条指令中指定多个标签方法有以下两种 注意
请确保使用双引号而不是单引号。特别是当您使用字符串值时例如LABEL example“foo-$ENV_VAR”单引号将按原样使用字符串而不解析拆变量的值。
构建镜像继承基础镜像或父镜像FROM行中的镜像中包含的标签。如果标签已经存在但具有不同的值则最近定义的值将覆盖以前设置的值。
要查看镜像标签请使用docker image inspect命令。您可以使用 --format选项只显示标签
3.11 MAINTAINER指令 (不建议)
MAINTAINER指令设置构建镜像的“作者”字段。LABEL指令是一个更灵活的方式您应该使用它因为它可以设置您需要的任何元数据并且可以很容易地查看例如使用docker inspect。如果要替代MAINTAINER指令可以使用 和其他标签一样它可以被docker inspect查看。
3.12 EXPOSE指令
EXPOSE指令通知Docker容器在运行时侦听指定的网络端口。您可以指定端口侦听TCP或UDP如果未指定协议则默认为TCP。
EXPOSE指令实际上并没有发布端口。它的作用是“构建镜像的人”告诉“运行容器的人”的说明说明要发布哪些端口。要在运行容器时发布端口请在docker run时使用-p标志来发布和映射一个或多个端口或者使用-P标志来发布所有公开的端口并将其映射到高段端口。
默认是 TCP。您也可以指定 UDP: 使用两行同时指定TCP和UDP 在这种情况下如果在docker运行的情况下使用-P端口将为TCP和UDP分别公开一次。请记住-P在主机上使用临时的高段主机端口因此TCP和UDP不使用相同的端口。
不管EXPOSE如何设置都可以在运行时使用-p标志来覆盖它们。例如 要设置端口重定向主机系统端口请参阅运行容器使用参数-P。docker network命令支持创建用于容器之间通信的网络而无需expose或发布特定端口因为连接到网络的容器可以通过任何端口相互通信。有关详细信息请参阅网络概述。
3.13 ENV指令
ENV指令设置环境变量key的值value。该值能在构建阶段的所有后续指令中使用并且可以在许多指令中充当变量替换。该值将被解释为其他环境变量所以如果它没有转义可以不使用引号。与命令行解析一样引号和反斜杠可以用于在值中包含空格。
示例 ENV指令允许一次设置多个keyvalue …下面的例子与上面的产生相同的结果 当从生成的镜像运行容器时使用ENV设置的环境变量将保持不变。您可以使用docker inspect查看这些值并使用 docker run–envkeyvalue 更改它们。
一个构建阶段可以继承来自父阶段或更早使用ENV设置的任何环境变量。更多信息请参阅多阶段构建。
环境变量的持久生效这可能会导致意想不到的副作用。例如设置ENV DEBIAN_FRONTENDnoninteractive会更改apt-get的行为并且可能会混淆您的镜像的用户。
如果只在构建过程中需要环境变量而不是在最终镜像中请考虑为单个命令设置一个值 或者用 ARG, 它不会在保存在最终镜像中: Alternative syntax ENV指令也可以使用替代语法 ENV , 忽略 。 举例: 这种语法不允许在单个ENV指令中设置多个环境变量并且可能会造成混淆。例如以下设置值为“TWOTHREEworld”的单个环境变量ONE 出于向后兼容性的考虑目前支持替代语法但由于上述原因不鼓励使用该语法并且可能在未来的版本中删除。
3.14 ADD指令
ADD有两种格式。后一种对于包含空白的路径是必需的。 可用的[选项]包括 ADD指令从src复制新文件、目录或远程文件URL并将它们添加到路径的镜像文件系统中。
可以指定多个src资源但如果它们是文件或目录则它们的路径将被解释为构建上下文的相对路径。
每个src都可能包含通配符并且将使用Go的文件路径匹配规则。例如
从构建上下文的根目录中选择“hom”开头的文件添加到/mydir/里请执行以下操作 在以下示例中是一个单字符通配符与例如“home.txt”匹配。 dest是一个绝对路径或WORKDIR的相对路径源将被按此路径复制到目标容器中。
下面的示例使用相对路径并将“test.txt”添加到WORKDIR/rerelativeDir/ 而这个例子使用了一个绝对路径并将“test.txt”添加到/absoluteDir/ 当添加包含特殊字符如[和]的文件或目录时需要按照Golang规则对这些路径进行转义以防止它们被视为匹配模式。例如要添加一个名为arr[0].txt的文件请使用以下命令 当是远程文件URL时目标将具有600的权限。如果远程取回文件具有HTTP Last Modified标头那么该header中的时间戳将用于设置目标文件的mtime。然而与ADD指令处理的其他文件一样mtime不包括在检测文件是否已更改和缓存是否应更新。
注意
如果通过STDINdocker-build-somefile传递Dockerfile进行构建则没有构建上下文因此Dockerfile只能包含基于URL的ADD指令。您也可以通过STDIN:docker-build-archive.tar.gz传递压缩的归档文件归档文件根目录下的Dockerfile和归档文件的其余部分将用作构建的上下文。
如果您的URL文件使用身份验证进行保护则需要使用RUN wget、RUN curl或使用容器中的其他工具因为ADD指令不支持身份验证。
注意
如果src的内容发生了更改则第一个遇到的ADD指令将使Dockerfile中以下所有指令的缓存失效。这包括使RUN指令的缓存失效。请参阅 Dockerfile最佳实践指南—利用构建缓存 了解更多信息。
ADD遵守以下规则
src路径必须位于构建上下文中你不能使用ADD . ./something/something因为构建器只能从上下文访问文件而 . ./something 指定了构建上下文根的父文件或目录。如果是一个URL并且以斜杠结尾那么可以从URL推断出文件名并将文件下载到dest/filename。例如ADD http://example.com/foobar / 将创建文件/foobar。URL必须nontrivial path复杂路径以便可以找到合适的文件名(http://example.com 是无效的。如果src是一个目录则会复制该目录的全部内容包括文件系统元数据。 注意目录本身不会被复制只复制其内容。如果src是一个可识别压缩格式identity、gzip、bzip2或xz的本地tar存档那么它将被解压为一个目录。来自远程URL的资源不会解压缩。当复制或解压缩目录时它具有与tar -x相同的行为。结果是以下各项的并集 目标路径和源树内容中存在的任何内容当发生冲突时在逐个文件的基础上以“2.”方式解决冲突。这句话没理解 注意 文件是否被识别为压缩格式完全取决于文件的内容而不是文件的名称。例如如果一个空文件恰好以.tar.gz结尾则它不会被识别为压缩文件也不会生成任何类型的解压缩错误消息而是将文件简单地复制到目的地。 如果src是任何其他类型的文件则会将其与元数据一起单独复制。在这种情况下如果dest以斜杠/结尾它将被视为一个目录并且src的内容将写入dest/basesrc。如果直接或使用通配符指定了多个src资源则dest必须是一个目录并且必须以斜线/结尾。如果src是一个文件并且dest没有以斜杠结尾则src的内容将被写成dest(filename)。如果dest不存在则会创建它以及路径中所有缺失的目录。
Adding private Git repositories私有git仓库
要通过SSH添加私有仓库请使用以下格式创建Dockerfile 这个Dockerfile可以用docker build --ssh或buildctl --build-ssh构建例如。
ADD --keep-git-dir选项
当src是远程Git存储库的HTTP或SSH地址时BuildKit会将Git存储库内的内容添加到镜像中默认情况下不包括.Git目录。 这个 --keep-git-dirtrue 标志允许您保留.git目录。
ADD --checksum选项 --checksum标志用于验证远程资源的校验和 --checksum标志当前仅支持HTTP源。
ADD --chown --chmod选项
详见下文 COPY --chown --chmod.
ADD --link选项
详见下文 COPY --link.
ADD --exclude选项
详见下文 COPY --exclude.
3.15 COPY指令
ADD有两种格式。后一种对于包含空白的路径是必需的。 可用的选项包括 COPY指令从src复制新文件或目录并将它们添加到容器文件系统中路径为dest。
可以指定多个src资源但如果它们是文件或目录则它们的路径将被解释为构建上下文的相对路径。
每个src都可能包含通配符并且将使用Go的文件路径匹配规则。例如
要在构建上下文的根目录中复制以“hom”开头的所有文件请执行以下操作 在以下示例中是一个单字符通配符与例如“home.txt”匹配。 dest是一个绝对路径或WORKDIR的相对路径源将被按此路径复制到目标容器中。
下面的示例使用相对路径并将“test.txt”复制到WORKDIR/rerelativeDir/ 而这个例子使用了一个绝对路径并将“test.txt”复制到/absoluteDir/ 当复制包含特殊字符如[和]的文件或目录时需要按照Golang规则对这些路径进行转义以防止它们被视为匹配模式。例如要添加一个名为arr[0].txt的文件请使用以下命令 注意如果你使用 STDIN (docker build - somefile)构建, 此时没有构建上下文, 所以 COPY 指令不能用.
COPY可选接受一个标志 --fromname该标志可用于将源定位设置为之前使用的构建阶段使用from . . AS创建而不使用用户发送的构建上下文。如果找不到具有指定名称的构建阶段则尝试使用具有相同名称的镜像。
COPY遵守以下规则
src路径必须位于构建上下文中你不能使用COPY . ./something/something因为构建器只能从上下文访问文件而 . ./something 指定了构建上下文根的父文件或目录。如果src是一个目录则会复制该目录的全部内容包括文件系统元数据。 注意目录本身不会被复制只复制其内容。如果src是任何其他类型的文件则会将其与元数据一起单独复制。在这种情况下如果dest以斜杠/结尾它将被视为一个目录并且src的内容将写入dest/basesrc。如果直接或使用通配符指定了多个src资源则dest必须是一个目录并且必须以斜线/结尾。如果src是一个文件并且dest没有以斜杠结尾则src的内容将被写成dest(filename)。如果dest不存在则会创建它以及路径中所有缺失的目录。 注意 如果src的内容发生了更改第一个遇到的COPY指令将使Dockerfile中所有后续指令的缓存失效。这也包括使RUN指令的缓存失效。有关更多信息请参阅Dockerfile最佳实践指南—利用构建缓存 了解更多信息。。
COPY --chown --chmod选项
注意当前仅支持八进制表示法。非八进制支持,请关注moby/buildkit#1951。 --chown和 --chmod功能仅在用于构建Linux容器的Dockerfiles上受支持而在Windows容器上不起作用。由于用户和组所有权概念不会在Linux和Windows之间转换因此使用/etc/passwd和/etc/group将用户和组名称转换为ID的功能会限制它仅适用于基于Linux操作系统的容器。
从构建上下文中复制的所有文件和目录都是使用UID和GID 0创建。除非使用可选的 --chown标志设置了用户名、组名或UID/GID组合约束复制内容的所有权。 --chown标志的格式允许使用用户名和组名字符串或者任意组合的整数UID和GID。提供不带组名的用户名或不带GID的UID将使用UID数字作为GID。如果提供了用户名或组名则容器的根文件系统/etc/passwd和/etc/group文件将分别完成从名称到UID或GID的转换。以下示例显示了 --chown标志的有效定义 如果容器根文件系统不包含/etc/passwd或/etc/group文件并且 --chown标志中使用了用户名或组名则COPY操作将导致构建失败。使用数字ID不需要查找也不依赖于容器根文件系统内容。
COPY --link选项
在COPY或ADD命令中启用此标志允许您使用增强语义指令复制文件其中文件在它们自己的层上保持独立并且当前一层的命令更改时它们不会失效。
当使用 --link时源文件将被复制到一个空的目标目录中。该目录将变成一个新层并链接到先前状态上。 相当于执行两个构建 和 并且将两个镜像的所有层合并在一起。
示例解释1.FROM alpine构建了一个层2.FROM scratch也构建了一个层这个层不包含1的内容只包含COPY /foo /bar这个层链接到之前的1上3.然后1和2合并。
使用 --link可以通过 --cache-from在后续构建中重用已构建的层即使之前的层已经更改。这对于多阶段构建尤其重要因为如果同一阶段中的任何先前命令发生更改则COPY --from语句之前获得的将失效从而需要重新构建中间阶段。使用 --link上一次构建的层将被重用并合并到新层的顶部。这也意味着当基础镜像更新时您可以轻松地重新调整镜像而无需再次执行整个构建。在后端BuildKit可以执行此重新基础操作而无需在客户端和仓库之间推送或拉取任何层。BuildKit将检测到这种情况并且只创建包含正确顺序的新层和旧层的镜像。
当使用 --link 而没有其他访问基础镜像中文件的命令时BuildKit可以避免拉下基础镜像的行为发生。在这种情况下BuildKit将只为COPY命令构建一个层并将它们直接推送到仓库链接基础镜像的顶层。
Incompatibilities with --linkfalse不适用情况 当COPY/ADD使用 --link时命令是无法从之前状态中读取任何文件。这意味着如果在之前的状态中目标不是文件而是一个包含符号链接的路径目录则COPY/ADD无法在路径后面追加。在最终镜像中使用 --link创建的目标路径应当始终是一个仅包含目录的路径。
如果您不依赖于在目标路径中遵循符号链接的行为则始终建议使用–link。–link的性能与默认行为相当或更好它为缓存重用创造了更好的条件。
上述官方关于COPY --link概念的解释还是挺晦涩的可以参见Dockerfile的COPY --link大神解释的非常清楚
COPY --parents选项
注意 目前稳定版语法中仍然不可用, 请使用docker/dockerfile:1.7-labs 版本 --parents标志为src项保留父目录。此标志默认为false。 此行为类似于Linux cp utility的 --parents或rsync --relative标志。
与Rsync一样可以通过在源路径中插入点和斜线./来限制保留哪些父目录。如果存在这种定义那么保留./之后的父目录。这在阶段之间拷贝可能是阶段之间使用 --from拷贝特别有用它需要源路径是绝对路径。 请注意如果没有指定 --parents标志任何文件名冲突都将使Linux cp操作失败并显示一条明确的错误消息cp:不会用’./y/a.txt’覆盖刚刚创建的’./x/a.txt’其中Buildkit将静默地覆盖目标文件。
虽然可以为仅由一个src条目组成的COPY指令保留目录结构但通常更有益的做法是尽可能降低生成镜像中的层数。因此使用 --parents标志Buildkit能够将多个COPY指令打包在一起从而保持目录结构的完整性。
COPY --exclude选项
注意 目前稳定版语法中仍然不可用, 请使用docker/dockerfile:1.7-labs 版本 使用 --exclude标志可以使用路径表达式指定要排除的文件。
路径表达式采用与src相同的格式支持通配符并使用Go的文件路径匹配规则。例如要添加所有以“hom”开头的文件不包括扩展名为.txt的文件 您可以为COPY指令多次指定–exclude选项。多次 --excludes是文件匹配即使文件路径在中也不会被复制。要添加所有以“hom”开头的文件不包括扩展名为.txt或.md的文件
3.16 ENTRYPOINT指令
ENTRYPOINT允许您配置容器作为可执行文件运行。 ENTRYPOINT有两种格式
exec 格式ENTRYPOINT [“executable”, “param1”, “param2”]shell 格式ENTRYPOINT command param1 param2
两者区别详见Shell and exec form
以下命令启动一个具有nginx服务的容器侦听端口80 docker run image的命令行参数将附加在exec格式下ENTRYPOINT中的所有元素后并将覆盖CMD中默认指定的所有元素。
这允许将参数传递给entry point例如 docker run image -d将把-d参数传递到entry point。您可以使用docker run --entrypoint标志来覆盖ENTRYPOINT指令。
ENTRYPOINT的shell格式阻止使用任何CMD命令行参数。它还将ENTRYPOINT作为/bin/sh -c的子命令启动该子命令不传递信号。这意味着可执行文件将不是容器的PID1也不会接收Unix信号。在这种情况下您的可执行文件不会收到来自docker stop container的SIGTERM。
只有Dockerfile中的最后一条ENTRYPOINT指令才会生效。
Exec 格式的 ENTRYPOINT 示例
您可以使用ENTRYPOINT的exec格式来设置相对固定的默认命令和参数然后使用CMD的任何一种格式来设置其他默认值CMD的默认值很可能会更改。 当您运行容器时您可以看到top是唯一的进程 要进一步检查结果可以使用docker exec 您可以使用docker停止test来优雅地请求top关闭。
以下Dockerfile显示使用ENTRYPOINT在前台运行Apache即作为PID 1 如果您需要为单个可执行文件编写启动脚本可以使用exec和gosu命令确保最终可执行文件接收Unix信号 最后如果您需要在关闭时进行一些额外的清理或与其他容器通信或者正在协调多个可执行文件您可能需要确保ENTRYPOINT脚本接收Unix信号传递这些信号然后再做一些其他工作 如果使用docker run -it --rm -p 80:80 --name test apache运行此镜像则可以使用docker exec或docker top检查容器的进程然后要求脚本停止apache 注意: 您可以使用 --entrypoint标志覆盖ENTRYPOINT指定的设置但这只能将二进制文件设置为exec它没有使用sh -c
Shell 格式 ENTRYPOINT 示例
您可以为ENTRYPOINT指定一个纯字符串格式它将在/bin/sh -c中执行。此格式将使用shell处理来替换shell环境变量并将忽略任何CMD或docker run的命令行参数。为了确保docker stop将正确地向运行的ENTRYPOINT可执行文件发出信号您需要记住用exec启动它 当您运行此镜像时您将看到仅有PID 1进程 docke stop 能让它干净地退出 如果您忘记将exec添加到ENTRYPOINT的开头 然后您可以运行它为了下一步操作设置一个名称 您可以从top的输出中看到指定的ENTRYPOINT不是PID 1。
如果随后运行docker stop test容器将不会干净地退出——stop命令将被迫在超时后发送SIGKILL
理解 CMD 和 ENTRYPOINT 是如何作用的
CMD和ENTRYPOINT指令都定义了运行容器时执行的命令。几乎没什么规则可以描述他们的合作关系
Dockerfile要求 CMD 与 ENTRYPOINT 两个命令中至少声明一个。当容器是可执行时应该定义 ENTRYPOINT。CMD可被定义作为ENTRYPOINT命令的缺省参数或者在容器中执行的一个临时命令。当使用替代参数运行容器时CMD将被覆盖
下表显示了针对不同ENTRYPOINT/CMD组合执行的命令 说明上表中定义方式参见官方文档Dockerfile reference - Shell and exec form
注意
如果基础镜像中定义了 CMD设置了 ENTRYPOINT会把 CMD 重置成空值。这种情况下CMD必须在当前镜像定义一个值
更多信息详见 理解CMD 和 ENTRYPOINT 是如何互相作用的
3.17 VOLUME指令
VOLUME指令使用指定的名称创建一个挂载点并将其标记为容纳来自本机主机或其他容器的外部挂载卷。该值可以是JSON数组VOLUME [“/var/log/”]也可以是带有多个参数的纯字符串如VOLUME /var/log或VOLUME /var/log/var/db。有关通过Docker客户端的更多信息/示例和挂载指令说明请参阅通过卷共享目录文档。
docker run命令在基础镜像中指定位置初始化包含任何数据新卷。例如看以下Dockerfile片段 此Dockerfile会构建一个镜像该镜像通过docker run在 /myvol上创建一个新的挂载点并将greeting文件复制到新创建的卷中。
关于指定卷的说明
关于Dockerfile中的卷请记住以下几点。
基于Windows容器上的卷使用基于Windows的容器时容器内卷的目标必须是以下之一 不存在或为空的目录C:以外的驱动器 从Dockerfile中更改卷如果任何构建步骤在声明卷后更改了卷中的数据则这些更改将被丢弃。JSON格式列表被解析为JSON数组。必须用双引号“而不是单引号将单词括起来。主机目录是在容器运行时声明的主机目录挂载点本质上依赖于主机。这是为了保持镜像的可移植性因为不能保证给定的主机目录在所有主机上都可用。因此您无法从Dockerfile中挂载主机目录。VOLUME指令不支持指定主机目录参数。创建或运行容器时必须指定挂载点。
3.18 USER指令
或 USER指令设置用户名或UID和可选的用户组或GID用作当前阶段剩余部分的默认用户和组。指定的用户用于执行RUN指令并在运行时运行相关的ENTRYPOINT和CMD命令。
请注意为用户指定组时该用户将仅具有指定的组成员身份。任何其他配置的组成员身份都将被忽略。
警告
当用户没有主组时镜像或下一条指令将以root组运行。 在Windows上如果用户不是内置帐户则必须首先创建该用户。这可以通过作为Dockerfile的一部分调用的net user命令来完成。
3.19 WORKDIR指令
WORKDIR指令为Dockerfile中的任何RUN、CMD、ENTRYPOINT、COPY和ADD指令设置工作目录。如果WORKDIR不存在即使它没有在任何后续的Dockerfile指令中使用它也会被创建。
WORKDIR指令可以在Dockerfile中多次使用。如果提供了一个相对路径它将是相对于上一个WORKDIR指令的路径。例如 这个Dockerfile中的最后一个pwd命令的输出将是/a/b/c。
WORKDIR指令可以解析先前使用ENV设置的环境变量。只能使用Dockerfile中明确设置的环境变量。例如 这个Dockerfile中最后一个pwd命令的输出将是/path/$DIRNAME
如果未指定则默认工作目录为/。在实践中如果您不是从头开始构建DockerfileFROM scratch那么WORKDIR可能是由您正在使用的基础镜像设置。
因此为了避免在未知目录中进行意外操作最好明确设置WORKDIR。
3.20 ARG指令
ARG指令定义了一个变量用户可以在构建时通过使用 --build ARG varnamevalue标志的docker构建命令将该变量传递给构建器。
警告
不建议使用构建参数来传递机密如用户凭据、API令牌等。构建参数在docker历史记录命令和最大模式来源证明中可见如果您使用Buildx GitHub Actions并且您的GitHub存储库是公共的则默认情况下会附加到镜像。
请参阅RUN --mounttypesecret部分了解构建镜像时使用机密的安全方法。
如果您指定了一个未在Dockerfile中定义的构建参数那么该构建将输出一个警告。 Dockerfile可以包括一个或多个ARG指令。例如以下是有效的Dockerfile
默认值
ARG指令可以选择性地包括一个默认值 如果ARG指令有一个默认值并且在构建时没有传递任何值则构建器将使用默认值。
范围
ARG变量在Dockerfile中定义的行生效而不是在使用它的命令行或其他地方生效。例如考虑这个Dockerfile 用户通过调用来构建此文件 第2行的USER的变量username的值为some_user随后在第3行中定义了username变量ARG。第4行的USER的变量username的值为what_user因为username参数已定义what_user值已在docker build命令行中传入。在ARG指令定义变量之前变量的任何使用都会将是空字符串。
ARG指令的作用域仅限在在定义它的构建阶段内。要在多个阶段中使用一个参数每个阶段都必须包含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。 然后假设此镜像是使用以下命令构建的 在这种情况下RUN指令使用v1.0.0而不是用户传递的ARG设置v2.0.1。这种行为类似于shell脚本其中本地作用域变量从定义点覆盖参数传入或从环境继承的变量。
使用上面的示例但使用不同的ENV规范您可以在ARG和ENV指令之间创建更有用的交互 与ARG指令不同ENV值始终保持在构建的镜像中。考虑一个没有 --build arg标志的docker构建 使用这个Dockerfile示例CONT_IMG_VER仍然保留在镜像中但其值为v1.0.0因为它是ENV指令在第3行中设置的默认值。
本例中的变量扩展技术允许您从命令行传递参数并通过利用ENV指令将它们持久化到最终镜像中。变量扩展仅支持 有限的Dockerfile指令集。
预定义ARG
Docker有一组预定义的ARG变量您可以在Dockerfile中不使用相应的ARG指令的情况下使用这些变量。
HTTP_PROXYhttp_proxyHTTPS_PROXYhttps_proxyFTP_PROXYftp_proxyNO_PROXYno_proxyALL_PROXYall_proxy
要使用这些请使用 --build-arg标志在命令行上传递它们例如 默认情况下这些预定义的变量被排除在docker历史记录的输出之外。排除它们可以降低HTTP_PROXY变量中意外泄露敏感身份验证信息的风险。
例如考虑使用构建以下Dockerfile
--build-arg HTTP_PROXYhttp://user:passproxy.lon.example.com在这种情况下HTTP_PROXY变量的值在docker历史记录中不保存也不会缓存。如果您更改访问地址并且您的代理服务器更改为http://user:passproxy.sfo.example.com后续构建不会导致缓存错过。
如果您需要覆盖此行为则可以在Dockerfile中添加ARG语句如下所示 构建这个Dockerfile时HTTP_PROXY将保留在docker历史记录中并且更改其值会使构建缓存无效。
全局范围的ARGS
此功能仅在使用BuildKit后端时可用。
BuildKit支持一组预定义的ARG变量其中包含执行构建的节点平台构建平台和生成镜像的平台目标平台上的信息。可以在docker构建中使用 --platform标志来指定目标平台。
以下ARG变量是自动设置的
TARGETPLATFORM - 构建结果的平台。例如linux/am64、linux/arm/v7、windows/am64。TARGETOS - TARGETPLATFORM的操作系统组件TARGETARCH - TARGETPLATFORM的体系结构组件TARGETVARIANT - TARGETPLATFORM的变体组件BUILDFORM - 执行构建的节点的平台。BUILDOS - BUILDFlatform的操作系统组件BUILDARCH - BUILDFlatform的体系结构组件BUILDFVARIANT-BUILDFORM的变体组件
这些参数是在全局范围内定义的因此在构建阶段或RUN命令中不自动可用。要在构建阶段中使用其中一个参数请重新定义它但不要赋值。 示例
BuildKit内置生成参数
类型类型描述BUILDKIT_CACHE_MOUNT_NS字符串设置可选的缓存ID命名空间。BUILDKIT_CONTEXT_KEEP_GIT_DIR布尔触发Git上下文以保留.Git目录。BUILDKIT_INLINE_CACHE2布尔是否将缓存元数据到镜像配置BUILDKIT_MULTI_PLATFORM布尔选择确定输出无论是否有多平台输出。BUILDKIT_SANDBOX_HOSTNAME字符串设置主机名默认buildkitssandboxBUILDKIT_SYNTAX字符串设置前端镜像SOURCE_DATE_EPOCH整型为创建的镜像和层设置Unix时间戳。更多信息详见reproducible builds。自Dockerfile 1.5、BuildKit 0.11起支持
示例: 保留.git目录 使用Git上下文时检出时不会保留.Git 目录。如果您想在构建过程中检索git信息那么保留它可能会很有用
对构建缓存的影响
ARG变量不会像ENV变量那样持久化到构建的镜像中。然而ARG变量确实以类似的方式影响构建缓存。如果Dockerfile定义了一个ARG变量该变量的值与以前的构建不同那么第一次使用时会发生“缓存未命中”而不是在定义时。特别是ARG指令后面的所有RUN指令都隐式使用ARG变量作为环境变量因此可能导致缓存未命中。除非Dockerfile中有匹配的ARG语句否则所有预定义的ARG变量都可以免于缓存。
示例看下面这两个Dockerfile 如果在命令行上指定 --build-arg CONT_IMG_VERvalue这两种情况下第2行的规范都不会导致缓存未命中第3行确实会导致缓存未命中。CONT_IMG_VER引起的RUN指令行实际上与 CONT_IMG_VERvalue echo hello相同因此如果value发生更改则会出现缓存未命中的情况。
再看同一命令行下的另一个示例 在本例中缓存未命中发生在第3行。由于ENV中的变量值引用了ARG变量并且该变量是通过命令行更改的因此会发生未命中。在本例中ENV命令会使镜像包含该值。
如果ENV指令覆盖相同名称的ARG指令如以下Dockerfile 第3行不会导致缓存未命中因为CONT_IMG_VER的值是常量hello。因此RUN第4行中使用的环境变量和值在不同的构建之间不会发生变化。
3.21 ONBUILD指令
ONBUILD指令向镜像中添加一条触发器指令该指令将在以后镜像用作另一个构建的基础时执行。触发器将在下游构建的上下文中执行就好像它是在下游Dockerfile中的FROM指令之后立即插入的一样。
任何构建指令都可以注册为触发器。
例如如果您的镜像是一个可重复使用的Python应用程序构建准备的它需要将应用程序源代码添加到特定目录中之后可能需要调用构建脚本。现在不能立刻调用ADD和RUN因为您还没有访问应用程序源代码的权限而且每个应用程序构建的源代码都不同。你可以简单地为应用程序开发人员提供一个样板Dockerfile将其复制粘贴到他们的应用程序中但这效率低容易出错而且很难更新因为它与特定于应用程序的代码混合在一起。
解决方案是使用ONBUILD注册高级指令以便稍后在下一个构建阶段运行。
以下是它的工作原理 当遇到ONBUILD指令时构建器会向正在构建的镜像的元数据添加一个触发器。该指令不会影响当前构建。 在构建结束时所有触发器的列表都存储在镜像清单中的键OnBuild下。可以使用docker inspect命令对它们进行检查。 稍后可以使用FROM指令将镜像用作新构建的基础。作为处理FROM指令的一部分下游构建器会查找ONBUILD触发器并以与注册时相同的顺序执行它们。如果任何触发器失败FROM指令将中止从而导致构建失败。如果所有触发器都成功FROM指令将完成构建将照常进行。 触发器在执行后会从最终镜像中清除。换句话说它们不是由“孙子辈”构建继承。
例如您可以添加以下内容 警告 不允许使用ONBUILD ONBUILD链接ONBUILD指令。 警告 ONBUILD指令不得触发FROM或MAINTAINER指令。
3.22 STOPSIGNAL指令
STOPSSIGNAL指令设置系统信号用于发送到容器使退出容器。该信号可以是SIGname格式的信号名称例如SIGKILL也可以是与内核系统调用表中的位置匹配的无符号数字例如9。如果未定义则默认值为SIGTERM。
在ocker run和docker create时使用 --stop signal标志可以覆写每个容器镜像的默认stopsignal。
3.23 HEALTHCHECK指令
HEALTHCHECK指令有两种形式 HEALTHCHECK [OPTIONS] CMD command通过在容器内运行命令来检查容器运行状况 HEALTHCHECK NONE禁用从基础镜像继承的任何健康检查
HEALTHCHECK指令告诉Docker如何测试容器以检查它是否仍在工作。这可以检测到一些情况例如web服务器陷入无限循环无法处理新的连接即使服务器进程仍在运行。
当容器指定了健康检查时除了正常状态外它还具有健康状态。此状态最初处于启动状态。只要健康检查通过它就会变得健康无论以前处于何种状态。在一定数量的连续故障之后它会变得不健康。
CMD之前可以显示的选项有 健康状况检查在容器启动interval秒后首次运行然后在上次检查完成后间隔interval秒再次运行。
如果单次检查花费的时间超过timeout秒则认为检查失败。
容器的运行健康检查连续失败达到retries次数被视为不正常。
start period提供容器启动运行的初始化时间。在此期间的检测失败将不会计入最大retries次数。但是如果在启动期间容器运行健康检查成功那么认为容器已启动并且后续所有连续失败都将计入最大retries次数。
start interval是指在启动期间进行健康检查之间的时间。此选项需要Docker Engine 25.0或更高版本支持。
Dockerfile中只能有一条HEALTHCHECK指令。如果您列出多个则只有最后一个HEALTHCHECK才会生效。
健康检查在CMD关键字后面的命令command部分可以是shell命令例如HEALTHCHECK CMD /bin/check-running或exec数组与其他Dockerfile命令一样有关详细信息请参阅例如ENTRYPOINT。
命令的退出状态指示容器的运行状况。可能的值为 0: success - 容器健康可以使用 1: unhealthy - 容器工作不正常 2: reserved - 保留未使用
例如每隔五分钟检查一次web服务器检查主页能否在三秒内打开 为了帮助调试失败的探测命令在stdout或stderr上写入的任何输出文本UTF-8编码都将存储在运行状况中并且可以使用docker inspect进行查询。这样的输出应该保持简短当前只存储前4096个字节。
当容器的运行状况发生变化时将生成具有新状态的health_status事件。
3.24 SHELL指令
SHELL指令允许覆写默认使用的shell。Linux上的默认shell为[“/bin/sh”“-c”]Windows上的默认shell为[“cmd”“/S”“/c”]。SHELL指令必须在Dockerfile中以JSON形式编写。
SHELL指令在Windows上特别有用因为Windows中有两种常用且截然不同的原生SHELLcmd和powershell以及可替换的shell比如sh。
SHELL指令可以出现多次。每个SHELL指令都会覆盖以前的所有SHELL指令并影响以后的所有指令。例如 Dockerfile中以下指令的shell格式会受到SHELL指令的影响RUN、CMD和ENTRYPOINT。
以下示例是Windows上常见的模式可以使用SHELL指令进行精简 构建器调用的命令将是 这是低效的原因有二。首先调用了一个不必要的cmd.exe命令处理器又名shell。其次shell形式的每个RUN指令都需要一个额外的powershell命令作为命令的前缀。
为了提高效率可以采用两种机制中的一种。一种是使用RUN命令的JSON形式例如 虽然JSON格式是明确的并且没有使用不必要的cmd.exe但它确实需要通过双引号和转义来提供更多的详细信息。另一种机制是使用SHELL指令和shell格式为Windows用户提供更自然的语法尤其是与escape语法分析器指令结合使用时 结果 SHELL指令也可用于修改shell的操作方式。例如在Windows上使用SHELL cmd /S /C /V:ON|OFF可以修改延迟环境变量扩展语义。
如果需要其他shell如zsh、csh、tcsh等也可以在Linux上使用SHELL指令。
3.25 Here-Documents用法
Here-documents允许Dockerfile使用后续RUN或COPY命令重定向输入。如果命令包含一个here-documentDockerfile会认为从下一行直到只包含here-doc结束符的行是同一命令的一部分。。
示例运行多行脚本
如果命令仅包含here-document则使用默认shell执行其内容。 或者在事件开头定义解释器。 更复杂的示例可能使用多个here-documents。
示例创建实时文件
使用COPY指令您可以替换here-doc指示符的源参数修改为将here-document 的内容直接写入文件。以下示例使用COPY指令创建一个包含hello-world的greeting.txt文件。 here-doc文档variable expansion and tab stripping rules应用。以下示例显示了一个小Dockerfile它使用带有here-document的COPY指令创建hello.sh脚本文件。 在这种情况下文件脚本会打印“hello-bar”因为在执行COPY指令时会展开变量。 相反如果您加引号here-document中的单词EOT的任何部分则在构建时不会扩展该变量。 请注意ARG FOObar在此多余可以删除。当脚本被调用时变量在运行时被解释
3.26 Dockerfile 示例
有关Dockerfiles的示例请参阅
“build images” section“get started” tutoriallanguage-specific getting started guidesbuild guide 文章转载自： http://www.morning.xtdms.com.gov.cn.xtdms.com http://www.morning.mpnff.cn.gov.cn.mpnff.cn http://www.morning.wgqtj.cn.gov.cn.wgqtj.cn http://www.morning.zpdjh.cn.gov.cn.zpdjh.cn http://www.morning.hyryq.cn.gov.cn.hyryq.cn http://www.morning.tqwcm.cn.gov.cn.tqwcm.cn http://www.morning.gwsdt.cn.gov.cn.gwsdt.cn http://www.morning.wtlyr.cn.gov.cn.wtlyr.cn http://www.morning.rwyw.cn.gov.cn.rwyw.cn http://www.morning.qbksx.cn.gov.cn.qbksx.cn http://www.morning.rmpfh.cn.gov.cn.rmpfh.cn http://www.morning.srwny.cn.gov.cn.srwny.cn http://www.morning.wkcl.cn.gov.cn.wkcl.cn http://www.morning.mbbgk.com.gov.cn.mbbgk.com http://www.morning.srbl.cn.gov.cn.srbl.cn http://www.morning.zmpqt.cn.gov.cn.zmpqt.cn http://www.morning.ntqgz.cn.gov.cn.ntqgz.cn http://www.morning.zfhzx.cn.gov.cn.zfhzx.cn http://www.morning.qfnrx.cn.gov.cn.qfnrx.cn http://www.morning.qlckc.cn.gov.cn.qlckc.cn http://www.morning.hdrsr.cn.gov.cn.hdrsr.cn http://www.morning.szoptic.com.gov.cn.szoptic.com http://www.morning.qqfcf.cn.gov.cn.qqfcf.cn http://www.morning.pmdlk.cn.gov.cn.pmdlk.cn http://www.morning.hzryl.cn.gov.cn.hzryl.cn http://www.morning.hxpff.cn.gov.cn.hxpff.cn http://www.morning.wtlyr.cn.gov.cn.wtlyr.cn http://www.morning.c7491.cn.gov.cn.c7491.cn http://www.morning.nlwrg.cn.gov.cn.nlwrg.cn http://www.morning.schwr.cn.gov.cn.schwr.cn http://www.morning.zsgbt.cn.gov.cn.zsgbt.cn http://www.morning.rwrn.cn.gov.cn.rwrn.cn http://www.morning.jzlkq.cn.gov.cn.jzlkq.cn http://www.morning.xsymm.cn.gov.cn.xsymm.cn http://www.morning.jwskq.cn.gov.cn.jwskq.cn http://www.morning.cpfbg.cn.gov.cn.cpfbg.cn http://www.morning.bygyd.cn.gov.cn.bygyd.cn http://www.morning.wtbzt.cn.gov.cn.wtbzt.cn http://www.morning.wyrsn.cn.gov.cn.wyrsn.cn http://www.morning.btwrj.cn.gov.cn.btwrj.cn http://www.morning.qpnb.cn.gov.cn.qpnb.cn http://www.morning.ktbjk.cn.gov.cn.ktbjk.cn http://www.morning.bfgbz.cn.gov.cn.bfgbz.cn http://www.morning.wptrm.cn.gov.cn.wptrm.cn http://www.morning.rnxw.cn.gov.cn.rnxw.cn http://www.morning.nhgkm.cn.gov.cn.nhgkm.cn http://www.morning.cnhgc.cn.gov.cn.cnhgc.cn http://www.morning.qnjcx.cn.gov.cn.qnjcx.cn http://www.morning.zdsdn.cn.gov.cn.zdsdn.cn http://www.morning.rqgjr.cn.gov.cn.rqgjr.cn http://www.morning.bkslb.cn.gov.cn.bkslb.cn http://www.morning.dnmwl.cn.gov.cn.dnmwl.cn http://www.morning.tgts.cn.gov.cn.tgts.cn http://www.morning.slfmp.cn.gov.cn.slfmp.cn http://www.morning.nthyjf.com.gov.cn.nthyjf.com http://www.morning.nj-ruike.cn.gov.cn.nj-ruike.cn http://www.morning.gthc.cn.gov.cn.gthc.cn http://www.morning.nfcxq.cn.gov.cn.nfcxq.cn http://www.morning.pkrtz.cn.gov.cn.pkrtz.cn http://www.morning.hyjpl.cn.gov.cn.hyjpl.cn http://www.morning.yrmpz.cn.gov.cn.yrmpz.cn http://www.morning.rdwm.cn.gov.cn.rdwm.cn http://www.morning.hxmqb.cn.gov.cn.hxmqb.cn http://www.morning.xlclj.cn.gov.cn.xlclj.cn http://www.morning.pkrtz.cn.gov.cn.pkrtz.cn http://www.morning.bslkt.cn.gov.cn.bslkt.cn http://www.morning.lnrhk.cn.gov.cn.lnrhk.cn http://www.morning.qhrsy.cn.gov.cn.qhrsy.cn http://www.morning.qcwck.cn.gov.cn.qcwck.cn http://www.morning.xtqld.cn.gov.cn.xtqld.cn http://www.morning.jjhrj.cn.gov.cn.jjhrj.cn http://www.morning.rwyw.cn.gov.cn.rwyw.cn http://www.morning.ynbyk.cn.gov.cn.ynbyk.cn http://www.morning.mjjty.cn.gov.cn.mjjty.cn http://www.morning.dpppx.cn.gov.cn.dpppx.cn http://www.morning.rhkq.cn.gov.cn.rhkq.cn http://www.morning.ngcsh.cn.gov.cn.ngcsh.cn http://www.morning.rhpgk.cn.gov.cn.rhpgk.cn http://www.morning.ysbrz.cn.gov.cn.ysbrz.cn http://www.morning.rwlns.cn.gov.cn.rwlns.cn
