Как использовать аргументы сборки Docker для настройки сборки образа

Механизм «сборки аргументов» Docker позволяет вам определять переменные среды, на которые можно ссылаться в вашем Dockerfile во время сборки образа. В отличие от обычных инструкций ENV, аргументы сборки отсутствуют в окончательном выходном изображении. Они предназначены для случаев, когда вы хотите настроить процесс сборки вместо созданных контейнеров.

Определение аргументов сборки

Вы определяете аргументы сборки внутри вашего Dockerfile, используя инструкции ARG:

ARG EXAMPLE_VAR
ARG DEMO_VAR

RUN echo $EXAMPLE_VAR

Два аргумента, EXAMPLE_VAR и DEMO_VAR, добавляются в сборку Dockerfile выше.

Вы устанавливаете значения доступных аргументов с помощью флага --build-arg для docker build. Повторите флаг несколько раз, чтобы охватить все аргументы, определенные в вашем Dockerfile:

docker build -t example-image:latest 
    --build-arg EXAMPLE_VAR=value1 
    --build-arg DEMO_VAR=value2 
    .

Сборка образца Dockerfile с помощью этой команды выдаст value1 на ваш терминал во время сборки. Переменная EXAMPLE_VAR становится доступной в среде сборки со значением value1. Компонент значения флага --build-arg является необязательным; опустив его, вы автоматически выберете значение переменной в вашей локальной среде оболочки.

Поскольку аргументы сборки не сохраняются в построенном образе, вы увидите пустую строку при запуске echo $EXAMPLE_VAR внутри контейнеров, созданных из example-image:latest. Переменные, на которые должны ссылаться работающие контейнеры, следует добавлять с помощью инструкций ENV и флагов сборки --env или -e.

Хотя их нет в финальном образе, аргументы сборки по-прежнему влияют на кеш сборки Docker. Изменение значения аргумента между сборками может привести к промахам кеша для инструкций, которые следуют за первой ссылкой на переменную. Определяющий оператор ARG не отвечает за аннулирование кеша.

FROM alpine:latest
ARG EXAMPLE_VAR

# Cache is not invalidated - arg hasn't been used
RUN example-command

# Build cache can't be used from this point onwards
RUN echo $EXAMPLE_VAR

Значения аргумента сборки по умолчанию

Инструкции ARG может быть присвоено значение по умолчанию для использования, когда не указан соответствующий флаг --build-arg:

ARG EXAMPLE_VAR=demo

Docker всегда будет предпочитать значение, заданное флагом --build-arg, когда оно доступно. Если он отсутствует, для EXAMPLE_VAR будет установлено значение demo в среде сборки. Это уменьшает количество флагов, которые необходимо указать при создании образа с аргументами, которые редко переопределяются.

Где можно использовать аргументы сборки?

На аргументы сборки можно ссылаться в инструкциях Dockerfile, которые следуют за ними. Они работают с большинством типов инструкций, включая команды RUN, выполняемые в промежуточных контейнерах сборки. На аргументы ссылаются так же, как и на переменные среды, используя синтаксис $EXAMPLE_VAR.

Инструкции ARG уникальны, поскольку они существенно влияют на сборку, но их можно использовать перед инструкциями FROM. Разрешается ссылаться на аргументы сборки внутри инструкции FROM, что позволяет выбрать другой базовый образ в зависимости от конфигурации пользователя:

ARG BASE_IMAGE_VERSION=alpine
FROM my-app-base:2-${BASE_IMAGE_VERSION}

docker build -t my-app:latest --build-arg BASE_IMAGE_VERSION=debian .

Аргументы сборки доступны из строки, в которой они определены. Любая следующая инструкция может ссылаться на значение аргументов сборки, созданных над ней в Dockerfile. Вы должны добавить инструкции ARG для всех аргументов сборки, которые вы будете использовать. Ссылка на аргумент до того, как он был определен, или использование --build-arg без соответствующего ARG приведет к пустой строке.

Аргументы сборки не работают на разных этапах сборки. Каждый этап действует как новая сборка с собственным набором аргументов сборки. Инструкции ARG, включенные в предыдущие этапы, не влияют на более поздние, если только они не повторяются на каждом этапе:

