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
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 infrastructurea 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/postgresqldocumentation 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.
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