Implementing Chart Deprecation Strategies

1. Marking Charts as Deprecated

Example: Deprecated chart

# Chart.yaml
apiVersion: v2
name: legacy-api
version: 2.0.1
deprecated: true        # Marks chart as deprecated in repo index
description: "[DEPRECATED] Use 'api' chart instead"

Effect	Detail
Repo index	Marked deprecated; hidden from search by default
Artifact Hub	Shows deprecation banner
Install	Still works (with warning)

2. Documenting Deprecation Reasons

Example: Annotations + README

annotations:
  artifacthub.io/changes: |
    - kind: deprecated
      description: "Replaced by 'api' chart; see UPGRADING.md"
  artifacthub.io/license: Apache-2.0

3. Providing Migration Paths

Doc	Content
UPGRADING.md	Step-by-step values mapping old → new
NOTES.txt	Runtime banner pointing to migration guide
Migration script	Tool to translate old values.yaml to new format

4. Setting Deprecation Timeline

Phase	Duration
Announce	Mark deprecated; continue accepting bug fixes
Grace period	≥6 months minimum (1 year for enterprise)
Freeze	Security fixes only
Remove	Stop publishing new versions; keep existing tags

5. Communicating to Users

Release notes announcement Mailing list / Slack notification Banner in NOTES.txt README header with timeline GitHub issue pinned Artifact Hub deprecated badge

6. Maintaining Deprecated Charts

Maintenance	During grace
Security fixes	Yes
Critical bugs	Yes
New features	No
K8s API updates	Yes (when needed for compatibility)

7. Removing Deprecated Charts

Step	Action
Stop releasing	No new chart versions
Update index	Keep existing entries (don't break installs)
Archive source	Move repo to `archived/`
Redirect docs	Replace README with pointer to successor

Warning: Never delete published chart versions from a repo or OCI registry. Users have pinned versions; removal breaks reproducible builds.

8. Archiving Old Chart Versions

Asset	Archive strategy
HTTP repo	Keep `.tgz` files; mark entries deprecated in `index.yaml`
OCI registry	Tag `:archived`; keep all version tags
Source repo	Tag final release; archive on GitHub

9. Redirecting to Replacements

Example: NOTES.txt redirect

┌──────────────────────────────────────────────────────────────┐
│ ⚠  This chart is DEPRECATED and will be removed on 2026-12.  │
│                                                              │
│ Please migrate to: oci://ghcr.io/acme/charts/api             │
│ Migration guide:   https://acme.io/docs/migrate-api          │
└──────────────────────────────────────────────────────────────┘

10. Handling Breaking Changes

Strategy	Detail
New chart name	Publish replacement under different name; users opt in
MAJOR bump	Same chart, breaking change documented in UPGRADING.md
Deprecation warnings	Emit via `fail` or NOTES.txt when removed values detected
Compatibility shim	Accept both old + new values for one MAJOR cycle
Schema validation	Reject removed values via `values.schema.json`

Related Cheat Sheets

Kubernetes