Last modified November 17, 2026
Cluster downgrades
Before a production upgrade, you might ask if you can go back to the previous release if something breaks. The short answer is no. Giant Swarm doesn’t test or support downgrading a workload cluster to an older release. Plan your upgrades so you never need to.
Why downgrades aren’t supported
A workload cluster release bundles Kubernetes with many other components, like the operating system, the container runtime, and the network plugin. An upgrade changes all them. Some of these changes are one way:
- A newer Kubernetes version can store resources in etcd in a format or API version that the older version can’t read.
- Components can migrate their own state or custom resources to a new schema during the upgrade.
- Major releases follow Kubernetes minor versions. The Kubernetes project doesn’t test downgrades between minor versions, so a downgrade of a major release has no upstream guarantee either.
A downgrade might work sometimes, but the result is unpredictable. A failed downgrade can leave the cluster in a worse state than the upgrade you wanted to undo. That’s why it isn’t an option we offer as a fallback.
Use staged upgrades instead
Reduce the risk of an upgrade by rolling it out in stages, so a problem shows up before it reaches production:
- Upgrade your development or staging clusters first.
- Run your workloads on the new release for a while and check that they behave as expected.
- Upgrade production clusters one at a time, or in small groups, rather than all at once.
- Spread production upgrades over different days or regions, so one issue can’t affect all them.
Before you start, read the changelog for the target release and make your workloads resilient to upgrades.
If an upgrade goes wrong
Contact Giant Swarm support right away through your usual channel. We’ll work with you to fix the issue on the current release, for example with a configuration change or a new patch release, rather than by downgrading the cluster. See the support overview for how to reach us.
Further reading
- Cluster upgrades explains how upgrades work and how to prepare your workloads for them.
- Workload cluster releases describes how releases are versioned.
Need help, got feedback?
We listen to your Slack support channel. You can also reach us at support@giantswarm.io. And of course, we welcome your pull requests!