The Chart.yaml File

The Chart.yaml file is required for a chart. It contains the following fields:

  1. apiVersion: The chart API version, always "v1" (required)
  2. name: The name of the chart (required)
  3. version: A SemVer 2 version (required)
  4. kubeVersion: A SemVer range of compatible Kubernetes versions (optional)
  5. description: A single-sentence description of this project (optional)
  6. keywords:
  7.   - A list of keywords about this project (optional)
  8. home: The URL of this project's home page (optional)
  9. sources:
  10.   - A list of URLs to source code for this project (optional)
  11. maintainers: # (optional)
  12.   - name: The maintainer's name (required for each maintainer)
  13.     email: The maintainer's email (optional for each maintainer)
  14.     url: A URL for the maintainer (optional for each maintainer)
  15. engine: gotpl # The name of the template engine (optional, defaults to gotpl)
  16. icon: A URL to an SVG or PNG image to be used as an icon (optional).
  17. appVersion: The version of the app that this contains (optional). This needn't be SemVer.
  18. deprecated: Whether this chart is deprecated (optional, boolean)
  19. tillerVersion: The version of Tiller that this chart requires. This should be expressed as a SemVer range: ">2.0.0" (optional)

If you are familiar with the Chart.yaml file format for Helm Classic, you willnotice that fields specifying dependencies have been removed. That is becausethe new Chart format expresses dependencies using the charts/ directory.

Other fields will be silently ignored.

Charts and Versioning

Every chart must have a version number. A version must follow theSemVer 2 standard. Unlike Helm Classic, KubernetesHelm uses version numbers as release markers. Packages in repositoriesare identified by name plus version.

For example, an nginx chart whose version field is set to version:1.2.3 will be named:

  1. nginx-1.2.3.tgz

More complex SemVer 2 names are also supported, such asversion: 1.2.3-alpha.1+ef365. But non-SemVer names are explicitlydisallowed by the system.

NOTE: Whereas Helm Classic and Deployment Manager were bothvery GitHub oriented when it came to charts, Kubernetes Helm does notrely upon or require GitHub or even Git. Consequently, it does not useGit SHAs for versioning at all.

The version field inside of the Chart.yaml is used by many of theHelm tools, including the CLI and the Tiller server. When generating apackage, the helm package command will use the version that it findsin the Chart.yaml as a token in the package name. The system assumesthat the version number in the chart package name matches the version number inthe Chart.yaml. Failure to meet this assumption will cause an error.

The appVersion field

Note that the appVersion field is not related to the version field. It isa way of specifying the version of the application. For example, the drupalchart may have an appVersion: 8.2.1, indicating that the version of Drupalincluded in the chart (by default) is 8.2.1. This field is informational, andhas no impact on chart version calculations.

Deprecating Charts

When managing charts in a Chart Repository, it is sometimes necessary todeprecate a chart. The optional deprecated field in Chart.yaml can be usedto mark a chart as deprecated. If the latest version of a chart in therepository is marked as deprecated, then the chart as a whole is considered tobe deprecated. The chart name can later be reused by publishing a newer versionthat is not marked as deprecated. The workflow for deprecating charts, asfollowed by the helm/chartsproject is:

  • Update chart’s Chart.yaml to mark the chart as deprecated, bumping the version
  • Release the new chart version in the Chart Repository
  • Remove the chart from the source repository (e.g. git)