diff --git a/docs/pages_en/advanced/buildah_mode.md b/docs/pages_en/advanced/buildah_mode.md index a184ccbcad..19e7e8c89e 100644 --- a/docs/pages_en/advanced/buildah_mode.md +++ b/docs/pages_en/advanced/buildah_mode.md @@ -3,32 +3,32 @@ title: Buildah mode permalink: advanced/buildah_mode.html --- -werf currently supports building of images _with docker server_ or _without docker server_ (in experimental mode). This page contains information, which is only applicable for experimental mode _without docker server_. Only dockerfile-images builder is available for this mode for now. Stapel-images builder will be available soon. +werf currently supports building images _with the Docker server_ or _without the Docker server_ (in experimental mode). This page contains information applicable only to the experimental mode _without the Docker server_. For now, only the Dockerfile image builder is available for this mode. The Stapel image builder will be available soon. -In experimental mode _without docker server_ werf uses built-in buildah in rootless mode. +In the experimental mode _without the Docker server_, werf uses built-in Buildah in rootless mode. -## Enable buildah +## Enable Buildah -Buildah is enabled by setting `WERF_BUILDAH_MODE` environment variable to one of the options: `auto`, `native-chroot`, `native-rootless` or `docker-with-fuse`. +Buildah is enabled by setting the `WERF_BUILDAH_MODE` environment variable to one of the following: `auto`, `native-chroot`, `native-rootless` or `docker-with-fuse`. -* `auto` — select mode automatically based on your platform and environment. -* `native-chroot` works only in Linux and uses `chroot` isolation level when running build containers. -* `native-rootless` works only in Linux and uses `rootless` isolation leven when running build containers. In this isolation level werf will use container runtime (runc or crun). -* `docker-with-fuse` is crossplatform mode, and it is the only available choice in MacOS or Windows. +* `auto` — select the mode automatically based on your platform and environment. +* `native-chroot` works only on Linux and uses the `chroot` isolation level when running build containers. +* `native-rootless` works only on Linux and uses the `rootless` isolation level when running build containers. At this isolation level werf will use container runtime (runc or crun). +* `docker-with-fuse` is a cross-platform mode and is the only choice available on MacOS or Windows. -Most users should just set `WERF_BUILDAH_MODE=auto` to enable experimental buildah mode. +Most users only need to set `WERF_BUILDAH_MODE=auto` to enable the experimental Buildah-based mode. ## Storage driver -Werf may use `overlay` or `vfs` storage driver: +werf can use `overlay` or `vfs` storage driver: -* `overlay` enables usage of overlayfs filesystem. Either native linux kernel overlayfs could be used if available or fuse-overlayfs. It is the default and recommended choice. -* `vfs` enables usage of virtual filesystem emulation instead of overlayfs. This filesystem has worse performance and requires privileged container, thus it is not recommended. But it may be required in some cases. +* `overlay` allows you to use the OverlayFS filesystem. You can either use the native Linux kernel's OverlayFS (if available) or fuse-overlayfs. It is the default and recommended choice. +* `vfs` allows you to use a virtual filesystem emulation instead of OverlayFS. This filesystem has worse performance and requires a privileged container, so its use is not recommended. However, it may be required in some cases. -Generally user should just use default `overlay`. Storage driver could be selected with the `WERF_BUILDAH_STORAGE_DRIVER` environment variable. +Normally, the user should just go with the default `overlay` driver. The storage driver can be selected with the `WERF_BUILDAH_STORAGE_DRIVER` environment variable. ### System requirements -Starting with Linux kernel version 5.11 rootless overlayfs is available (technically from 5.13 version, which contains bugfix to enable rootless overlayfs with SELinux, but most major linux distributions has been backported this bugfix to 5.11 kernel). +Rootless OverlayFS is available starting with Linux kernel version 5.11 (strictly speaking, it was initially implemented in version 5.13 via a bugfix to enable rootless overlayFS in SELinux, but most major Linux distributions have backported it into kernel 5.11). -If your kernel does not support rootless overlayfs, then fuse-overlayfs will be used. +If your kernel does not support rootless OverlayFS, fuse-overlayfs will be used. diff --git a/docs/pages_en/advanced/ci_cd/run_in_container/how_it_works.md b/docs/pages_en/advanced/ci_cd/run_in_container/how_it_works.md index cd53a0df4e..b38210d18d 100644 --- a/docs/pages_en/advanced/ci_cd/run_in_container/how_it_works.md +++ b/docs/pages_en/advanced/ci_cd/run_in_container/how_it_works.md @@ -3,40 +3,40 @@ title: How it works permalink: advanced/ci_cd/run_in_container/how_it_works.html --- -werf currently supports building of images _with docker server_ or _without docker server_ (in experimental mode). This page contains information, which is only applicable for experimental mode _without docker server_. Only dockerfile-images builder is available for this mode for now. Stapel-images builder will be available soon. +werf currently supports building images _with the Docker server_ or _without the Docker server_ (in experimental mode). This page contains information applicable only to the experimental mode _without the Docker server_. For now, only the Dockerfile image builder is available for this mode. The Stapel image builder will be available soon. -General info how to enable buildah in werf is available at [buildah mode page]({{ "/advanced/buildah_mode.html" | true_relative_url }}). +General info on how to enable Buildah in werf is available on the [Buildah mode page]({{ "/advanced/buildah_mode.html" | true_relative_url }}). ## Modes of operation -Depending on user system conformance with [buildah mode system requirements]({{ "/advanced/buildah_mode.html#system-requirements" | true_relative_url }}) and depending on user needs there are 3 ways to use werf with buildah inside containers: +Depending on whether the user's system meets the [Buildah mode system requirements]({{ "/advanced/buildah_mode.html#system-requirements" | true_relative_url }}) and depending on the user needs, there are 3 ways to use werf with Buildah inside containers: -1. Use [Linux kernel with rootless overlayfs]({{ "/advanced/buildah_mode.html#system-requirements" | true_relative_url }}). -2. Use [Linux kernel without rootless overlayfs]({{ "/advanced/buildah_mode.html#system-requirements" | true_relative_url }}) and privileged container. -3. Use [Linux kernel without rootless overlayfs]({{ "/advanced/buildah_mode.html#system-requirements" | true_relative_url }}) and non-privileged container with additional settings. +1. Use [Linux kernel with rootless OverlayFS]({{ "/advanced/buildah_mode.html#system-requirements" | true_relative_url }}). +2. Use [Linux kernel without rootless OverlayFS]({{ "/advanced/buildah_mode.html#system-requirements" | true_relative_url }}) and a privileged container. +3. Use [Linux kernel without rootless OverlayFS]({{ "/advanced/buildah_mode.html#system-requirements" | true_relative_url }}) and an unprivileged container with additional settings. -### Linux kernel with rootless overlayfs +### Linux kernel with rootless OverlayFS -This way you only required to **disable apparmor** and **seccomp** profiles in a container which runs werf. +In this case, you only need to **disable the AppArmor** and **seccomp** profiles in the container where werf is running. -### Linux kernel without rootless overlayfs and privileged container +### Linux kernel without rootless OverlayFS and privileged container -In the case your Linux kernel does not have [rootless overlayfs]({{ "/advanced/buildah_mode.html#system-requirements" | true_relative_url }}), buildah and werf uses fuse-overlayfs instead. +If your Linux kernel does not have [rootless OverlayFS]({{ "/advanced/buildah_mode.html#system-requirements" | true_relative_url }}), Buildah and werf will use fuse-overlayfs instead. -To enable usage of fuse-overlayfs in such case using a **privileged container** to run werf is one option. +One of the options in this case is to run werf in a **privileged container** to enable fuse-overlayfs. -### Linux kernel without rootless overlayfs and non-privileged container +### Linux kernel without rootless OverlayFS and non-privileged container -In the case your Linux kernel does not have [rootless overlayfs]({{ "/advanced/buildah_mode.html#system-requirements" | true_relative_url }}), buildah and werf uses fuse-overlayfs instead. +If your Linux kernel does not support [OverlayFS in the rootless mode]({{ "/advanced/buildah_mode.html#system-requirements" | true_relative_url }}), Buildah and werf will use fuse-overlayfs instead. -To enable usage of fuse-overlayfs in such case without using a privileged container, run werf in a container with the following options: +To use fuse-overlayfs without a privileged container, run werf in a container with the following parameters: -1. **Disabled apparmor** and **seccomp** profiles . -2. Enabled `/dev/fuse` device. +1. The **AppArmor** and **seccomp** profiles are **disabled**. +2. The `/dev/fuse` device is enabled. ## Available werf images -Following images are provided with builtin werf. Each image will be updated through the same release process as used in the trdl package manager, [more info about release channels]({{ "installation.html#all-changes-in-werf-go-through-all-release-channels" | true_relative_url }}). +Below is a list of images with built-in werf. Each image is updated as part of a release process based on the trdl package manager ([learn more about the release channels]({{ "installation.html#all-changes-in-werf-go-through-all-release-channels" | true_relative_url }}). * `ghcr.io/werf/werf:latest` -> `ghcr.io/werf/werf:1.2-stable`; * `ghcr.io/werf/werf:1.2-alpha` -> `ghcr.io/werf/werf:1.2-alpha-alpine`; @@ -64,7 +64,7 @@ Following images are provided with builtin werf. Each image will be updated thro ### `fuse: device not found` -Full error may look like: +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 @@ -73,11 +73,11 @@ fuse-overlayfs: cannot mount: No such file or directory time="2021-12-06T11:30:20Z" level=error msg="exit status 1" ``` -Solution: enable fuse device for a container which runs werf, [more info](#linux-kernel-without-rootless-overlayfs-and-non-privileged-container). +Solution: enable the fuse device for the container in which werf is running ([details](#linux-kernel-without-rootless-overlayfs-and-non-privileged-container)). ### `flags: 0x1000: permission denied` -Full error may look like: +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" @@ -88,11 +88,11 @@ Error: unable to get buildah client: unable to create new Buildah instance with time="2021-12-06T11:23:23Z" level=error msg="exit status 1" ``` -Solution: disable apparmor and seccomp profiles with options like `--security-opt seccomp=unconfined` and `--security-opt apparmor=unconfined` or by setting special annotations in a Pod, [more info](#linux-kernel-without-rootless-overlayfs-and-non-privileged-container) +Solution: disable AppArmor and seccomp profiles with `--security-opt seccomp=unconfined` and `--security-opt apparmor=unconfined` or add special annotations to a Pod ([details](#linux-kernel-without-rootless-overlayfs-and-non-privileged-container)). ### `unshare(CLONE_NEWUSER): Operation not permitted` -Full error may look like: +The complete error message may look as follows: ``` Error during unshare(CLONE_NEWUSER): Operation not permitted @@ -100,4 +100,4 @@ ERRO[0000] error parsing PID "": strconv.Atoi: parsing "": invalid syntax ERRO[0000] (unable to determine exit status) ``` -Solution: disable apparmor and seccomp profiles with options like `--security-opt seccomp=unconfined` and `--security-opt apparmor=unconfined` or by setting special annotations in a Pod, or use a privileged container, [more info](#modes-of-operation). +Solution: 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](#modes-of-operation)). diff --git a/docs/pages_en/advanced/ci_cd/run_in_container/use_docker_container.md b/docs/pages_en/advanced/ci_cd/run_in_container/use_docker_container.md index 324912f079..1b45de8435 100644 --- a/docs/pages_en/advanced/ci_cd/run_in_container/use_docker_container.md +++ b/docs/pages_en/advanced/ci_cd/run_in_container/use_docker_container.md @@ -1,21 +1,21 @@ --- -title: Use docker container +title: Use Docker container permalink: advanced/ci_cd/run_in_container/use_docker_container.html --- -> NOTICE: werf currently supports building of images with connection to the docker-server or without connection docker-server (in experimental mode). Building of images without docker-server is available in experimental mode for now and it is the only recommended way. +> NOTICE: werf currently supports building images _with the Docker server_ or _without the Docker server_ (in experimental mode). Building images without the Docker server is still experimental, however, it is the only recommended mode. -## Build images without docker server (NEW!) +## Build images without the Docker server (NEW!) -> NOTICE: Only dockerfile-images builder is available for this type of build for now. Stapel-images builder will be available soon. +> NOTICE: For now, only the Dockerfile image builder is available for this type of builds. The Stapel image builder will be available soon. -There is official image with werf 1.2 for this method (1.1 is not supported): `ghcr.io/werf/werf`. +There is an official image with werf 1.2 for this method (1.1 is not supported): `ghcr.io/werf/werf`. -Select and proceed with one of the [available modes of operation]({{ "advanced/ci_cd/run_in_container/how_it_works.html#modes-of-operation" | true_relative_url }}). +Select one of the [available operating modes]({{ "advanced/ci_cd/run_in_container/how_it_works.html#modes-of-operation" | true_relative_url }}). -### Linux kernel with rootless overlayfs +### Linux kernel with rootless OverlayFS -Only disable seccomp and apparmor profiles in such case. Example command: +In this case, you only need to disable the seccomp and AppArmor profiles. Below is an example of a command that does this: ```shell docker run \ @@ -23,9 +23,9 @@ docker run \ ghcr.io/werf/werf:latest WERF_COMMAND ``` -### Linux kernel without rootless overlayfs and privileged container +### Linux kernel without rootless OverlayFS and privileged container -Just use privileged container in such case. Example command: +In this case, just use the privileged container. Below is an example of a command that does this: ```shell docker run \ @@ -33,9 +33,9 @@ docker run \ ghcr.io/werf/werf:latest WERF_COMMAND ``` -### Linux kernel without rootless overlayfs and non-privileged container +### Linux kernel without rootless OverlayFS and non-privileged container -Disable seccomp and apparmor profiles and enable `/dev/fuse` in the container (so that `fuse-overlayfs` could work) in such case. Example command: +In this case, disable the seccomp and AppArmor profiles and enable `/dev/fuse` in the container (so that `fuse-overlayfs` can work). Below is an example of a command that does this: ```shell docker run \ @@ -44,13 +44,13 @@ docker run \ ghcr.io/werf/werf:latest WERF_COMMAND ``` -## Build images with docker server (not recommended) +## Build images with the Docker server (not recommended) -### Local docker server +### Local Docker server -This method supports building of dockerfile-images or stapel-images. +This method supports building Dockerfile images or Stapel images. -Example command: +Below is an example of a command that does this: ```shell docker run \ @@ -61,17 +61,17 @@ docker run \ IMAGE WERF_COMMAND ``` -Build your own docker image with werf for this method. +For this method, build your own Docker image using werf. -### Remote docker server +### Remote Docker server -This method supports only building of dockerfile-images. Stapel-images is not supported, because stapel images builder use mounts from host system into docker images. +This method only supports building Dockerfile images. Stapel images are not supported because the Stapel image builder uses mounts from the host system to Docker images. -The easiest way to use remote docker server inside docker container is docker-in-docker (dind). +The easiest way to use a remote Docker server inside a Docker container is Docker-in-Docker (dind). -Build your own docker image based on `docker:dind` for this method. +For this method, build your own image based on `docker:dind`. -Example command: +Below is an example of a command: ```shell docker run \ @@ -83,4 +83,4 @@ Build your own docker image with werf for this method. ## Troubleshooting -If you have any problems please refer to the [troubleshooting section]({{ "advanced/ci_cd/run_in_container/how_it_works.html#troubleshooting" | true_relative_url }}) +In case of problems, refer to the [troubleshooting section]({{ "advanced/ci_cd/run_in_container/how_it_works.html#troubleshooting" | true_relative_url }}) diff --git a/docs/pages_en/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_docker_executor.md b/docs/pages_en/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_docker_executor.md index 4be99a8c7b..256646580f 100644 --- a/docs/pages_en/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_docker_executor.md +++ b/docs/pages_en/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_docker_executor.md @@ -1,15 +1,15 @@ --- -title: Use Gitlab CI/CD with docker executor +title: Use Gitlab CI/CD with Docker executor permalink: advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_docker_executor.html --- -> NOTICE: werf currently supports building of images _with docker server_ or _without docker server_ (in experimental mode). This page contains instructions, which are only applicable for experimental mode _without docker server_. Only dockerfile-images builder is available for this mode for now. Stapel-images builder will be available soon. +> NOTICE: werf currently supports building images _with the Docker server_ or _without the Docker server_ (in experimental mode). This page contains information applicable only to the experimental mode _without the Docker server_. For now, only the Dockerfile image builder is available for this mode. The Stapel image builder will be available soon. -## 1. Setup kubernetes gitlab runner +## 1. Configure GitLab rinner for Kubernetes -Select and proceed with one of the [available modes of operation]({{ "advanced/ci_cd/run_in_container/how_it_works.html#modes-of-operation" | true_relative_url }}), depending on your gitlab runner capabilities. +Select one of the [available operating modes]({{ "advanced/ci_cd/run_in_container/how_it_works.html#modes-of-operation" | true_relative_url }}) (depending on the capabilities of your GitLab runner) and navigate to it. -### Linux kernel with rootless overlayfs +### Linux kernel with rootless OverlayFS Basic runner configuration: @@ -23,7 +23,7 @@ Basic runner configuration: ... ``` -### Linux kernel without rootless overlayfs and privileged container +### Linux kernel without rootless OverlayFS and privileged container Basic runner configuration: @@ -37,7 +37,7 @@ Basic runner configuration: ... ``` -### Linux kernel without rootless overlayfs and non-privileged container +### Linux kernel without rootless OverlayFS and non-privileged container Basic runner configuration: @@ -52,13 +52,13 @@ Basic runner configuration: ... ``` -## 2. Setup access for kubernetes cluster +## 2. Configure access to the Kubernetes cluster -Setup `WERF_KUBECONFIG_BASE64` secret environment variable in gitlab project with the content of `~/.kube/config` in base64 encoding. werf will automatically use this configuration to connect to the kubernetes cluster. +Assign the `WERF_KUBECONFIG_BASE64` environment variable in the GitLab project a base64-encoded value from `~/.kube/config`. werf will automatically use this configuration to connect to the Kubernetes cluster. -## 3. Configure project gitlab-ci.yml +## 3. Configure gitlab-ci.yml of the project -Basic build and deploy job for a project: +Below is a basic build and deploy job for a project: ```yaml stages: @@ -75,4 +75,4 @@ Build and deploy application: ## Troubleshooting -If you have any problems please refer to the [troubleshooting section]({{ "advanced/ci_cd/run_in_container/how_it_works.html#troubleshooting" | true_relative_url }}) +In case of problems, refer to the [Troubleshooting section]({{ "advanced/ci_cd/run_in_container/how_it_works.html#troubleshooting" | true_relative_url }}) diff --git a/docs/pages_en/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_kubernetes_executor.md b/docs/pages_en/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_kubernetes_executor.md index b07f604a63..8eab924d89 100644 --- a/docs/pages_en/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_kubernetes_executor.md +++ b/docs/pages_en/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_kubernetes_executor.md @@ -1,25 +1,25 @@ --- -title: Use Gitlab CI/CD with kubernetes executor +title: Use GitLab CI/CD with Kubernetes executor permalink: advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_kubernetes_executor.html --- -> NOTICE: werf currently supports building of images _with docker server_ or _without docker server_ (in experimental mode). This page contains instructions, which are only applicable for experimental mode _without docker server_. Only dockerfile-images builder is available for this mode for now. Stapel-images builder will be available soon. +> NOTICE: werf currently supports building images _with the Docker server_ or _without the Docker server_ (in experimental mode). This page contains information applicable only to the experimental mode _without the Docker server_. For now, only the Dockerfile image builder is available for this mode. The Stapel image builder will be available soon. -## 1. Prepare kubernetes cluster +## 1. Prepare the Kubernetes cluster -Select and proceed with one of the [available modes of operation]({{ "advanced/ci_cd/run_in_container/how_it_works.html#modes-of-operation" | true_relative_url }}). +Select one of the [available operating modes]({{ "advanced/ci_cd/run_in_container/how_it_works.html#modes-of-operation" | true_relative_url }}). -### Linux kernel with rootless overlayfs +### Linux kernel with rootless OverlayFS -No actions needed. +No additional actions are required. -### Linux kernel without rootless overlayfs and privileged container +### Linux kernel without rootless OverlayFS and privileged container -No actions needed. +No additional actions are required. -### Linux kernel without rootless overlayfs and non-privileged container +### Linux kernel without rootless OverlayFS and non-privileged container -[Fuse device plugin](https://github.com/kuberenetes-learning-group/fuse-device-plugin) needed to enable `/dev/fuse` device in containers running werf: +The [fuse device plugin](https://github.com/kuberenetes-learning-group/fuse-device-plugin) is one of the ways to enable the `/dev/fuse` device in containers with werf: ``` # werf-fuse-device-plugin-ds.yaml @@ -53,13 +53,13 @@ spec: path: /var/lib/kubelet/device-plugins ``` -Apply provided device plugin in the `kube-system` namespace: +Apply the above plugin manifest to the `kube-system` namespace: ``` kubectl -n kube-system apply -f werf-fuse-device-plugin-ds.yaml ``` -Also let's define a limit range so that Pods created in some namespace will have an access to the `/dev/fuse`: +Let's also create a LimitRange policy so that Pods created in some namespace have access to `/dev/fuse`: ``` # enable-fuse-limit-range.yaml @@ -74,18 +74,18 @@ spec: github.com/fuse: 1 ``` -Create namespace `gitlab-ci` and limit range in this namespace (later we will setup gitlab-runner to use this namespace when creating Pods to run ci-jobs): +Create a `gitlab-ci` namespace and apply the LimitRange manifest in that namespace (we will later configure the GitLab runner to use that namespace when creating Pods for running CI jobs): ``` kubectl create namespace gitlab-ci kubectl apply -f enable-fuse-pod-limit-range.yaml ``` -## 2. Setup kubernetes gitlab runner +## 2. Setup the GitLab runner in Kubernetes Select and proceed with one of the [available modes of operation]({{ "advanced/ci_cd/run_in_container/how_it_works.html#modes-of-operation" | true_relative_url }}). -### Linux kernel with rootless overlayfs +### Linux kernel with rootless OverlayFS Basic runner configuration (`/etc/gitlab-runner/config.toml`): @@ -99,9 +99,9 @@ Basic runner configuration (`/etc/gitlab-runner/config.toml`): pod_annotations = ["container.apparmor.security.beta.kubernetes.io/werf-converge=unconfined"] ``` -For more options consult [gitlab kubernetes executor documentation page](https://docs.gitlab.com/runner/executors/kubernetes.html). +For more options, consult the [Kubernetes executor for GitLab runner documentation](https://docs.gitlab.com/runner/executors/kubernetes.html). -### Linux kernel without rootless overlayfs and privileged container +### Linux kernel without rootless OverlayFS and privileged container Basic runner configuration (`/etc/gitlab-runner/config.toml`): @@ -115,9 +115,9 @@ Basic runner configuration (`/etc/gitlab-runner/config.toml`): privileged = true ``` -For more options consult [gitlab kubernetes executor documentation page](https://docs.gitlab.com/runner/executors/kubernetes.html). +For more options, consult the [Kubernetes executor for GitLab runner documentation](https://docs.gitlab.com/runner/executors/kubernetes.html). -### Linux kernel without rootless overlayfs and non-privileged container +### Linux kernel without rootless OverlayFS and non-privileged container Basic runner configuration (`/etc/gitlab-runner/config.toml`): @@ -132,20 +132,20 @@ Basic runner configuration (`/etc/gitlab-runner/config.toml`): pod_annotations = ["container.apparmor.security.beta.kubernetes.io/werf-converge=unconfined"] ``` -Note that `gitlab-ci` namespace has been specified. The same namespace should be used as in the step 1 to create auto pod limit settings. +Note that the `gitlab-ci` namespace has been specified. This namespace should be the same as in step 1 to automatically generate Pod limits. -For more options consult [gitlab kubernetes executor documentation page](https://docs.gitlab.com/runner/executors/kubernetes.html). +For more options, consult the [Kubernetes executor for GitLab runner documentation](https://docs.gitlab.com/runner/executors/kubernetes.html). -## 3. Configure project access to target kubernetes cluster +## 3. Configure project access to the target Kubernetes cluster -There are 2 ways to access kubernetes cluster which is the target cluster to deploy your application into: +There are 2 ways to access the target Kubernetes cluster to which the application is deployed: -1. Using special service account from kubernetes executor. This method only suitable when kubernetes executor runs in the target kubernetes cluster. -2. Using configured kube config. +1. Using Service Account for the Kubenetes executor. This method is only suitable if the Kubernetes executor is running in the target Kubernetes cluster. +2. Using kubeconfig with the appropriate settings. -### Service account +### Service Account -Example service account configuration named `gitlab-kubernetes-runner-deploy`: +Here is an example configuration of a Service Account named `gitlab-kubernetes-runner-deploy`: ```yaml apiVersion: v1 @@ -167,7 +167,7 @@ subjects: namespace: default ``` -Adjust gitlab-runner configuration (`/etc/gitlab-runner/config.toml`) to use this service account: +Adjust the GitLab runner configuration (`/etc/gitlab-runner/config.toml`) to use this Service Account: ```toml [[runners]] @@ -178,15 +178,15 @@ Adjust gitlab-runner configuration (`/etc/gitlab-runner/config.toml`) to use thi ... ``` -### Kube config +### Kubeconfig -Setup `WERF_KUBECONFIG_BASE64` secret environment variable in gitlab project with the content of `~/.kube/config` in base64 encoding. werf will automatically use this configuration to connect to the kubernetes cluster which is the target for application. +Assign the base64-encoded contents of `~/.kube/config` to the `WERF_KUBECONFIG_BASE64` environment variable in the GitLab project. werf will automatically use this configuration to connect to the target Kubernetes cluster. -This method is suitable when kubernetes executor and target kubernetes cluster are 2 different clusters. +This method is appropriate when the Kubernetes executor and the target Kubernetes cluster are two different clusters. -## 4. Configure project gitlab-ci.yml +## 4. Configure gitlab-ci.yml of the project -Basic build and deploy job for a project: +Below is a description of the basic build and deploy job for a project: ```yaml stages: @@ -203,4 +203,4 @@ Build and deploy application: ## Troubleshooting -If you have any problems please refer to the [troubleshooting section]({{ "advanced/ci_cd/run_in_container/how_it_works.html#troubleshooting" | true_relative_url }}) +In case of problems, refer to the [Troubleshooting section]({{ "advanced/ci_cd/run_in_container/how_it_works.html#troubleshooting" | true_relative_url }}) diff --git a/docs/pages_en/advanced/ci_cd/run_in_container/use_kubernetes.md b/docs/pages_en/advanced/ci_cd/run_in_container/use_kubernetes.md index e7d51e7db0..239333c81b 100644 --- a/docs/pages_en/advanced/ci_cd/run_in_container/use_kubernetes.md +++ b/docs/pages_en/advanced/ci_cd/run_in_container/use_kubernetes.md @@ -1,25 +1,25 @@ --- -title: Use kubernetes +title: Use Kubernetes permalink: advanced/ci_cd/run_in_container/use_kubernetes.html --- -> NOTICE: werf currently supports building of images _with docker server_ or _without docker server_ (in experimental mode). This page contains instructions, which are only applicable for experimental mode _without docker server_. Only dockerfile-images builder is available for this mode for now. Stapel-images builder will be available soon. +> NOTICE: werf currently supports building images _with the Docker server_ or _without the Docker server_ (in experimental mode). This page contains information applicable only to the experimental mode _without the Docker server_. For now, only the Dockerfile image builder is available for this mode. The Stapel image builder will be available soon. -## 1. Prepare kubernetes cluster +## 1. Prepare the Kubernetes cluster -Select and proceed with one of the [available modes of operation]({{ "advanced/ci_cd/run_in_container/how_it_works.html#modes-of-operation" | true_relative_url }}). +Select one of the [available operating modes]({{ "advanced/ci_cd/run_in_container/how_it_works.html#modes-of-operation" | true_relative_url }}) and navigate to it. -### Linux kernel with rootless overlayfs +### Linux kernel with rootless OverlayFS -No actions needed. +No additional actions are required. -### Linux kernel without rootless overlayfs and privileged container +### Linux kernel without rootless OverlayFS and privileged container -No actions needed. +No additional actions are required. -### Linux kernel without rootless overlayfs and non-privileged container +### Linux kernel without rootless OverlayFS and non-privileged container -[Fuse device plugin](https://github.com/kuberenetes-learning-group/fuse-device-plugin) needed to enable `/dev/fuse` device in containers running werf: +The [fuse device plugin](https://github.com/kuberenetes-learning-group/fuse-device-plugin) is required to enable the `/dev/fuse` device in werf containers: ``` # werf-fuse-device-plugin-ds.yaml @@ -53,15 +53,15 @@ spec: path: /var/lib/kubelet/device-plugins ``` -Apply provided device plugin in the `kube-system` namespace: +Apply the above plugin manifest to the `kube-system` namespace: ``` kubectl -n kube-system apply -f werf-fuse-device-plugin-ds.yaml ``` -## 2. Configure access to container registry +## 2. Configure access to the container registry -Prepare base64 docker config to access your registry. +Prepare the Docker configuration in base64 format to access the registry. ```yaml # registrysecret.yaml @@ -74,7 +74,7 @@ data: type: kubernetes.io/dockerconfigjson ``` -Create `registrysecret` in the target application namespace: +Create the `registrysecret` in the application namespace: ```shell kubectl -n quickstart-application apply -f registrysecret.yaml @@ -82,7 +82,7 @@ kubectl -n quickstart-application apply -f registrysecret.yaml ## 3. Configure service account for werf -werf need a service account to access kubernetes cluster when deploying application. +A service account is needed for werf to access the Kubernetes cluster when deploying the application. ```yaml # werf-service-account.yaml @@ -106,19 +106,19 @@ subjects: namespace: quickstart-application ``` -Create described special service account `werf` with `cluster-admin` role in the target application namespace: +Create the `werf` service account described above with the `cluster-admin` role in the target application namespace: ```shell kubectl -n quickstart-application apply -f werf-service-account.yaml ``` -## 4. Perform application deployment +## 4. Deploy the application -Select and proceed with one of the [available modes of operation]({{ "advanced/ci_cd/run_in_container/how_it_works.html#modes-of-operation" | true_relative_url }}). +Select one of the [available operating modes]({{ "advanced/ci_cd/run_in_container/how_it_works.html#modes-of-operation" | true_relative_url }}) and navigate to it. -### Linux kernel with rootless overlayfs +### Linux kernel with rootless OverlayFS -werf converge command will run in the one-shot Pod. Note that `CONTAINER_REGISTRY_REPO` should be replaced with real address of container registry repo, for which there is `registrysecret` configured in the previous step. +The werf converge command will be executed in a special Pod. Note that `CONTAINER_REGISTRY_REPO` must be replaced with the real address of the container registry repo for which we configured `registrysecret` at the previous step. ```yaml # werf-converge.yaml @@ -159,16 +159,16 @@ spec: path: config.json ``` -Create pod and perform application deployment in the target namespace: +Create a Pod and deploy the application to the target namespace: ```shell kubectl -n quickstart-application apply -f werf-converge.yaml kubectl -n quickstart-application logs -f werf-converge ``` -### Linux kernel without rootless overlayfs and privileged container +### Linux kernel without rootless OverlayFS and privileged container -werf converge command will run in the one-shot Pod. Note that `CONTAINER_REGISTRY_REPO` should be replaced with real address of container registry repo, for which there is `registrysecret` configured in the previous step. +The werf converge command will be executed in a special Pod. Note that `CONTAINER_REGISTRY_REPO` must be replaced with the real address of the container registry repo for which we configured `registrysecret` at the previous step. ```yaml # werf-converge.yaml @@ -216,9 +216,9 @@ kubectl -n quickstart-application apply -f werf-converge.yaml kubectl -n quickstart-application logs -f werf-converge ``` -### Linux kernel without rootless overlayfs and non-privileged container +### Linux kernel without rootless OverlayFS and non-privileged container -werf converge command will run in the one-shot Pod. Note that `CONTAINER_REGISTRY_REPO` should be replaced with real address of container registry repo, for which there is `registrysecret` configured in the previous step. +The werf converge command will be executed in a special Pod. Note that `CONTAINER_REGISTRY_REPO` must be replaced with the real address of the container registry repo for which we configured `registrysecret` at the previous step. ```yaml # werf-converge.yaml @@ -271,4 +271,4 @@ kubectl -n quickstart-application logs -f werf-converge ## Troubleshooting -If you have any problems please refer to the [troubleshooting section]({{ "advanced/ci_cd/run_in_container/how_it_works.html#troubleshooting" | true_relative_url }}) +In case of problems, refer to the [Troubleshooting section]({{ "advanced/ci_cd/run_in_container/how_it_works.html#troubleshooting" | true_relative_url }}) diff --git a/docs/pages_en/internals/build_process.md b/docs/pages_en/internals/build_process.md index 981fca593f..a6f475df4f 100644 --- a/docs/pages_en/internals/build_process.md +++ b/docs/pages_en/internals/build_process.md @@ -129,8 +129,8 @@ After building a tree of image dependencies, werf splits the assembly process in ## Buildah -Werf supports usage of buildah in experimental mode to build images. In this mode only dockerfile-images are supported for now (stapel support is planned). +werf supports using Buildah in experimental mode to build images. Only Dockerfile images are supported in this mode for now (we plan to add Stapel support soon). -In this mode overall build process remains the same, only backend containers engine and storage changed from docker-server to buildah. +In this mode, the overall build process remains the same, only the backend container engine and storage are switched from docker-server to buildah. -More information about buildah is available in the [buildah mode article]({{ "/advanced/buildah_mode.html" | true_relative_url }}) +For more information about Buildah, see the [Buildah mode article]({{ "/advanced/buildah_mode.html" | true_relative_url }}) diff --git a/docs/pages_ru/advanced/buildah_mode.md b/docs/pages_ru/advanced/buildah_mode.md new file mode 100644 index 0000000000..7c3ae95fac --- /dev/null +++ b/docs/pages_ru/advanced/buildah_mode.md @@ -0,0 +1,34 @@ +--- +title: Режим сборки с использованием Buildah +permalink: advanced/buildah_mode.html +--- + +В настоящее время werf поддерживает сборку образов с _использованием Docker-сервера_ или _без его использования_ (в экспериментальном режиме). Эта страница содержит сведения, которые применимы только для экспериментального режима _без Docker-сервера_. На данный момент для этого типа сборки доступен только сборщик образов на основе Dockerfile'ов. Сборщик Stapel будет доступен через некоторое время. + +В экспериментальном режиме _без Docker-сервера_ werf использует встроенный Buildah в rootless-режиме. + +## Включение Buildah + +Buildah включается установкой переменной окружения `WERF_BUILDAH_MODE` в один из вариантов: `auto`, `native-chroot`, `native-rootless` или `docker-with-fuse`. + +* `auto` — автоматический выбор режима в зависимости от платформы и окружения; +* `native-chroot` работает только в Linux и использует `chroot`-изоляцию для сборочных контейнеров; +* `native-rootless` работает только в Linux и использует `rootless`-изоляцию для сборочных контейнеров. На этом уровне изоляции werf использует среду выполнения сборочных операций в контейнерах (runc или crun). +* `docker-with-fuse` — только этот кроссплатформенный режим доступен для MacOS или Windows. + +Большинству пользователей для включения экспериментального режима Buildah достаточно установить `WERF_BUILDAH_MODE=auto`. + +## Драйвер хранилища + +werf может использовать драйвер хранилища `overlay` или `vfs`: + +* `overlay` позволяет использовать файловую систему OverlayFS. Можно использовать либо встроенную в ядро Linux поддержку OverlayFS (если она доступна), либо реализацию fuse-overlayfs. Это рекомендуемый выбор по умолчанию. +* `vfs` обеспечивает доступ к виртуальной файловой системе вместо OverlayFS. Эта файловая система уступает по производительности и требует привилегированного контейнера, поэтому ее не рекомендуется использовать. Однако в некоторых случаях она может пригодиться. + +Как правило, достаточно использовать драйвер по умолчанию (`overlay`). Драйвер хранилища можно задать с помощью переменной окружения `WERF_BUILDAH_STORAGE_DRIVER`. + +### Системные требования + +Rootless-файловая система OverlayFS доступна, начиная с ядра Linux версии 5.11 (строго говоря, с версии 5.13, которая содержит багфикс для включения rootless OverlayFS в SELinux, но большинство основных дистрибутивов Linux бэкпортировали его в ядро 5.11). + +Если ваше ядро не поддерживает OverlayFS в режиме rootless, будет использоваться fuse-overlayfs. diff --git a/docs/pages_ru/advanced/ci_cd/run_in_container/how_it_works.md b/docs/pages_ru/advanced/ci_cd/run_in_container/how_it_works.md new file mode 100644 index 0000000000..e7aa927aa0 --- /dev/null +++ b/docs/pages_ru/advanced/ci_cd/run_in_container/how_it_works.md @@ -0,0 +1,103 @@ +--- +title: Принципы работы +permalink: advanced/ci_cd/run_in_container/how_it_works.html +--- + +ПРИМЕЧАНИЕ: в настоящее время werf поддерживает сборку образов с _использованием Docker-сервера_ или _без его использования_ (в экспериментальном режиме). Информация на данной странице применима только к экспериментальному режиму _без использования Docker-сервера_. Пока для этого режима доступен только сборщик образов на основе Dockerfile'ов. Сборщик Stapel будет доступен через некоторое время. + +Общая информация о том, как включить Buildah в werf, доступна на странице [режима сборки с использованием Buildah]({{ "/advanced/buildah_mode.html" | true_relative_url }}). + +## Режимы работы + +В зависимости от соответствия системы пользователя [требованиям режима Buildah]({{ "/advanced/buildah_mode.html#системные-требования" | true_relative_url }}) и в зависимости от потребностей пользователя существует 3 способа использования werf с Buildah внутри контейнеров: + +1. Использовать [ядро Linux с поддержкой OverlayFS в режиме rootless]({{ "/advanced/buildah_mode.html#системные-требования" | true_relative_url }}). +2. Использовать [ядро Linux без поддержки OverlayFS в режиме rootless]({{ "/advanced/buildah_mode.html#системные-требования" | true_relative_url }}) и привилегированный контейнер. +3. Использовать [ядро Linux без поддержки OverlayFS в режиме rootless]({{ "/advanced/buildah_mode.html#системные-требования" | true_relative_url }}) и непривилегированный контейнер с дополнительными настройками. + +### Ядро Linux с поддержкой OverlayFS в режиме rootless + +В данном случае необходимо только **отключить** профили **seccomp** и **AppArmor** в контейнере с werf. + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование привилегированного контейнера + +В случае, если ваше ядро Linux не поддерживает [OverlayFS в режиме rootless]({{ "/advanced/buildah_mode.html#системные-требования" | true_relative_url }}), Buildah и werf вместо нее будут использовать fuse-overlayfs. + +Чтобы использовать fuse-overlayfs, можно воспользоваться **привилегированным контейнером** для запуска werf. + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование непривилегированного контейнера + +В случае, если ваше ядро Linux не поддерживает [OverlayFS в режиме rootless]({{ "/advanced/buildah_mode.html#системные-требования" | true_relative_url }}), Buildah и werf вместо нее будут использовать fuse-overlayfs. + +Чтобы воспользоваться fuse-overlayfs без привилегированного контейнера, запустите werf в контейнере со следующими параметрами: + +1. **Отключены** профили **seccomp** и **AppArmor**. +2. Включено устройство `/dev/fuse`. + +## Доступные образы werf + +Ниже приведен список образов со встроенной утилитой werf. Каждый образ обновляется в рамках релизного процесса, основанного на менеджере пакетов trdl ([подробнее о каналах обновлений]({{ "installation.html#все-изменения-в-werf-проходят-через-цепочку-каналов-обновлений" | true_relative_url }})). + +* `ghcr.io/werf/werf:latest` -> `ghcr.io/werf/werf:1.2-stable`; +* `ghcr.io/werf/werf:1.2-alpha` -> `ghcr.io/werf/werf:1.2-alpha-alpine`; +* `ghcr.io/werf/werf:1.2-beta` -> `ghcr.io/werf/werf:1.2-beta-alpine`; +* `ghcr.io/werf/werf:1.2-ea` -> `ghcr.io/werf/werf:1.2-ea-alpine`; +* `ghcr.io/werf/werf:1.2-stable` -> `ghcr.io/werf/werf:1.2-stable-alpine`; +* `ghcr.io/werf/werf:1.2-alpha-alpine`; +* `ghcr.io/werf/werf:1.2-beta-alpine`; +* `ghcr.io/werf/werf:1.2-ea-alpine`; +* `ghcr.io/werf/werf:1.2-stable-alpine`; +* `ghcr.io/werf/werf:1.2-alpha-ubuntu`; +* `ghcr.io/werf/werf:1.2-beta-ubuntu`; +* `ghcr.io/werf/werf:1.2-ea-ubuntu`; +* `ghcr.io/werf/werf:1.2-stable-ubuntu`; +* `ghcr.io/werf/werf:1.2-alpha-centos`; +* `ghcr.io/werf/werf:1.2-beta-centos`; +* `ghcr.io/werf/werf:1.2-ea-centos`; +* `ghcr.io/werf/werf:1.2-stable-centos`; +* `ghcr.io/werf/werf:1.2-alpha-fedora`; +* `ghcr.io/werf/werf:1.2-beta-fedora`; +* `ghcr.io/werf/werf:1.2-ea-fedora`; +* `ghcr.io/werf/werf:1.2-stable-fedora`. + +## Устранение проблем + +### `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 ([подробности](#ядро-linux-без-поддержки-overlayfs-в-режиме-rootless-и-использование-непривилегированного-контейнера)). + +### `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 ([подробности](#ядро-linux-без-поддержки-overlayfs-в-режиме-rootless-и-использование-непривилегированного-контейнера)). + +### `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 или используйте привилегированный контейнер ([подробности](#режимы-работы)). diff --git a/docs/pages_ru/advanced/ci_cd/run_in_container/use_docker_container.md b/docs/pages_ru/advanced/ci_cd/run_in_container/use_docker_container.md new file mode 100644 index 0000000000..17610de2cc --- /dev/null +++ b/docs/pages_ru/advanced/ci_cd/run_in_container/use_docker_container.md @@ -0,0 +1,86 @@ +--- +title: С помощью контейнеров Docker +permalink: advanced/ci_cd/run_in_container/use_docker_container.html +--- + +> ПРИМЕЧАНИЕ: в настоящее время werf поддерживает сборку образов с _использованием Docker-сервера_ или _без его использования_ (в экспериментальном режиме). Сборка образов без Docker-сервера пока доступна в экспериментальном режиме, однако это единственный рекомендуемый способ запуска werf в контейнерах. + +## Сборка образов без Docker-сервера (Новинка!) + +> ВНИМАНИЕ: Пока для этого типа сборки доступен только сборщик образов на основе Dockerfile'ов. Сборщик Stapel будет доступен через некоторое время. + +Для этого метода доступен официальный образ с werf 1.2 (1.1 не поддерживается): `ghcr.io/werf/werf`. + +Выберите один из [доступных режимов работы]({{ "advanced/ci_cd/run_in_container/how_it_works.html#режимы-работы" | true_relative_url }}) и перейдите к нему. + +### Ядро Linux с поддержкой OverlayFS в режиме rootless + +В этом случае необходимо отключить только профили **seccomp** и **AppArmor**. Для этого можно воспользоваться командой следующего вида: + +```shell +docker run \ + --security-opt seccomp=unconfined --security-opt apparmor=unconfined \ + ghcr.io/werf/werf:latest WERF_COMMAND +``` + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование привилегированного контейнера + +В этом случае просто используйте привилегированный контейнер. Для этого можно воспользоваться командой следующего вида: + +```shell +docker run \ + --privileged \ + ghcr.io/werf/werf:latest WERF_COMMAND +``` + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование непривилегированного контейнера + +Отключите профили seccomp и AppArmor и включите `/dev/fuse` в контейнере (чтобы `fuse-overlayfs` могла работать). Пример команды: + +```shell +docker run \ + --device /dev/fuse \ + --security-opt seccomp=unconfined --security-opt apparmor=unconfined \ + ghcr.io/werf/werf:latest WERF_COMMAND +``` + +## Сборка образов с помощью Docker-сервера (не рекомендуется) + +### Локальный Docker-сервер + +Этот метод поддерживает сборку Dockerfile-образов или Stapel-образов. + +Пример команды: + +```shell +docker run \ + --privileged \ + --volume $HOME/.werf:/root/.werf \ + --volume /tmp:/tmp \ + --volume /var/run/docker.sock:/var/run/docker.sock \ + IMAGE WERF_COMMAND +``` + +Для этого метода соберите свой собственный образ Docker с помощью werf. + +### Удаленный Docker-сервер + +Этот метод поддерживает только сборку Dockerfile-образов. Образы Stapel не поддерживаются, поскольку сборщик Stapel-образов использует монтирования из хост-системы в Docker-образы. + +Самый простой способ использовать удаленный Docker-сервер внутри Docker-контейнера — это Docker-in-Docker (dind). + +Для этого метода соберите свой собственный образ на базе `docker:dind`. + +Пример команды: + +```shell +docker run \ + --env DOCKER_HOST="tcp://HOST:PORT" \ + IMAGE WERF_COMMAND +``` + +Для этого метода соберите свой собственный образ Docker с помощью werf. + +## Устранение проблем + +Если у вас возникли какие-либо сложности, пожалуйста, обратитесь к разделу [Устранение проблем]({{ "advanced/ci_cd/run_in_container/how_it_works.html#устранение-проблем" | true_relative_url }}) diff --git a/docs/pages_ru/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_docker_executor.md b/docs/pages_ru/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_docker_executor.md new file mode 100644 index 0000000000..e6557360b4 --- /dev/null +++ b/docs/pages_ru/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_docker_executor.md @@ -0,0 +1,78 @@ +--- +title: С помощью GitLab CI/CD с Docker executor +permalink: advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_docker_executor.html +--- + +> ПРИМЕЧАНИЕ: в настоящее время werf поддерживает сборку образов с _использованием Docker-сервера_ или _без его использования_ (в экспериментальном режиме). Эта страница содержит инструкции, которые подходят только для экспериментального режима _без Docker-сервера_. На данный момент для этого типа сборки доступен только сборщик образов на основе Dockerfile'ов. Сборщик Stapel будет доступен через некоторое время. + +## 1. Настройте GitLab-раннер в Kubernetes + +Выберите один из [доступных режимов работы]({{ "advanced/ci_cd/run_in_container/how_it_works.html#режимы-работы" | true_relative_url }}) (в зависимости от возможностей вашего GitLab-раннера) и перейдите к нему. + +### Ядро Linux с поддержкой OverlayFS в режиме rootless + +Базовая конфигурация раннера: + +```toml +[[runners]] + name = "docker-runner-for-werf" + executor = "docker" + ... + [runners.docker] + security_opt = ["seccomp:unconfined", "apparmor:unconfined"] + ... +``` + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование привилегированного контейнера + +Базовая конфигурация раннера: + +```toml +[[runners]] + name = "docker-runner-for-werf" + executor = "docker" + ... + [runners.docker] + privileged = true + ... +``` + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование непривилегированного контейнера + +Базовая конфигурация раннера: + +```toml +[[runners]] + name = "docker-runner-for-werf" + executor = "docker" + ... + [runners.docker] + security_opt = ["seccomp:unconfined", "apparmor:unconfined"] + devices = ["/dev/fuse"] + ... +``` + +## 2. Настройте доступ к кластеру Kubernetes + +Присвойте переменной окружения `WERF_KUBECONFIG_BASE64` в GitLab-проекте значение из файла `~/.kube/config`, закодированное в base64. werf будет автоматически использовать данную конфигурацию для подключения к кластеру Kubernetes. + +## 3. Настройте файл gitlab-ci.yml проекта + +Ниже приведено описание базового задания по сборке и развертыванию проекта: + +```yaml +stages: + - build-and-deploy + +Build and deploy application: + stage: build-and-deploy + image: ghcr.io/werf/werf + script: + - source $(werf ci-env gitlab --as-file) + - werf converge + tags: ["docker-runner-for-werf"] +``` + +## Устранение проблем + +Если у вас возникли какие-либо сложности, пожалуйста, обратитесь к разделу [Устранение проблем]({{ "advanced/ci_cd/run_in_container/how_it_works.html#устранение-проблем" | true_relative_url }}) diff --git a/docs/pages_ru/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_kubernetes_executor.md b/docs/pages_ru/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_kubernetes_executor.md new file mode 100644 index 0000000000..9c24972e2a --- /dev/null +++ b/docs/pages_ru/advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_kubernetes_executor.md @@ -0,0 +1,206 @@ +--- +title: С помощью Gitlab CI/CD с Kubernetes executor +permalink: advanced/ci_cd/run_in_container/use_gitlab_ci_cd_with_kubernetes_executor.html +--- + +> ПРИМЕЧАНИЕ: в настоящее время werf поддерживает сборку образов с _использованием Docker-сервера_ или _без его использования_ (в экспериментальном режиме). Эта страница содержит инструкции, которые подходят только для экспериментального режима _без Docker-сервера_. На данный момент для этого типа сборки доступен только сборщик образов на основе Dockerfile'ов. Сборщик Stapel будет доступен через некоторое время. + +## 1. Подготовьте кластер Kubernetes + +Выберите один из [доступных режимов работы]({{ "advanced/ci_cd/run_in_container/how_it_works.html#режимы-работы" | true_relative_url }}) и перейдите к нему. + +### Ядро Linux с поддержкой OverlayFS в режиме rootless + +Дополнительные действия не требуются. + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование привилегированного контейнера + +Дополнительные действия не требуются. + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование непривилегированного контейнера + +Для подключения устройства `/dev/fuse` в контейнерах под управлением werf необходим плагин [fuse device](https://github.com/kuberenetes-learning-group/fuse-device-plugin): + +``` +# werf-fuse-device-plugin-ds.yaml +apiVersion: apps/v1 +kind: DaemonSet +metadata: + name: werf-fuse-device-plugin +spec: + selector: + matchLabels: + name: werf-fuse-device-plugin + template: + metadata: + labels: + name: werf-fuse-device-plugin + spec: + hostNetwork: true + containers: + - image: soolaugust/fuse-device-plugin:v1.0 + name: fuse-device-plugin-ctr + securityContext: + allowPrivilegeEscalation: false + capabilities: + drop: ["ALL"] + volumeMounts: + - name: device-plugin + mountPath: /var/lib/kubelet/device-plugins + volumes: + - name: device-plugin + hostPath: + path: /var/lib/kubelet/device-plugins +``` + +Примените приведенный выше манифест плагина в пространстве имен `kube-system`: + +``` +kubectl -n kube-system apply -f werf-fuse-device-plugin-ds.yaml +``` + +Также давайте создадим политику LimitRange с тем, чтобы Pod'ы, создаваемые в некотором пространстве имен, имели доступ к `/dev/fuse`: + +``` +# enable-fuse-limit-range.yaml +apiVersion: v1 +kind: LimitRange +metadata: + name: enable-fuse-limit-range +spec: + limits: + - type: "Container" + default: + github.com/fuse: 1 +``` + +Создайте пространство имен `gitlab-ci` и примените манифест LimitRange в этом пространстве имен (позже мы настроим раннер GitLab на использование этого пространства имен при создании Pod'ов для выполнения CI-заданий): + +``` +kubectl create namespace gitlab-ci +kubectl apply -f enable-fuse-pod-limit-range.yaml +``` + +## 2. Настройте GitLab-раннер в Kubernetes + +Выберите один из [доступных режимов работы]({{ "advanced/ci_cd/run_in_container/how_it_works.html#режимы-работы" | true_relative_url }}) и перейдите к нему. + +### Ядро Linux с поддержкой OverlayFS в режиме rootless + +Базовая конфигурация раннера (`/etc/gitlab-runner/config.toml`): + +```toml +[[runners]] + name = "kubernetes-runner-for-werf" + executor = "kubernetes" + ... + [runners.kubernetes] + ... + pod_annotations = ["container.apparmor.security.beta.kubernetes.io/werf-converge=unconfined"] +``` + +О дополнительных опциях можно узнать из [документации к Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html). + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование привилегированного контейнера + +Базовая конфигурация раннера (`/etc/gitlab-runner/config.toml`): + +```toml +[[runners]] + name = "kubernetes-runner-for-werf" + executor = "kubernetes" + ... + [runners.kubernetes] + ... + privileged = true +``` + +О дополнительных опциях можно узнать из документации к [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html). + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование непривилегированного контейнера + +Базовая конфигурация раннера (`/etc/gitlab-runner/config.toml`): + +```toml +[[runners]] + name = "kubernetes-runner-for-werf" + executor = "kubernetes" + ... + [runners.kubernetes] + ... + namespace = "gitlab-ci" + pod_annotations = ["container.apparmor.security.beta.kubernetes.io/werf-converge=unconfined"] +``` + +Обратите внимание, что было указано пространство имен `gitlab-ci`. Это пространство имен должно быть таким же, что и на шаге 1, для автоматической генерации лимитов Pod'ов. + +О дополнительных опциях можно узнать из документации к [Kubernetes executor](https://docs.gitlab.com/runner/executors/kubernetes.html). + +## 3. Настройте доступ проекта к целевому кластеру Kubernetes + +Существует 2 способа доступа к целевому кластеру Kubernetes, в который разворачивается приложение: + +1. Используя Service Account для Kubenetes executor. Этот метод подходит только в том случае, если Kubernetes executor работает в целевом кластере Kubernetes. +2. Используя kubeconfig с соответствующим настройками. + +### Service account + +Вот пример конфигурации Service Account'а с именем `gitlab-kubernetes-runner-deploy`: + +```yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: gitlab-kubernetes-runner-deploy +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: werf +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin +subjects: + - kind: ServiceAccount + name: werf + namespace: default +``` + +Скорректируйте конфигурацию GitLab-раннера (`/etc/gitlab-runner/config.toml`), чтобы использовать этот Service Account: + +```toml +[[runners]] + name = "kubernetes-runner-for-werf" + ... + [runners.kubernetes] + service_account = "gitlab-kubernetes-runner-deploy" + ... +``` + +### Kubeconfig + +Присвойте переменной окружения `WERF_KUBECONFIG_BASE64` в GitLab-проекте содержимое файла `~/.kube/config`, закодированное в base64. werf будет автоматически использовать эту конфигурацию для подключения к целевому кластеру Kubernetes. + +Этот метод подходит для случаев, когда Kubernetes executor и целевой кластер Kubernetes — два разных кластера. + +## 4. Настройте файл gitlab-ci.yml проекта + +Ниже приведено описание базового задания по сборке и развертыванию проекта: + +```yaml +stages: + - build-and-deploy + +Build and deploy application: + stage: build-and-deploy + image: ghcr.io/werf/werf + script: + - source $(werf ci-env gitlab --as-file) + - werf converge + tags: ["kubernetes-runner-for-werf"] +``` + +## Устранение проблем + +Если у вас возникли какие-либо сложности, пожалуйста, обратитесь к разделу [Устранение проблем]({{ "advanced/ci_cd/run_in_container/how_it_works.html#устранение-проблем" | true_relative_url }}) diff --git a/docs/pages_ru/advanced/ci_cd/run_in_container/use_kubernetes.md b/docs/pages_ru/advanced/ci_cd/run_in_container/use_kubernetes.md new file mode 100644 index 0000000000..a0d70c3b58 --- /dev/null +++ b/docs/pages_ru/advanced/ci_cd/run_in_container/use_kubernetes.md @@ -0,0 +1,275 @@ +--- +title: С помощью Kubernetes +permalink: advanced/ci_cd/run_in_container/use_kubernetes.html +--- + +> ПРИМЕЧАНИЕ: в настоящее время werf поддерживает сборку образов с _использованием Docker-сервера_ или _без его использования_ (в экспериментальном режиме). Эта страница содержит инструкции, которые подходят только для экспериментального режима _без Docker-сервера_. На данный момент для этого типа сборки доступен только сборщик образов на основе Dockerfile'ов. Сборщик Stapel будет доступен через некоторое время. + +## 1. Подготовьте кластер Kubernetes + +Выберите один из [доступных режимов работы]({{ "advanced/ci_cd/run_in_container/how_it_works.html#modes-of-operation" | true_relative_url }}) и перейдите к нему. + +### Ядро Linux с поддержкой OverlayFS в режиме rootless + +Дополнительные действия не требуются. + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование привилегированного контейнера + +Дополнительные действия не требуются. + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование непривилегированного контейнера + +Для подключения устройства `/dev/fuse` в контейнерах под управлением werf необходим плагин [Fuse device](https://github.com/kuberenetes-learning-group/fuse-device-plugin): + +``` +# werf-fuse-device-plugin-ds.yaml +apiVersion: apps/v1 +kind: DaemonSet +metadata: + name: werf-fuse-device-plugin +spec: + selector: + matchLabels: + name: werf-fuse-device-plugin + template: + metadata: + labels: + name: werf-fuse-device-plugin + spec: + hostNetwork: true + containers: + - image: soolaugust/fuse-device-plugin:v1.0 + name: fuse-device-plugin-ctr + securityContext: + allowPrivilegeEscalation: false + capabilities: + drop: ["ALL"] + volumeMounts: + - name: device-plugin + mountPath: /var/lib/kubelet/device-plugins + volumes: + - name: device-plugin + hostPath: + path: /var/lib/kubelet/device-plugins +``` + +Примените приведенный выше манифест плагина в пространстве имен `kube-system`: + +``` +kubectl -n kube-system apply -f werf-fuse-device-plugin-ds.yaml +``` + +## 2. Настройте доступ к реестру контейнеров + +Подготовьте конфигурацию Docker в формате base64 для доступа к реестру. + +```yaml +# registrysecret.yaml +apiVersion: v1 +kind: Secret +metadata: + name: registrysecret +data: + .dockerconfigjson: +type: kubernetes.io/dockerconfigjson +``` + +Создайте `registrysecret` в пространстве имен приложения: + +```shell +kubectl -n quickstart-application apply -f registrysecret.yaml +``` + +## 3. Настройте service account для werf + +Service account необходим werf для доступа к кластеру Kubernetes при развертывании приложения. + +```yaml +# werf-service-account.yaml +apiVersion: v1 +kind: ServiceAccount +metadata: + name: werf + namespace: quickstart-application +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: werf +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin +subjects: + - kind: ServiceAccount + name: werf + namespace: quickstart-application +``` + +Создайте описанный выше service account `werf` с ролью `cluster-admin` в пространстве имен приложения: + +```shell +kubectl -n quickstart-application apply -f werf-service-account.yaml +``` + +## 4. Выполните развертывание приложения + +Выберите один из [доступных режимов работы]({{ "advanced/ci_cd/run_in_container/how_it_works.html#режимы=работы" | true_relative_url }}) и перейдите к нему. + +### Ядро Linux с поддержкой OverlayFS в режиме rootless + +Команда werf converge будет выполняться в специальном Pod'е. Обратите внимание, что `CONTAINER_REGISTRY_REPO` следует заменить на реальный адрес репозитория реестра контейнеров, для которого на предыдущем шаге мы настраивали `registrysecret`. + + +```yaml +# werf-converge.yaml +apiVersion: v1 +kind: Pod +metadata: + name: werf-converge + annotations: + "container.apparmor.security.beta.kubernetes.io/werf-converge": "unconfined" +spec: + serviceAccount: werf + automountServiceAccountToken: true + restartPolicy: Never + containers: + - name: werf-converge + image: ghcr.io/werf/werf + args: + - "sh" + - "-ec" + - | + git clone --depth 1 https://github.com/werf/quickstart-application.git $HOME/quickstart-application && + cd $HOME/quickstart-application && + werf converge --release quickstart-application --repo CONTAINER_REGISTRY_REPO + env: + - name: WERF_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + volumeMounts: + - mountPath: /home/build/.docker/ + name: registrysecret + volumes: + - name: registrysecret + secret: + secretName: registrysecret + items: + - key: .dockerconfigjson + path: config.json +``` + +Создайте pod и разверните приложение в соответствующем пространстве имен: + +```shell +kubectl -n quickstart-application apply -f werf-converge.yaml +kubectl -n quickstart-application logs -f werf-converge +``` + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование привилегированного контейнера + +Команда werf converge будет выполняться в специальном Pod'е. Обратите внимание, что `CONTAINER_REGISTRY_REPO` следует заменить на реальный адрес репозитория реестра контейнеров, для которого на предыдущем шаге мы настраивали `registrysecret`. + +```yaml +# werf-converge.yaml +apiVersion: v1 +kind: Pod +metadata: + name: werf-converge +spec: + serviceAccount: werf + automountServiceAccountToken: true + restartPolicy: Never + containers: + - name: werf-converge + image: ghcr.io/werf/werf + securityContext: + privileged: true + args: + - "sh" + - "-ec" + - | + git clone --depth 1 https://github.com/werf/quickstart-application.git $HOME/quickstart-application && + cd $HOME/quickstart-application && + werf converge --release quickstart-application --repo CONTAINER_REGISTRY_REPO + env: + - name: WERF_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + volumeMounts: + - mountPath: /home/build/.docker/ + name: registrysecret + volumes: + - name: registrysecret + secret: + secretName: registrysecret + items: + - key: .dockerconfigjson + path: config.json +``` + +Создайте pod и разверните приложение в соответствующем пространстве имен: + +```shell +kubectl -n quickstart-application apply -f werf-converge.yaml +kubectl -n quickstart-application logs -f werf-converge +``` + +### Ядро Linux без поддержки OverlayFS в режиме rootless и использование непривилегированного контейнера + +Команда werf converge будет выполняться в специальном Pod'е. Обратите внимание, что `CONTAINER_REGISTRY_REPO` следует заменить на реальный адрес репозитория реестра контейнеров, для которого на предыдущем шаге мы настраивали `registrysecret`. + +```yaml +# werf-converge.yaml +apiVersion: v1 +kind: Pod +metadata: + name: werf-converge + annotations: + "container.apparmor.security.beta.kubernetes.io/werf-converge": "unconfined" +spec: + serviceAccount: werf + automountServiceAccountToken: true + restartPolicy: Never + containers: + - name: werf-converge + image: ghcr.io/werf/werf + resources: + limits: + github.com/fuse: 1 + args: + - "sh" + - "-ec" + - | + git clone --depth 1 https://github.com/werf/quickstart-application.git $HOME/quickstart-application && + cd $HOME/quickstart-application && + werf converge --release quickstart-application --repo CONTAINER_REGISTRY_REPO + env: + - name: WERF_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + volumeMounts: + - mountPath: /home/build/.docker/ + name: registrysecret + volumes: + - name: registrysecret + secret: + secretName: registrysecret + items: + - key: .dockerconfigjson + path: config.json +``` + +Создайте pod и разверните приложение в целевом пространстве имен: + +```shell +kubectl -n quickstart-application apply -f werf-converge.yaml +kubectl -n quickstart-application logs -f werf-converge +``` + +## Устранение проблем + +Если у вас возникли какие-либо сложности, пожалуйста, обратитесь к разделу [Устранение проблем]({{ "advanced/ci_cd/run_in_container/how_it_works.html#troubleshooting" | true_relative_url }}) diff --git a/docs/pages_ru/internals/build_process.md b/docs/pages_ru/internals/build_process.md index ab398ca5e6..575f540e40 100644 --- a/docs/pages_ru/internals/build_process.md +++ b/docs/pages_ru/internals/build_process.md @@ -122,3 +122,11 @@ werf использует алгоритм оптимистичных блоки │ - ⛵ image app └ Concurrent builds plan (no more than 5 images at the same time) ``` + +## Buildah + +werf поддерживает использование Buildah в экспериментальном режиме для сборки образов. В этом режиме пока поддерживаются только Dockerfile-образы (планируется поддержка Stapel). + +При этом процесс сборки не изменился, перемены коснулись только бэкенда контейнеров и хранилища (сервер Docker был заменен на Buildah). + +Более подробную информацию о Buildah можно получить в разделе [Режим сборки с использованием Buildah.]({{ "/advanced/buildah_mode.html" | true_relative_url }})