docker buildx build

Начать сборку

Использование

$ docker buildx build [OPTIONS] PATH | URL | -

Обратитесь к разделу параметров для обзора доступных OPTIONS для этой команды.

Описание

Команда buildx build запускает сборку с помощью BuildKit. Эта команда похожа на пользовательский интерфейс команды docker build и принимает те же флаги и аргументы.

Документацию по большинству данных флагов см. в документации сборка Docker. Здесь мы задокументируем подмножество новых флагов.

Примеры использования этой команды см. в разделе примеров далее.

Параметры

Имя, сокращенно	По умолчанию	Описание
–добавить хост		Добавляет пользовательское сопоставление хоста и IP-адреса (формат: `host:ip` )
–allow		Разрешить дополнительные привилегированные права (например, `network.host` , `security.insecure` )
–build-arg		Устанавливает переменные времени сборки
–build-context		Дополнительные контексты сборки (например, имя=путь)
–cache-from		Внешние источники кэша (например, `user/app:cache`, `type=local,src=path/to/dir`)
–cache-to		Цели экспорта кэша (например, `user/app:cache` , `type=local,dest=path/to/dir` )
–cgroup-parent		Необязательная родительская контрольная группа для контейнера
`--compress`		Сожмите контекст сборки с помощью gzip
`--cpu-period`		Ограничьте период CPU CFS (Completely Fair Scheduler)
`--cpu-quota`		Ограничьте квоту CPU CFS (Completely Fair Scheduler)
`--cpu-shares` , `-c`		Доли ЦП (относительный вес)
`--cpuset-cpus`		ЦП, в которых разрешено выполнение ( `0-3` , `0,1` )
`--cpuset-mems`		MEM, в которых разрешено выполнение ( `0-3` , `0,1` )
–file , -f		Имя Dockerfile (по умолчанию: `PATH/Dockerfile`)
`--force-rm`		Всегда удаляйте промежуточные контейнеры
`--iidfile`		Записывает идентификатор образа в файл
`--invoke`		Вызвать команду после сборки [экспериментальная]
`--isolation`		Технология изоляции контейнеров
`--label`		Устанавливает метаданные для образа
–load		Сокращение для `--output=type=docker`
`--memory` , `-m`		Лимит памяти
`--memory-swap`		Ограничение подкачки равно памяти плюс подкачка: `-1`, чтобы включить неограниченную подкачку
–metadata-file		Записывает метаданные результата сборки в файл
`--network`		Устанавливает сетевой режим для инструкций `RUN` во время сборки
`--no-cache`		Не используйте кеш при построении образа
`--no-cache-filter`		Не кэшировать указанные этапы
–output , -o		Назначение вывода (формат: `type=local,dest=path` )
–platform		Устанавливает целевую платформу для сборки
`--print`		Распечатывает результат запроса информации (например, план, цели) [экспериментальный]
–progress	`auto`	Устанавливает тип вывода прогресса ( `auto` , `plain` , `tty` ). Используйте обычный, чтобы показывает вывод контейнера
`--pull`		Всегда пытайтесь извлечь все образы, на которые есть ссылки
–push		Сокращение для `--output=type=registry`
`--quiet` , `-q`		Подавить вывод сборки и распечатывает идентификатор образа в случае успеха
`--rm`	`true`	Удаляет промежуточные контейнеры после успешной сборки
–secret		Секрет для сборки (формат: `id=mysecret[,src=/local/secret]`)
`--security-opt`		Параметры безопасности
–shm-size		Размер `/dev/shm`
`--squash`		Соедините вновь созданные слои в один новый слой
–ssh		Сокет или ключи агента SSH, которые будут доступны для сборки (формат: `default\|&lt;id&gt;[=&lt;socket&gt;\|&lt;key&gt;[,&lt;key&gt;]]` )
–tag , -t		Имя и, возможно, тег (формат: `name:tag`)
–target		Устанавливает целевую стадию сборки для сборки
–ulimit		Улимит варианты
–builder		Переопределить настроенный экземпляр построителя

Примеры

Разрешить дополнительные привилегированные права (–allow)

--allow=ENTITLEMENT

Разрешить дополнительные привилегированные права. Список прав:

network.host — разрешает выполнение в сети хоста.
security.insecure — разрешает выполнение без песочницы. См. связанные расширения Dockerfile.

Чтобы права были включены, демон buildkitd также должен разрешить их с помощью --allow-insecure-entitlement (см. флаги –buildkitd-)

Примеры

$ docker buildx create --use --name insecure-builder --buildkitd-flags '--allow-insecure-entitlement security.insecure'
$ docker buildx build --allow security.insecure .

Устанавливает переменные времени сборки (–build-arg)

Same as docker build command.

Есть также полезные встроенные аргументы сборки, такие как:

BUILDKIT_CONTEXT_KEEP_GIT_DIR=<bool> запускает контекст git, чтобы сохраняет каталог .git
BUILDKIT_INLINE_BUILDINFO_ATTRS=<bool> встроенные атрибуты информации о сборке в конфигурации образа или нет
BUILDKIT_INLINE_CACHE=<bool> метаданные встроенного кэша в конфигурацию образа или нет
BUILDKIT_MULTI_PLATFORM=<bool> выбрать детерминированный вывод независимо от того, многоплатформенный вывод или нет

$ docker buildx build --build-arg BUILDKIT_MULTI_PLATFORM=1 .

Примечание

Другие встроенные аргументы сборки можно найти в Справочные документы Dockerfile.

Дополнительные контексты сборки (–build-context)

--build-context=name=VALUE

Определяет дополнительный контекст сборки с указанным содержимым. В Dockerfile доступ к контексту возможен при использовании FROM name или --from=name. Когда Dockerfile определяет этап с тем же именем, он перезаписывается.

Значение может быть локальным исходным каталогом, локальный каталог, совместимый с макетом OCI, образом контейнера (с префиксом docker-image://), Git или URL-адресом HTTP.

Заменяет alpine:latest на закрепленный:

$ docker buildx build --build-context alpine=docker-image://alpine@sha256:0123456789 .

Открывает вторичный локальный исходный каталог:

$ docker buildx build --build-context project=path/to/project/source .
# docker buildx build --build-context project=https://github.com/myuser/project.git .

FROM alpine
COPY --from=project myfile /

Исходное образ из каталога макетов OCI

Источник образа из локального Каталог, совместимый с макетом OCI :

$ docker buildx build --build-context foo=oci-layout:///path/to/local/layout@sha256:abcd12345 .

FROM alpine
RUN apk add git

COPY --from=foo myfile /

FROM foo

Каталог макета OCI должен соответствовать Спецификация макета OCI. Он ищет исключительно хэши. Он не использует разрешение image:tag для поиска хэша манифеста; это зависит от вас.

Формат --build-context должен быть: <context>=oci-layout://<path- to-local-layout>@sha256:<hash-of-manifest> , где:

context — это имя контекста сборки, используемое в Dockerfile.
path-to-local-layout — это путь на локальном компьютере, где вы используете docker build, к макету OCI, совместимому со спецификацией.
hash-of-manifest — это хэш манифеста для образа. Это может быть манифест для одной архитектуры или индекс для нескольких архитектур.

Переопределить настроенный экземпляр построителя (–builder)

Same as buildx –builder.

Использовать внешний источник кеша для сборки (–cache-from)

--cache-from=[NAME|type=TYPE[,KEY=VALUE]]

Используйте внешний источник кеша для сборки. Поддерживаемые типы: registry, local и gha.

источник реестра может импортирует кеш из манифеста кеша или (специальной) конфигурации образа в реестре.
local источник может импортировать кеш из локальных файлов, ранее экспортированных с помощью --cache-to.
gha источник может импортирует кеш из ранее экспортированного кеша с --cache-to в вашем репозитории GitHub

Если тип не указан, используется экспортёр registry с указанной ссылкой.

Драйвер docker в настоящее время поддерживает только импорт кэша сборки из реестра.

$ docker buildx build --cache-from=user/app:cache .
$ docker buildx build --cache-from=user/app .
$ docker buildx build --cache-from=type=registry,ref=user/app .
$ docker buildx build --cache-from=type=local,src=path/to/cache .
$ docker buildx build --cache-from=type=gha .

Дополнительная информация об экспортерах кеша и доступных атрибутах: https://github.com/moby/buildkit#export-cache

Экспортировать кеш сборки во внешнее место назначения кеша (–cache-to)

--cache-to=[NAME|type=TYPE[,KEY=VALUE]]

Экспортировать кэш сборки во внешнее место назначения кэша. Поддерживаемые типы: registry, local, inline и gha.

тип реестра экспортирует кеш сборки в манифест кеша в реестре.
Тип local экспортирует кэш в локальный каталог на клиенте.
Тип inline записывает метаданные кэша в конфигурацию образа.
Тип gha экспортирует кеш через API службы Github Actions Cache.

Драйвер docker в настоящее время поддерживает только экспорт метаданных встроенного кэша в конфигурацию образа. В качестве альтернативы --build-arg BUILDKIT_INLINE_CACHE=1 можно использовать для запуска экспортера встроенного кеша.

Ключ атрибута:

mode — указывает, сколько слоев экспортируется с кэшем. min on экспортирует только те слои, которые уже находятся на заключительном этапе сборки, max экспортирует слои для всех этапов. Метаданные всегда экспортируются для всей сборки.

$ docker buildx build --cache-to=user/app:cache .
$ docker buildx build --cache-to=type=inline .
$ docker buildx build --cache-to=type=registry,ref=user/app .
$ docker buildx build --cache-to=type=local,dest=path/to/cache .
$ docker buildx build --cache-to=type=gha .

Дополнительная информация об экспортерах кеша и доступных атрибутах: https://github.com/moby/buildkit#export-cache

Загружает результат одноплатформенной сборки в

Сокращение для --output=type=docker . Автоматически загрузит результат сборки для одной платформы в docker images.

Записывает метаданные результата сборки в файл (–metadata-file)

Чтобы выводит метаданные сборки, такие как дайджест образа, передать флаг --metadata-file. Метаданные будут записаны как объект JSON в указанный файл. Каталог указанного файла должен уже существовать и быть доступным для записи.

$ docker buildx build --load --metadata-file metadata.json .
$ cat metadata.json

{
  "containerimage.buildinfo": {
    "frontend": "dockerfile.v0",
    "attrs": {
      "context": "https://github.com/crazy-max/buildkit-buildsources-test.git#master",
      "filename": "Dockerfile",
      "source": "docker/dockerfile:master"
    },
    "sources": [
      {
        "type": "docker-image",
        "ref": "docker.io/docker/buildx-bin:0.6.1@sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0",
        "pin": "sha256:a652ced4a4141977c7daaed0a074dcd9844a78d7d2615465b12f433ae6dd29f0"
      },
      {
        "type": "docker-image",
        "ref": "docker.io/library/alpine:3.13",
        "pin": "sha256:026f721af4cf2843e07bba648e158fb35ecc876d822130633cc49f707f0fc88c"
      }
    ]
  },
  "containerimage.config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
  "containerimage.descriptor": {
    "annotations": {
      "config.digest": "sha256:2937f66a9722f7f4a2df583de2f8cb97fc9196059a410e7f00072fc918930e66",
      "org.opencontainers.image.created": "2022-02-08T21:28:03Z"
    },
    "digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3",
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "size": 506
  },
  "containerimage.digest": "sha256:19ffeab6f8bc9293ac2c3fdf94ebe28396254c993aea0b5a542cfb02e0883fa3"
}

Устанавливает действие экспорта для результата сборки (-o, –output)

-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]

Задаёт действие экспорта для результата сборки. В docker build все сборки заканчиваются созданием образа контейнера и его экспортом в docker images. buildx позволяет настраивать данный шаг, позволяя экспортировать результаты непосредственно в клиент, архивы образов oci, реестр и т.д.

Buildx с драйвером docker в настоящее время поддерживает только локальный экспортёр, экспортёр tarball и экспортёр образов. Драйвер docker-container поддерживает все экспортеры.

