Managing Chart Versions
1. Using Semantic Versioning
| Increment | Trigger |
|---|---|
| MAJOR | Breaking changes (renamed values, removed templates, schema-incompatible) |
| MINOR | Backward-compatible feature additions |
| PATCH | Bug fixes, doc updates |
| Pre-release | 1.5.0-rc.1, 1.5.0-alpha.2 |
| Build metadata | 1.5.0+commit.abc123 (ignored in version comparison) |
2. Incrementing Chart Version
| Change | Bump |
|---|---|
| New optional value | MINOR |
| Renamed value | MAJOR |
| Image tag update | PATCH or MINOR (also bump appVersion) |
| Template restructure | MAJOR if upgrade path requires migration |
3. Setting Application Version
| Field | Purpose |
|---|---|
appVersion | Tracks application — independent of chart version |
| Always quote | Prevents YAML coercion (e.g. 1.10 → 1.1) |
4. Creating Version Constraints
| Constraint | Allowed |
|---|---|
1.2.3 | Exact |
=1.2.3 | Exact (explicit) |
!=1.2.3 | Not equal |
>1.2.3 <2.0 | Composite range |
1.x / 1.2.x | Wildcard |
5. Using Version Ranges
6. Pinning Exact Versions
| Practice | Reason |
|---|---|
| Pin in production | Reproducibility, avoid surprise breakage |
| Allow ranges in dev | Pick up patches automatically |
| Commit Chart.lock | Lock resolved versions |
7. Using Tilde Range
| Pattern | Matches |
|---|---|
~1.2.3 | >=1.2.3 <1.3.0 (patch updates) |
~1.2 | >=1.2.0 <1.3.0 |
~1 | >=1.0.0 <2.0.0 |
8. Using Caret Range
| Pattern | Matches |
|---|---|
^1.2.3 | >=1.2.3 <2.0.0 (minor + patch) |
^0.2.3 | >=0.2.3 <0.3.0 (0.x treated specially) |
^0.0.3 | >=0.0.3 <0.0.4 |
9. Maintaining Changelog
Example: Annotations-based changelog
# Chart.yaml
annotations:
artifacthub.io/changes: |
- kind: added
description: Support for ExternalSecrets
- kind: fixed
description: Probe timeout default raised to 30s
- kind: deprecated
description: 'imageTag' replaced by 'image.tag'10. Tagging Chart Releases
| Tag scheme | Example |
|---|---|
| Chart name + version | api-1.4.2 (chart-releaser default) |
| Version only | v1.4.2 (single-chart repos) |
| Immutable | Never re-tag a published version |