Helm in Practice

Versioning and Deprecating Charts

Helm chart versioning is more than bookkeeping. It shapes how charts are packaged, distributed, and understood by anyone deploying your application. A chart's version communicates compatibility, intent, and the nature of changes between releases.

Helm follows Semantic Versioning (SemVer) for chart versions, using the familiar MAJOR.MINOR.PATCH format:

• MAJOR: Increment for incompatible or breaking changes.
• MINOR: Increment when adding functionality in a backward-compatible way.
• PATCH: Increment for backward-compatible fixes.

Chart versions are immutable identifiers. Once published, a chart version must never change. If updates are needed, release a new version that follows SemVer rules:

• Add a feature without breaking anything → bump MINOR (1.2.0 → 1.3.0).
• Fix a bug → bump PATCH (1.2.0 → 1.2.1).
• Introduce a breaking change → bump MAJOR (1.2.0 → 2.0.0).

Chart Packages and SemVer

Every chart must declare a version in Chart.yaml. This version becomes part of the chart package name used by repositories:

todo-chart-1.0.0.tgz

Helm supports full SemVer 2 syntax, including pre-releases and metadata:

version: 1.2.3-beta.1+exp.sha.5114f85

Non-SemVer formats are rejected, except when Helm can safely coerce them (for example, v1.2 → 1.2.0).

When packaging a chart, Helm expects the file name version and the Chart.yaml version to match. A mismatch causes packaging errors.

The appVersion Field

appVersion represents the version of the application the chart deploys. It is not related to the chart's version field.

Example:

version: 1.5.0       # chart version
appVersion: "1.2.55"  # application version

appVersion is informational only; Helm does not use it for compatibility checks. Wrapping it in quotes is highly recommended to avoid YAML parsing issues (e.g., 2.0 being interpreted as a float).