Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 38 ยท Repositories and OCI

Packaging, Versioning and .helmignore

Package charts with helm package, understand version vs appVersion, SemVer bump rules, .helmignore and what ends up inside the .tgz, with a bump-rules stand-in.

A chart directory is for development. To share or deploy it, you package it into a versioned archive. helm package turns a directory into name-version.tgz: one file you can upload to a repository, push to a registry, attach to a CI artifact or hand to a customer.

helm package

Terminal
helm package ./webapp
# Successfully packaged chart and saved it to: /work/webapp-0.3.0.tgz

helm package ./webapp --destination ./dist
helm package ./webapp --version 0.4.0-rc.1 --app-version 1.9.0
helm package ./webapp --dependency-update

The file name comes from name and version in Chart.yaml. Useful flags:

Flag Effect
--destination DIR Write the archive somewhere else
--version X Override the chart version for this package only
--app-version X Override appVersion for this package only
--dependency-update Run helm dependency update first
--sign --key K --keyring R Create a provenance file (see chart security)

Overriding --version in CI lets a pipeline stamp each build (0.4.0-build.123) without editing files.

version versus appVersion

Two fields in Chart.yaml look alike and mean different things:

YAML
apiVersion: v2
name: webapp
version: 0.3.0        # the CHART's version
appVersion: "1.8.2"   # the version of the APPLICATION inside
  • version must be valid SemVer 2 and identifies the packaging: templates, defaults and structure of the chart. Repositories and helm upgrade --version use it.
  • appVersion is free text informing humans which application release the chart deploys by default (often the default image tag). Helm does not interpret it.

You bump version whenever the chart changes, even if the app did not (new probe, new value). You bump appVersion when the default application version changes. Often both change together, but not always.

Common bump rules for the chart version, following SemVer:

Change Bump
Fix a template bug, change a default without breaking users patch (0.3.0 to 0.3.1)
Add a backward-compatible value or resource minor (0.3.0 to 0.4.0)
Rename or remove values, change selectors, drop a resource major (0.3.0 to 1.0.0)

Charts with version below 1.0.0 are allowed to break on minor bumps, but treat that as an excuse only for early development.

Python Stand-in: pick the next chart version

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

What goes into the archive

Everything in the chart directory except what .helmignore excludes. The file works like .gitignore:

TEXT
# .helmignore
.git/
.github/
*.swp
*.bak
tests/fixtures/
ci/
README.dev.md

Always ignore CI configuration, editor files and large fixtures: they bloat the archive and may leak internal details. Keep charts small as well: Helm stores each release revision in a Kubernetes Secret, which is limited to about 1 MB, so huge charts or giant values can make installs fail.

Inspect a package before publishing:

Terminal
tar -tzf webapp-0.3.0.tgz
helm show chart webapp-0.3.0.tgz
helm lint webapp-0.3.0.tgz
Python Stand-in: which files survive .helmignore

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The same chart in different states

A healthy release process produces three kinds of versions:

  1. Development builds 0.4.0-dev.17 from every merge request, published to a scratch repository.
  2. Release candidates 0.4.0-rc.1 that QA installs.
  3. Releases 0.4.0, immutable, signed.

Pre-release identifiers sort before the release, and ^0.4.0 does not match 0.4.0-rc.1, so nobody picks a candidate by accident. See Helm in GitHub Actions for automating this.

Mistakes to avoid

  • Forgetting to bump version. The repository then has two different archives with the same name. Add a CI check that fails when the chart changed but the version did not.
  • Using latest as the image tag in appVersion defaults. Pin the tag so a release is reproducible.
  • Quoting appVersion. Write "1.8.2" in quotes: unquoted 1.10 becomes the number 1.1 in YAML.
  • Packaging with uncommitted dependency changes. Run with --dependency-update or commit Chart.lock.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which field must be valid SemVer 2?

    The chart version is SemVer 2; appVersion is informational free text.
  2. 2. You rename a value that users set. How should you bump the chart version?

    Renaming values breaks existing user configuration, which is a breaking change.
  3. 3. What is .helmignore for?

    It lists patterns for files left out of the .tgz, like .gitignore.

Summary

  • helm package produces name-version.tgz; override --version and --app-version in CI.
  • version is the chart's SemVer; appVersion is the application's, informational.
  • Use .helmignore, keep charts small, publish immutable versions with a rc-to-release flow.

Next: OCI Registries