Экспортеры

Экспортеры сохраняют результаты сборки в заданном типе вывода. Вы указываете экспортёр для использования с –output CLIoption. Buildx поддерживает следующие экспортеры:

  • image: экспортирует результат сборки в образ контейнера.

  • registry: экспортирует результат сборки в образ контейнера и помещает его в указанный реестр.

  • local: экспортирует корневую файловую систему сборки в локальный каталог.

  • tar: упаковывает корневую файловую систему сборки в локальный tarball.

  • oci: экспортирует результат сборки в локальную файловую систему в формате Макет образа OCI.

  • docker: экспортирует результат сборки в локальную файловую систему в формате Docker-образ.

  • cacheonly: не экспортирует вывод сборки, а запускает сборку и создаёт кэш.

Использование экспортеров

Чтобы указывает экспортера, используйте следующий синтаксис команды:

$ docker buildx build --tag <registry>/<image> \
  --output type=<TYPE> .

В большинстве распространенных случаев использования не требуется указывать, какой экспортёр использовать в явном виде. Вам нужно указывает экспортёр, только если вы собираетесь как-то настроить вывод или сохраняет его на диске. Опции --load и --push позволяют Buildx определить, какой экспортёр использовать.

Например, если вы используете опцию --push в сочетании с --tag, Buildx автоматически использует экспортёр image и настраивает экспортёр на перенос результатов в указанный реестр.

Чтобы получает полную гибкость от различных экспортеров, предлагаемых BuildKit, вы используете флаг --output, который позволяет вам настраивать параметры экспортера.

Примеры использования

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

Загрузка в хранилище образов

Buildx часто используется для создания образов контейнеров, которые могут быть загружены в хранилище образов. В этом случае на помощь приходит экспортёр docker. В следующем примере показано, как создать образ с помощью экспортера docker и загружает его в локальное хранилище образов, используя опцию --output:

$ docker buildx build \
  --output type=docker,name=<registry>/<image> .

Buildx CLI будет автоматически использовать экспортёр docker и загружать его в хранилище образов, если вы предоставите опции --tag и --load:

$ docker buildx build --tag <registry>/<image> --load .

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

Образы, загруженные в хранилище образов, доступны для docker run сразу после завершения сборки, и вы увидите их в списке образов при выполнении команды docker images.

Переход к реестру

Чтобы передать собранный образ в реестр контейнеров, можно использовать экспортеры registry или image.

Когда вы передаете опцию --push в Buildx CLI, вы инструктируете BuildKit вытолкнуть собранный образ в указанный реестр:

$ docker buildx build --tag <registry>/<image> --push .

При этом используется экспортёр image и устанавливается параметр push. Это то же самое, что использовать следующую длинную команду с параметром --output:

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true .

Вы также можете использовать экспортёр registry, который делает то же самое:

$ docker buildx build \
  --output type=registry,name=<registry>/<image> .

Экспорт макета образа в файл

Вы можете использовать экспортеры oci или docker для сохранения результатов сборки в виде макета образа в локальной файловой системе. Оба данных экспортера генерируют архивный файл tar, содержащий соответствующий макет образа. Параметр dest определяет целевой путь вывода tar-архива.

$ docker buildx build --output type=oci,dest=./image.tar .
[+] Building 0.8s (7/7) FINISHED
 ...
 => exporting to oci image format                                                                     0.0s
 => exporting layers                                                                                  0.0s
 => exporting manifest sha256:c1ef01a0a0ef94a7064d5cbce408075730410060e253ff8525d1e5f7e27bc900        0.0s
 => exporting config sha256:eadab326c1866dd247efb52cb715ba742bd0f05b6a205439f107cf91b3abc853          0.0s
 => sending tarball                                                                                   0.0s
$ mkdir -p out && tar -C out -xf ./image.tar
$ tree out
out
├── blobs
│   └── sha256
│       ├── 9b18e9b68314027565b90ff6189d65942c0f7986da80df008b8431276885218e
│       ├── c78795f3c329dbbbfb14d0d32288dea25c3cd12f31bd0213be694332a70c7f13
│       ├── d1cf38078fa218d15715e2afcf71588ee482352d697532cf316626164699a0e2
│       ├── e84fa1df52d2abdfac52165755d5d1c7621d74eda8e12881f6b0d38a36e01775
│       └── fe9e23793a27fe30374308988283d40047628c73f91f577432a0d05ab0160de7
├── index.json
├── manifest.json
└── oci-layout

