How to create kunai Template

Objectives

This tutorial will explain how to create a template for Kunai and how to update it.

Prerequisites

A Sylva management cluster with a provider for the desired environment.

High-Level Design

Lifecycle

Templates are GitRepositories with Release tags. Developers should commit all changes and propose them as merge requests. They should validate on their side that the template is working as expected. A tag is pushed to the commit when the template is considered mature enough to be globally available.

Release tags are essential for versioning and managing the lifecycle of templates in Kunai. This section outlines the steps to create and manage these tags effectively.

Tag Formats

Delivery Tags:
- Format: 1.0.10
- Characteristics: Non-modifiable and non-reusable.
Development/Integration Tags:
- Format: 1.0.10dev
- Characteristics: Indicates a development or integration version.

Steps to Create a New Release Tag

Determine the Version: Decide on the new version number following the appropriate format.
Update the Template: Ensure that the template is updated and tested thoroughly before tagging.
Commit Changes: Commit the changes to the Git repository with a clear message indicating the version update.
Create the Tag: Use the following Git command to create a new tag:
```
git tag -a <tag_name> -m "Release <tag_name>"
```
Replace with the appropriate version format (e.g., 1.0.10 or 1.0.10dev).
Push the Tag: Push the newly created tag to the remote repository:
```
git push origin <tag_name>
```
Document Release Notes: Create a release-notes.md or release-notes.txt file that includes:
- Functional Enhancements and Changes: Detail the functional enhancements or changes introduced in this release. This should include new features, improvements to existing functionalities, and any deprecated features. Providing clear descriptions will help users quickly grasp the benefits of the new release.
- Matrix Compatibility Test Explanation: Provide a comprehensive explanation of the matrix compatibility test conducted. This should cover:
  - The version of the management cluster.
  - The minimum required version of kunai.
  - The version of the deployed workload cluster.
  - Include any specific scenarios tested and the outcomes, ensuring users understand how different versions interact and the implications for their deployments.

Best Practices

Ensure that all changes are validated and tested before tagging.
Follow semantic versioning principles to maintain clarity in versioning.
Keep the release notes updated with each new tag to facilitate better understanding for users.

Namespace Explanation

First, we need to understand how Kunai operates with GitOps using Flux.

kunai-namespace-design

Gitrepository namespace

When registering a GitRepository in Kunai, a dedicated namespace is created to host all resources required for the workload cluster. The namespace should follow this naming convention:

<git_repository_name>

Info

Discussion are ongoing about implementing the following naming convention

kunai-gitrepository--<git_repository_name>

The following resources are required:

Created by Kunai:
- GitRepository: Points to the Git repository to be synchronized using FluxCD.
- Secret: Hosts the credentials and ca.crt for accessing the GitRepository.
- Kustomize: Configures FluxCD to reconcile the GitRepository.
Created by Administrator:
- SecretStore: Currently, a ClusterSecretStore is used. This will transition to a SecretStore placed in each GitRepository namespace to access only authorized secrets for the GitRepository.

In Kunai, workload clusters are created using templates, which generate Kubernetes resources that define the workload cluster. These resources are referred to as root units.

Workload cluster namespace definition

This namespace is dedicated to each workload cluster, hosting all resources responsible for its creation. These resources are termed Sylva units. The namespace should follow this naming convention:

<workload_cluster_name>

Info

Discussion are ongoing about implementing the following naming convention

wc--<git_repository_name>--<workload_cluster_name>

GitRepository Structure

kunai-gitrepository-design

Templates

This folder contains all templates, following the naming convention:

<template_name>@<template_version>

Workloads

This folder contains all workload cluster definitions, following the naming convention:

<workload_cluster_name>

Kustomization.yaml

This file is a generic kustomization.yaml. All workload clusters referenced in this file will be synchronized by the FluxCD controller deployed in the management cluster. Any workload clusters in the Git repository not referenced in this file will be deleted by FluxCD.

Labels.yaml

This file is managed by Kunai and contains all available labels and the workload clusters associated with each label.

Template Structure

form.yaml

Forms are validated using JSON Schema. The documentation is available here. For readability, this JSON Schema is stored in Git in YAML format and converted to the relevant format for validating components.

readme.txt

Contains the title of the form.

uiSchema.yaml

Acts like a CSS file but in YAML format. The documentation is available here.

kustomization.template

Links to all resources that should be created to generate a workload cluster.

Other .template Files

Currently, we are using the Sylva-unit Helm release to generate the workload cluster. Thus, we need to create the namespace using a Helm release to allow for a clean deletion process.

In the future, we will use the Sylva unit operator CRD to generate the workload cluster. This operator will be responsible for generating the namespace using the naming convention.

All credentials should be retrieved from Vault using an ExternalSecret CRD. Values provided to customize the creation of the workload cluster should be provided as ConfigMaps. We can create as many ConfigMaps as needed to divide the configuration into logical elements.

Cluster Structure

formdata.yaml

This file contains the raw values provided by the user in YAML format.

info.yaml

A file used by Kunai to understand the template name and version used by the workload cluster.

.template Files

All .template files are converted to .yaml files, and the templating process is applied with the values provided by the user.