From f0579be5b2f0b44285377f93d114d4b91ce9a7fa Mon Sep 17 00:00:00 2001 From: Timofey Kirillov Date: Thu, 13 Apr 2023 15:36:23 +0300 Subject: [PATCH] feat(multiarch): minimal docs about multiplatform mode Signed-off-by: Timofey Kirillov --- docs/pages_en/usage/build/images.md | 54 ++++++++++++++++++++++++++++ docs/pages_en/usage/build/process.md | 16 +++++++++ docs/pages_ru/usage/build/images.md | 54 ++++++++++++++++++++++++++++ docs/pages_ru/usage/build/process.md | 16 +++++++++ 4 files changed, 140 insertions(+) diff --git a/docs/pages_en/usage/build/images.md b/docs/pages_en/usage/build/images.md index ae51669780..037c45ef7e 100644 --- a/docs/pages_en/usage/build/images.md +++ b/docs/pages_en/usage/build/images.md @@ -363,3 +363,57 @@ dependencies: ``` During the build, werf will automatically insert the appropriate names and identifiers into the referenced build-arguments. werf will take care of all orchestration and dependency mapping and then build everything in one step (as part of the `werf build` command). + +## Building for target platform + +Using `--platform` parameter user can choose target platform for built images: + +```shell +werf build --platform linux/arm64 +``` + +— werf builds all final images from werf.yaml for the target platform using emulation. + +You can also set target platform with `build.platform` configuration directive: + +```yaml +# werf.yaml +project: example +configVersion: 1 +build: + platform: + - linux/arm64 +--- +image: frontend +dockerfile: frontend/Dockerfile +--- +image: backend +dockerfile: backend/Dockerfile +``` + +In this case running `werf build` command without parameters will start building images for the specified platform (explicitly passed `--platform` parameter redefines werf.yaml setting). + +> **NOTE:** Preparation of host-system for multiplatform building, and also additional information about multiplatform support for different syntaxes and backends are available [in the building process article]({{ "/usage/build/process.html" | true_relative_url }}). + +### Build multiplatform images + +werf supports buildling of images for multiple platforms at the same time. In such case werf publishes special manifest into the container registry, this manifest includes built images for each specified target platform (when pulling such an image a client will receive image built for the client platform). + +Tou can define list of target platforms with such configuration: + +```yaml +# werf.yaml +project: example +configVersion: 1 +build: + platform: + - linux/arm64 + - linux/amd64 + - linux/arm/v7 +``` + +This list also can be redefined by the `--platform` parameter like that: + +```shell +werf build --platform=linux/amd64,linux/i386 +``` diff --git a/docs/pages_en/usage/build/process.md b/docs/pages_en/usage/build/process.md index ba70ae2872..6b4810c8a8 100644 --- a/docs/pages_en/usage/build/process.md +++ b/docs/pages_en/usage/build/process.md @@ -361,3 +361,19 @@ The format of `WERF_BUILDAH_ULIMIT=type=softlimit[:hardlimit][,type=softlimit[:h * "rttime": maximum amount of real-time execution between blocking syscalls; * "sigpending": maximum number of pending signals (ulimit -i); * "stack": maximum stack size (ulimit -s). + +### Multiplatform builds + +Multiplatform building uses crossplatform instructions execution mechanics provided by the [linux kernel](https://en.wikipedia.org/wiki/Binfmt_misc) and qemu emulator. The easiest way to register the most architectures emulation in your host system is to use qemu-user-static like that: + +```shell +docker run --rm --privileged multiarch/qemu-user-static --reset -p yes +``` + +This table summarizes support of multiplatform building for different configuration syntax, modes of building and build backends: + +| | buildah | docker-server | +|--- |--- |--- | +| **Dockerfile** | full support | full support | +| **staged Dockerfile** | full support | no support | +| **stapel** | full support | linux/amd64 only | diff --git a/docs/pages_ru/usage/build/images.md b/docs/pages_ru/usage/build/images.md index b3e5597893..177fc6d094 100644 --- a/docs/pages_ru/usage/build/images.md +++ b/docs/pages_ru/usage/build/images.md @@ -363,3 +363,57 @@ dependencies: ``` В процессе сборки werf автоматически подставит в указанные build-arguments соответствующие имена и идентификаторы. Всю оркестрацию и выстраивание зависимостей werf возьмёт на себя и произведёт сборку за один шаг (вызов `werf build`). + +## Сборка образов под произвольную платформу + +При сборке можно выбрать целевую платформу для собираемых образов с помощью параметра `--platform`: + +```shell +werf build --platform linux/arm64 +``` + +— все конечные образы, указанные в werf.yaml, будут собраны для указанной платформы с использованием эмуляции. + +Целевую платформу можно также указать директивой конфигурации `build.platform`: + +```yaml +# werf.yaml +project: example +configVersion: 1 +build: + platform: + - linux/arm64 +--- +image: frontend +dockerfile: frontend/Dockerfile +--- +image: backend +dockerfile: backend/Dockerfile +``` + +В этом случае запуск `werf build` без параметров вызовет сборку образов для указанной платформы (при этом явно указанный параметр `--platform` переопределяет значение из werf.yaml). + +> **ЗАМЕЧАНИЕ:** Подготовка хост-системы для мультиплатформенной сборки и поддержка этого режима для различных синтаксисов инструкций и бекендов рассмотрены [в разделе про сборочный процесс]({{ "/usage/build/process.html" | true_relative_url }}). + +### Сборка мультиплатформенных образов + +Поддерживается и сборка образов сразу для набора архитектур. В этом случае в container registry публикуется манифест включающий в себя собранные образы под каждую из указанных платформ (во время скачивания такого образа автоматически будет выбираться образ под требуемую архитектуру). + +Можно определить список платформ с помощью конфигурации: + +```yaml +# werf.yaml +project: example +configVersion: 1 +build: + platform: + - linux/arm64 + - linux/amd64 + - linux/arm/v7 +``` + +Список можно также переопределить параметром `--platform` непосредственно в момент вызова сборки: + +```shell +werf build --platform=linux/amd64,linux/i386 +``` diff --git a/docs/pages_ru/usage/build/process.md b/docs/pages_ru/usage/build/process.md index 2ed64383d7..68cf051bd2 100644 --- a/docs/pages_ru/usage/build/process.md +++ b/docs/pages_ru/usage/build/process.md @@ -361,3 +361,19 @@ werf может использовать драйвер хранилища `over * "rttime": maximum amount of real-time execution between blocking syscalls; * "sigpending": maximum number of pending signals (ulimit -i); * "stack": maximum stack size (ulimit -s). + +### Мультиплатформенная сборка + +Мультиплатформенная сборка использует механизмы кроссплатформенного исполнения инструкций, предоставляемые [ядром linux](https://en.wikipedia.org/wiki/Binfmt_misc) и эмулятором qemu. Самый простой способ зарегистрировать в хост-системе эмуляторы для большинства архитектур — воспользоваться образом qemu-user-static: + +```shell +docker run --rm --privileged multiarch/qemu-user-static --reset -p yes +``` + +Поддержка мультиплатформенной сборки для разных вариантов синтаксиса сборки, режимов сборки и используемого бекенда: + +| | buildah | docker-server | +|--- |--- |--- | +| **Dockerfile** | полная поддержка | полная поддержка | +| **staged Dockerfile** | полная поддержка | не поддерживается | +| **stapel** | полная поддержка | только linux/amd64 |