Migrating and Upgrading Charts
1. Upgrading Chart API Version
Example: v1 → v2
# Old (Chart.yaml)
apiVersion: v1
# requirements.yaml was external
# New (Chart.yaml)
apiVersion: v2
dependencies:
- name: postgresql
version: "15.3.0"
repository: https://charts.bitnami.com/bitnami
type: application2. Migrating from requirements.yaml
| Step | Action |
|---|---|
| Move | Copy requirements.yaml contents under dependencies: in Chart.yaml |
| Delete | Remove requirements.yaml and requirements.lock |
| Rebuild | helm dependency update regenerates Chart.lock |
3. Updating Deprecated Kubernetes APIs
| Old API | New API |
|---|---|
extensions/v1beta1 Deployment | apps/v1 |
extensions/v1beta1 Ingress | networking.k8s.io/v1 |
policy/v1beta1 PodDisruptionBudget | policy/v1 |
autoscaling/v2beta2 HPA | autoscaling/v2 |
batch/v1beta1 CronJob | batch/v1 |
rbac.authorization.k8s.io/v1beta1 | rbac.authorization.k8s.io/v1 |
4. Handling Breaking Changes
| Change type | Strategy |
|---|---|
| Renamed value | Accept both for one MAJOR cycle; emit deprecation via NOTES.txt |
| Removed template | Document in CHANGELOG with migration path |
| Selector change | Force fresh install — selectors are immutable |
5. Testing Migration Changes
| Step | Tool |
|---|---|
| Diff old vs new | helm diff upgrade |
| Render both | helm template old/ > o.yaml; helm template new/ > n.yaml; diff o.yaml n.yaml |
| Test in staging | Run full helm upgrade against representative cluster |
6. Rolling Back Failed Migrations
Example: Atomic with auto-rollback
helm upgrade api ./chart --atomic --timeout 15m -f values-prod.yaml
# Manual rollback if needed
helm rollback api7. Updating Chart Dependencies
| Workflow | Command |
|---|---|
| Resolve latest | helm dependency update |
| Lock | Commit updated Chart.lock |
| CI rebuild | helm dependency build (lock-file driven) |
8. Migrating to OCI Registries
| Step | Command |
|---|---|
| Login | helm registry login ghcr.io |
| Push existing | helm push chart.tgz oci://ghcr.io/acme/charts |
| Update dependencies | Change repo URL to oci://... in Chart.yaml |
| Deprecate HTTP repo | Keep mirroring for transition period |
9. Converting to Library Charts
| Change | Detail |
|---|---|
Chart.yaml | Add type: library |
| Templates | Convert manifests to define blocks in _*.tpl |
| Values | Remove resource-specific defaults; document expected inputs |
| Consumers | Add as dependency + include helpers in their templates |
10. Documenting Migration Steps
| Doc | Content |
|---|---|
UPGRADING.md | Version-by-version migration notes |
| CHANGELOG annotation | artifacthub.io/changes in Chart.yaml |
NOTES.txt | Runtime warnings for deprecated values |