Chart Versioning

Chart Versioning is the practice of managing and incrementing the version numbers of Helm charts in a consistent, meaningful way to track changes, ensure compatibility, and facilitate deployment workflows. It defines how new releases of a chart are identified and helps users and automation tools to distinguish between different iterations of the same chart, reflecting updates, bug fixes, or breaking changes.

Versioning Components

Chart.yaml Version Field

The version field in the Chart.yaml file specifies the version of the chart itself. This version indicates changes in the chart's structure, templates, or metadata and follows semantic versioning principles. It is used by Helm to manage chart releases and dependencies.

Example snippet from Chart.yaml:

apiVersion: v2
name: mychart
version: 1.2.3
appVersion: 2.1.0

• version: Chart version, incremented with every chart update.
• appVersion: Version of the application the chart deploys; informational only.

appVersion Field

The appVersion field represents the version of the underlying application or service that the chart deploys. It is a descriptive field to indicate which version of the application is installed but does not affect chart version resolution or upgrades.

Semantic Versioning (SemVer) in Helm Charts

Helm chart versions follow Semantic Versioning (SemVer), which uses the format:

MAJOR.MINOR.PATCH

• MAJOR: Incremented for incompatible or breaking changes.
• MINOR: Incremented when functionality is added in a backward-compatible manner.
• PATCH: Incremented for backward-compatible bug fixes or small changes.

Example progression:

• 1.0.0 — Initial stable release.
• 1.1.0 — Added new features without breaking compatibility.
• 1.1.1 — Fixed bugs without adding features.
• 2.0.0 — Introduced breaking changes requiring attention before upgrade.

Pre-release and build metadata tags can also be used for more granular control, e.g.,

1.2.0-beta.1 or 1.2.0+build.1234

Versioning Best Practices

Consistent Version Increments

• Always increment the version field on any change to the chart, even minor documentation or metadata updates.
• Reflect the nature of the change accurately using SemVer rules.
• Avoid skipping version numbers to maintain clarity in the release history.

Synchronization Between Chart and Application Versions

• Update appVersion when the packaged application version changes.
• Do not increment version just because appVersion changes unless the chart itself requires modifications to support that application update.

Version Control and Releases

• Tag chart versions in source control to maintain history and enable rollbacks.
• Use automated CI/CD pipelines to validate and package charts with correct versioning.
• Publish chart versions to repositories to allow users to select specific versions during deployment.

Helm Chart Repository Version Management

Helm repositories maintain an index.yaml file that lists all available chart versions, metadata, and download URLs. Proper chart versioning ensures:

• Clear upgrade paths for users.
• Ability to specify exact chart versions during helm install or helm upgrade commands.
• Prevention of conflicts or overwrites by ensuring unique version numbers.

Example command to install a specific chart version:

helm install myrelease myrepo/mychart --version 1.2.3

Handling Breaking Changes and Deprecations

When introducing breaking changes:

• Increment the MAJOR version number.
• Document upgrade notes clearly in the chart's README.md or CHANGELOG.md.
• Consider maintaining legacy chart versions for backward compatibility if possible.

When deprecating features or templates:

• Communicate deprecations through chart documentation.
• Use annotations or Helm hooks to warn users during installation or upgrade.

Automation and Tooling Support

Many tools and CI/CD systems integrate with Helm versioning to:

• Automatically increment chart versions based on commit messages or pull requests.
• Validate version formats before packaging.
• Publish charts to repositories with version control.
• Enforce version locking for dependencies using requirements.yaml or Chart.yaml dependencies.

Ensuring accurate chart versioning supports smooth continuous delivery and reliable infrastructure management.

Summary of Key Fields in Chart.yaml for Versioning

By maintaining clear, consistent, and semantically correct chart versioning, Helm charts can effectively communicate changes, enable reliable deployments, and integrate seamlessly into DevOps workflows.