Сборка образа может обращаться к закрытому репозиторию или API. Токен нужен во время одного шага, но не должен превращаться в часть образа, build context или журнала CI. BuildKit secret mount передаёт файл нужному RUN на время выполнения.
Отделить секрет сборки от runtime-секрета
Секрет сборки используется при получении зависимостей или артефактов. Он не создаёт автоматически секрет при запуске готового контейнера. Для runtime нужно отдельно спроектировать механизм выдачи в среде эксплуатации.
Не передавайте пароль через ARG или ENV и не делайте COPY с последующим удалением: промежуточные слои, метаданные и кеш способны сохранить следы значения. Замена способа передачи не отменяет необходимости проверить команды внутри RUN.
Подготовить учебный контекст
Все примеры используют искусственное значение, не рабочий токен:
mkdir -p demo-build/.secrets
cd demo-build
printf '%s\n' 'DEMO_VALUE_ONLY' > .secrets/api-token.txt
printf '%s\n' '.secrets/' > .dockerignore.dockerignore исключает каталог из контекста. Флаг --secret всё равно может прочитать указанный клиентский файл. В CI получайте значение из защищённого хранилища runner, а не из файла, добавленного в Git.
Dockerfile
# syntax=docker/dockerfile:1
FROM alpine:3
RUN --mount=type=secret,id=api_token,required=true \
test -s /run/secrets/api_token && printf 'Secret is available\n'
RUN test ! -e /run/secrets/api_token
CMD ["sh", "-c", "test ! -e /run/secrets/api_token && echo Runtime has no build secret"]Первый RUN проверяет наличие непустого файла, не печатая значение. Во втором шаге mount уже отсутствует. required=true заставляет сборку завершиться ошибкой, если секрет не передан. Для воспроизводимой рабочей сборки фиксируйте версию или digest базового образа по своей политике.
Передать секрет клиентом
docker buildx build --load \
--secret id=api_token,src=.secrets/api-token.txt \
-t sysadm-secret-demo:local .
docker run --rm sysadm-secret-demo:localИмя id должно совпадать с Dockerfile. --load загружает учебный образ в локальное хранилище Docker. Для иной схемы builder выберите поддерживаемый способ экспорта, не меняя модель передачи секрета.
Что mount не предотвращает
Если RUN выведет файл через cat, скопирует его в /app или вставит значение в создаваемую конфигурацию, секрет снова утечёт. Не включайте shell tracing set -x рядом с чувствительной операцией. Также проверьте сторонний downloader: он может записывать Authorization в отладочный журнал.
Для закрытого пакета передавайте секрет по поддерживаемому файловому интерфейсу инструмента. Не заменяйте mount подстановкой токена в URL, который затем отображается в логах.
Кеш и ротация
Содержимое секрета само по себе не инвалидирует кеш шага. Если смена токена должна привести к повторному получению другого артефакта, управление кешем нужно спроектировать отдельно. В не секретный аргумент можно передать номер версии артефакта, но не пароль или хеш слабого пароля.
Документация по кешу: Build cache invalidation.
Проверить рабочую сборку
- Без обязательного секрета нужный шаг завершается ошибкой.
- Секрет не появился в build context и репозитории.
- Готовый контейнер не содержит build-secret mount.
- В логах и создаваемых файлах нет значения тестового маркера.
- После проверки используется токен минимальных прав с понятной ротацией.
Учебный тест подтверждает жизненный цикл mount, но не доказывает отсутствие утечки в произвольном Dockerfile. Для реального проекта проверяйте все инструкции и журналы CI.
Источник материала: Секреты Docker-сборки через BuildKit: токен без ARG, ENV и COPY (англоязычный материал разработчиков). Русскоязычная инструкция подготовлена самостоятельно; технические сведения проверены 11 октября 2026 года.