Migrating and Upgrading Charts

1. Upgrading Chart API Version

API Version	Description	Notes
apiVersion: v1	Legacy API version for Helm 2	Deprecated and unsupported in Helm 3
apiVersion: v2	Current API version for Helm 3	Required for Helm 3 charts

Example: Migrating from v1 to v2

# Before (v1)
apiVersion: v1
name: my-app
version: 1.0.0
description: A sample chart

# After (v2)
apiVersion: v2
name: my-app
version: 1.0.0
description: A sample chart
type: application
appVersion: "1.0.0"

Note: When upgrading to v2, ensure all dependencies and templates are compatible with Helm 3.

2. Migrating from requirements.yaml

Feature	Description	Migration Path
requirements.yaml	`requirements.yaml` is deprecated in favor of `Chart.yaml` dependencies	Use `helm dependency` commands to migrate
dependencies	Defined in `Chart.yaml` under `dependencies`	Move entries from `requirements.yaml` to `Chart.yaml`

Example: Migrating dependencies

# Before (requirements.yaml)
apiVersion: v2
dependencies:
  - name: mysql
    version: "8.0.1"
    repository: "https://charts.helm.sh/stable"
  - name: redis
    version: "12.0.0"
    repository: "@bitnami"

# After (Chart.yaml)
apiVersion: v2
name: my-app
version: 1.0.0
dependencies:
  - name: mysql
    version: "8.0.1"
    repository: "https://charts.helm.sh/stable"
  - name: redis
    version: "12.0.0"
    repository: "@bitnami"

Note: The helm dependency command can help automate this migration.

Warning: Ensure all repository URLs are updated to use the new repository field format.

3. Updating Deprecated Kubernetes APIs

API Version	Replacement	Deprecated Since	Notes
apps/v1beta1	`apps/v1`	Kubernetes 1.14	ReplicaSets and Deployments in `v1beta1` are deprecated. Use `apps/v1` for modern deployments.
apps/v1beta2	`apps/v1`	Kubernetes 1.14	ReplicaSets and Deployments in `v1beta2` are deprecated. Use `apps/v1` for modern deployments.
extensions/v1beta1	`networking.k8s.io/v1`	Kubernetes 1.14	Deprecated Ingress resources in `extensions/v1beta1` should be updated to `networking.k8s.io/v1`.
batch/v1beta1	`batch/v1`	Kubernetes 1.21	CronJobs in `batch/v1beta1` are deprecated. Use `batch/v1`.
autoscaling/v1	`autoscaling/v2`	Kubernetes 1.22	HorizontalPodAutoscaler in `v1` is deprecated. Use `v2` for more features.

Example: Updating Ingress API Version

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: example-service
            port:
              number: 80

Note: When migrating, ensure that all resources using deprecated API versions are updated to their new equivalents. Helm charts should be updated to use the latest stable Kubernetes API versions.

4. Handling Breaking Changes

Note: Breaking changes in Helm charts can occur during major version upgrades or when chart maintainers modify the underlying Kubernetes resources.

Change Type	Description	Action Required	Impact Level
API Version Changes	Changes in Kubernetes API versions (e.g., `apps/v1` vs `extensions/v1beta1`)	Update chart to use supported API versions	High
Resource Removal	Removal of deprecated resources or features (e.g., `Ingress` class changes)	Update chart to remove or replace removed resources	High
Template Changes	Modifications to chart templates affecting resource generation	Review and update templates to align with new structure	Medium
Value Schema Changes	Changes in `values.yaml` schema or default values	Update `values.yaml` to match new schema and defaults	Medium
Dependency Updates	Changes in chart dependencies (e.g., new versions of sub-charts)	Update `requirements.yaml` or `Chart.yaml` dependencies	Low

Example: Updating API Version in Deployment Template

# Old template (deprecated API version)
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3

# Updated template (supported API version)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  replicas: 3

Example: Updating Values Schema

# Old values.yaml
replicaCount: 3
image:
  repository: nginx
  tag: "1.20"

# Updated values.yaml (schema change)
replicaCount: 3
image:
  repository: nginx
  tag: "1.21"
  pullPolicy: IfNotPresent

Best Practices for Breaking Change Handling

Review release notes for breaking changes before upgrading charts
Test upgrades in a staging environment first
Use helm template to preview changes before applying them
Back up existing resources before major upgrades
Update dependencies in Chart.yaml or requirements.yaml to match new versions

Workflow for Handling Breaking Changes

Identify breaking changes in the new chart version
Update values.yaml to align with new schema
Modify templates if needed to support new API versions or resource structures
Test the updated chart in a non-production environment
Apply changes to production after validation

5. Testing Migration Changes

Example: Running Tests Locally

helm test my-release

