How to Upgrade Kube-Prometheus-Stack: Versions, CRDs, and Release Notes

A helm upgrade on kube-prometheus-stack looks like a one-line command, and most of the time it is. But this chart bundles Custom Resource Definitions that Helm deliberately does not touch on upgrade — skip that step and the upgrade can silently leave your cluster running a mismatched CRD schema. Here's the sequence that avoids that.

Why Upgrades Need Care

kube-prometheus-stack moves fast — new chart versions ship regularly as Prometheus, Grafana, Alertmanager, and the Prometheus Operator all release their own updates upstream. Most of those updates are routine. The ones that bite are major version jumps that change CRD schemas (Prometheus, Alertmanager, PrometheusRule, ServiceMonitor) or rename values.yaml keys — and Helm's upgrade command doesn't warn you about either.

Checking Your Current and Latest Version

Before upgrading anything, confirm what you're running and what's available:

# Current installed version
helm list -n monitoring

# Every version available in the repo
helm repo update
helm search repo prometheus-community/kube-prometheus-stack --versions

The chart version and the Kubernetes-app versions it installs (Prometheus, Grafana, etc.) are versioned independently — always check the Chart.yaml appVersion field alongside the chart version itself.

Why Helm Doesn't Upgrade CRDs Automatically

This is the single most common source of broken kube-prometheus-stack upgrades. Helm's design intentionally never updates or deletes CRDs on helm upgrade — it only installs them once, on first helm install. This is a Helm-wide safety decision, not a bug specific to this chart: CRD changes are irreversible and can delete existing custom resources, so Helm leaves that step to the operator.

For kube-prometheus-stack specifically, that means every upgrade that touches CRDs (new alerting fields, new ServiceMonitor options) requires applying the updated CRDs from the chart's crds/ directory before running helm upgrade:

# Pull the chart locally to access its CRDs
helm pull prometheus-community/kube-prometheus-stack --untar

# Apply the updated CRDs first
kubectl apply -f kube-prometheus-stack/crds/

The Safe Upgrade Sequence

1. Check the release notes for the target version and note any breaking values.yaml changes.
2. Apply updated CRDs manually, as shown above.
3. Back up current Grafana dashboards and any custom values overrides.
4. Run helm upgrade --reuse-values monitoring prometheus-community/kube-prometheus-stack -n monitoring.
5. Verify all pods return to Running with kubectl get pods -n monitoring.

--reuse-values keeps your existing customizations from the values.yaml configuration intact instead of resetting to chart defaults.

Reading Release Notes First

The chart's changelog, published alongside every release in the prometheus-community/helm-charts repository, is the only reliable source for what changed between versions. Skimming it before every upgrade — especially across a major version boundary — is the cheapest insurance against a broken deployment.

Kubernetes and Helm Version Compatibility

kube-prometheus-stack tracks current Kubernetes releases closely and is typically updated within days of a new minor version. As a baseline: Kubernetes v1.19+ and Helm v3.2+ are required, but newer chart versions frequently raise that floor — always check the specific version's requirements before upgrading a cluster running an older Kubernetes release.

Pinning a Chart Version in GitOps Pipelines

If kube-prometheus-stack is deployed through ArgoCD, Flux, or a CI pipeline rather than manually from a terminal, resist the temptation to track the chart's latest version automatically. Pin an explicit chart version in your Chart.yaml dependency or ArgoCD Application manifest, and bump it deliberately as its own reviewed change — the same CRD and values.yaml risks apply whether the upgrade is triggered by a person or a pipeline, and an unpinned version means a routine sync can trigger a major upgrade with no review at all.

If Something Breaks: Rolling Back

Helm keeps a revision history for every release, which makes rollback straightforward:

# List revision history
helm history monitoring -n monitoring

# Roll back to the previous working revision
helm rollback monitoring -n monitoring

The one thing rollback won't undo is CRDs you already applied forward — if the new CRD schema removed a field your old PrometheusRule objects depended on, you may need to restore those CRDs manually as well.

Testing an Upgrade Before It Touches Production

For anything beyond a patch release, it's worth seeing what an upgrade will actually change before it changes it. helm upgrade --dry-run --debug renders the full set of manifests Helm would apply without touching the cluster, which is enough to catch a renamed values.yaml key or an unexpectedly large diff before it happens for real.

Where the stakes are higher — a major version jump, or a cluster with strict change-control — mirror the upgrade in a staging namespace or a throwaway cluster first. Because kube-prometheus-stack's CRDs are cluster-scoped, a second namespace in the same cluster shares the same CRD versions as production, so a genuinely separate staging cluster is the only way to test a CRD-changing upgrade in true isolation.

Frequently Asked Questions

How do I check my current kube-prometheus-stack version?

Run helm list -n monitoring, or helm search repo prometheus-community/kube-prometheus-stack --versions to see every available version.

Does Helm upgrade CRDs automatically?

No — this is a deliberate Helm safety behavior. You must apply updated CRDs manually before upgrading.

What happens if an upgrade fails?

Use helm rollback monitoring <revision> -n monitoring to revert. Keep in mind CRDs applied forward don't automatically roll back.

Conclusion

Upgrading kube-prometheus-stack is routine maintenance, not a risky event — as long as CRDs are updated manually first and release notes are read before jumping major versions. Combine that discipline with a tested rollback path, and version upgrades stop being something to dread.