From 7f841c3aec30f6331342dbeeb051aba00e16de9c Mon Sep 17 00:00:00 2001
From: Ekaterina Kazakova <eromanova@mirantis.com>
Date: Mon, 14 Oct 2024 23:44:39 +0400
Subject: [PATCH] Add docs about cluster updates and template management

---
 docs/template/template-management.md | 54 ++++++++++++++++++++++++++++
 docs/update/cluster-update.md        | 30 ++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 docs/template/template-management.md
 create mode 100644 docs/update/cluster-update.md

diff --git a/docs/template/template-management.md b/docs/template/template-management.md
new file mode 100644
index 0000000..33612d2
--- /dev/null
+++ b/docs/template/template-management.md
@@ -0,0 +1,54 @@
+# Template LifeCycle Management
+
+Cluster and Service Templates can be delivered to target namespaces using the `TemplateManagement`,
+`ClusterTemplateChain` and `ServiceTemplateChain` objects. `TemplateManagement` object contains the list of
+access rules to apply. Each access rule contains the namespaces' definition to deliver templates into and
+the template chains. Each `ClusterTemplateChain` and `ServiceTemplateChain` contains the supported templates
+and the upgrade sequences for them.
+
+The example of the Cluster Template Management:
+
+1. Create `ClusterTemplateChain` object in the system namespace (defaults to `hmc-system`). Properly configure
+   the list of `availableUpgrades` for the specified `ClusterTemplate` if the upgrade is allowed. For example:
+
+```yaml
+apiVersion: hmc.mirantis.com/v1alpha1
+kind: ClusterTemplateChain
+metadata:
+  name: aws
+  namespace: hmc-system
+spec:
+  supportedTemplates:
+    - name: aws-standalone-cp-0-0-1
+      availableUpgrades:
+        - name: aws-standalone-cp-0-0-2
+    - name: aws-standalone-cp-0-0-2
+```
+
+2. Edit `TemplateManagement` object and configure the `spec.accessRules`.
+   For example, to apply all templates and upgrade sequences defined in the `aws` `ClusterTemplateChain` to the
+   `default` namespace, the following `accessRule` should be added:
+
+```yaml
+spec:
+  accessRules:
+  - targetNamespaces:
+      list:
+        - default
+    clusterTemplateChains:
+      - aws
+```
+
+The HMC controllers will deliver all the `ClusterTemplate` objects across the target namespaces.
+As a result, the new objects should be created:
+
+* `ClusterTemplateChain` `default/aws`
+* `ClusterTemplate` `default/aws-standalone-cp-0-0-1`
+* `ClusterTemplate` `default/aws-standalone-cp-0-0-2` (available for the upgrade from `aws-standalone-cp-0-0-1`)
+
+> [!NOTE]
+> 1. The target `ClusterTemplate` defined as the available for the upgrade should reference the same helm chart name
+> as the source `ClusterTemplate`. Otherwise, after the upgrade is triggered, the cluster will be removed and then,
+> recreated from scratch even if the objects in the helm chart are the same.
+> 2. The target template should not affect immutable fields or any other incompatible internal objects upgrades,
+> otherwise the upgrade will fail.
diff --git a/docs/update/cluster-update.md b/docs/update/cluster-update.md
new file mode 100644
index 0000000..035ed8c
--- /dev/null
+++ b/docs/update/cluster-update.md
@@ -0,0 +1,30 @@
+# Managed Cluster update
+
+To update the `ManagedCluster` update `spec.template` in the `ManagedCluster` object to the new `ClusterTemplate` name:
+
+Run:
+
+```bash
+kubectl edit managedcluster.hmc <cluster-name> -n <cluster-namespace>
+```
+
+and set `spec.template` to the new template name.
+
+Then, check the status of the `ManagedCluster` object:
+
+```bash
+kubectl get managedcluster.hmc <cluster-name> -n <cluster-namespace>
+```
+
+To get more details, run the previous command with `-o=yaml` option and check the `status.conditions`.
+
+> [!NOTE]
+> The `ManagedCluster` is allowed to be updated to the specific templates only. The templates available for the update
+> are defined in the `ClusterTemplateChain` objects. Also, the `TemplateManagement` object should contain properly
+> configured `spec.accessRules` with the list of `ClusterTemplateChain` object names and the namespaces where
+> the supported templates from the chain spec will be delivered. For details, see:
+> [Template LifeCycle Management](../template/template-management.md#template-lifecycle-management)
+
+<!---
+TODO: Later all `ClusterTemplates` that are available for the update will be shown in the `ManagedCluster` status.
+-->