Helm / Basic: chart and rendering foundations / Lesson 2

Chart layout and version contracts

Read a minimal application chart and keep package metadata, application identifiers and supported platform assumptions coherent.

About 5 min readContent reviewed 2026-10-28

On this page

Lesson goals

Explain the roles of Chart.yaml, values.yaml, templates and charts.
Choose coherent package and application version fields.
Review package contents without treating packaging as deployment.

Map the directory contract

Helm recognizes a deliberate chart layout. Chart.yaml declares metadata; values.yaml supplies defaults; templates holds text that becomes manifests; charts holds packaged or unpacked dependencies. Optional values.schema.json constrains values, while crds has special lifecycle semantics studied later. Files placed beside these reserved paths can be application configuration assets, provided the chart includes them intentionally. A source tree is not automatically a clean package. Inspect examples, temporary reports and private material before packaging. The directory name should match the chart name so readers and automation agree about the artifact they are reviewing.

text Minimal reviewed source layout

catalog/
  Chart.yaml
  values.yaml
  values.schema.json
  templates/
    configmap.yaml
    _helpers.tpl

The tree is illustrative. The helper is not emitted as a manifest; the schema file is optional but useful.

Read metadata as a contract

For Helm 3 application charts, apiVersion v2 describes the chart format rather than a Kubernetes resource API. The version field identifies the chart package and follows semantic versioning. appVersion is descriptive application metadata and need not follow semantic versioning; quote it to preserve string intent. The example separates a packaging change from application build 2.7.1. Changing a default port or helper can require a chart version change even when the image stays identical. Conversely, updating the application does not mean every other chart behavior changed. Explain the compatibility impact in release notes.

yaml Chart.yaml metadata fragment

apiVersion: v2
name: catalog
description: Synthetic catalog application chart
type: application
version: 0.4.0
appVersion: "2.7.1"

This file is chart metadata, not a Kubernetes object. The version numbers are teaching choices and make no support claim.

Separate compatibility dimensions

Chart compatibility has several dimensions: supported values, generated Kubernetes APIs, application configuration and persistent data. A package can preserve its values interface while introducing a workload API unavailable on an older cluster. A quoted appVersion does not select an image unless a template explicitly uses it. Prefer an explicit image tag or digest input when reproducible image selection matters, and explain its relation to metadata. If kubeVersion is declared, treat it as a compatibility constraint for Helm validation rather than proof of admission policy or runtime behavior on every matching distribution.

Audit the package boundary

Packaging includes more than the files visible in a manifest diff. A forgotten example export or embedded credentials can travel with the archive even when no template reads it. Use .helmignore to express exclusions, then inspect the resulting artifact in an authorized local workflow. Exclusions are not a secrecy system: do not put real credentials in source or assume an ignored file never reached history. The course creates no archive with Helm because that client is unavailable. Its directory and metadata snippets remain review material, and validation reports state that limitation explicitly.

Document ownership and change

A chart README should explain prerequisites, configurable values, resource ownership and incompatible changes. Describe whether dependencies are bundled, which objects are optional and which names must remain stable across upgrades. A short application description alone cannot support a safe review of a major chart change. For the synthetic catalog, a change from one configuration key to two keys requires a migration example, even if both versions render successfully. Reviewers need the old input, new input and resulting difference. Version labels help organize this evidence but cannot replace a concrete behavioral explanation.

Common errors and fixes

Chart.yaml uses apps/v1 as apiVersion

Why it happens: Kubernetes resource metadata was copied into package metadata.
How to fix it: Use chart apiVersion v2 for the Helm 3 chart and keep resource APIs inside templates.
Prevent it next time: Review chart metadata and generated object metadata as separate schemas.

Changing appVersion leaves the image unchanged

Why it happens: The template uses image.tag rather than Chart.AppVersion.
How to fix it: Inspect the image expression and set its documented input deliberately.
Prevent it next time: Explain whether application metadata is descriptive or an image default.

An archive contains a private local export

Why it happens: The package boundary was assumed to match rendered manifests.
How to fix it: Remove private material from source and review artifact contents and history exposure.
Prevent it next time: Keep synthetic examples in charts and audit exclusions before distribution.

Check your understanding

1. A helper changes labels while application 2.7.1 stays fixed. Which version deserves review?

Show worked solution

The chart version changes because the packaged behavior changed. appVersion may remain 2.7.1. Review whether labels are descriptive or used by immutable selectors: a cosmetic-looking helper change can affect ownership and routing. Select a version increment according to the chart compatibility policy and describe the actual change, rather than equating all label edits with harmless formatting.

2. Where should a static synthetic application settings file live, and how should it be reviewed?