ARG в Docker: параметры сборки

Иллюстрация Docker с логотипом и контейнерами

Build args (инструкции ARG в Dockerfile) позволяют передавать значения в среду сборки образа Docker без сохранения их в итоговом образе. Используйте ARG для настраиваемых параметров сборки (версия базового образа, фичи, флаги компиляции), но не для секретов — для них лучше BuildKit secrets. ARG влияет на кэш сборки: изменение значения может вызвать промахи кэша.

Быстрые ссылки

Определение параметров сборки
Значения по умолчанию
Где можно использовать ARG
Предопределённые аргументы сборки
Когда использовать ARG
Практическое руководство и чек-листы
Сводка

Что такое ARG в Dockerfile

ARG — это инструкция Dockerfile, которая объявляет имя переменной, доступной только в процессе сборки образа. В отличие от ENV, значения, переданные через ARG, не попадают в финальный образ и не видны запущенным контейнерам. ARG удобны для конфигурации процесса сборки: выбора базового образа, переключения флагов сборки, задания путей и т. п.

Определение простого аргумента:

ARG EXAMPLE_VAR

Пример использования нескольких ARG и вывода их значений во время сборки:

ARG EXAMPLE_VAR
ARG DEMO_VAR

RUN echo $EXAMPLE_VAR
RUN echo $DEMO_VAR

Чтобы задать значения, используйте флаг –build-arg при запуске docker build. Флаг можно повторять несколько раз, по одному для каждого аргумента:

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

Если после = не указано значение, Docker заберёт значение соответствующей переменной из локальной оболочки (shell) при сборке.

Важно: так как ARG не сохраняются в образе, команды внутри запущенного контейнера увидят пустую строку для этих переменных. Для значений, которые должны быть доступны в рантайме, используйте ENV или настройте переменные окружения контейнера через –env/-e.

Поведение AR G и кэш Docker

ARG влияет на кэширование слоёв. Если значение аргумента меняется между сборками, инструкции, следующие за первой ссылкой на эту переменную, могут не использовать кэш. При этом само объявление ARG не вызывает инвалидации кэша — инвалидация происходит при первой инструкции, где значение используется.

Пример:

FROM alpine:latest

ARG EXAMPLE_VAR

# Кэш пока не инвалидирован - переменная ещё не использована
RUN example-command

# С этого шага кэш может быть недоступен, если EXAMPLE_VAR изменён
RUN echo $EXAMPLE_VAR

Если EXAMPLE_VAR изменится, Docker не сможет использовать закэшированные результаты для шагов, следующих за первым использованием этого аргумента.

Значения по умолчанию для ARG

Вы можете задать значение по умолчанию прямо в Dockerfile:

ARG EXAMPLE_VAR=demo

Если флаг –build-arg для EXAMPLE_VAR не указан при сборке, переменная внутри процесса сборки примет значение demo. При наличии –build-arg значение из командной строки приоритетно.

Где можно использовать ARG

ARG доступны в любых инструкциях Dockerfile, которые следуют за объявлением ARG.
Их можно подставлять в RUN, в строках команд, в шаблонах, в выражениях расширения ${VAR:-default} и т. п.
Особенность: ARG можно определять до FROM. Такие аргументы доступны для подстановки в инструкцию FROM (например, чтобы выбрать базовый образ), но не будут доступны для последующих инструкций, если не повторить ARG внутри стадии.

Пример выбора базового образа через ARG:

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, где объявлены. Если вы ссылаетесь на аргумент до объявления — вы получите пустую строку. Также использование –build-arg без соответствующего ARG даёт пустую строку.

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

Каждая стадия многослойной сборки (multi-stage build) рассматривается как отдельная область видимости для ARG. Аргументы из предыдущих стадий не переносятся автоматически в следующую. Если необходимо, повторите ARG в каждой стадии:

FROM php:latest
ARG BUILD_VERSION

FROM composer:latest
ARG BUILD_VERSION

Если ARG объявлен до любого FROM (вне стадий), он доступен только для подстановки в FROM инструкциях всех стадий, но последующие инструкции внутри стадии не увидят его, если ARG не повторён в этой стадии:

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

# Чтобы использовать внутри стадии, повторите ARG
ARG BASE_IMAGE_VERSION
RUN echo $BASE_IMAGE_VERSION

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

Docker предоставляет ряд аргументов по умолчанию для определённых случаев (например, прокси-переменные), которые работают даже без явного объявления ARG в Dockerfile при использовании соответствующих –build-arg. Эти переменные также исключаются из вывода docker history, чтобы не раскрывать потенциально чувствительные значения.

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

Когда стоит использовать ARG

Подходящие случаи:

Параметры, влияющие только на процесс сборки: версия базового образа, опции компиляции, флаги включения/выключения функций.
Сценарии, где вы хотите один Dockerfile для нескольких конфигураций образа.
Автоматизация CI/CD, где значения передаёт система сборки.

Когда не стоит использовать ARG:

Секреты (ключи, токены). Они могут быть видны в истории образа и, следовательно, уязвимы при доступе к образу.
Данные, которые должны быть доступны в рантайме — для этого используйте ENV или передачу переменных при запуске контейнера.

Для секретов используйте BuildKit secrets. Они монтируются как файлы в процессе сборки и не превращаются в инструкции образа.

Практические шаблоны и примеры

Шпаргалка команд для сборки:

# Передать один аргумент
docker build -t app:latest --build-arg APP_ENV=staging .

# Передать несколько аргументов
docker build -t app:latest \
  --build-arg APP_ENV=prod \
  --build-arg ENABLE_FEATURE=true \
  --build-arg BASE_IMAGE_VERSION=3.15 .

# Использовать значение из локальной оболочки
export TOKEN=abc123
docker build --build-arg TOKEN .

Пример Dockerfile с условным использованием ARG и ENV:

# Dockerfile
ARG BASE=alpine
FROM mybase:${BASE}

ARG BUILD_TYPE=release
RUN if [ "$BUILD_TYPE" = "debug" ] ; then echo "Debug build" ; fi

ENV RUNTIME_VAR=default

Мини-методология разработки образов с ARG:

Определите набор переменных, которые реально меняются между билдами.
Дайте разумные значения по умолчанию в Dockerfile, если это уместно.
Документируйте все –build-arg в README или CI-конфигурации.
Для чувствительных данных используйте BuildKit secrets, не ARG.

Безопасность и приватность

ARG видны в истории образа (docker history), поэтому не используйте их для секретов.
BuildKit secrets или вариации систем управления секретами (vault, CI secret variables) — предпочтительнее для токенов/ключей.
Если вы публикуете образы публично, выполните проверку docker history и содержимого слоёв, чтобы убедиться, что чувствительные данные не утекли.

Примечание о GDPR и данных пользователей: ARG обычно используются для настроек сборки и не служат механизмом хранения пользовательских персональных данных. Тем не менее, избегайте встраивания в образ любых чувствительных персональных данных и документов, даже временно, во время сборки.

Чек-листы по ролям

Разработчик

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

DevOps/CI

Настроить передачу –build-arg в pipeline (например, в GitHub Actions, GitLab CI).
Использовать секреты CI для токенов и BuildKit secrets для монтирования в build.
Проверять историю образа перед публикацией.

SecOps

Проверить docker history и содержимое слоёв на наличие секретов.
Настроить сканирование образов и аудиторские правила для предупреждения о попадании секретов.

Сценарии, когда ARG не подойдёт (контрпримеры)

Вам нужен токен для подключения к приватному репозиторию во время сборки: лучше BuildKit secret.
Переменные должны быть доступны в финальном контейнере для рантайма: используйте ENV или передавайте при запуске контейнера.
Необходимо, чтобы значение было одинаковым для всех стадий сборки без повторного объявления: повторите ARG в каждой стадии или объявите его и повторите внутри этапа.

Критерии приёмки

Dockerfile документирован: все ARG перечислены и объяснены.
Сборка с дефолтными значениями проходит локально.
Сборка с передачей –build-arg корректно изменяет поведение образа на этапе сборки (проверяется логами RUN).
В истории образа отсутствуют секреты или чувствительные строки.

Плейбук при изменении ARG в CI

Обновить документацию и CHANGELOG о новой возможности/переменной.
Добавить/обновить переменную в CI-конфиге (переменные окружения руннера или секреты).
Запустить тестовую сборку и прогон интеграционных тестов.
Проверить docker history на утечки.
Деплоить образ в staging, затем в production.

Решение задач: дерево выбора

flowchart TD
  A[Нужно передать значение в сборку?] -->|Нет| B[Не использовать ARG]
  A -->|Да| C[Является ли значение секретом?]
  C -->|Да| D[Использовать BuildKit secrets или провайдер секретов]
  C -->|Нет| E[Должно ли значение быть в рантайме?]
  E -->|Да| F[Использовать ENV или передать при запуске контейнера]
  E -->|Нет| G[Использовать ARG]

Тест-кейсы и приёмка

TC1: Сборка с –build-arg задаёт ожидаемое значение (проверить вывод RUN echo).
TC2: Сборка без –build-arg использует значение по умолчанию из Dockerfile.
TC3: Переменная, объявленная до FROM и использованная в FROM, корректно подставляется.
TC4: ARG не попал в ENV финального контейнера (запустить контейнер и проверить echo $VAR пустое).
TC5: Docker history не содержит секретов при использовании –build-arg для нерегулируемых значений.

Советы по миграции и совместимости

Если у вас был ранее жёстко захардкоженный базовый образ, замените его на ARG с дефолтным значением для плавного перехода.
При миграции на BuildKit проверьте список доступных автоматических переменных (TARGETOS, TARGETARCH и т. д.).
Для многоступенчатых сборок явно повторяйте ARG в каждой стадии, где требуется значение.

Краткое резюме

ARG нужны для параметризации процесса сборки образа и не сохраняются в финальном образе.
Не используйте ARG для секретов; применяйте BuildKit secrets для безопасного доступа к чувствительным данным.
ARG влияет на кэш: изменение значения может вызвать промахи кэша для следующих шагов.
Для значений, которые нужны в рантайме, используйте ENV или передачу переменных при запуске контейнера.

Ключевые рекомендации: документируйте все параметры сборки, давайте осмысленные значения по умолчанию и интегрируйте безопасный механизм секретов в ваш CI/CD.