Implementing Chart Deprecation Strategies
1. Marking Charts as Deprecated
| Field | Value | Description |
|---|---|---|
| deprecated | true |
Set to true to mark the chart as deprecated in the index. |
| annotations.deprecation-date | 2025-06-01 |
Date when the chart was marked as deprecated. |
| annotations.deprecation-message | This chart is deprecated and will be removed in v4.0.0 |
Human-readable message explaining the deprecation and migration path. |
Example: Setting Chart as Deprecated
apiVersion: v2
name: example-app
description: An example application chart
version: 1.2.3
appVersion: "1.0.0"
deprecated: true
annotations:
deprecation-date: "2025-06-01"
deprecation-message: "This chart is deprecated and will be removed in v4.0.0. Please migrate to the new chart at example.com/new-app"
Note: Setting
deprecated: true in the Chart.yaml file will prevent Helm from installing or upgrading this chart, but it will still be available in the repository index.
2. Documenting Deprecation Reasons
| Reason Type | Description | Documentation Example |
|---|---|---|
| Security Vulnerability | Chart contains known security issues that are no longer patched. | Chart.yaml includes a note: "This chart is deprecated due to unpatched CVE-2023-12345" |
| Feature Obsolescence | Chart features are replaced by more robust or modern alternatives. | README.md states: "Use new-chart instead for enhanced capabilities." |
| Performance Degradation | Chart performance is significantly worse than newer versions or alternatives. | CHANGELOG.md notes: "Legacy chart version 1.2.0 has poor performance under load." |
| Maintenance Burden | Chart is no longer actively maintained or supported by the author. | README.md includes: "No longer maintained. Please migrate to stable-chart." |
Example: Deprecation Notice in Chart Metadata
apiVersion: v2
name: example-chart
version: 1.0.0
appVersion: "1.2.3"
deprecated: true
annotations:
deprecated-reason: "Security vulnerability CVE-2023-12345"
migration-guide: "https://example.com/docs/migrate-to-new-chart"
Note: The
deprecated field in Chart.yaml signals Helm to warn users during installation or upgrade.
Warning: Do not remove deprecated charts from repositories immediately; allow time for users to migrate.
3. Providing Migration Paths
Example: Chart Version Migration
# Chart.yaml
apiVersion: v2
name: my-app
version: 2.0.0
appVersion: "1.2.0"
annotations:
migration.path: "https://example.com/docs/migrate-from-v1-to-v2"
| Migration Type | Description | Implementation | Notes |
|---|---|---|---|
| Major Version Bump | Breaking changes requiring manual intervention | version: 2.0.0 |
Include migration guide in annotations |
| Minor Version Update | Backward-compatible enhancements | version: 1.1.0 |
Automated migration paths possible |
| Patch Version Fix | Non-breaking bug fixes | version: 1.0.1 |
No migration required |
Note: Migration paths should be documented in the chart's README and linked via
annotations.Warning: Ensure all deprecated values are properly handled or mapped in new versions.
Migration Strategy Summary
- Use semantic versioning to signal breaking changes
- Provide clear migration documentation in chart annotations
- Support automated migration where possible
- Test migration paths with real-world configurations
4. Setting Deprecation Timeline
| Timeline Element | Description | Configuration |
|---|---|---|
| deprecation.schedule | Sets the deprecation start date | "2025-06-01" |
| deprecation.eol | End of life date for the chart | "2026-06-01" |
| deprecation.migration.path | Migration steps or documentation link | "https://example.com/migration-guide" |
Example: Chart.yaml deprecation fields
apiVersion: v2
name: example-app
version: 1.2.3
appVersion: "1.2.0"
annotations:
deprecated: true
deprecation.schedule: "2025-06-01"
deprecation.eol: "2026-06-01"
deprecation.migration.path: "https://example.com/migration-guide"Note: Setting a clear deprecation timeline helps users plan their migration and ensures compliance with support policies.
5. Communicating to Users
Example: Deprecation Notice in Chart README
# MyChart
## Deprecation Notice
This chart is deprecated and will reach end-of-life on 2025-12-31.
### Migration Path
See [migration guide](https://example.com/migrate-mychart) for details.
| Notice Type | Description | Implementation |
|---|---|---|
| README.md | Deprecation notice in chart documentation | Add deprecation banner and migration path |
| values.yaml | Deprecated values with warnings | Include deprecated flag and note in comments |
| templates/NOTES.txt | Release notes with deprecation info | Display warning on chart install/upgrade |
Best Practices for User Communication
- Provide clear timeline for deprecation
- Offer migration steps or alternative solutions
- Use consistent messaging across all chart components
- Include version compatibility matrix in documentation
Warning: Users must be notified at least 3 months before deprecation to allow for migration.
6. Maintaining Deprecated Charts
| Aspect | Description | Recommendation |
|---|---|---|
| Chart Versioning | Deprecated charts should retain their original version numbers to maintain compatibility for existing installations. | Do not increment versions just for deprecation; keep version tags consistent with previous releases. |
| Documentation Updates | Include deprecation notices and migration guidance in the chart's README or documentation. | Add a dedicated DEPRECATED section in the README with steps to migrate or upgrade. |
| Support Status | Deprecated charts may still receive security patches or critical bug fixes. | Clearly state the support timeline (e.g., DEPRECATED as of v3.0, support until Q2 2025). |
| Helm Repository | Deprecated charts should remain in the repository but marked clearly. | Use helm repo update to ensure users can still pull the chart, but warn on installation. |
Example: Chart Metadata with Deprecation Notice
apiVersion: v2
name: example-app
description: A Helm chart for deploying the Example App.
version: 1.2.0
appVersion: "1.0.0"
deprecated: true
annotations:
helm.sh/deprecation-date: "2025-06-01"
Note: Setting
deprecated: true in the Chart.yaml will cause Helm to show a warning when installing or upgrading the chart.
Warning: Users should not rely on deprecated charts for new deployments. They are only suitable for maintaining existing installations.
7. Removing Deprecated Charts
Note: This section outlines the process of removing deprecated Helm charts from a repository or cluster, including considerations for backward compatibility and migration.
| Action | Description | Impact |
|---|---|---|
| helm repo remove | Removes a chart repository from the local Helm configuration. | Deletes local reference; does not affect charts already installed. |
| helm uninstall | Uninstalls a release from the cluster. | Removes chart resources from the cluster. |
| helm delete | Alias for helm uninstall. |
Same effect as uninstall. |
Workflow: Removing Deprecated Charts
- Identify all releases using deprecated charts.
- Backup any critical data or configurations from the chart's release.
- Uninstall the chart using
helm uninstall. - Remove the chart from any local or remote repositories.
- Update documentation to reflect removal of deprecated charts.
Summary of Chart Removal Considerations
- Ensure no dependent services rely on the deprecated chart before removal.
- Use
helm listto identify all releases using the chart. - Back up any persistent data or configuration before uninstalling.
- Update CI/CD pipelines to stop referencing deprecated chart versions.
8. Archiving Old Chart Versions
| Property | Description | Example |
|---|---|---|
| archive | Flag to archive chart versions in the repository | helm repo archive my-repo |
| version | Version of chart to archive | helm repo archive my-repo --version 1.2.0 |
Note: Archiving prevents deletion of chart versions, but does not remove them from the repository index.
9. Redirecting to Replacements
Example: Redirecting to a Replacement Chart
apiVersion: v1
kind: ConfigMap
metadata:
name: chart-redirect
data:
redirect-url: "https://example.com/charts/new-replacement-chart"
| Field | Description | Usage |
|---|---|---|
| redirect-url | URL to the replacement chart or documentation | Used by chart consumers to find updated resources |
Note: Ensure the redirect URL is accessible and provides clear migration steps.
Warning: Redirects should not break existing installations or cause data loss.
10. Handling Breaking Changes
| Change Type | Description | Impact | Action Required |
|---|---|---|---|
| API Version Changes | Migration from v1 to v2 or newer |
Charts may fail to install or upgrade without changes | Update chart dependencies and templates to use new API versions |
| Template Renaming | Renaming of template files or directories | Templates may no longer be rendered as expected | Update references in templates/ directory and any custom overrides |
| Value Structure Changes | Changing structure of values.yaml or default values |
Existing deployments may not reflect updated configurations | Update values.yaml and provide migration documentation |
| Resource Removal | Removal of Kubernetes resources (e.g., Deployment, Service) |
Resources will be deleted during upgrade if not handled carefully | Implement pre-upgrade hooks or manual steps to preserve data |
Example: Migrating from v1 to v2 API Version
# Before (v1)
apiVersion: v1
kind: Service
metadata:
name: my-service
# After (v2)
apiVersion: v1
kind: Service
metadata:
name: my-service
Note: When upgrading, ensure that all
apiVersion references in templates are updated to reflect the new Kubernetes API versions.
Warning: Breaking changes in Helm charts can cause deployment failures or data loss. Always test upgrades in a staging environment before applying to production.