> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/installation/kubernetes/kubernetes-upgrade.md).

# Upgrading OpenIAM

Decide whether you are doing a minor or a major upgrade of a Kubernetes deployment, then take the checks that apply to both before you start.

A Kubernetes deployment is upgraded in one of two ways, and which one you are doing is the first thing to establish — they differ in what they touch and how long the window needs to be.

## Which upgrade are you doing?

The question is not how far apart the version numbers look. It is **whether you are staying on your current release line or crossing to a different one.**

<table data-header-hidden><thead><tr><th width="154.4000244140625"></th><th></th><th></th></tr></thead><tbody><tr><td></td><td><a href="/installation/kubernetes/kubernetes-upgrade/minor-upgrade.md">Minor upgrade</a></td><td><a href="/installation/kubernetes/kubernetes-upgrade/major-upgrade.md">Major upgrade</a></td></tr><tr><td><strong>What it is</strong></td><td>A point upgrade inside the line you are already on</td><td>A move onto a different release line — any 4.2.1.x → any 2026.x</td></tr><tr><td><strong>How it runs</strong></td><td>Set the release, check out the matching tag, re-run the deployment</td><td>Data migration steps first, then the same redeploy</td></tr><tr><td><strong>Support case</strong></td><td>Not required</td><td><strong>Required.</strong> OpenIAM confirms the path from your starting version</td></tr><tr><td><strong>Databases</strong></td><td>Unchanged</td><td>New databases and new microservices are added, each provisioned before you start</td></tr><tr><td><strong>Infrastructure</strong></td><td>Unchanged</td><td>Components are replaced, and their data has to be carried across</td></tr><tr><td><strong>Downtime</strong></td><td>The rolling redeploy</td><td>Planned — parts of the procedure take the stack down deliberately</td></tr><tr><td><strong>What you get</strong></td><td>Fixes on the line you are on</td><td>Everything shipped since the lines diverged</td></tr></tbody></table>

{% hint style="warning" %}
**The 4.2.1.x and 2026 lines run in parallel.** 4.2.1.x releases are still cut after 2026 releases exist, so a higher 4.2.1.x number does not mean newer than a 2026 release. Staying on 4.2.1.x is a maintenance decision; moving to 2026 is a feature decision.
{% endhint %}

## Two pages apply to both

* [**Release-specific steps**](/installation/kubernetes/kubernetes-upgrade/release-specific-steps.md) — a few 2026 releases add a database and a chart, which no redeploy can create for you. Check this against every release you pass through, not only the one you stop at.
* [**After a major upgrade**](/installation/kubernetes/kubernetes-upgrade/after-a-major-upgrade.md) — what to put right once a major upgrade completes. Most of it is database and configuration work that applies to both platforms.

## Before any upgrade

These apply whichever kind you are doing.

* **Back up all five places a Kubernetes deployment holds state** — the database schemas, the `secrets` secret, the secret store's data, its unseal keys and root token, and the deployment configuration. A managed database backup on its own is not a backup of the deployment. The procedure is in [*Back up and restore*](/installation/kubernetes/back-up-and-restore.md).
* **Record which version of the deployment materials is running.** A restore needs the `setup-no-tf.sh` that was in use, so upgrading and restoring at the same time gives you neither.
* **Commit your local customisations** to your fork of the deployment repository before you check out a new tag, so they can be merged forward rather than rediscovered.
* **Read the release notes for your target.** They carry anything specific to the version you are moving to.

{% hint style="danger" %}
**The schema migration is not reversible by re-running the previous version.** Once the migration job has run, going back means restoring from backup — which is why the backup above is a prerequisite and not a precaution.
{% endhint %}

## Related

* [Upgrading OpenIAM — RPM](/installation/rpm/rpm-upgrade.md) — the same decision, on an RPM deployment
* [Deploy with Helm](/installation/kubernetes/deploy-with-helm.md) — the deployment these upgrades run against
* [Back up and restore](/installation/kubernetes/back-up-and-restore.md) — the five-part backup, and the restore rehearsal
* [Verify a Kubernetes deployment](/installation/kubernetes/verify.md) — what a healthy stack looks like afterwards

*Last reviewed 9 September 2026.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/installation/kubernetes/kubernetes-upgrade.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.