Working with Chart.yaml
1. Defining Chart Name and Version
| Field | Rules | Example |
|---|
name | Lowercase, alphanumeric + dashes, ≤63 chars, DNS-1123 | my-app |
version | SemVer 2.0 (MAJOR.MINOR.PATCH); required for packaging | 1.4.2 |
2. Setting Application Version
Example: Quote appVersion
appVersion: "2.7.0" # always quote — YAML may parse 1.10 as 1.1
| Field | Purpose |
|---|
appVersion | Version of the application packaged (free-form string) |
| Default image tag | If .Values.image.tag empty, helpers commonly fall back to .Chart.AppVersion |
3. Declaring API Version
| apiVersion | Compatible Helm | Required |
|---|
v2 CURRENT | 3.0+ | Yes for new charts |
v1 LEGACY | 2.x (still readable by 3.x) | No |
4. Specifying Chart Type
| type | Installable | Use |
|---|
application | Yes | Default; produces a release |
library | No | Reusable helpers; only consumed as a dependency |
5. Adding Chart Description
Example: Description field
description: |
Production-ready REST API service with Postgres, Redis cache,
and built-in OpenTelemetry instrumentation.
| Tip | Reason |
|---|
| Keep ≤200 chars on one line | Shown in helm search output |
| Use block scalar for long | Still searchable; better readability |
6. Adding Keywords and Sources
keywords:
- api
- rest
- postgres
- microservice
sources:
- https://github.com/acme/api
- https://github.com/acme/charts
7. Listing Chart Maintainers
| Field | Purpose |
|---|
name | Person or team (required) |
email | Contact email (optional) |
url | GitHub profile / website (optional) |
Example: maintainers block
maintainers:
- name: Platform Team
email: platform@acme.io
url: https://github.com/acme
8. Setting Home URL
| Field | Usage |
|---|
home | Project landing page (rendered as link on Artifact Hub) |
9. Adding Icon URL
| Field | Requirements |
|---|
icon | HTTPS URL to SVG/PNG (≤200KB); square aspect ratio recommended |
10. Marking Chart Deprecated
Example: Deprecate with migration note
deprecated: true
description: |
DEPRECATED: use acme/api-v2 chart. Migration guide:
https://docs.acme.io/charts/migrate-api-v2
Note: Repositories like Artifact Hub flag deprecated charts and hide them from default search.
11. Setting Kubernetes Version Constraint
| Constraint | Meaning |
|---|
kubeVersion: ">=1.27.0" | Minimum cluster version |
">=1.27.0-0 <1.31.0-0" | Tested range; -0 includes pre-release |
"~1.28" | Patch-level changes only |
Warning: Constraints without -0 exclude pre-release versions like v1.30.0-rc.1.