TRG 5.02 - Chart structure

Status	Created	Post-History
Draft	17-Jul-2023	templates/NOTES.txt made optional
Active	10-Jan-2023	add prerequisite and TL;DR as requirement in README.md
Active	10-Nov-2022	Initial release

Why

Following best practices when creating the chart helps everyone better understand, deploy and test the product. Having similar structure for every Helm chart enables easy understand, simple implementation of testing and deployment workflows.

Having the helm chart in the same directory than everyone else allows for easy finding the right helm chart.

Description

Each Helm chart should follow a specific structure. Helm provides recommendations for creating charts.

For Eclipse Tractus-X Helm charts the following requirements must be met:

• Helm chart location inside Git repository
• Helm chart file structure defined below

Chart Location

Helm charts must be located inside the /charts directory of the Git repository.

charts/
  chartNameA/
    Chart.yaml
    ...
  chartNameB/
    Chart.yaml
    ...
AUTHORS.md
DEPENDENCIES.md
LICENSE
README.md

For further details about the Git repository structure, please refer to TRG 2.03 - Repo Structure.

Chart File Structure

License/Copyright Headers required

It is mandatory to add a valid license/copyright header to each file (except of rendered files, e.g. Markdown files) in the Git repository!

For further details, please refer to How to make your Catena-X product OSS ready.

For Eclipse Tractus-X Helm charts we expect the following charts structure as a minimal set (except of optional parts):

chartName/
  .helmignore          # mandatory
  Chart.yaml           # mandatory
  LICENSE              # mandatory
  README.md            # mandatory
  values.yaml          # mandatory
  crds/                # optional
  templates/           # mandatory, except of umbrella Helm charts
  templates/NOTES.txt  # optional 

For further details on Helm chart basics, please refer to Helm documentation.

The Chart.yaml File

The following represents the minimum set of expected fields in Chart.yaml file:

apiVersion: The chart API Version
name: The name of the chart
appVersion: The application version the chart will install
version: A SemVer 2 version of the chart
description: A brief description of the chart
home: The URL of the product home page
sources:
  - A list of URLs to source code of this project
dependencies: # A list of the chart requirements (if any)
  - name: The name of the chart
    version: The version of the chart
    repository: The repository URL
maintainers: # Optional, could become mandatory in Eclipse repositories
  - name: Maintainers name
    email: optional
    url: A URL for the maintainer, optional

For further details about the Chart.yaml file please refer to Helm documentation.

The LICENSE File

The file must contain the Apache 2.0 License.

The README.md File

The README.md file must contain:

• a brief explanation of what the Helm chart will install

• a section of "Prerequisites" includes the required kubernetes version, helm version and other necessary prerequisites and their versions. Example:

  - Kubernetes 1.19+
  - Helm 3.2.0+
  - PV provisioner support in the underlying infrastructure

• a section of "TL;DR" that includes the helm commands to add and install the helm chart, Example:

  helm repo add my-repo https://charts.bitnami.com/bitnami
  helm install my-release my-repo/postgresql

• documentation of default values for this Helm chart (helm-docs may help).

The values.yaml File

The values.yaml file contains all necessary variables the Helm chart requires for successful installation. At the same time this enables users to override the default values.

For best practices on values.yaml files, please refer to TRG 5.05 - Chart Values or Helm documentation.

multiple values files not allowed

All default values must be introduced with values.yaml file to successfully install the Helm chart.

There must be no additional values-xyz.yaml files, e.g. to specify environment specific values. Only values.yaml file is allowed!

The crds Directory

If the Helm chart installs custom resource definitions, this directory is the place to locate the manifest files in.

For further details, refer to Helm documentation.

The templates Directory

The templates directory contains manifest files, which will be deployed during Helm chart installation. For further details, refer to Helm documentation.

The templates/NOTES.txt File

The content of templates/NOTES.txt will be printed after Helm chart installation. The file is evaluated as a template file with all possibilities of templating.

.helmignore

The .helmignore file should contain as a minimal set the following entries:

# Accept only values.yaml
values?*.yaml
values?*.yml