Option	Values	Description
--timeout	`300s`	Timeout for the test to complete
--cleanup	`false`	Remove test pods after completion

Note: Tests are defined in the test section of the Chart's values.yaml.

Warning: Ensure all dependencies are installed before running tests.

6. Rolling Back Failed Migrations

Action	Command	Description
Rollback to previous revision	`helm rollback <RELEASE_NAME>`	Revert the release to the previous revision
Rollback to specific revision	`helm rollback <RELEASE_NAME> <REVISION_NUMBER>`	Revert the release to a specific revision number

Example: Rolling Back to Previous Revision

helm rollback my-app

Example: Rolling Back to Specific Revision

helm rollback my-app 3

Note: The rollback command will reinstall the previous revision's release. If the previous revision had a different chart version, it will be rolled back to that version.

Warning: Rolling back may not restore all changes made to the cluster since the previous revision. Ensure that any manual changes or custom configurations are handled appropriately.

7. Updating Chart Dependencies

Dependency	Version	Updated	Notes
name	`nginx`	`v1.20.1`	Updated from `v1.19.5`
repository	`https://charts.bitnami.com/bitnami`	`https://charts.bitnami.com/bitnami`	No change
version	`12.0.0`	`12.1.0`	New stable version

Example: Updating dependencies in Chart.yaml

apiVersion: v2
name: my-app
version: 1.0.0
dependencies:
  - name: nginx
    version: 12.1.0
    repository: https://charts.bitnami.com/bitnami

Note: Run helm dependency update after updating Chart.yaml to fetch new versions.

8. Migrating to OCI Registries

As of Helm 3.8+, charts can be stored in OCI registries, offering a more standardized and secure way to manage chart distributions.

Feature	Description	Notes
oci://	Protocol prefix for OCI registry charts	Used in `helm install` and `helm pull`
helm registry login	Authenticate with OCI registry	Required before pushing/pulling charts
helm push	Push chart to OCI registry	Replaces `helm package` and `helm registry push`

Example: Pushing Chart to OCI Registry

helm registry login my-oci-registry.com
helm push my-chart-1.0.0.tgz oci://my-oci-registry.com/charts/my-chart

Example: Installing Chart from OCI Registry

helm install my-release oci://my-oci-registry.com/charts/my-chart --version 1.0.0

Note: Helm 3.8+ supports OCI registries natively, making chart distribution more consistent with container image standards.

Warning: Ensure your registry supports OCI chart storage before migrating.

Migration Steps

Update chart dependencies to use OCI URLs
Repackage and push charts to OCI registry
Update deployment scripts to use oci:// URLs
Verify chart integrity and functionality post-migration

9. Converting to Library Charts

Library charts are reusable chart components that can be included as dependencies in other charts. They provide a way to share common functionality across multiple Helm charts.

Property	Description	Example
apiVersion	API version of the chart	`v2`
name	Name of the chart	`my-library-chart`
version	Chart version	`1.0.0`
type	Chart type - must be `library`	`library`

Example: Library Chart Configuration

apiVersion: v2
name: my-library-chart
version: 1.0.0
type: library
description: A reusable library chart for common components

Note: Library charts cannot be installed directly. They must be included as dependencies in other charts.

Library Chart vs Application Chart

Library Chart: Reusable components, no direct installation
Application Chart: Complete application deployment, can be installed directly

10. Documenting Migration Steps

Example: Migration Documentation Template

# Migration Guide for Chart v2.0 to v3.0
#
# This document outlines the steps required to migrate from version 2.0 to 3.0 of the Helm chart.

## Summary
- Chart name: my-app-chart
- Old version: 2.0.0
- New version: 3.0.0
- Key changes: Breaking changes in configuration, new dependencies

## Migration Steps
1. Backup current configuration and data
2. Update chart version in values.yaml
3. Apply new chart with updated values
4. Verify application functionality

## Configuration Changes
| Old Key | New Key | Notes |
|---------|---------|-------|
| `old.config.value` | `new.config.value` | Renamed |
| `old.database.port` | `database.port` | Moved to subchart |

## Breaking Changes
- The `old.config.value` field has been removed.
- Database configuration is now handled in a subchart.

## Rollback Instructions
If migration fails:
1. Revert to previous chart version
2. Restore from backup
3. Reapply configuration

Step	Description	Notes
1. Backup Configuration	Export current chart values and secrets	Use `helm get values <release-name>`
2. Update Chart Version	Change `version` in Chart.yaml	Ensure compatibility with new dependencies
3. Apply Migration	Install or upgrade with new chart	Validate `helm status <release-name>`
4. Verify Functionality	Check application behavior and logs	Run integration tests if available

Note: Always test migration steps in a staging environment before applying to production.

Warning: Never skip backup steps during migration. Data loss is possible if not properly backed up.