Если в качестве значения указан только путь, buildx будет использовать локальный экспортёр с этим путём в качестве места назначения. Если значение равно «-», buildx будет использовать экспортёр tar и записывать в stdout .

$ docker buildx build -o . .
$ docker buildx build -o outdir .
$ docker buildx build -o - - > out.tar
$ docker buildx build -o type=docker .
$ docker buildx build -o type=docker,dest=- . > myimage.tar
$ docker buildx build -t tonistiigi/foo -o type=registry

Поддерживаемые экспортируемые типы:

`local`

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

Ключ атрибута:

dest — каталог назначения, куда будут записываться файлы

`tar`

Тип экспорта tar записывает все файлы результатов в виде одного архива на клиенте. В многоплатформенных сборках все результаты будут помещены в подкаталоги их платформы.

Ключ атрибута:

dest — путь назначения, куда будет записан tarball. «-» пишет на стандартный вывод.

`oci`

Тип экспорта oci записывает образ результата или список манифестов в виде архива Макет образа OCI на клиенте.

Ключ атрибута:

dest — путь назначения, куда будет записан tarball. «-» пишет на стандартный вывод.

`docker`

Тип экспорта docker записывает образ результата для одной платформы в виде архива Спецификация образа Docker на клиенте. Тарболы, созданные этим экспортером, также совместимы с OCI.

В настоящее время мультиплатформенные образа нельзя экспортировать с типом экспорта docker. Наиболее распространенный опция использования многоплатформенных образов — это прямая отправка в реестр (см. registry).

Ключи атрибутов:

dest — путь назначения, куда будет записан tarball. Если не указано, tar будет автоматически загружен в текущий экземпляр Docker.
context — имя контекста Docker, куда импортирует результат

`image`

Средство экспорта image записывает результат сборки в виде образа или списка манифестов. При использовании драйвера docker образ появится в docker images. При желании образ можно автоматически отправить в реестр, указав атрибуты.

Ключи атрибутов:

name — имя (ссылки) для нового образа.
push — логическое значение для автоматической отправки образа.

`registry`

Экспортёр registry — это сокращение для type=image,push=true.

Задаёт целевые платформы для сборки (–platform)

--platform=value[,value]

Устанавливает целевую платформу для сборки. Все команды FROM внутри Dockerfile без собственного флага --platform будут извлекать базовые образы для этой платформы, и это значение также будет платформой результирующего образа. Значением по умолчанию будет текущая платформа демона buildkit.

При использовании драйвера docker-container с buildx данный флаг может принимать несколько значений в качестве входных данных, разделенных запятой. С несколькими значениями результат будет создан для всех указанных платформ и объединен в единый список манифеста.

Если Dockerfile необходимо вызвать команду RUN, сборщику требуется поддержка во время выполнения для указанной платформы. В чистой настройке вы можете выполнять только команды RUN для архитектуры вашей системы. Если ваше ядро поддерживает средства запуска binfmt_misc для дополнительных архитектур, buildx подберет их автоматически. Релизы Docker для настольных ПК поставляются с binfmt_misc, автоматически настроенным для архитектур arm64 и arm. Вы можете увидеть, какие платформы среды выполнения поддерживает ваш текущий экземпляр сборщика, запустив docker buildx inspect --bootstrap .

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

Формат спецификатора платформы определён в исходный код контейнера .

$ docker buildx build --platform=linux/arm64 .
$ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
$ docker buildx build --platform=darwin .

Устанавливает тип вывода прогресса (–progress)

--progress=VALUE

Устанавливает тип вывода прогресса (авто, обычный, tty). Используйте обычный, чтобы показывает вывод контейнера (по умолчанию «авто»).

Примечание

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

В следующем примере во время сборки используются выходные данные plain:

$ docker buildx build --load --progress=plain .

#1 [internal] load build definition from Dockerfile
#1 transferring dockerfile: 227B 0.0s done
#1 DONE 0.1s

#2 [internal] load .dockerignore
#2 transferring context: 129B 0.0s done
#2 DONE 0.0s
...

