From 1b35c5e5cd9709093cf1375085022e7760c596a2 Mon Sep 17 00:00:00 2001 From: Ekaterina Kazakova <41469478+eromanova@users.noreply.github.com> Date: Tue, 10 Dec 2024 18:22:08 +0400 Subject: [PATCH] Update BYO templates documentation (#51) Relates to https://github.com/Mirantis/hmc/issues/615 Related hmc core changes: https://github.com/Mirantis/hmc/pull/699 Closes #50 --- docs/template/byo-templates.md | 131 ++++++++++++++++++++++----------- 1 file changed, 87 insertions(+), 44 deletions(-) diff --git a/docs/template/byo-templates.md b/docs/template/byo-templates.md index d401a29..df34b3e 100644 --- a/docs/template/byo-templates.md +++ b/docs/template/byo-templates.md @@ -1,25 +1,23 @@ # Bring your own Templates -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. Label it with `hmc.mirantis.com/managed: "true"`. -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. Label it with `hmc.mirantis.com/managed: "true"`. -3. Create a `ClusterTemplate`, `ServiceTemplate` or `ProviderTemplate` object 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. -For `ClusterTemplate` and `ServiceTemplate` configure the namespace where this template should reside -(`metadata.namespace`). +This guide outlines the steps to bring your own Template to HMC. -> NOTE: -> `ClusterTemplate` and `ServiceTemplate` objects should reside in the same namespace as the `ManagedCluster` -> referencing them. The `ManagedCluster` can't reference the Template from another namespace (the creation request will -> be declined by the admission webhook). All `ClusterTemplates` and `ServiceTemplates` shipped with HMC reside in the -> system namespace (defaults to `hmc-system`). To get the instructions on how to distribute Templates along multiple -> namespaces, read [Template Life Cycle Management](main.md#template-life-cycle-management). +## Create a Source Object + +> INFO: +> Skip this step if you're using an existing source. -Here is an example of a custom `ClusterTemplate` with the `HelmChart` reference: +A source object defines where the Helm chart is stored. The source can be one of the following types: +[HelmRepository](https://fluxcd.io/flux/components/source/helmrepositories/), +[GitRepository](https://fluxcd.io/flux/components/source/gitrepositories/) or +[Bucket](https://fluxcd.io/flux/components/source/buckets/). + +> NOTES: +> 1. The source object must exist in the same namespace as the Template. +> 2. For cluster-scoped `ProviderTemplates`, the referenced source must reside in the **system** namespace +> (default: `hmc-system`). + +### Example: Custom Source Object with HelmRepository Kind ```yaml apiVersion: source.toolkit.fluxcd.io/v1 @@ -27,8 +25,6 @@ kind: HelmRepository metadata: name: custom-templates-repo namespace: hmc-system - labels: - hmc.mirantis.com/managed: "true" spec: insecure: true interval: 10m0s @@ -37,49 +33,96 @@ spec: url: oci://ghcr.io/external-templates-repo/charts ``` +## Create the Template + +Create a Template object of the desired type: + +* `ClusterTemplate` +* `ServiceTemplate` +* `ProviderTemplate` + +For `ClusterTemplate` and `ServiceTemplate` configure the namespace where this template should reside +(`metadata.namespace`). +The custom Template requires a helm chart definition in the `.spec.helm.chartSpec` field of the +[HelmChartSpec](https://fluxcd.io/flux/components/source/api/v1/#source.toolkit.fluxcd.io/v1.HelmChartSpec) kind or +the reference to already existing `HelmChart` object in `.spec.helm.chartRef`. + +> NOTE: +> `spec.helm.chartSpec` and `spec.helm.chartRef` are mutually exclusive. + +To automatically create the `HelmChart` for the `Template`, configure the following custom helm chart parameters +under `spec.helm.chartSpec`: + +| **Field** | **Description** | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| +| `sourceRef`
[LocalHelmChartSourceReference](https://fluxcd.io/flux/components/source/api/v1/#source.toolkit.fluxcd.io/v1.LocalHelmChartSourceReference) | Reference to the source object (e.g., `HelmRepository`, `GitRepository`, or `Bucket`) in the same namespace as the Template. | +| `chart`
string | The name of the Helm chart available in the source. | +| `version`
string | Version is the chart version semver expression. Defaults to **latest** when omitted. | +| `interval`
[Kubernetes meta/v1.Duration](https://pkg.go.dev/k8s.io/apimachinery/pkg/apis/meta/v1#Duration) | The frequency at which the `sourceRef` is checked for updates. Defaults to **10 minutes**. | + +For the complete list of the `HelmChart` parameters, see: +[HelmChartSpec](https://fluxcd.io/flux/components/source/api/v1/#source.toolkit.fluxcd.io/v1.HelmChartSpec). + +The controller will automatically create the `HelmChart` object based on the chartSpec defined in +`.spec.helm.chartSpec`. + +> NOTE: +> `ClusterTemplate` and `ServiceTemplate` objects should reside in the same namespace as the `ManagedCluster` +> referencing them. The `ManagedCluster` can't reference the Template from another namespace (the creation request will +> be declined by the admission webhook). All `ClusterTemplates` and `ServiceTemplates` shipped with HMC reside in the +> system namespace (defaults to `hmc-system`). To get the instructions on how to distribute Templates along multiple +> namespaces, read [Template Life Cycle Management](main.md#template-life-cycle-management). + +### Example: Custom ClusterTemplate with the Chart Definition to Create a new HelmChart + ```yaml -apiVersion: source.toolkit.fluxcd.io/v1 -kind: HelmChart +apiVersion: hmc.mirantis.com/v1alpha1 +kind: ClusterTemplate metadata: - name: custom-template-chart + name: custom-template namespace: hmc-system - labels: - hmc.mirantis.com/managed: "true" spec: - interval: 5m0s - chart: custom-template-chart-name - reconcileStrategy: ChartVersion - sourceRef: - kind: HelmRepository - name: custom-templates-repo - version: 0.2.0 + providers: + - bootstrap-k0smotron + - control-plane-k0smotron + - infrastructure-openstack + helm: + chartSpec: + chart: os-k0smotron + sourceRef: + kind: HelmRepository + name: custom-templates-repo ``` +### Example: Custom ClusterTemplate Referencing an Existing HelmChart object + ```yaml apiVersion: hmc.mirantis.com/v1alpha1 kind: ClusterTemplate metadata: - name: os-k0smotron + name: custom-template namespace: hmc-system spec: - providers: - - bootstrap-k0smotron - - control-plane-k0smotron - - infrastructure-openstack helm: chartRef: kind: HelmChart - name: custom-template-chart - namespace: default + name: custom-chart ``` -The `*Template` should follow the rules mentioned below: -`.spec.providers` should contain the list of required Cluster API providers: `infrastructure`, `bootstrap` and -`control-plane`. 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: +## Required and exposed providers definition + +The `*Template` object must specify the list of Cluster API providers that are either **required** (for +`ClusterTemplates` and `ServiceTemplates`) or **exposed** (for `ProviderTemplates`). These providers include +`infrastructure`, `bootstrap`, and `control-plane`. This can be achieved in two ways: + +1. By listing the providers explicitly in the `spec.providers` field. +2. Alternatively, by including specific annotations in the `Chart.yaml` of the referenced Helm chart. +The annotations should list the providers as a `comma-separated` value. + +For example: -`ClusterTemplate` spec: +`Template` spec: ```yaml spec: