> 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/solution-architecture/deployment/upgrade-strategy.md). # Taking a new release How this estate takes a new release — the two upgrade paths and how they differ, what the downtime honestly is, why the rollback plan is a database backup nothing takes for you, and what an upgrade do ## What this is, and when you need it This page settles **how the estate takes a new release, and what that costs in downtime, risk and discipline**. It is a decision customers make before they buy, and "how do upgrades work?" is one of the two or three questions a CIO always asks. You need it when the operating model is written, when a maintenance-window commitment has to be made, and when anyone proposes a customization — because the shape of an upgrade determines which kinds of customization are safe and which are quietly reverted. ## The decision | Path | What it is | Downtime | What it costs you | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | **Packaged Linux, in place** | A scripted upgrade that stops the whole platform, replaces binaries, runs the migrations forward and starts everything again | A full outage on every node | Nothing else to build, but no rollback, no database backup taken for you, and connectors left behind | | **Containers, replace the images** | Every workload moves to a new global version; the schema migration runs as its own job | A rolling replacement in principle | The shipped Terraform forces pod recreation rather than a graceful roll, and nothing sequences the migration against the workloads | | **Blue-green at whole-platform level** | Two complete stacks; cut the load balancer over | Near zero at cut-over | A second database set and a second everything — feasible, but entirely your design | The first two are the shipped paths and they differ fundamentally, not by degree. An architect has to know which one the estate is on before committing to a window, a rollback or a version currency target. ## Downtime, honestly **On the packaged path the window is a full outage, and it is dominated by startup rather than by the migration.** The upgrade stops every service, flushes the cache — destroying every HTTP session with it, since sessions live there — replaces the binaries, migrates against a quiet database, and starts everything again. The last step is what surprises people. **Services will not come up until every infrastructure dependency reports healthy** — the secrets store, the graph store and its backing store, the cache, the search tier and the broker are all gated on, and each service polls for that signal before starting. On a large estate that gating is most of the window: the migration time is the number people estimate and the startup time is the number they experience. **On the container path a rolling replacement is possible in principle.** The declared strategy replaces pods one at a time, so with several replicas the gateway and consoles can roll without dropping the endpoint, and **sessions survive** because they live in the cache — a genuine and often-missed benefit. Two shipped defaults work against it: the Terraform path forces **pod recreation rather than a graceful roll**, and on that same path **nothing sequences the schema migration against the workloads**. The declarative GitOps path does order it, which is a reason to choose it where the window matters. One further detail: **the cache cannot be flushed** on containers, because the shipped configuration disables the flush commands. ## There is no rollback **The packaged upgrade takes a file-level backup and no database dump, and migrations run forward only.** There is no reverse migration and no undo. Once the migrations have run, the file backup alone will not restore the previous release: the binaries it restores expect the previous schema, and the schema has moved. **The design consequence is that a database backup taken immediately before the upgrade is the customer's rollback plan, and nothing in the tooling takes it for them.** It has to cover every schema — the set is restored together or not at all, as [Availability and recovery](/solution-architecture/deployment/availability-and-recovery.md) sets out — and it has to be taken after the platform is stopped and before the migrations run. Write that into the runbook as a gate, not a recommendation. Note too that the upgrade run does not abort on a failed step, so a partially completed upgrade is a state you can reach and have to recognise. ## Mixed versions, and what actually runs together **The shipped tooling has one global version.** A single value sets every image tag and every chart version; there is no per-service versioning to hold one component back. The message contract argues the same way: **inter-service messages carry no version field, no capability negotiation and no schema registry**, so compatibility between releases is whether the message shapes happen to line up, which nobody verifies. Three positions follow: * **Blue-green at whole-platform level is feasible** and is the only clean way to avoid a window. It needs a second database set, because two stacks cannot share a schema at different versions. * **A rolling replacement within one stack does briefly run mixed versions** against one broker and one schema. Schema-version checking at startup is not uniform across the services, so a service can start against a schema at the wrong version and fail later rather than refusing to start. The shipped tooling deploys a single version across the estate, so plan an upgrade as a co-ordinated change rather than a per-service one, and agree any staged approach with OpenIAM as part of the upgrade plan. * **Anything else is not designed for.** The packaged procedure never has two versions live, which is precisely why it is a full outage. ### Connectors drift by default **The packaged platform upgrade does not touch connectors or source adapters**; they stay at the version they were installed at. That is a mixed-version state the shipped upgrade creates every time it runs, and the reason connector versions belong in the estate's inventory separately from the platform's. The Windows connector family is versioned on its own series and carries a documented compatibility constraint with platform versions: the queue type used for broker communication changed at a named platform release, and connectors from a named version onward default to the new type, with a connector-side setting to fall back for older platforms. Check that mapping before an upgrade, and plan connector upgrades as their own workstream — see [Connector placement](/solution-architecture/integration/connector-placement.md). ## What an upgrade does to your customization For each kind of customization: where it lives, and what each path does to it. | Customization | Where it lives | Packaged path | Container path | | ---------------------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------- | | Groovy scripts | On disk; only metadata in the database | Survives — never visited. Shipped script *updates* also never arrive | Survives on a shared volume | | Custom connectors | With the connector processes, or their own charts | Survives, and is not upgraded | Own chart, on the global version | | Modified property files | On disk with the deployment | Survives the supported upgrade; overwritten if the package is installed directly instead | Regenerated from deployment values | | Workflow definitions | On disk with the deployment | Survives; never updated | Replaced with the image | | UI customization | Labels and translations in the database, static assets on disk | Static assets wiped and replaced; database labels at risk from migrations, below | Replaced with the image | | Service unit changes | With the host's service definitions | Your edits survive; **shipped changes do not arrive** | Not applicable | | Internal proxy configuration | On the host | **Edited in place on every upgrade**, then validated, then restarted by hand | Rendered from the chart | **The pattern worth naming: on the packaged path, customization is protected by omission rather than by design.** The upgrade does not visit most of the directories where customization lives — good for the customization, bad for everything else in those directories, because **shipped improvements to those same files never reach an upgraded host**. Only a fresh install gets the current tree, so over several releases an upgraded estate and a freshly installed one diverge invisibly. ## Shipped content and your configuration share the same tables The sharpest thing on this page, and the reason the table above is not the whole story. OpenIAM's shipped content and the customer's configuration live in **the same database tables, distinguished only by well-known identifiers**, and upgrade migrations reassert shipped rows by identifier — typically removing the row and re-inserting the shipped version. Three categories illustrate it: * **System property values.** A property whose shipped default a customer deliberately changed can be reset to it; one recent release did exactly this to the property capping concurrent sessions, `org.openiam.session.max.concurrent`. Properties are also removed outright when a capability retires. * **Mail templates.** A shipped template's body is re-inserted wholesale when it changes, so any restyling is lost. * **Menu items and their entitlements.** A shipped menu item's labels, translations and role grants can be deleted and re-created with the shipped grant, so re-scoping it to a different role is lost. Migrations touch customer data too: a release may back-fill a new object onto every existing record of a kind, and that back-fill assumes the shipped arrangement. **The design rule this yields is short: customize by adding, not by editing shipped objects.** Create your own property, template, menu item or role and leave the shipped one alone. Where that is genuinely impossible, **keep a written record of every shipped object you did edit, because an upgrade will not tell you it changed one back.** That register is a deliverable of the configuration work — see *Change configuration safely* in the Administration Guide. ## How far behind can an estate be? **The supported upgrade path depends on the version being upgraded from.** Two properties of the migration tooling decide it, and both are worth settling with OpenIAM for a specific starting version when the upgrade is planned rather than when it is executed. The *shape* is consistent, and it is enough to design against in the meantime. **Migrations are cumulative back to a floor that differs by database engine** — the earliest release the shipped trees can carry forward is materially later on some engines than others, so an old estate on an engine with a late floor may have no direct path. **The operator then sets a baseline by hand, and its correct value depends on the version being upgraded from**; get it wrong and you either replay migrations that have run or skip ones that have not. **There are named stepping-stone releases that cannot be skipped.** Separate upgrade tooling ships for particular starting points, and at least one refuses any target but its designated next release. **Upgrades are therefore stepped, not arbitrary jumps**, and *"how far behind is this estate?"* is worth asking before signing — the answer can turn one upgrade into three. **Schemas have also been added over time**, each in a named release, and crossing one of those boundaries means **a new database, a new user and new credentials must exist before the upgrade runs**. The tooling refuses to start until they are configured, so it is an infrastructure and secrets task with its own lead time. ### The schema count This release deploys seven schemas. The point behind the arithmetic matters more than the number: **the count is not fixed**, each schema is independently versioned, and a new one is a routine event that arrives with a database, a user and a credential attached. Size the backup — and the restore rehearsal that proves it — to the schemas the release you are deploying actually deploys. ## What a rehearsal has to prove [Environments and tenancy](/solution-architecture/deployment/environments-and-tenancy.md) covers the case for a fourth environment dedicated to upgrade rehearsal. Given everything above, a rehearsal that only proves "the upgrade completed" has not earned its cost. It has to prove five things: that **the migrations complete against a copy of production data**, since the risk lives in rows the estate has edited; **the measured window**, including the startup gating and not only the migration; that **the pre-upgrade backup restores**, taken exactly as the runbook says, because an untested rollback plan is not one; **which shipped objects were changed back**, by comparing the register of edited objects against the post-upgrade state — the check nothing else performs; and that **the connectors still work at the version they are on**. Run it against the production topology. ## What we recommend **Take a full database backup immediately before every upgrade, as a gate rather than a task.** Nothing in the tooling does it, migrations are one-way, and this is the entire rollback plan. If the change record does not name the backup and its verified restore, the change should not proceed. **Customize by adding, and keep a register of any shipped object you had to edit.** This one discipline removes most of the upgrade risk on this page and costs nothing at the time. **On containers, use the declarative deployment path if the window matters.** It is the one shipped route that sequences the schema migration ahead of the workloads. **Plan an upgrade as three workstreams:** the platform, the connectors, and the configuration review afterwards. The middle is invisible in the tooling; the last is the only place a reverted customization gets caught. And **budget the fourth environment** where upgrades will be frequent or the estate large, because the rehearsal is the only place the five proofs above can be obtained. **Ask "how far behind is this estate?" before committing to a date.** Stepping stones, engine-specific floors and a manually set baseline mean an old estate may need several upgrades in sequence. What changes this advice is a small, lightly customized estate on a recent release: there the packaged in-place upgrade with a verified database backup is adequate, and blue-green and a rehearsal environment are cost without benefit. The advice tightens in proportion to how much configuration has been done and how far behind the estate has drifted — both of which grow quietly. ## What OpenIAM does not do here * **There is no automated rollback and no reverse migration.** Migrations run forward only, the packaged backup covers files rather than the database, and **nothing takes a database backup for you** on either path. * **Schema-version checking at start is not uniform across the services.** Where it is absent, a service starts against a schema at the wrong version and fails later rather than refusing to start. * **The upgrade path is not a fixed matrix.** It depends on the version being upgraded from — migrations are cumulative to an engine-dependent floor and some releases are mandatory stepping stones — so confirm the path for a specific starting version with OpenIAM when the upgrade is planned. * **There is no per-service versioning.** One global version sets every image and every chart. * **Inter-service messages carry no version or capability information**, so cross-version compatibility is not designed for and is verified nowhere. * **The packaged upgrade does not upgrade connectors**, and **nothing reports which shipped objects an upgrade changed back** — no diff, no warning, no log entry naming your configuration. ## Related * [Environments and tenancy](/solution-architecture/deployment/environments-and-tenancy.md) — the case for a rehearsal environment, and why configuration is rebuilt rather than promoted. * [Availability and recovery](/solution-architecture/deployment/availability-and-recovery.md) — why the pre-upgrade backup has to cover every schema at once. * *Change configuration safely* in the Administration Guide — the habits that make customize-by-adding practical. * *What a backup and restore must cover* in the Administration Guide — the scope of the backup this page makes a gate. * The [Installation Guide](/installation/installation.md) — running the upgrade, and the stepping-stone tooling. *Applies to OpenIAM 2026.8.1. Last reviewed 13 August 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/solution-architecture/deployment/upgrade-strategy.md?ask=&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.