From 4afcf032cdd56fc5dc266e65033c07717cb8b62c Mon Sep 17 00:00:00 2001 From: Ilya Lesikov Date: Fri, 28 Apr 2023 12:36:20 +0300 Subject: [PATCH] fix(docs): cleanup docs moved to install Signed-off-by: Ilya Lesikov --- docs/_data/sidebars/_documentation.yml | 6 - docs/_data/sidebars/documentation.yml | 6 - docs/pages_en/usage/build/process.md | 60 +--------- .../pages_en/usage/build/run_in_containers.md | 110 ------------------ docs/pages_ru/usage/build/process.md | 60 +--------- .../pages_ru/usage/build/run_in_containers.md | 110 ------------------ 6 files changed, 2 insertions(+), 350 deletions(-) delete mode 100644 docs/pages_en/usage/build/run_in_containers.md delete mode 100644 docs/pages_ru/usage/build/run_in_containers.md diff --git a/docs/_data/sidebars/_documentation.yml b/docs/_data/sidebars/_documentation.yml index 9e34557462..1f8deae672 100644 --- a/docs/_data/sidebars/_documentation.yml +++ b/docs/_data/sidebars/_documentation.yml @@ -49,9 +49,6 @@ entries: - title: Build process url: /usage/build/process.html - - title: Run in containers - url: /usage/build/run_in_containers.html - - title: Deploy f: - title: Overview @@ -183,9 +180,6 @@ entries: - title: Сборочный процесс url: /usage/build/process.html - - title: Работа в контейнерах - url: /usage/build/run_in_containers.html - - title: Развертывание f: - title: Обзор diff --git a/docs/_data/sidebars/documentation.yml b/docs/_data/sidebars/documentation.yml index f32541f0a1..eef0a32dbe 100644 --- a/docs/_data/sidebars/documentation.yml +++ b/docs/_data/sidebars/documentation.yml @@ -687,9 +687,6 @@ entries: - title: Build process url: /usage/build/process.html - - title: Run in containers - url: /usage/build/run_in_containers.html - - title: Deploy f: - title: Overview @@ -821,9 +818,6 @@ entries: - title: Сборочный процесс url: /usage/build/process.html - - title: Работа в контейнерах - url: /usage/build/run_in_containers.html - - title: Развертывание f: - title: Обзор diff --git a/docs/pages_en/usage/build/process.md b/docs/pages_en/usage/build/process.md index cb0b56cb87..ba38842dff 100644 --- a/docs/pages_en/usage/build/process.md +++ b/docs/pages_en/usage/build/process.md @@ -304,65 +304,7 @@ werf converge --repo registry.mydomain.org/repo --synchronization :local > **NOTE:** This method is only suitable if all werf runs are triggered by the same runner in your CI/CD system. -## Configuring the build backend - - - -werf supports Docker Server or Buildah as backend for building images. Buildah provides full containerization and layer-by-layer Dockerfile builds with caching of all intermediate layers into the container registry. Docker Server is currently the default backend. - -> **NOTE:** The Buildah backend does not currently support storing images locally, only [storing images in the container registry](#layer-by-layer-image-caching) is supported. - -### Docker - -Docker Server is currently the default backend and no additional configuration is required. - -### Buildah - -> **NOTE:** Buildah is currently only available to Linux users and Windows users with the WSL2 subsystem enabled. For macOS, we suggest using a virtual machine to run werf in Buildah mode. - -werf uses Buildah in rootless mode to build images without a Docker server. Buildah is built into the werf binary. You can find the host system requirements to run werf with the Buildah backend [in the installation instructions](/installation.html). - -Buildah can be enabled by setting the `WERF_BUILDAH_MODE` environment variable to one of the options: `auto`, `native-chroot`, `native-rootless`. Most users only have to set `WERF_BUILDAH_MODE=auto` to enable Buildah mode. - -#### Level of assembly isolation - -By default, in `auto` mode, werf automatically sets the isolation level depending on the platform and environment. - -2 types of assembly container isolation are supported: -1. Chroot is an option that does not use the container runtime; it can be enabled as follows: `WERF_BUILDAH_MODE=native-chroot`. -2. Rootless is an option involving container runtime (crun or runc or kata or runsc must be installed on the system); it can be enabled as follows: `WERF_BUILAH_MODE=native-rootless`. - -#### Storage driver - -werf supports the `overlay` or `vfs` storage driver: - -* `overlay` allows you to use the OverlayFS filesystem. You can either use the Linux kernel's built-in support for OverlayFS (if available) or you can use the fuse-overlayfs implementation. This is the recommended default choice. -* `vfs` provides access to a virtual filesystem instead of OverlayFS. This file system is inferior in performance and requires a privileged container, so it is not recommended. However, it may be useful in some cases. - -Generally, the default driver (`overlay`) is enough. The storage driver can be set using the `WERF_BUILDAH_STORAGE_DRIVER` environment variable. - -#### Ulimits - -By default, the Buildah mode in werf inherits system ulimits when the build containers are started. The user can override these parameters using the `WERF_BUILDAH_ULIMIT` environment variable. - -The format of `WERF_BUILDAH_ULIMIT=type=softlimit[:hardlimit][,type=softlimit[:hardlimit],...]` is comma-separated limit values: -* "core": maximum core dump size (ulimit -c); -* "cpu": maximum CPU time (ulimit -t); -* "data": maximum size of a process's data segment (ulimit -d); -* "fsize": maximum size of new files (ulimit -f); -* "locks": maximum number of file locks (ulimit -x); -* "memlock": maximum amount of locked memory (ulimit -l); -* "msgqueue": maximum amount of data in message queues (ulimit -q); -* "nice": niceness adjustment (nice -n, ulimit -e); -* "nofile": maximum number of open files (ulimit -n); -* "nproc": maximum number of processes (ulimit -u); -* "rss": maximum size of a process's (ulimit -m); -* "rtprio": maximum real-time scheduling priority (ulimit -r); -* "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 builds Multiplatform builds use the cross-platform instruction execution mechanics provided by the [Linux kernel](https://en.wikipedia.org/wiki/Binfmt_misc) and the QEMU emulator. The easiest way to register emulators for most architectures on your host system is to use the `qemu-user-static` image: diff --git a/docs/pages_en/usage/build/run_in_containers.md b/docs/pages_en/usage/build/run_in_containers.md deleted file mode 100644 index b55d81388c..0000000000 --- a/docs/pages_en/usage/build/run_in_containers.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Run in containers -permalink: usage/build/run_in_containers.html ---- - -### Pre-built images - - - -The recommended way to run werf in containers is to use the official werf images from `registry.werf.io/werf/werf`. You can launch werf in a container as follows: - -```shell -docker run \ - --security-opt seccomp=unconfined --security-opt apparmor=unconfined \ - registry.werf.io/werf/werf:1.2-stable WERF_COMMAND -``` - -If the Linux kernel does not support rootless OverlayFS, then fuse-overlayfs should be used: - -```shell -docker run \ - --device /dev/fuse \ - --security-opt seccomp=unconfined --security-opt apparmor=unconfined \ - registry.werf.io/werf/werf:1.2-stable WERF_COMMAND -``` - -It is recommended to use the `registry.werf.io/werf/werf:1.2-stable` image. The following images are also available: -- `registry.werf.io/werf/werf:latest` — an alias for `registry.werf.io/werf/werf:1.2-stable`; -- `registry.werf.io/werf/werf:1.2-{alpha|beta|ea|stable|rock-solid}` — all images are based on Alpine, the user must choose the release (stability) channel; -- `registry.werf.io/werf/werf:1.2-{alpha|beta|ea|stable|rock-solid}-{alpine|ubuntu|fedora}` — the user must choose the release (stability) channel and the the underlying distribution. - -These images use the Buildah backend. Switching to the Docker Server backend is not supported. - -### Building images using the Docker server (not recommended) - -> **NOTE:** No official werf images are provided for this method. - -To use a local Docker server, you have to mount the Docker socket in a container and use privileged mode: - -```shell -docker run \ - --privileged \ - --volume $HOME/.werf:/root/.werf \ - --volume /tmp:/tmp \ - --volume /var/run/docker.sock:/var/run/docker.sock \ - IMAGE WERF_COMMAND -``` - -— this method supports building Dockerfile images or Stapel images. - -Use the following command to run the Docker server over TCP: - -```shell -docker run --env DOCKER_HOST="tcp://HOST:PORT" IMAGE WERF_COMMAND -``` - -— this method only supports building Dockerfile images. Stapel images are not supported because the Stapel image builder mounts host system directories into the build containers. - -### Troubleshooting - - - -#### `fuse: device not found` - -The complete error message may look as follows: - -``` -error mounting new container: error mounting build container "53f916e7a334a4bb0d9dbc38a0901718d40b99765002bb7f2f2e5464b1db4294": error creating overlay mount to /home/build/.local/share/containers/storage/overlay/49e856f537ba58afdc09137291133994cd1305e40df72c4fab43077cbd405477/merged, mount_data=",lowerdir=/home/build/.local/share/containers/storage/overlay/l/Z5GEVIFIIQ7H262DYUTX3YOVR6:/home/build/.local/share/containers/storage/overlay/l/PJBBW6UNUNGI37IX6R3LDNPX3J:/home/build/.local/share/containers/storage/overlay/l/MUYSUONLQVE4CJMQVDCH2UBAVQ:/home/build/.local/share/containers/storage/overlay/l/67JHKJDCKBTI4R3Q5S5YG44AD3:/home/build/.local/share/containers/storage/overlay/l/3S72G4SWKDXILGANUOCESP5LDK,upperdir=/home/build/.local/share/containers/storage/overlay/49e856f537ba58afdc09137291133994cd1305e40df72c4fab43077cbd405477/diff,workdir=/home/build/.local/share/containers/storage/overlay/49e856f537ba58afdc09137291133994cd1305e40df72c4fab43077cbd405477/work,volatile": using mount program /usr/bin/fuse-overlayfs: fuse: device not found, try 'modprobe fuse' first -fuse-overlayfs: cannot mount: No such file or directory -: exit status 1 -time="2021-12-06T11:30:20Z" level=error msg="exit status 1" -``` - -How to fix it: enable the fuse device for the container in which werf is running ([details]({{ "usage/build/run_in_containers.html" | true_relative_url }})). - -#### `flags: 0x1000: permission denied` - -The complete error message may look as follows: - -``` -time="2021-12-06T11:23:23Z" level=debug msg="unable to create kernel-style whiteout: operation not permitted" -time="2021-12-06T11:23:23Z" level=debug msg="[graphdriver] trying provided driver \"overlay\"" -time="2021-12-06T11:23:23Z" level=debug msg="overlay: mount_program=/usr/bin/fuse-overlayfs" -Running time 0.01 seconds -Error: unable to get buildah client: unable to create new Buildah instance with mode "native-rootless": unable to get storage: mount /home/build/.local/share/containers/storage/overlay:/home/build/.local/share/containers/storage/overlay, flags: 0x1000: permission denied -time="2021-12-06T11:23:23Z" level=error msg="exit status 1" -``` - -How to fix it: disable AppArmor and seccomp profiles with `--security-opt seccomp=unconfined` and `--security-opt apparmor=unconfined` or add special annotations to a Pod ([details]({{ "usage/build/run_in_containers.html" | true_relative_url }})). - -#### `unshare(CLONE_NEWUSER): Operation not permitted` - -The complete error message may look as follows: - -``` -Error during unshare(CLONE_NEWUSER): Operation not permitted -ERRO[0000] error parsing PID "": strconv.Atoi: parsing "": invalid syntax -ERRO[0000] (unable to determine exit status) -``` - -How to fix it: disable AppArmor and seccomp profiles with `--security-opt seccomp=unconfined` and `--security-opt apparmor=unconfined`, add special annotations to a Pod or use a privileged container ([details]({{ "usage/build/run_in_containers.html" | true_relative_url }})). - -#### `User namespaces are not enabled in /proc/sys/kernel/unprivileged_userns_clone` - -How to fix it: -```bash -# Enable unprivileged user namespaces: -echo 'kernel.unprivileged_userns_clone = 1' | sudo tee -a /etc/sysctl.conf -sudo sysctl -p -``` \ No newline at end of file diff --git a/docs/pages_ru/usage/build/process.md b/docs/pages_ru/usage/build/process.md index bfe1ecd561..9ac2e2c4cb 100644 --- a/docs/pages_ru/usage/build/process.md +++ b/docs/pages_ru/usage/build/process.md @@ -304,65 +304,7 @@ werf converge --repo registry.mydomain.org/repo --synchronization :local > **ЗАМЕЧАНИЕ:** Данный способ подходит лишь в том случае, если в вашей CI/CD системе все запуски werf происходят с одного и того же раннера. -## Настройка сборочного бэкенда - - - -werf поддерживает использование Docker-сервер или Buildah в качестве бекенда для сборки образов. Buildah обеспечивает полноценную работу в контейнерах и послойную сборку Dockerfile'ов с кешированием всех промежуточных слоёв в container registry. Docker-сервер на данный момент является бекэндом, используемым по умолчанию. - -> **ЗАМЕЧАНИЕ:** Сборочный бекэнд Buildah на данный момент не поддерживает хранение образов локально, поддерживается только [хранение образов в container registry](#послойное-кэширование-образов). - -### Docker - -Docker-сервер на данный момент является бекэндом, используемым по умолчанию, и никакая дополнительная настройка не требуется. - -### Buildah - -> **ЗАМЕЧАНИЕ:** На данный момент Buildah доступен только для пользователей Linux и Windows с включённой подсистемой WSL2. Для пользователей macOS предлагается использование виртуальной машины для запуска werf в режиме Buildah. - -Для сборки без Docker-сервера werf использует Buildah в rootless-режиме. Buildah встроен в бинарник werf. Требования к хост-системе для запуска werf с бэкендом Buildah можно найти [в инструкциях по установке](/installation.html). - -Buildah включается установкой переменной окружения `WERF_BUILDAH_MODE` в один из вариантов: `auto`, `native-chroot`, `native-rootless`. Большинству пользователей для включения режима Buildah достаточно установить `WERF_BUILDAH_MODE=auto`. - -#### Уровень изоляции сборки - -По умолчанию в режиме `auto` werf автоматически выбирает уровень изоляции в зависимости от платформы и окружения. - -Поддерживается 2 варианта изоляции сборочных контейнеров: -1. Chroot — вариант без использования container runtime, включается переменной окружения `WERF_BUILDAH_MODE=native-chroot`. -2. Rootless — вариант с использованием container runtime (в системе должен быть установлен crun, или runc, или kata, или runsc), включается переменной окружения `WERF_BUILAH_MODE=native-rootless`. - -#### Драйвер хранилища - -werf может использовать драйвер хранилища `overlay` или `vfs`: - -* `overlay` позволяет использовать файловую систему OverlayFS. Можно использовать либо встроенную в ядро Linux поддержку OverlayFS (если она доступна), либо реализацию fuse-overlayfs. Это рекомендуемый выбор по умолчанию. -* `vfs` обеспечивает доступ к виртуальной файловой системе вместо OverlayFS. Эта файловая система уступает по производительности и требует привилегированного контейнера, поэтому ее не рекомендуется использовать. Однако в некоторых случаях она может пригодиться. - -Как правило, достаточно использовать драйвер по умолчанию (`overlay`). Драйвер хранилища можно задать с помощью переменной окружения `WERF_BUILDAH_STORAGE_DRIVER`. - -#### Ulimits - -По умолчанию Buildah-режим в werf наследует системные ulimits при запуске сборочных контейнеров. Пользователь может переопределить эти параметры с помощью переменной окружения `WERF_BUILDAH_ULIMIT`. - -Формат `WERF_BUILDAH_ULIMIT=type=softlimit[:hardlimit][,type=softlimit[:hardlimit],...]` — конфигурация лимитов, указанные через запятую: -* "core": maximum core dump size (ulimit -c); -* "cpu": maximum CPU time (ulimit -t); -* "data": maximum size of a process's data segment (ulimit -d); -* "fsize": maximum size of new files (ulimit -f); -* "locks": maximum number of file locks (ulimit -x); -* "memlock": maximum amount of locked memory (ulimit -l); -* "msgqueue": maximum amount of data in message queues (ulimit -q); -* "nice": niceness adjustment (nice -n, ulimit -e); -* "nofile": maximum number of open files (ulimit -n); -* "nproc": maximum number of processes (ulimit -u); -* "rss": maximum size of a process's (ulimit -m); -* "rtprio": maximum real-time scheduling priority (ulimit -r); -* "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`: diff --git a/docs/pages_ru/usage/build/run_in_containers.md b/docs/pages_ru/usage/build/run_in_containers.md deleted file mode 100644 index 834ba9bf3c..0000000000 --- a/docs/pages_ru/usage/build/run_in_containers.md +++ /dev/null @@ -1,110 +0,0 @@ ---- -title: Работа в контейнерах -permalink: usage/build/run_in_containers.html ---- - -### Готовые образы - - - -Рекомендуемым вариантом запуска werf в контейнерах является использование официальных образов werf из `registry.werf.io/werf/werf`. Запуск werf в контейнере выглядит следующим образом: - -```shell -docker run \ - --security-opt seccomp=unconfined --security-opt apparmor=unconfined \ - registry.werf.io/werf/werf:1.2-stable WERF_COMMAND -``` - -Если ядро Linux не предоставляет OverlayFS для пользовательского режима без root, то следует использовать fuse-overlayfs: - -```shell -docker run \ - --device /dev/fuse \ - --security-opt seccomp=unconfined --security-opt apparmor=unconfined \ - registry.werf.io/werf/werf:1.2-stable WERF_COMMAND -``` - -Рекомендуется использовать образ `registry.werf.io/werf/werf:1.2-stable`, также доступны следующие образы: -- `registry.werf.io/werf/werf:latest` — алиас для `registry.werf.io/werf/werf:1.2-stable`; -- `registry.werf.io/werf/werf:1.2-{alpha|beta|ea|stable|rock-solid}` — все образы основаны на Alpine, выбираем только канал стабильности; -- `registry.werf.io/werf/werf:1.2-{alpha|beta|ea|stable|rock-solid}-{alpine|ubuntu|fedora}` — выбираем канал стабильности и базовый дистрибутив. - -При использовании этих образов автоматически будет использоваться бэкенд Buildah. Опций для переключения на использование в качестве бекэнда Docker-сервера не предусматривается. - -### Работа через Docker-сервер (не рекомендуется) - -> **ЗАМЕЧАНИЕ:** Для этого метода официальных образов с werf не предоставляется. - -Для использования локального Docker-сервера необходимо примонтировать Docker-сокет в контейнер и использовать привилегированный режим: - -```shell -docker run \ - --privileged \ - --volume $HOME/.werf:/root/.werf \ - --volume /tmp:/tmp \ - --volume /var/run/docker.sock:/var/run/docker.sock \ - IMAGE WERF_COMMAND -``` - -— этот метод поддерживает сборку Dockerfile-образов или stapel-образов. - -Для работы с Docker-сервером по tcp можно использовать следующую команду: - -```shell -docker run --env DOCKER_HOST="tcp://HOST:PORT" IMAGE WERF_COMMAND -``` - -— такой метод поддерживает только сборку Dockerfile-образов. Образы stapel не поддерживаются, поскольку сборщик stapel-образов использует монтирование директорий из хост-системы в сборочные контейнеры. - -### Устранение проблем - - - -#### `fuse: device not found` - -Полностью данная ошибка может выглядеть следующим образом: - -``` -error mounting new container: error mounting build container "53f916e7a334a4bb0d9dbc38a0901718d40b99765002bb7f2f2e5464b1db4294": error creating overlay mount to /home/build/.local/share/containers/storage/overlay/49e856f537ba58afdc09137291133994cd1305e40df72c4fab43077cbd405477/merged, mount_data=",lowerdir=/home/build/.local/share/containers/storage/overlay/l/Z5GEVIFIIQ7H262DYUTX3YOVR6:/home/build/.local/share/containers/storage/overlay/l/PJBBW6UNUNGI37IX6R3LDNPX3J:/home/build/.local/share/containers/storage/overlay/l/MUYSUONLQVE4CJMQVDCH2UBAVQ:/home/build/.local/share/containers/storage/overlay/l/67JHKJDCKBTI4R3Q5S5YG44AD3:/home/build/.local/share/containers/storage/overlay/l/3S72G4SWKDXILGANUOCESP5LDK,upperdir=/home/build/.local/share/containers/storage/overlay/49e856f537ba58afdc09137291133994cd1305e40df72c4fab43077cbd405477/diff,workdir=/home/build/.local/share/containers/storage/overlay/49e856f537ba58afdc09137291133994cd1305e40df72c4fab43077cbd405477/work,volatile": using mount program /usr/bin/fuse-overlayfs: fuse: device not found, try 'modprobe fuse' first -fuse-overlayfs: cannot mount: No such file or directory -: exit status 1 -time="2021-12-06T11:30:20Z" level=error msg="exit status 1" -``` - -Решение: включите fuse device для контейнера, в котором запущен werf ([подробности]({{ "usage/build/run_in_containers.html" | true_relative_url }})).. - -#### `flags: 0x1000: permission denied` - -Полностью данная ошибка может выглядеть следующим образом: - -``` -time="2021-12-06T11:23:23Z" level=debug msg="unable to create kernel-style whiteout: operation not permitted" -time="2021-12-06T11:23:23Z" level=debug msg="[graphdriver] trying provided driver \"overlay\"" -time="2021-12-06T11:23:23Z" level=debug msg="overlay: mount_program=/usr/bin/fuse-overlayfs" -Running time 0.01 seconds -Error: unable to get buildah client: unable to create new Buildah instance with mode "native-rootless": unable to get storage: mount /home/build/.local/share/containers/storage/overlay:/home/build/.local/share/containers/storage/overlay, flags: 0x1000: permission denied -time="2021-12-06T11:23:23Z" level=error msg="exit status 1" -``` - -Решение: отключите профили AppArmor и seccomp с помощью параметров `--security-opt seccomp=unconfined` и `--security-opt apparmor=unconfined`, добавьте специальные аннотации в Pod ([подробности]({{ "usage/build/run_in_containers.html" | true_relative_url }})). - -#### `unshare(CLONE_NEWUSER): Operation not permitted` - -Полностью данная ошибка может выглядеть следующим образом: - -``` -Error during unshare(CLONE_NEWUSER): Operation not permitted -ERRO[0000] error parsing PID "": strconv.Atoi: parsing "": invalid syntax -ERRO[0000] (unable to determine exit status) -``` - -Решение: отключите профили AppArmor и seccomp с помощью параметров `--security-opt seccomp=unconfined` и `--security-opt apparmor=unconfined`, добавьте специальные аннотации в Pod или используйте привилегированный контейнер ([подробности]({{ "usage/build/run_in_containers.html" | true_relative_url }})). - -#### `User namespaces are not enabled in /proc/sys/kernel/unprivileged_userns_clone` - -Решение: -```bash -# Включить непривилегированные user namespaces: -echo 'kernel.unprivileged_userns_clone = 1' | sudo tee -a /etc/sysctl.conf -sudo sysctl -p -```