FROM php:latest
ARG BUILD_VERSION

FROM composer:latest
ARG BUILD_VERSION

Оба этапа явно определяют аргумент BUILD_VERSION, поэтому значение, установленное с помощью --build-arg, будет предоставлено каждому из них.

Соображения, касающиеся этапа сборки, также применимы, когда вы используете ARG перед инструкцией FROM. Эти аргументы существуют вне любой стадии сборки; они используются всеми операторами FROM, но на них нельзя ссылаться, следуя инструкциям. Если вы хотите повторно использовать аргумент сборки уровня FROM внутри этапа, повторите инструкцию ARG, чтобы получить его значение:

# Only applies to FROM instructions
ARG BASE_IMAGE_VERSION=alpine
FROM my-app-base:2-${BASE_IMAGE_VERSION}

# Reference the outer build argument
ARG BASE_IMAGE_VERSION

# Works as expected
RUN echo $BASE_IMAGE_VERSION

Помимо этих особых проблем, аргументы ведут себя аналогично переменным среды во всех других отношениях. Вы можете переопределить их значения с помощью инструкций ARG и ENV, интерполировать их в строки и использовать в выражениях расширения вида $ {EXAMPLE_VAR:-demo . Это выбирает demo в качестве значения, когда переменная EXAMPLE_VAR не установлена.

Предопределенные аргументы сборки

Docker по умолчанию поддерживает некоторые аргументы сборки, даже если вы не включили их инструкции ARG в свой Dockerfile. Они связаны с настройками прокси и работают всякий раз, когда используется соответствующий флаг --build-arg. Переменные также исключаются из вывода docker history, чтобы избежать раскрытия потенциально конфиденциальных сведений, для которых они предназначены — подробнее об этой команде и ее последствиях ниже.

Сборки, обрабатываемые серверной частью BuildKit, также могут получить доступ к нескольким другим предопределенным аргументам сборки. Они поставляются с автоматически введенными значениями. Список включает TARGETOS, TARGETARCH, TARGETPLATFORM и BUILDOS, BUILDARCH и BUILDPLATFORM и ряд других. Переменные описывают характеристики среды сборки и платформы, на которую нацелен новый образ.

Когда использовать аргументы сборки?

Аргументы сборки можно использовать для внедрения конфигурации в сборки образов Docker. Это способ динамически изменять окончательный образ без написания нескольких файлов Dockerfile.

Вы можете использовать этот механизм для изменения базового образа сборки, изменения команд, выполняемых инструкциями RUN, и предоставления изменяемых пользователем настроек, которые предоставляют параметры настройки изображения. Аргументы сборки имеют смысл для большинства значений, которые используются только в процессе сборки и которые вы не хотите жестко закодировать в своем Dockerfile.

В некоторых ситуациях следует использовать альтернативные подходы. Несмотря на удобство, аргументы сборки не идеальны для секретных данных, таких как токены и ключи аутентификации. Поскольку ARG — это инструкция Dockerfile, переменные и их значения видны при просмотре изображения с помощью команды docker history. Таким образом, любой, у кого есть доступ к вашему образу, может просмотреть ключи, использованные во время сборки.

Учетные данные, используемые для аутентификации процесса сборки в реестрах пакетов и репозиториях системы управления версиями, лучше всего предоставлять в виде секретов сборки BuildKit. Они предназначены для обработки конфиденциальной информации и монтируются в виде файлов в среду сборки, а не становятся инструкциями образа.

Краткое содержание

Аргументы сборки позволяют настраивать сборки образов Docker, используя комбинацию инструкций Dockerfile и аргументов командной строки во время сборки. В отличие от переменных среды, аргументы сборки недоступны для запущенных контейнеров, хотя они все еще видны в истории слоев изображения.

Аргумент сборки — правильный выбор для неконфиденциальных настраиваемых пользователем параметров, влияющих на процесс сборки. Вместо этого используйте переменную среды, если вы хотите показать значение в конечном изображении. Секреты BuildKit — лучший третий вариант для любых ценных данных, к которым ваша сборка должна получить доступ.