Экспорт файловой системы

Если вы не хотите создавать образ из результатов сборки, а вместо этого экспортировать собранную файловую систему, вы можете использовать экспортеры local и tar.

Экспортёр local распаковывает файловую систему в структуру каталогов в указанном месте. Экспортёр tar создаёт архивный файл tarball.

$ docker buildx build --output type=tar,dest=<path/to/output> .

Экспортёр local полезен в многоступенчатых сборках <build_building_multi-stage>, поскольку позволяет экспортировать только минимальное количество артефактов сборки. Например, самодостаточные двоичные файлы.

Только кэш-экспорт

Экспортёр cacheonly можно использовать, если вы хотите просто запускает сборку, не экспортируя никаких результатов. Это может быть полезно, например, если вы хотите запускает тестовую сборку. Или, если вы хотите сначала запускает сборку, а затем создает экспорт с помощью последующих команд. Экспортёр cacheonly создаёт кэш сборки, поэтому все последующие сборки будут мгновенными.

$ docker buildx build --output type=cacheonly

Если вы не указываете экспортёр, и не предоставляете опции сокращения, например, --load, которая автоматически выбирает соответствующий экспортёр, Buildx по умолчанию использует экспортёр cacheonly. За исключением случаев, когда вы собираете с использованием драйвера docker, в этом случае вы используете экспортёр docker.

Buildx регистрирует предупреждение при использовании cacheonly в качестве значения по умолчанию:

$ docker buildx build .
WARNING: No output specified with docker-container driver.
         Build result will only remain in the build cache.
         To push result image into registry use --push or
         to load image into docker use --load

Многочисленные экспортеры

Вы можете указывает только один экспортёр для любой конкретной сборки (подробности см. в данный запрос). Но вы можете выполняет несколько сборок одну за другой, чтобы дважды экспортировать один и тот же контент. BuildKit кэширует сборку, поэтому, если какой-либо из слоев не изменится, все последующие сборки, следующие за первой, выполняются мгновенно.

В следующем примере показано, как запускает одну и ту же сборку дважды, сначала используя image, а затем local.

$ docker buildx build --output type=image,tag=<registry>/<image> .
$ docker buildx build --output type=local,dest=<path/to/output> .

Параметры конфигурации

В этом разделе рассмотрены некоторые параметры конфигурации, доступные для экспортеров.

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

Здесь рассмотрены следующие общие параметры:

Компрессия

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

Для выбора алгоритма сжатия можно использовать параметр compression. Например, для построения image с compression=zstd:

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true,compression=zstd .

Используйте параметр compression-level=<value> вместе с параметром compression, чтобы выбрать уровень сжатия для алгоритмов, которые его поддерживают:

  • 0-9 для gzip и estargz

  • 0-22 для zstd

Как правило, чем больше число, тем меньше будет результирующий файл и тем дольше будет выполняться сжатие.

Используйте параметр force-compression=true для принудительного повторного сжатия слоев, импортированных из предыдущего образа, если запрашиваемый алгоритм сжатия отличается от предыдущего алгоритма сжатия.

Примечание

В методах сжатия gzip и estargz используется сжимает/gzip пакет, а в zstd — пакет zstd.

Типы носителей OCI

Экспортеры, выводящие образы контейнеров, поддерживают создание образов либо с медиатипами Docker (по умолчанию), либо с медиатипами OCI. Это поддерживается экспортерами image, registry, oci и docker.

Для экспорта образов с установленными типами носителей OCI используйте свойство oci-mediatypes. Например, с экспортером image:

$ docker buildx build \
  --output type=image,name=<registry>/<image>,push=true,oci-mediatypes=true .

Информация о строительстве

Экспортеры, выводящие образы контейнеров, позволяют встраивать информацию о сборке, включая информацию об исходном запросе на сборку и источниках, использованных во время сборки. Это поддерживается экспортерами image, registry, oci и docker.

Эта информация о сборке прикрепляется к конфигурации образа:

{
  "moby.buildkit.buildinfo.v0": "<base64>"
}

По умолчанию зависимости сборки прикрепляются к конфигурации образа. Вы можете отключить это поведение, установив значение buildinfo=false.

Что дальше?

Читает о каждом из экспортеров, чтобы узнать, как они работают и как их использовать: