From cb2f362822151de51b0f9b0aa1009ccd8a43d138 Mon Sep 17 00:00:00 2001
From: Ilya Lesikov <ilya@lesikov.com>
Date: Wed, 5 Jun 2024 11:50:32 +0300
Subject: [PATCH] docs(configurator): update Getting Started for Kubernetes

Signed-off-by: Ilya Lesikov <ilya@lesikov.com>
---
 .../gitlab_kubernetes_main_section.md.liquid  | 151 ++++++++++----
 .../linux/buildah/infra.md.liquid             | 178 ++++++++++++-----
 .../linux/buildah/infra.md.liquid             |  93 ++++++---
 .../gitlab_kubernetes_main_section.md.liquid  | 157 +++++++++++----
 .../linux/buildah/infra.md.liquid             | 187 +++++++++++++-----
 .../linux/buildah/infra.md.liquid             | 102 ++++++----
 6 files changed, 626 insertions(+), 242 deletions(-)

diff --git a/bin/configurator/static/_includes/en/configurator/partials/ci/gitlab_kubernetes_main_section.md.liquid b/bin/configurator/static/_includes/en/configurator/partials/ci/gitlab_kubernetes_main_section.md.liquid
index 7a274d7ce..6717b07e3 100644
--- a/bin/configurator/static/_includes/en/configurator/partials/ci/gitlab_kubernetes_main_section.md.liquid
+++ b/bin/configurator/static/_includes/en/configurator/partials/ci/gitlab_kubernetes_main_section.md.liquid
@@ -2,72 +2,126 @@
 
 - GitLab;
 
-- Kubernetes to run the GitLab Runner.
+- Kubernetes to run GitLab Kubernetes Executor.
 
-### Installing and registering the GitLab Runner
+### Install GitLab Runner
 