Примечание

Проверяет также наш Руководство по управлению выводом цвета для изменения цветов, которые используются для вывода информации на терминал.

Отправить результат сборки в реестр (–push)

Сокращение для --output=type=registry . Автоматически отправит результат сборки в реестр.

Секрет для сборки (–secret)

--secret=[type=TYPE[,KEY=VALUE]

Раскрывает секрет сборки. Секрет может быть использован сборкой с использованием монтирования RUN –mount=type=secret.

Если type не установлен, он будет обнаружен. Поддерживаемые типы:

`file`

Ключи атрибутов:

id — идентификатор секрета. По умолчанию используется базовое имя пути src.
src, source — секретное имя файла. id используется, если не установлено.

# syntax=docker/dockerfile:1.4
FROM python:3
RUN pip install awscli
RUN --mount=type=secret,id=aws,target=/root/.aws/credentials \
  aws s3 cp s3://... ...

$ docker buildx build --secret id=aws,src=$HOME/.aws/credentials .

`env`

Ключи атрибутов:

id — идентификатор секрета. По умолчанию используется имя env.
env — секретная переменная среды. id используется, если не установлен, иначе будет искать src, source, если id не установлен.

# syntax=docker/dockerfile:1.4
FROM node:alpine
RUN --mount=type=bind,target=. \
  --mount=type=secret,id=SECRET_TOKEN \
  SECRET_TOKEN=$(cat /run/secrets/SECRET_TOKEN) yarn run test

$ SECRET_TOKEN=token docker buildx build --secret id=SECRET_TOKEN .

Размер/dev/shm (–shm-size)

Формат <number><unit>. number должен быть больше, чем 0. Единица измерения не является обязательной и может быть b (байты), k (килобайты), m (мегабайты) или g (гигабайты). Если вы опустите единицу измерения, система использует байты.

Сокет или ключи агента SSH для предоставления сборке (–ssh)

--ssh=default|<id>[=<socket>|<key>[,<key>]]

Это может быть полезно, когда для некоторых команд в вашем Dockerfile требуется особая аутентификация SSH (например, клонирование частного репозитория).

--ssh предоставляет сокет или ключи агента SSH для сборки и может использоваться с монтированием RUN –mount=type=ssh.

Пример доступа к Gitlab с использованием сокета агента SSH:

# syntax=docker/dockerfile:1.4
FROM alpine
RUN apk add --no-cache openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan gitlab.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh ssh -q -T git@gitlab.com 2>&1 | tee /hello
# "Welcome to GitLab, @GITLAB_USERNAME_ASSOCIATED_WITH_SSHKEY" should be printed here
# with the type of build progress is defined as `plain`.

$ eval $(ssh-agent)
$ ssh-add ~/.ssh/id_rsa
(Input your passphrase here)
$ docker buildx build --ssh default=$SSH_AUTH_SOCK .

Установить ulimits (–ulimit)

--ulimit указывается с мягким и жестким ограничением как таковым: например, <type>=<soft limit>[:<hard limit>] :

$ docker buildx build --ulimit nofile=1024:1024 .

Примечание

Если вы не укажете hard limit, для обоих значений будет использоваться soft limit. Если ulimits не установлены, они наследуются от установленного по умолчанию ulimits в демоне.

Родительская команда

Команда	Описание
docker buildx	Docker Buildx

Связанные команды

Команда	Описание
docker buildx bake	Сборка из файла
docker buildx build	Начать сборку
docker buildx create	Создаёт новый экземпляр построителя
docker buildx du	Использование диска
docker buildx imagetools	Команды для работы с образами в реестре
docker buildx inspect	Проверяет текущий экземпляр построителя
docker buildx ls	Список экземпляров построителя
docker buildx prune	Удаляет кеш сборки
docker buildx rm	Удаляет экземпляр построителя
docker buildx stop	Останавливает экземпляр построителя
docker buildx use	Устанавливает текущий экземпляр построителя
docker buildx version	Показывает информацию о версии buildx

« предыдущий | следующий »