From d4032375376da1c226f75f36074da7535172a2cf Mon Sep 17 00:00:00 2001
From: eromanova <eromanova@mirantis.com>
Date: Thu, 25 Jul 2024 18:15:28 +0400
Subject: [PATCH] Document Template system

HMC-102
---
 README.md              |   2 +
 docs/templates/main.md | 128 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 130 insertions(+)
 create mode 100644 docs/templates/main.md

diff --git a/README.md b/README.md
index cc866d188..cf61bd6d3 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,8 @@ export KUBECONFIG=<path-to-management-kubeconfig>
 kubectl get template -n hmc-system -o go-template='{{ range .items }}{{ if eq .status.type "deployment" }}{{ .metadata.name }}{{ printf "\n" }}{{ end }}{{ end }}'
 ```
 
+For details about the `Template system` in HMC, see [Templates system](docs/templates/main.md#templates-system).
+
 2. Create the file with the `Deployment` configuration:
 
 > Substitute the parameters enclosed in angle brackets with the corresponding values.\
diff --git a/docs/templates/main.md b/docs/templates/main.md
new file mode 100644
index 000000000..6327340f1
--- /dev/null
+++ b/docs/templates/main.md
@@ -0,0 +1,128 @@
+# Templates system
+
+By default, Hybrid Container Cloud delivers a set of default `Template` objects. You can also build your own templates
+and use them for deployment.
+
+## Custom deployment Templates
+
+> At the moment all `Templates` should reside in the `hmc-system` namespace. But they can be referenced
+> by `Deployments` from any namespace.
+
+Here are the instructions on how to bring your own Template to HMC:
+
+1. Create a [HelmRepository](https://fluxcd.io/flux/components/source/helmrepositories/) object containing the URL to the
+external Helm repository.
+2. Create a [HelmChart](https://fluxcd.io/flux/components/source/helmcharts/) object referencing the `HelmRepository` as a
+`sourceRef`, specifying the name and version of your Helm chart.
+3. Create a `Template` object in `hmc-system` namespace referencing this helm chart in `spec.helm.chartRef`.
+`chartRef` is a field of the
+[CrossNamespaceSourceReference](https://fluxcd.io/flux/components/helm/api/v2/#helm.toolkit.fluxcd.io/v2.CrossNamespaceSourceReference) kind.
+
+Here is an example of a custom `Template` with the `HelmChart` reference:
+
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: HelmRepository
+metadata:
+  name: custom-templates-repo
+  namespace: hmc-system
+spec:
+  insecure: true
+  interval: 10m0s
+  provider: generic
+  type: oci
+  url: oci://ghcr.io/external-templates-repo/charts
+```
+
+```yaml
+apiVersion: source.toolkit.fluxcd.io/v1
+kind: HelmChart
+metadata:
+  name: custom-template-chart
+  namespace: hmc-system
+spec:
+  interval: 5m0s
+  chart: custom-template-chart-name
+  reconcileStrategy: ChartVersion
+  sourceRef:
+    kind: HelmRepository
+    name: custom-templates-repo
+  version: 0.2.0
+```
+
+```yaml
+apiVersion: hmc.mirantis.com/v1alpha1
+kind: Template
+metadata:
+  name: os-k0smotron
+  namespace: hmc-system
+spec:
+  type: deployment
+  providers:
+    infrastructure:
+      - openstack
+    bootstrap:
+      - k0s
+    controlPlane:
+      - k0smotron
+  helm:
+    chartRef:
+      kind: HelmChart
+      name: custom-template-chart
+      namespace: default
+```
+
+The `Template` should follow the rules mentioned below:
+1. `spec.type` should be `deployment` (as an alternative, the referenced helm chart may contain the
+`hmc.mirantis.com/type: deployment` annotation in `Chart.yaml`).
+2. `spec.providers` should contain the list of required Cluster API providers: `infrastructure`, `bootstrap` and
+`controlPlane`. As an alternative, the referenced helm chart may contain the specific annotations in the
+`Chart.yaml` (value is a list of providers divided by comma). These fields are only used for validation. For example:
+
+`Template` spec:
+
+```yaml
+spec:
+  providers:
+    infrastructure:
+      - aws
+    bootstrap:
+      - k0s
+    controlPlane:
+      - k0smotron
+```
+
+`Chart.yaml`:
+
+```bash
+annotations:
+  hmc.mirantis.com/infrastructure-providers: aws
+  hmc.mirantis.com/controlplane-providers: k0smotron
+  hmc.mirantis.com/bootstrap-providers: k0s
+```
+
+## Remove Templates shipped with HMC
+
+If you need to limit the cluster templates that exist in your HMC installation, follow the instructions below:
+
+1. Get the list of `deployment` Templates shipped with HMC:
+
+```bash
+kubectl get templates -n hmc-system -l helm.toolkit.fluxcd.io/name=hmc-templates  | grep deployment
+```
+
+Example output:
+```bash
+aws-hosted-cp              deployment   true
+aws-standalone-cp          deployment   true
+```
+
+2. Remove the templates from the list:
+
+```bash
+kubectl delete template -n hmc-system <template-name>
+
+```
+<!---
+TODO: document `--create-template=false` controller flag once the templates are limited to deployment templates only.
+-->