feat(docs): New article about resources adoption

https://werf.io/documentation/v1.2/advanced/helm/deploy_process/resources_adoption.html Signed-off-by: Timofey Kirillov <timofey.kirillov@flant.com>
werf · May 24, 2022 · 5ab8f26 · 5ab8f26
1 parent 967a6aa
commit 5ab8f26
Show file tree

Hide file tree

Showing 4 changed files with 62 additions and 0 deletions.
diff --git a/docs/_data/sidebars/_documentation.yml b/docs/_data/sidebars/_documentation.yml
@@ -76,6 +76,9 @@ entries:
                   - title: Annotating and labeling of chart resources
                     url: /advanced/helm/deploy_process/annotating_and_labeling.html
 
+                  - title: Resources adoption
+                    url: /advanced/helm/deploy_process/resources_adoption.html
+
               - title: Releases
                 f:
                   - title: Release
@@ -294,6 +297,9 @@ entries:
                   - title: Аннотации и лейблы для ресурсов чарта
                     url: /advanced/helm/deploy_process/annotating_and_labeling.html
 
+                  - title: Принятие ресурсов в релиз
+                    url: /advanced/helm/deploy_process/resources_adoption.html
+
               - title: Релизы
                 f:
                   - title: Релиз

diff --git a/docs/_data/sidebars/documentation.yml b/docs/_data/sidebars/documentation.yml
@@ -744,6 +744,9 @@ entries:
                   - title: Annotating and labeling of chart resources
                     url: /advanced/helm/deploy_process/annotating_and_labeling.html
 
+                  - title: Resources adoption
+                    url: /advanced/helm/deploy_process/resources_adoption.html
+
               - title: Releases
                 f:
                   - title: Release
@@ -962,6 +965,9 @@ entries:
                   - title: Аннотации и лейблы для ресурсов чарта
                     url: /advanced/helm/deploy_process/annotating_and_labeling.html
 
+                  - title: Принятие ресурсов в релиз
+                    url: /advanced/helm/deploy_process/resources_adoption.html
+
               - title: Релизы
                 f:
                   - title: Релиз

diff --git a/docs/pages_en/advanced/helm/deploy_process/resources_adoption.md b/docs/pages_en/advanced/helm/deploy_process/resources_adoption.md
@@ -0,0 +1,25 @@
+---
+title: Resources adoption
+permalink: advanced/helm/deploy_process/resources_adoption.html
+---
+
+By default Helm and werf can only manage resources that was created by the Helm or werf itself. If you try to deploy chart with the new resource in the `.helm/templates` that already exists in the cluster and was created outside werf then the following error will occur:
+
+```
+Error: helm upgrade have failed: UPGRADE FAILED: rendered manifests contain a resource that already exists. Unable to continue with update: KIND NAME in namespace NAMESPACE exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to RELEASE_NAME; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to RELEASE_NAMESPACE
+```
+
+This error prevents destructive behaviour when some existing resource would occasionally become part of helm release.
+
+However, if it is the desired outcome, then edit this resource in the cluster and set the following annotations and labels:
+
+```yaml
+metadata:
+  annotations:
+    meta.helm.sh/release-name: "RELEASE_NAME"
+    meta.helm.sh/release-namespace: "NAMESPACE"
+  labels:
+    app.kubernetes.io/managed-by: Helm
+```
+
+After the next deploy this resource will be adopted into the new release revision. Resource will be updated to the state defined in the chart manifest.
diff --git a/docs/pages_ru/advanced/helm/deploy_process/resources_adoption.md b/docs/pages_ru/advanced/helm/deploy_process/resources_adoption.md
@@ -0,0 +1,25 @@
+---
+title: Принятие ресурсов в релиз
+permalink: advanced/helm/deploy_process/resources_adoption.html
+---
+
+По умолчанию Helm и werf позволяют управлять лишь теми ресурсами, которые были созданы самим Helm или werf в рамках релиза. При попытке выката чарта с манифестом ресурса, который уже существует в кластере и который был создан не с помощью Helm или werf, тогда возникнет следующая ошибка:
+
+```
+Error: helm upgrade have failed: UPGRADE FAILED: rendered manifests contain a resource that already exists. Unable to continue with update: KIND NAME in namespace NAMESPACE exists and cannot be imported into the current release: invalid ownership metadata; label validation error: missing key "app.kubernetes.io/managed-by": must be set to "Helm"; annotation validation error: missing key "meta.helm.sh/release-name": must be set to RELEASE_NAME; annotation validation error: missing key "meta.helm.sh/release-namespace": must be set to RELEASE_NAMESPACE
+```
+
+Данная ошибка предотвращает деструктивное поведение, когда некоторый уже существующий релиз случайно становится частью выкаченного релиза.
+
+Однако если данное поведение является желаемым, то требуется отредактировать целевой ресурс в кластере и добавить в него следующие аннотации и лейблы:
+
+```yaml
+metadata:
+  annotations:
+    meta.helm.sh/release-name: "RELEASE_NAME"
+    meta.helm.sh/release-namespace: "NAMESPACE"
+  labels:
+    app.kubernetes.io/managed-by: Helm
+```
+
+После следующего деплоя этот ресурс будет принят в новую ревизию релиза и соотвественно будет приведен к тому состоянию, которое описано в манифесте чарта.