-Follow [official instructions](https://docs.gitlab.com/runner/register/index.html) to install the GitLab Runner in Kubernetes and registering it.
+Follow [official instructions](https://docs.gitlab.com/runner/install/) to install and register the GitLab Runner. If you are going to install your GitLab Runner in Kubernetes, then install it to `gitlab-ci` namespace.
 
-### Configuring the GitLab Runner
+### Basic GitLab Runner configuration (no caching)
 
-Modify the configuration of the registered GitLab Runner by adding the following parameters to its `config.toml`:
+Add the following to the GitLab Runner configuration file `config.toml`:
 
 ```toml
 [[runners]]
-  name = "<name of the registered Runner>"
+  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true"]
+
   [runners.kubernetes]
     namespace = "gitlab-ci"
+
     [runners.kubernetes.pod_annotations]
       "container.apparmor.security.beta.kubernetes.io/build" = "unconfined"
+
     [runners.kubernetes.pod_security_context]
       run_as_non_root = true
       run_as_user = 1000
       run_as_group = 1000
       fs_group = 1000
-```
-
-Add the following parameters to enable `.werf` and `/builds` caching (recommended):
 
-```toml
-[[runners]]
-  name = "<name of the registered Runner>"
-  [runners.kubernetes]
-    [[runners.kubernetes.volumes.pvc]]
+    [[runners.kubernetes.volumes.empty_dir]]
       name = "gitlab-ci-kubernetes-executor-werf-cache"
       mount_path = "/home/build/.werf"
-    [[runners.kubernetes.volumes.pvc]]
+
+    [[runners.kubernetes.volumes.empty_dir]]
       name = "gitlab-ci-kubernetes-executor-builds-cache"
       mount_path = "/builds"
+
+    [[runners.kubernetes.volumes.empty_dir]]
+      name = "gitlab-ci-kubernetes-executor-helper-home"
+      mount_path = "/home/helper"
+
+    [[runners.kubernetes.pod_spec]]
+      name = "fix helper HOME"
+      patch = '''
+        containers:
+        - name: helper
+          env:
+          - name: HOME
+            value: /home/helper
+      '''
+      patch_type = "strategic"
 ```
 
-... or these if caching is not needed:
+### Basic Gitlab Runner Configuration (with caching using Persistent Volumes)
+
+Add the following to the GitLab Runner configuration file `config.toml`:
 
 ```toml
 [[runners]]
-  name = "<name of the registered Runner>"
+  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true"]
+
   [runners.kubernetes]
-    [[runners.kubernetes.volumes.empty_dir]]
+    namespace = "gitlab-ci"
+
+    [runners.kubernetes.pod_annotations]
+      "container.apparmor.security.beta.kubernetes.io/build" = "unconfined"
+
+    [runners.kubernetes.pod_security_context]
+      run_as_non_root = true
+      run_as_user = 1000
+      run_as_group = 1000
+      fs_group = 1000
+
+    [[runners.kubernetes.volumes.pvc]]
       name = "gitlab-ci-kubernetes-executor-werf-cache"
       mount_path = "/home/build/.werf"
-    [[runners.kubernetes.volumes.empty_dir]]
+
+    [[runners.kubernetes.volumes.pvc]]
       name = "gitlab-ci-kubernetes-executor-builds-cache"
       mount_path = "/builds"
-```
 
-Add one more parameter if you are going to deploy applications using werf to the same cluster in which the GitLab Runner is running:
-
-```toml
-[[runners]]
-  name = "<name of the registered Runner'а>"
-  [runners.kubernetes]
-    service_account = "gitlab-ci-kubernetes-executor"
-```
+    [[runners.kubernetes.volumes.pvc]]
+      name = "gitlab-ci-kubernetes-executor-helper-home"
+      mount_path = "/home/helper"
 
-You may want to perform [additional configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) of the GitLab Runner as well.
+    [[runners.kubernetes.pod_spec]]
+      name = "fix helper HOME"
+      patch = '''
+        containers:
+        - name: helper
+          env:
+          - name: HOME
+            value: /home/helper
+      '''
+      patch_type = "strategic"
 
-### Configuring Kubernetes
+    [[runners.kubernetes.pod_spec]]
+      name = "fix volumes permissions"
+      patch = '''
+        initContainers:
+        - name: fix-volumes-permissions
+          image: alpine
+          command:
+          - sh
+          - -ec
+          - |
+            chown :$(id -g) /home/build/.werf /builds /home/helper
+            chmod g+rwx /home/build/.werf /builds /home/helper
+          securityContext:
+            runAsUser: 0
+            runAsNonRoot: false
+          volumeMounts:
+          - mountPath: /home/build/.werf
+            name: gitlab-ci-kubernetes-executor-werf-cache
+          - mountPath: /builds
+            name: gitlab-ci-kubernetes-executor-builds-cache
+          - mountPath: /home/helper
+            name: gitlab-ci-kubernetes-executor-helper-home
+      '''
+      patch_type = "strategic"
+```
 
-If you enabled caching of `.werf` and `/builds` in the GitLab Runner configuration, create appropriate PersistentVolumeClaims in the cluster, for example:
+Create PVCs:
 
 ```shell
 kubectl create -f - <<EOF
@@ -95,10 +149,26 @@ spec:
   resources:
     requests:
       storage: 30Gi
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: gitlab-ci-kubernetes-executor-helper-home
+  namespace: gitlab-ci
+spec:
+  accessModes:
+    - ReadWriteMany
+  resources:
+    requests:
+      storage: 30Gi
 EOF
 ```
 
-If you are going to deploy applications to the same cluster in which GitLab Runner is running, configure RBAC in the cluster to run GitLab Runner with the following command:
+### Configure access to Kubernetes from Gitlab Executor Pods
+
+werf will run in GitLab Kubernetes Executor Pods. Usually you are going to deploy with werf to the same cluster where GitLab Kubernetes Executor Pods are running. If so, you need to configure custom ServiceAccount and ClusterRoleBinding.
+
+Create a ServiceAccount and a ClusterRoleBinding:
 
 ```shell
 kubectl create -f - <<EOF
@@ -126,7 +196,17 @@ EOF
 
 > For greater security, consider creating a more restricted ClusterRole/Role and using it instead of the `cluster-admin` cluster role above.
 
-If the Kubernetes nodes on which the GitLab Runner is hosted run with a Linux kernel version 5.12 or lower, then enable FUSE for GitLab Runner on that cluster using the following command:
+Now add this line to the GitLab Runner configuration file `config.toml`:
+
+```toml
+[[runners]]
+  [runners.kubernetes]
+    service_account = "gitlab-ci-kubernetes-executor"
+```
+
+### Allow FUSE (for Kubernetes Nodes with Linux kernel older than 5.13)
+
+If the Kubernetes Nodes on which you are going to run Kubernetes Executor Pods have Linux kernel version older than 5.13, then you need to allow FUSE:
 
 ```shell
 kubectl create -f - <<EOF
@@ -174,8 +254,6 @@ spec:
 EOF
 ```
 
-{% include configurator/partials/ci/configuring_the_container_registry.md.liquid %}
-
 ### Preparing Kubernetes for multi-platform building (optional)
 
 {% include configurator/partials/ci/cross_platform_note.md.liquid %}
@@ -189,6 +267,7 @@ apiVersion: apps/v1
 kind: DaemonSet
 metadata:
   name: qemu-user-static
+  namespace: gitlab-ci
   labels:
     app: qemu-user-static
 spec:
@@ -218,3 +297,5 @@ spec:
               memory: 50Mi
 EOF
 ```
+
+{% include configurator/partials/ci/configuring_the_container_registry.md.liquid %}
diff --git a/bin/configurator/static/_includes/en/configurator/tab/ci/argocd-with-gitlab-ci-cd/simple/kubernetes-runner/linux/buildah/infra.md.liquid b/bin/configurator/static/_includes/en/configurator/tab/ci/argocd-with-gitlab-ci-cd/simple/kubernetes-runner/linux/buildah/infra.md.liquid
index 990af7fe1..5aa7cbb0c 100644
--- a/bin/configurator/static/_includes/en/configurator/tab/ci/argocd-with-gitlab-ci-cd/simple/kubernetes-runner/linux/buildah/infra.md.liquid
+++ b/bin/configurator/static/_includes/en/configurator/tab/ci/argocd-with-gitlab-ci-cd/simple/kubernetes-runner/linux/buildah/infra.md.liquid
@@ -2,77 +2,131 @@
 
 - GitLab;
 
-- Kubernetes to run the GitLab Runner;
+- Kubernetes to run GitLab Kubernetes Executor;
 
 - [Argo CD](https://argo-cd.readthedocs.io/en/stable/getting_started/#1-install-argo-cd).
 
-### Installing and registering the GitLab Runner
+### Install GitLab Runner
 
-Follow the [official instructions](https://docs.gitlab.com/runner/register/index.html) on how to install the GitLab Runner in Kubernetes and register it.
+Follow [official instructions](https://docs.gitlab.com/runner/install/) to install and register the GitLab Runner. If you are going to install your GitLab Runner in Kubernetes, then install it to `gitlab-ci` namespace.
 
-### Configuring the GitLab Runner
+### Basic GitLab Runner configuration (no caching)
 
-Modify the configuration of the registered GitLab Runner by adding the following parameters to its `config.toml`:
+Add the following to the GitLab Runner configuration file `config.toml`:
 
 ```toml
 [[runners]]
-  name = "<name of the registered Runner>"
+  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true"]
+
   [runners.kubernetes]
     namespace = "gitlab-ci"
+
     [runners.kubernetes.pod_annotations]
       "container.apparmor.security.beta.kubernetes.io/build" = "unconfined"
+
     [runners.kubernetes.pod_security_context]
       run_as_non_root = true
       run_as_user = 1000
       run_as_group = 1000
       fs_group = 1000
-```
-
-Add the following parameters to enable `.werf` and `/builds` caching (recommended):
 
-```toml
-[[runners]]
-  name = "<name of the registered Runner>"
-  [runners.kubernetes]
-    [[runners.kubernetes.volumes.pvc]]
+    [[runners.kubernetes.volumes.empty_dir]]
       name = "gitlab-ci-kubernetes-executor-werf-cache"
       mount_path = "/home/build/.werf"
-    [[runners.kubernetes.volumes.pvc]]
+
+    [[runners.kubernetes.volumes.empty_dir]]
       name = "gitlab-ci-kubernetes-executor-builds-cache"
       mount_path = "/builds"
+
+    [[runners.kubernetes.volumes.empty_dir]]
+      name = "gitlab-ci-kubernetes-executor-helper-home"
+      mount_path = "/home/helper"
+
+    [[runners.kubernetes.pod_spec]]
+      name = "fix helper HOME"
+      patch = '''
+        containers:
+        - name: helper
+          env:
+          - name: HOME
+            value: /home/helper
+      '''
+      patch_type = "strategic"
 ```
 
-... or these, if caching is not needed:
+### Basic Gitlab Runner Configuration (with caching using Persistent Volumes)
+
+Add the following to the GitLab Runner configuration file `config.toml`:
 
 ```toml
 [[runners]]
-  name = "<name of the registered Runner>"
+  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true"]
+
   [runners.kubernetes]
-    [[runners.kubernetes.volumes.empty_dir]]
+    namespace = "gitlab-ci"
+
+    [runners.kubernetes.pod_annotations]
+      "container.apparmor.security.beta.kubernetes.io/build" = "unconfined"
+
+    [runners.kubernetes.pod_security_context]
+      run_as_non_root = true
+      run_as_user = 1000
+      run_as_group = 1000
+      fs_group = 1000
+
+    [[runners.kubernetes.volumes.pvc]]
       name = "gitlab-ci-kubernetes-executor-werf-cache"
       mount_path = "/home/build/.werf"
-    [[runners.kubernetes.volumes.empty_dir]]
+
+    [[runners.kubernetes.volumes.pvc]]
       name = "gitlab-ci-kubernetes-executor-builds-cache"
       mount_path = "/builds"
-```
-
-Add one more parameter if you are going to deploy applications using werf to the same cluster in which the GitLab Runner is running:
 
-```toml
-[[runners]]
-  name = "<name of the registered Runner'а>"
-  [runners.kubernetes]
-    service_account = "gitlab-ci-kubernetes-executor"
+    [[runners.kubernetes.volumes.pvc]]
+      name = "gitlab-ci-kubernetes-executor-helper-home"
+      mount_path = "/home/helper"
+
+    [[runners.kubernetes.pod_spec]]
+      name = "fix helper HOME"
+      patch = '''
+        containers:
+        - name: helper
+          env:
+          - name: HOME
+            value: /home/helper
+      '''
+      patch_type = "strategic"
+
+    [[runners.kubernetes.pod_spec]]
+      name = "fix volumes permissions"
+      patch = '''
+        initContainers:
+        - name: fix-volumes-permissions
+          image: alpine
+          command:
+          - sh
+          - -ec
+          - |
+            chown :$(id -g) /home/build/.werf /builds /home/helper
+            chmod g+rwx /home/build/.werf /builds /home/helper
+          securityContext:
+            runAsUser: 0
+            runAsNonRoot: false
+          volumeMounts:
+          - mountPath: /home/build/.werf
+            name: gitlab-ci-kubernetes-executor-werf-cache
+          - mountPath: /builds
+            name: gitlab-ci-kubernetes-executor-builds-cache
+          - mountPath: /home/helper
+            name: gitlab-ci-kubernetes-executor-helper-home
+      '''
+      patch_type = "strategic"
 ```
 
-You may want to perform [additional configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) of the GitLab Runner as well.
-
-### Configuring Kubernetes
-
-If you enabled caching of `.werf` and `/builds` in the GitLab Runner configuration, create appropriate PersistentVolumeClaims in the cluster, for example:
+Create PVCs:
 
 ```shell
-$ kubectl create -f - <<EOF
+kubectl create -f - <<EOF
 ---
 apiVersion: v1
 kind: PersistentVolumeClaim
@@ -97,13 +151,29 @@ spec:
   resources:
     requests:
       storage: 30Gi
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: gitlab-ci-kubernetes-executor-helper-home
+  namespace: gitlab-ci
+spec:
+  accessModes:
+    - ReadWriteMany
+  resources:
+    requests:
+      storage: 30Gi
 EOF
 ```
 
-If you are going to deploy applications to the same cluster in which the GitLab Runner is running, configure RBAC in the cluster to run GitLab Runner using the following command:
+### Configure access to Kubernetes from Gitlab Executor Pods
+
+werf will run in GitLab Kubernetes Executor Pods. Usually you are going to deploy with werf to the same cluster where GitLab Kubernetes Executor Pods are running. If so, you need to configure custom ServiceAccount and ClusterRoleBinding.
+
+Create a ServiceAccount and a ClusterRoleBinding:
 
 ```shell
-$ kubectl create -f - <<EOF
+kubectl create -f - <<EOF
 ---
 apiVersion: v1
 kind: ServiceAccount
@@ -128,10 +198,20 @@ EOF
 
 > For greater security, consider creating a more restricted ClusterRole/Role and using it instead of the `cluster-admin` cluster role above.
 
-If the Kubernetes nodes on which the GitLab Runner is hosted are running Linux kernel 5.12 or lower, enable FUSE for the GitLab Runner on that cluster using the following command:
+Now add this line to the GitLab Runner configuration file `config.toml`:
+
+```toml
+[[runners]]
+  [runners.kubernetes]
+    service_account = "gitlab-ci-kubernetes-executor"
+```
+
+### Allow FUSE (for Kubernetes Nodes with Linux kernel older than 5.13)
+
+If the Kubernetes Nodes on which you are going to run Kubernetes Executor Pods have Linux kernel version older than 5.13, then you need to allow FUSE:
 
 ```shell
-$ kubectl create -f - <<EOF
+kubectl create -f - <<EOF
 ---
 apiVersion: apps/v1
 kind: DaemonSet
@@ -176,21 +256,28 @@ spec:
 EOF
 ```
 
-### Configuring the container registry
+### Install Argo CD Image Updater
+
+Install Argo CD Image Updater with the ["continuous deployment of OCI Helm chart type application" patch](https://github.com/argoproj-labs/argocd-image-updater/pull/405):
 
-[Enable garbage collection](https://docs.gitlab.com/ee/administration/packages/container_registry.html#container-registry-garbage-collection) for your container registry.
+```shell
+kubectl apply -n argocd -f https://raw.githubusercontent.com/werf/3p-argocd-image-updater/master/manifests/install.yaml
+```
 
 ### Preparing Kubernetes for multi-platform building (optional)
 
-> This step is only needed to build images for platforms other than the host platform on which werf is being run.
+{% include configurator/partials/ci/cross_platform_note.md.liquid %}
 
 Register emulators on your Kubernetes nodes using qemu-user-static:
 
-```yaml
+```shell
+kubectl create -f - <<EOF
+---
 apiVersion: apps/v1
 kind: DaemonSet
 metadata:
   name: qemu-user-static
+  namespace: gitlab-ci
   labels:
     app: qemu-user-static
 spec:
@@ -218,12 +305,7 @@ spec:
             requests:
               cpu: 50m
               memory: 50Mi
+EOF
 ```
 
-### Installing Argo CD Image Updater
-
-Install Argo CD Image Updater with the ["continuous deployment of OCI Helm chart type application" patch](https://github.com/argoproj-labs/argocd-image-updater/pull/405):
-
-```shell
-kubectl apply -n argocd -f https://raw.githubusercontent.com/werf/3p-argocd-image-updater/master/manifests/install.yaml
-```
+{% include configurator/partials/ci/configuring_the_container_registry.md.liquid %}
diff --git a/bin/configurator/static/_includes/en/configurator/tab/ci/other-ci-cd-system/simple/kubernetes-runner/linux/buildah/infra.md.liquid b/bin/configurator/static/_includes/en/configurator/tab/ci/other-ci-cd-system/simple/kubernetes-runner/linux/buildah/infra.md.liquid
index 4e2bb56bd..aaa5f5b55 100644
--- a/bin/configurator/static/_includes/en/configurator/tab/ci/other-ci-cd-system/simple/kubernetes-runner/linux/buildah/infra.md.liquid
+++ b/bin/configurator/static/_includes/en/configurator/tab/ci/other-ci-cd-system/simple/kubernetes-runner/linux/buildah/infra.md.liquid
@@ -4,9 +4,9 @@
 
 - Kubernetes for running CI jobs with your CI system's Kubernetes Runner.
 
-### Configuring the Runner
+### Basic Runner configuration (no caching)
 
-Configure your CI system's Runner so that the containers you create have the following configuration:
+Configure your CI system's Runner so that the Pods you create have the following configuration:
 
 ```yaml
 apiVersion: v1
@@ -16,6 +16,13 @@ metadata:
   annotations:
     "container.apparmor.security.beta.kubernetes.io/build": unconfined
 spec:
+  containers:
+  - volumeMounts:
+    - name: werf-cache
+      mountPath: /home/build/.werf
+  volumes:
+  - name: werf-cache
+    emptyDir: {}
   securityContext:
     runAsNonRoot: true
     runAsUser: 1000
@@ -23,10 +30,33 @@ spec:
     fsGroup: 1000
 ```
 
-To enable `.werf` caching (recommended), the Pods must have some additional configuration:
+### Basic Runner configuration (with caching using Persistent Volumes)
+
+Configure your CI system's Runner so that the Pods you create have the following configuration:
 
 ```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  namespace: ci
+  annotations:
+    "container.apparmor.security.beta.kubernetes.io/build": unconfined
 spec:
+  initContainers:
+  - name: fix-volumes-permissions
+    image: alpine
+    command:
+    - sh
+    - -ec
+    - |
+      chown :$(id -g) /home/build/.werf
+      chmod g+rwx /home/build/.werf
+    securityContext:
+      runAsUser: 0
+      runAsNonRoot: false
+    volumeMounts:
+    - mountPath: /home/build/.werf
+      name: werf-cache
   containers:
   - volumeMounts:
     - name: werf-cache
@@ -35,34 +65,18 @@ spec:
   - name: werf-cache
     persistentVolumeClaim:
       claimName: ci-kubernetes-runner-werf-cache
+  securityContext:
+    runAsNonRoot: true
+    runAsUser: 1000
+    runAsGroup: 1000
+    fsGroup: 1000
 ```
 
-... if caching is not needed, use the following configuration:
-
-```yaml
-spec:
-  containers:
-  - volumeMounts:
-    - name: werf-cache
-      mountPath: /home/build/.werf
-  volumes:
-  - name: werf-cache
-    emptyDir: {}
-```
-
-Add the following configuration if you are going to deploy applications using werf to the same cluster in which the Kubernetes Runner is running:
-
-```yaml
-spec:
-  serviceAccountName: ci-kubernetes-runner
-```
-
-### Configuring Kubernetes
-
-If you enabled caching of `.werf` in the Kubernetes Runner configuration, create the appropriate PersistentVolumeClaim in the cluster as follows:
+Create PVC:
 
 ```shell
 kubectl create -f - <<EOF
+---
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
@@ -77,7 +91,11 @@ spec:
 EOF
 ```
 
-If you are going to deploy applications to the same cluster in which Kubernetes Runner is running, configure RBAC in the cluster to run CI jobs with the following command:
+### Configure access to Kubernetes from Runner Pods
+
+If werf will run directly in Runner Pods and you are going to deploy with werf to the **same** cluster where Runner Pods are running, then you need to configure custom ServiceAccount and ClusterRoleBinding.
+
+Create a ServiceAccount and a ClusterRoleBinding:
 
 ```shell
 kubectl create -f - <<EOF
@@ -105,7 +123,16 @@ EOF
 
 > For greater security, consider creating a more restricted ClusterRole/Role and using it instead of the `cluster-admin` cluster role above.
 
-If the Kubernetes nodes on which the Kubernetes Runner is hosted have Linux kernel version 5.12 or lower, enable FUSE for the Kubernetes Runner on that cluster using the following command:
+Now add this line to Pod spawned by your Runner:
+
+```yaml
+spec:
+  serviceAccountName: ci-kubernetes-runner
+```
+
+### Allow FUSE (for Kubernetes Nodes with Linux kernel older than 5.13)
+
+If the Kubernetes Nodes on which you are going to run Runner Pods have Linux kernel version older than 5.13, then you need to allow FUSE:
 
 ```shell
 kubectl create -f - <<EOF
@@ -153,10 +180,6 @@ spec:
 EOF
 ```
 
-### Configuring the container registry
-
-[Enable garbage collection]({{ "/docs/v2/usage/cleanup/cr_cleanup.html#container-registrys-garbage-collector" | relative_url }}) for your container registry.
-
 ### Preparing Kubernetes for multi-platform building (optional)
 
 > This step only needed to build images for platforms other than host platform running werf.
@@ -170,6 +193,7 @@ apiVersion: apps/v1
 kind: DaemonSet
 metadata:
   name: qemu-user-static
+  namespace: ci
   labels:
     app: qemu-user-static
 spec:
@@ -199,3 +223,8 @@ spec:
               memory: 50Mi
 EOF
 ```
+
+### Configuring the container registry
+
+[Enable garbage collection]({{ "/docs/v2/usage/cleanup/cr_cleanup.html#container-registrys-garbage-collector" | relative_url }}) for your container registry.
+
diff --git a/bin/configurator/static/_includes/ru/configurator/partials/ci/gitlab_kubernetes_main_section.md.liquid b/bin/configurator/static/_includes/ru/configurator/partials/ci/gitlab_kubernetes_main_section.md.liquid
index e29b3ac9a..cfe175225 100644
--- a/bin/configurator/static/_includes/ru/configurator/partials/ci/gitlab_kubernetes_main_section.md.liquid
+++ b/bin/configurator/static/_includes/ru/configurator/partials/ci/gitlab_kubernetes_main_section.md.liquid
@@ -2,72 +2,126 @@
 
 - GitLab;
 
-- Kubernetes для запуска GitLab Runner.
+- Kubernetes для запуска GitLab Kubernetes Executor.
 
-### Установка и регистрация GitLab Runner
+### Установка GitLab Runner
 
-Для установки GitLab Runner в Kubernetes и его регистрации в GitLab следуйте [официальным инструкциям](https://docs.gitlab.com/runner/register/index.html).
+Следуйте [официальным инструкциям](https://docs.gitlab.com/runner/install/) для установки и регистрации GitLab Runner. Если вы собираетесь устанавливать ваш GitLab Runner в Kubernetes, то установите его в namespace `gitlab-ci`.
 
-### Настройка GitLab Runner
+### Базовая настройка GitLab Runner (без кеширования)
 
-Измените конфигурацию зарегистрированного GitLab Runner'а, добавив в его `config.toml` следующие параметры:
+Добавьте следующее в конфигурационный файл GitLab Runner `config.toml`:
 
 ```toml
 [[runners]]
-  name = "<имя зарегистрированного Runner'а>"
+  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true"]
+
   [runners.kubernetes]
     namespace = "gitlab-ci"
+
     [runners.kubernetes.pod_annotations]
       "container.apparmor.security.beta.kubernetes.io/build" = "unconfined"
+
     [runners.kubernetes.pod_security_context]
       run_as_non_root = true
       run_as_user = 1000
       run_as_group = 1000
       fs_group = 1000
-```
-
-Если нужно кеширование `.werf` и `/builds` (рекомендуется), то добавьте эти параметры:
 
-```toml
-[[runners]]
-  name = "<имя зарегистрированного Runner'а>"
-  [runners.kubernetes]
-    [[runners.kubernetes.volumes.pvc]]
+    [[runners.kubernetes.volumes.empty_dir]]
       name = "gitlab-ci-kubernetes-executor-werf-cache"
       mount_path = "/home/build/.werf"
-    [[runners.kubernetes.volumes.pvc]]
+
+    [[runners.kubernetes.volumes.empty_dir]]
       name = "gitlab-ci-kubernetes-executor-builds-cache"
       mount_path = "/builds"
+
+    [[runners.kubernetes.volumes.empty_dir]]
+      name = "gitlab-ci-kubernetes-executor-helper-home"
+      mount_path = "/home/helper"
+
+    [[runners.kubernetes.pod_spec]]
+      name = "fix helper HOME"
+      patch = '''
+        containers:
+        - name: helper
+          env:
+          - name: HOME
+            value: /home/helper
+      '''
+      patch_type = "strategic"
 ```
 
-... а если не нужно, то добавьте эти:
+### Базовая настройка Gitlab Runner (с кешированием в Persistent Volumes)
+
+Добавьте следующее в конфигурационный файл GitLab Runner `config.toml`:
 
 ```toml
 [[runners]]
-  name = "<имя зарегистрированного Runner'а>"
+  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true"]
+
   [runners.kubernetes]
-    [[runners.kubernetes.volumes.empty_dir]]
+    namespace = "gitlab-ci"
+
+    [runners.kubernetes.pod_annotations]
+      "container.apparmor.security.beta.kubernetes.io/build" = "unconfined"
+
+    [runners.kubernetes.pod_security_context]
+      run_as_non_root = true
+      run_as_user = 1000
+      run_as_group = 1000
+      fs_group = 1000
+
+    [[runners.kubernetes.volumes.pvc]]
       name = "gitlab-ci-kubernetes-executor-werf-cache"
       mount_path = "/home/build/.werf"
-    [[runners.kubernetes.volumes.empty_dir]]
+
+    [[runners.kubernetes.volumes.pvc]]
       name = "gitlab-ci-kubernetes-executor-builds-cache"
       mount_path = "/builds"
-```
 
-Если будете развертывать приложения с werf в тот же кластер, в котором запускается GitLab Runner, то добавьте ещё один параметр:
-
-```toml
-[[runners]]
-  name = "<имя зарегистрированного Runner'а>"
-  [runners.kubernetes]
-    service_account = "gitlab-ci-kubernetes-executor"
-```
+    [[runners.kubernetes.volumes.pvc]]
+      name = "gitlab-ci-kubernetes-executor-helper-home"
+      mount_path = "/home/helper"
 
-При желании произведите [дополнительную конфигурацию](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) GitLab Runner'а.
+    [[runners.kubernetes.pod_spec]]
+      name = "fix helper HOME"
+      patch = '''
+        containers:
+        - name: helper
+          env:
+          - name: HOME
+            value: /home/helper
+      '''
+      patch_type = "strategic"
 
-### Настройка Kubernetes
+    [[runners.kubernetes.pod_spec]]
+      name = "fix volumes permissions"
+      patch = '''
+        initContainers:
+        - name: fix-volumes-permissions
+          image: alpine
+          command:
+          - sh
+          - -ec
+          - |
+            chown :$(id -g) /home/build/.werf /builds /home/helper
+            chmod g+rwx /home/build/.werf /builds /home/helper
+          securityContext:
+            runAsUser: 0
+            runAsNonRoot: false
+          volumeMounts:
+          - mountPath: /home/build/.werf
+            name: gitlab-ci-kubernetes-executor-werf-cache
+          - mountPath: /builds
+            name: gitlab-ci-kubernetes-executor-builds-cache
+          - mountPath: /home/helper
+            name: gitlab-ci-kubernetes-executor-helper-home
+      '''
+      patch_type = "strategic"
+```
 
-Если в конфигурации GitLab Runner вы включили кеширование `.werf` и `/builds`, то создайте в кластере соответствующие PersistentVolumeClaims, например:
+Создайте PVC:
 
 ```shell
 kubectl create -f - <<EOF
@@ -95,10 +149,26 @@ spec:
   resources:
     requests:
       storage: 30Gi
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: gitlab-ci-kubernetes-executor-helper-home
+  namespace: gitlab-ci
+spec:
+  accessModes:
+    - ReadWriteMany
+  resources:
+    requests:
+      storage: 30Gi
 EOF
 ```
 
-Если будете разворачивать приложения в тот же кластер, в котором запускается GitLab Runner, то в кластере для запуска GitLab Runner'а настройте RBAC следующей командой:
+### Настройте доступ к Kubernetes из GitLab Executor Pod'ов
+
+werf будет запускаться в GitLab Executor Pod'ах. Скорее всего вы будете деплоить с werf в тот же кластер, в котором запускаются GitLab Executor Pod'ы. Если так, то вам нужно настроить отдельные ServiceAccount и ClusterRoleBinding.
+
+Создайте ServiceAccount и ClusterRoleBinding:
 
 ```shell
 kubectl create -f - <<EOF
@@ -124,9 +194,19 @@ subjects:
 EOF
 ```
 
-> Для большей безопасности можете создать более ограниченную ClusterRole/Role и использовать её вместо кластерной роли `cluster-admin` выше.
+> Для большей безопасности подумайте над использованием более ограниченной в правах ClusterRole/Role и используйте её вместо `cluster-admin` ClusterRole выше.
 
-Если Kubernetes-узлы для GitLab Runner имеют ядро Linux версии 5.12 или ниже, то разрешите в этом кластере использование FUSE для GitLab Runner следующей командой:
+Теперь добавьте эту строку в конфигурационный файл GitLab Runner `config.toml`:
+
+```toml
+[[runners]]
+  [runners.kubernetes]
+    service_account = "gitlab-ci-kubernetes-executor"
+```
+
+### Разрешите использование FUSE (для Kubernetes Nodes с ядром Linux старее, чем 5.13)
+
+Если Kubernetes Nodes, на которых вы будете запускать Kubernetes Executor Pods, имеют версию ядра Linux старее 5.13, то вам нужно разрешить использование FUSE:
 
 ```shell
 kubectl create -f - <<EOF
@@ -174,13 +254,11 @@ spec:
 EOF
 ```
 
-{% include configurator/partials/ci/configuring_the_container_registry.md.liquid %}
-
-### Подготовка кластера Kubernetes к мультиплатформенной сборке (опционально)
+### Настройка Kubernetes для мульти-платформенных сборок (опционально)
 
 {% include configurator/partials/ci/cross_platform_note.md.liquid %}
 
-Регистрируем на узлах Kubernetes эмуляторы с помощью образа qemu-user-static:
+Активируйте эмуляторы для ваших Kubernetes Nodes, используя qemu-user-static:
 
 ```shell
 kubectl create -f - <<EOF
@@ -189,6 +267,7 @@ apiVersion: apps/v1
 kind: DaemonSet
 metadata:
   name: qemu-user-static
+  namespace: gitlab-ci
   labels:
     app: qemu-user-static
 spec:
@@ -218,3 +297,5 @@ spec:
               memory: 50Mi
 EOF
 ```
+
+{% include configurator/partials/ci/configuring_the_container_registry.md.liquid %}
diff --git a/bin/configurator/static/_includes/ru/configurator/tab/ci/argocd-with-gitlab-ci-cd/simple/kubernetes-runner/linux/buildah/infra.md.liquid b/bin/configurator/static/_includes/ru/configurator/tab/ci/argocd-with-gitlab-ci-cd/simple/kubernetes-runner/linux/buildah/infra.md.liquid
index d65e91df4..dd06f48b1 100644
--- a/bin/configurator/static/_includes/ru/configurator/tab/ci/argocd-with-gitlab-ci-cd/simple/kubernetes-runner/linux/buildah/infra.md.liquid
+++ b/bin/configurator/static/_includes/ru/configurator/tab/ci/argocd-with-gitlab-ci-cd/simple/kubernetes-runner/linux/buildah/infra.md.liquid
@@ -2,77 +2,131 @@
 
 - GitLab;
 
-- Kubernetes для запуска GitLab Runner;
+- Kubernetes для запуска GitLab Kubernetes Executor;
 
 - [Argo CD](https://argo-cd.readthedocs.io/en/stable/getting_started/#1-install-argo-cd).
 
-### Установка и регистрация GitLab Runner
+### Установка GitLab Runner
 
-Установите GitLab Runner в Kubernetes и зарегистрируйте его, следуя [официальным инструкциям](https://docs.gitlab.com/runner/register/index.html).
+Следуйте [официальным инструкциям](https://docs.gitlab.com/runner/install/) для установки и регистрации GitLab Runner. Если вы собираетесь устанавливать ваш GitLab Runner в Kubernetes, то установите его в namespace `gitlab-ci`.
 
-### Настройка GitLab Runner
+### Базовая настройка GitLab Runner (без кеширования)
 
-Измените конфигурацию зарегистрированного GitLab Runner'а, добавив в его `config.toml` следующие параметры:
+Добавьте следующее в конфигурационный файл GitLab Runner `config.toml`:
 
 ```toml
 [[runners]]
-  name = "<имя зарегистрированного Runner'а>"
+  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true"]
+
   [runners.kubernetes]
     namespace = "gitlab-ci"
+
     [runners.kubernetes.pod_annotations]
       "container.apparmor.security.beta.kubernetes.io/build" = "unconfined"
+
     [runners.kubernetes.pod_security_context]
       run_as_non_root = true
       run_as_user = 1000
       run_as_group = 1000
       fs_group = 1000
-```
-
-Добавьте следующие параметры, чтобы включить кеширование `.werf` и `/builds` (рекомендуется):
 
-```toml
-[[runners]]
-  name = "<имя зарегистрированного Runner'а>"
-  [runners.kubernetes]
-    [[runners.kubernetes.volumes.pvc]]
+    [[runners.kubernetes.volumes.empty_dir]]
       name = "gitlab-ci-kubernetes-executor-werf-cache"
       mount_path = "/home/build/.werf"
-    [[runners.kubernetes.volumes.pvc]]
+
+    [[runners.kubernetes.volumes.empty_dir]]
       name = "gitlab-ci-kubernetes-executor-builds-cache"
       mount_path = "/builds"
+
+    [[runners.kubernetes.volumes.empty_dir]]
+      name = "gitlab-ci-kubernetes-executor-helper-home"
+      mount_path = "/home/helper"
+
+    [[runners.kubernetes.pod_spec]]
+      name = "fix helper HOME"
+      patch = '''
+        containers:
+        - name: helper
+          env:
+          - name: HOME
+            value: /home/helper
+      '''
+      patch_type = "strategic"
 ```
 
-... или эти, если кеширование не требуется:
+### Базовая настройка Gitlab Runner (с кешированием в Persistent Volumes)
+
+Добавьте следующее в конфигурационный файл GitLab Runner `config.toml`:
 
 ```toml
 [[runners]]
-  name = "<имя зарегистрированного Runner'а>"
+  environment = ["FF_USE_ADVANCED_POD_SPEC_CONFIGURATION=true"]
+
   [runners.kubernetes]
-    [[runners.kubernetes.volumes.empty_dir]]
+    namespace = "gitlab-ci"
+
+    [runners.kubernetes.pod_annotations]
+      "container.apparmor.security.beta.kubernetes.io/build" = "unconfined"
+
+    [runners.kubernetes.pod_security_context]
+      run_as_non_root = true
+      run_as_user = 1000
+      run_as_group = 1000
+      fs_group = 1000
+
+    [[runners.kubernetes.volumes.pvc]]
       name = "gitlab-ci-kubernetes-executor-werf-cache"
       mount_path = "/home/build/.werf"
-    [[runners.kubernetes.volumes.empty_dir]]
+
+    [[runners.kubernetes.volumes.pvc]]
       name = "gitlab-ci-kubernetes-executor-builds-cache"
       mount_path = "/builds"
-```
-
-Добавьте еще один параметр, если планируете развертывать приложения с помощью werf на том же кластере, на котором запущен GitLab Runner:
 
-```toml
-[[runners]]
-  name = "<имя зарегистрированного Runner'а>"
-  [runners.kubernetes]
-    service_account = "gitlab-ci-kubernetes-executor"
+    [[runners.kubernetes.volumes.pvc]]
+      name = "gitlab-ci-kubernetes-executor-helper-home"
+      mount_path = "/home/helper"
+
+    [[runners.kubernetes.pod_spec]]
+      name = "fix helper HOME"
+      patch = '''
+        containers:
+        - name: helper
+          env:
+          - name: HOME
+            value: /home/helper
+      '''
+      patch_type = "strategic"
+
+    [[runners.kubernetes.pod_spec]]
+      name = "fix volumes permissions"
+      patch = '''
+        initContainers:
+        - name: fix-volumes-permissions
+          image: alpine
+          command:
+          - sh
+          - -ec
+          - |
+            chown :$(id -g) /home/build/.werf /builds /home/helper
+            chmod g+rwx /home/build/.werf /builds /home/helper
+          securityContext:
+            runAsUser: 0
+            runAsNonRoot: false
+          volumeMounts:
+          - mountPath: /home/build/.werf
+            name: gitlab-ci-kubernetes-executor-werf-cache
+          - mountPath: /builds
+            name: gitlab-ci-kubernetes-executor-builds-cache
+          - mountPath: /home/helper
+            name: gitlab-ci-kubernetes-executor-helper-home
+      '''
+      patch_type = "strategic"
 ```
 
-При необходимости проведите [дополнительную настройку](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) GitLab Runner'а.
-
-### Настройка Kubernetes
-
-Если вы включили кеширование `.werf` и `/builds` в конфигурации GitLab Runner'а, создайте соответствующие PersistentVolumeClaims в кластере, например:
+Создайте PVC:
 
 ```shell
-$ kubectl create -f - <<EOF
+kubectl create -f - <<EOF
 ---
 apiVersion: v1
 kind: PersistentVolumeClaim
@@ -97,13 +151,29 @@ spec:
   resources:
     requests:
       storage: 30Gi
+---
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: gitlab-ci-kubernetes-executor-helper-home
+  namespace: gitlab-ci
+spec:
+  accessModes:
+    - ReadWriteMany
+  resources:
+    requests:
+      storage: 30Gi
 EOF
 ```
 
-Если планируется развертывать приложения в том же кластере, в котором запущен GitLab Runner, настройте RBAC в кластере для запуска GitLab Runner'а с помощью следующей команды:
+### Настройте доступ к Kubernetes из GitLab Executor Pod'ов
+
+werf будет запускаться в GitLab Executor Pod'ах. Скорее всего вы будете деплоить с werf в тот же кластер, в котором запускаются GitLab Executor Pod'ы. Если так, то вам нужно настроить отдельные ServiceAccount и ClusterRoleBinding.
+
+Создайте ServiceAccount и ClusterRoleBinding:
 
 ```shell
-$ kubectl create -f - <<EOF
+kubectl create -f - <<EOF
 ---
 apiVersion: v1
 kind: ServiceAccount
@@ -126,12 +196,30 @@ subjects:
 EOF
 ```
 
-> Для большей безопасности создайте более ограниченную роль ClusterRole/Role и используйте ее вместо указанной выше роли `cluster-admin`.
+> Для большей безопасности подумайте над использованием более ограниченной в правах ClusterRole/Role и используйте её вместо `cluster-admin` ClusterRole выше.
+
+Теперь добавьте эту строку в конфигурационный файл GitLab Runner `config.toml`:
+
+```toml
+[[runners]]
+  [runners.kubernetes]
+    service_account = "gitlab-ci-kubernetes-executor"
+```
+
+### Установка Argo CD Image Updater
 
-Если узлы Kubernetes, на которых размещен GitLab Runner, работают с ядром Linux версии 5.12 или ниже, включите FUSE для GitLab Runner'а в этом кластере с помощью следующей команды:
+Установите Argo CD Image Updater с патчем ["continuous deployment of OCI Helm chart type application"](https://github.com/argoproj-labs/argocd-image-updater/pull/405):
 
 ```shell
-$ kubectl create -f - <<EOF
+kubectl apply -n argocd -f https://raw.githubusercontent.com/werf/3p-argocd-image-updater/master/manifests/install.yaml
+```
+
+### Разрешите использование FUSE (для Kubernetes Nodes с ядром Linux старее, чем 5.13)
+
+Если Kubernetes Nodes, на которых вы будете запускать Kubernetes Executor Pods, имеют версию ядра Linux старее 5.13, то вам нужно разрешить использование FUSE:
+
+```shell
+kubectl create -f - <<EOF
 ---
 apiVersion: apps/v1
 kind: DaemonSet
@@ -176,21 +264,20 @@ spec:
 EOF
 ```
 
-### Настройка container registry
-
-[Включите сборку мусора](https://docs.gitlab.com/ee/administration/packages/container_registry.html#container-registry-garbage-collection) в своем container registry.
-
-### Подготовка Kubernetes для многоплатформенной сборки (опционально)
+### Настройка Kubernetes для мульти-платформенных сборок (опционально)
 
-> Этот шаг необходим только если собираются образы для платформ, отличных от хост-платформы, на которой запущен werf.
+{% include configurator/partials/ci/cross_platform_note.md.liquid %}
 
-С помощью qemu-user-static зарегистрируйте эмуляторы в Kubernetes:
+Активируйте эмуляторы для ваших Kubernetes Nodes, используя qemu-user-static:
 
-```yaml
+```shell
+kubectl create -f - <<EOF
+---
 apiVersion: apps/v1
 kind: DaemonSet
 metadata:
   name: qemu-user-static
+  namespace: gitlab-ci
   labels:
     app: qemu-user-static
 spec:
@@ -218,12 +305,8 @@ spec:
             requests:
               cpu: 50m
               memory: 50Mi
+EOF
 ```
 
-### Установка Argo CD Image Updater
-
-Установите Argo CD Image Updater с патчем ["continuous deployment of OCI Helm chart type application"](https://github.com/argoproj-labs/argocd-image-updater/pull/405):
+{% include configurator/partials/ci/configuring_the_container_registry.md.liquid %}
 
-```shell
-kubectl apply -n argocd -f https://raw.githubusercontent.com/werf/3p-argocd-image-updater/master/manifests/install.yaml
-```
diff --git a/bin/configurator/static/_includes/ru/configurator/tab/ci/other-ci-cd-system/simple/kubernetes-runner/linux/buildah/infra.md.liquid b/bin/configurator/static/_includes/ru/configurator/tab/ci/other-ci-cd-system/simple/kubernetes-runner/linux/buildah/infra.md.liquid
index e51c9a52a..0c837ca0d 100644
--- a/bin/configurator/static/_includes/ru/configurator/tab/ci/other-ci-cd-system/simple/kubernetes-runner/linux/buildah/infra.md.liquid
+++ b/bin/configurator/static/_includes/ru/configurator/tab/ci/other-ci-cd-system/simple/kubernetes-runner/linux/buildah/infra.md.liquid
@@ -3,10 +3,10 @@
 - CI-система;
 
 - Kubernetes для запуска CI-задач с установленным Kubernetes Runner вашей CI-системы.
+-
+### Базовая настройка Runner (без кеширования)
 
-### Настройка Runner'а
-
-Настройте Kubernetes Runner вашей CI-системы так, чтобы создаваемые им Pod'ы имели следующую конфигурацию:
+Настройте раннер вашей CI-системы так, чтобы создаваемые им Pod'ы имели следующую конфигурацию:
 
 ```yaml
 apiVersion: v1
@@ -16,6 +16,13 @@ metadata:
   annotations:
     "container.apparmor.security.beta.kubernetes.io/build": unconfined
 spec:
+  containers:
+  - volumeMounts:
+    - name: werf-cache
+      mountPath: /home/build/.werf
+  volumes:
+  - name: werf-cache
+    emptyDir: {}
   securityContext:
     runAsNonRoot: true
     runAsUser: 1000
@@ -23,10 +30,33 @@ spec:
     fsGroup: 1000
 ```
 
-Если нужно кеширование `.werf` (рекомендуется), то Pod'ы должны иметь дополнительную конфигурацию:
+### Базовая настройка Runner (с кешированием в Persistent Volumes)
+
+Настройте раннер вашей CI-системы так, чтобы создаваемые им Pod'ы имели следующую конфигурацию:
 
 ```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  namespace: ci
+  annotations:
+    "container.apparmor.security.beta.kubernetes.io/build": unconfined
 spec:
+  initContainers:
+  - name: fix-volumes-permissions
+    image: alpine
+    command:
+    - sh
+    - -ec
+    - |
+      chown :$(id -g) /home/build/.werf
+      chmod g+rwx /home/build/.werf
+    securityContext:
+      runAsUser: 0
+      runAsNonRoot: false
+    volumeMounts:
+    - mountPath: /home/build/.werf
+      name: werf-cache
   containers:
   - volumeMounts:
     - name: werf-cache
@@ -35,34 +65,18 @@ spec:
   - name: werf-cache
     persistentVolumeClaim:
       claimName: ci-kubernetes-runner-werf-cache
+  securityContext:
+    runAsNonRoot: true
+    runAsUser: 1000
+    runAsGroup: 1000
+    fsGroup: 1000
 ```
 
-... а если кеширование не нужно, то пусть имеют эту конфигурацию:
-
-```yaml
-spec:
-  containers:
-  - volumeMounts:
-    - name: werf-cache
-      mountPath: /home/build/.werf
-  volumes:
-  - name: werf-cache
-    emptyDir: {}
-```
-
-Если будете развертывать приложения с werf в тот же кластер, в котором запускается Kubernetes Runner, то добавьте эту конфигурацию:
-
-```yaml
-spec:
-  serviceAccountName: ci-kubernetes-runner
-```
-
-### Настройка Kubernetes
-
-Если в конфигурации Kubernetes Runner'а вы включили кеширование `.werf`, то создайте в кластере соответствующий PersistentVolumeClaim, например:
+Создайте PVC:
 
 ```shell
 kubectl create -f - <<EOF
+---
 apiVersion: v1
 kind: PersistentVolumeClaim
 metadata:
@@ -77,7 +91,11 @@ spec:
 EOF
 ```
 
-Если будете развертывать приложения в тот же кластер, в котором запускается Kubernetes Runner, то в кластере для запуска CI-задач настройте RBAC следующей командой:
+### Настройте доступ в Kubernetes из Runner Pod'ов
+
+Если werf запускается напрямую в Runner Pod'ах и вы собираетесь деплоить с werf в тот же кластер, где запускаются Runner Pod'ы, то вам нужно настроить отдельные ServiceAccount и ClusterRoleBinding.
+
+Создайте ServiceAccount и ClusterRoleBinding:
 
 ```shell
 kubectl create -f - <<EOF
@@ -103,9 +121,18 @@ subjects:
 EOF
 ```
 
-> Для большей безопасности можете создать более ограниченную ClusterRole/Role и использовать её вместо кластерной роли `cluster-admin` выше.
+> Для большей безопасности подумайте над использованием более ограниченной в правах ClusterRole/Role и используйте её вместо `cluster-admin` ClusterRole выше.
 
-Если Kubernetes-узлы для Kubernetes Runner'а имеют ядро Linux версии 5.12 или ниже, то разрешите в этом кластере использование FUSE для Kubernetes Runner следующей командой:
+Теперь добавьте эту строку в Pod, создаваемый вашим раннером:
+
+```yaml
+spec:
+  serviceAccountName: ci-kubernetes-runner
+```
+
+### Разрешите использование FUSE (для Kubernetes Nodes с ядром Linux старее, чем 5.13)
+
+Если Kubernetes Nodes, на которых вы будете запускать Runner Pods, имеют версию ядра Linux старее 5.13, то вам нужно разрешить использование FUSE:
 
 ```shell
 kubectl create -f - <<EOF
@@ -153,15 +180,11 @@ spec:
 EOF
 ```
 
-### Конфигурация container registry
-
-[Включите сборщик мусора]({{ "/docs/v2/usage/cleanup/cr_cleanup.html#%D1%81%D0%B1%D0%BE%D1%80%D1%89%D0%B8%D0%BA-%D0%BC%D1%83%D1%81%D0%BE%D1%80%D0%B0-container-registry" | relative_url }}) вашего container registry.
-
-### Подготовка кластера Kubernetes к мультиплатформенной сборке (опционально)
+### Настройка Kubernetes для мульти-платформенных сборок (опционально)
 
-> Данный шаг требуется только для сборки образов для платформ, отличных от платформы системы, где запущен werf.
+> Этот шаг нужен только для сборки образов для платформ, отличных от платформы системы, где запущен werf.
 
-Регистрируем на узлах Kubernetes эмуляторы с помощью образа qemu-user-static:
+Активируйте эмуляторы для ваших Kubernetes Nodes, используя qemu-user-static:
 
 ```shell
 kubectl create -f - <<EOF
@@ -170,6 +193,7 @@ apiVersion: apps/v1
 kind: DaemonSet
 metadata:
   name: qemu-user-static
+  namespace: ci
   labels:
     app: qemu-user-static
 spec:
@@ -199,3 +223,7 @@ spec:
               memory: 50Mi
 EOF
 ```
+
+### Конфигурация container registry
+
+[Включите сборщик мусора]({{ "/docs/v2/usage/cleanup/cr_cleanup.html#%D1%81%D0%B1%D0%BE%D1%80%D1%89%D0%B8%D0%BA-%D0%BC%D1%83%D1%81%D0%BE%D1%80%D0%B0-container-registry" | relative_url }}) вашего container registry.