> 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/major-upgrade.md).

# Major upgrade

Crossing from the 4.2.1 line onto the 2026 line on Kubernetes — new databases, new microservices, and a search tier that has to be migrated.

{% hint style="danger" %}
**Draft — not ready to follow.** The structure below is settled; the procedures are not yet verified against a running cluster. Do not use this page for an upgrade until this notice is removed.
{% endhint %}

## What this is, and when you need it

A move from any **4.2.1.x** release onto the **2026** line, on a Kubernetes deployment. The worked target below is **2026.8.2**.

Unlike a [minor upgrade](/installation/kubernetes/kubernetes-upgrade/minor-upgrade.md), this is not the ordinary deployment run against a newer version. Three things happen underneath it that the deployment cannot do on its own: the search tier is replaced and its data carried across, new databases are provisioned, and subsystems that used to live inside `openiam-esb` are deployed as separate services with their own data.

{% hint style="warning" %}
This is a supported upgrade. Open a support case before you begin — OpenIAM confirms the correct target for your starting version, which is not always the newest release.
{% endhint %}

## What changes, coming from 4.2.1.x

Fifteen releases sit between 4.2.1.x and 2026.8.2.

### Your deployment goes from two databases to eight

4.2.1.x ran on `openiam` and `activiti`. Across this span the platform broke six subsystems out into their own services, each owning its own database:

<table><thead><tr><th width="137.5999755859375">Arrived in</th><th width="217.4000244140625">Database</th><th>Service</th></tr></thead><tbody><tr><td>4.2.2</td><td><code>groovy</code></td><td><code>groovy-manager</code></td></tr><tr><td>2026.3.1</td><td><code>auditlog</code></td><td><code>audit-log-manager</code></td></tr><tr><td>2026.5.2</td><td><code>batchtasks</code></td><td><code>batch-task-manager</code></td></tr><tr><td>2026.6.1</td><td><code>certification</code></td><td><code>certification-manager</code></td></tr><tr><td>2026.7.1</td><td><code>pbac</code></td><td><code>pbac-manager</code></td></tr><tr><td>2026.8.1</td><td><code>privacy</code></td><td><code>privacy-manager</code></td></tr></tbody></table>

This upgrade crosses all six — take every set of steps in [*Release-specific steps*](/installation/kubernetes/kubernetes-upgrade/release-specific-steps.md).

{% hint style="danger" %}
**This changes what a backup has to cover.** A backup written against 4.2.1.x captures two databases out of eight. It will still complete, still report success, and no longer be a rollback position.
{% endhint %}

### Two infrastructure components were replaced

Moving onto the 2026 line replaces two components: **Elasticsearch with OpenSearch** — a licensing change, not a preference — and **ETCD with Consul**. FileBeat, MetricBeat and Kibana are no longer used.

The OpenSearch move is the one that needs work from you: the audit log index has to be dumped out of Elasticsearch and loaded into OpenSearch, which means running both in a reduced, unauthenticated state for the duration.

### Custom Groovy scripts that extend certification or batch tasks must be updated

Base classes moved package twice across this span. Scripts referencing the old packages fail to compile. The shipped scripts under `conf/iamscripts/` were updated; anything customised was not. The full table of package moves is in [*Release-specific steps*](/installation/kubernetes/kubernetes-upgrade/release-specific-steps.md#custom-groovy-scripts-must-be-re-pointed).

### Custom Groovy scripts that reach outside their sandbox will stop working

2026.8.2 runs Groovy scripts inside a sandboxed engine instead of an unrestricted shell. A script that touches system properties, arbitrary classes, the filesystem or the network directly will fail once this upgrade completes. Review your customised scripts for these before you upgrade — a script that only reads its own parameters and calls approved APIs is unaffected.

### What you gain

<table><thead><tr><th width="201.60003662109375">Area</th><th>What arrives between 4.2.1.x and 2026.8.2</th></tr></thead><tbody><tr><td><strong>Segregation of duties</strong></td><td>The whole subsystem — policy management, enforcement during access requests, continuous violation monitoring, mitigating controls and a violations report. Then a <strong>Rule Set Catalog</strong> of pre-built libraries for Manufacturing, HR and Payroll, Financial Services, Plant Maintenance and SAP Basis in US and EU variants, with drift detection, re-sync, rule set comparison, and scheduled detection runs that email a digest</td></tr><tr><td><strong>Access certification</strong></td><td>Rewritten, then rebuilt again. Event-driven campaigns, <strong>campaign preview</strong> — the full scope and reviewer calculation against real data, with every exclusion and its reason, promoted to launch from the snapshot — <strong>extended user search</strong> for building campaign populations without SQL, launch history, bulk approval, side-by-side entitlement comparison against a peer or a previous campaign, entitlement descriptions in the reviewer's view, and a pending-review-only filter. Campaign History, preview and report downloads were substantially reworked for large campaigns in 2026.8.2</td></tr><tr><td><strong>Identity risk</strong></td><td>New. Risk-driven campaign scope with a minimum-risk threshold, live risk that updates mid-campaign with drift indicators and a factor breakdown, a <strong>User Risk</strong> page showing the grant path for every access row, and a Risk Score Configuration screen</td></tr><tr><td><strong>Privacy management</strong></td><td>New in 2026.8.1: an event-sourced <strong>consent ledger</strong> with a live current-state projection, a registry of processing purposes, activities and lawful authorities with governed versioning, a durable privacy event backbone with reconciliation, evidence records for every state change, and a Privacy Administration Console. 2026.8.2 adds <strong>notice authoring</strong> — versioned per language, with a draft-to-publish approval chain — and a self-service <strong>Privacy Center</strong> where users manage their own consent and preferences</td></tr><tr><td><strong>Access control</strong></td><td>A <strong>PBAC console</strong> with shadow, percentage and full rollout modes, a simulation runner that shows what a policy would decide without changing anything, and a decision log recording which policies applied. Delegated access requests can be disabled per application</td></tr><tr><td><strong>Authentication</strong></td><td>Compromised-password detection against Have I Been Pwned, passwordless sign-in with FIDO2 and the OpenIAM Auth App, and risk-based authentication with device intelligence</td></tr><tr><td><strong>Administration scope</strong></td><td>Virtual tenants — organization administrators can be scoped so they see only their own organizations, in both the Webconsole and SelfService</td></tr><tr><td><strong>Operations</strong></td><td>Prometheus monitoring, a descriptive analytics dashboard, a redesigned Groovy Manager with bulk import and export, RequestId enrichment across logs, a redesigned SelfService portal, and CJIS and STIG deployment profiles on RHEL</td></tr><tr><td><strong>Connectors</strong></td><td>Multi-instance Windows installer for .NET v6, PowerShell connectors shareable between production and non-production, and connector-level query-injection protection</td></tr><tr><td><strong>Security</strong></td><td>2026.8.2 closes a reflected XSS path on password reset, sandboxes Groovy script execution, parameterizes Oracle and PostgreSQL DDL against injection, and restores proper TLS verification in the Tableau, SAP UME, Thales and Salesforce connectors — see the Groovy sandbox note above before you upgrade</td></tr></tbody></table>

## Before you begin

Take the backups and checks in [*Upgrading OpenIAM*](/installation/kubernetes/kubernetes-upgrade.md#before-any-upgrade) first.

{% hint style="warning" %}
**Three prerequisites specific to this upgrade are not yet confirmed:** the earliest release you can start from, the node headroom needed while both search tiers run side by side, and whether the audit-log export threshold that applies on RPM applies here too. Confirm all three with OpenIAM support when you open the case.
{% endhint %}

## Provision the new databases and deploy their services

All six are covered in [*Release-specific steps*](/installation/kubernetes/kubernetes-upgrade/release-specific-steps.md) — the databases, the Helm values blocks that inject their names, and the one-shot data migrations that `batch-task-manager` and `certification-manager` need. Take every set: this upgrade crosses all of them.

## Migrate the search tier to OpenSearch

The audit log index has to be dumped out of Elasticsearch and loaded into OpenSearch. The two run side by side for the duration, both in a reduced and unauthenticated state, and parts of the stack are deliberately taken down while it happens — this is the longest part of the upgrade and the part that most needs a rehearsal.

{% hint style="danger" %}
**Not yet written.** A procedure exists but is documented against an older release line and has not been run against a current cluster. Ask OpenIAM support for the current sequence rather than adapting an older one — it includes `terraform state` edits that are difficult to undo.
{% endhint %}

## Redeploy and verify

{% hint style="warning" %}
**Not yet written.** This section will cover the final redeploy and the checks that prove the upgrade landed: every release reporting `deployed`, the new services running, the audit log queryable through OpenSearch, and a campaign visible after the certification migration. Until it exists, use [*Verify a Kubernetes deployment*](/installation/kubernetes/verify.md).
{% endhint %}

## Related

* [Release-specific steps](/installation/kubernetes/kubernetes-upgrade/release-specific-steps.md) — the six databases and services this upgrade crosses
* [After a major upgrade](/installation/kubernetes/kubernetes-upgrade/after-a-major-upgrade.md) — what to put right once it completes
* [Minor upgrade](/installation/kubernetes/kubernetes-upgrade/minor-upgrade.md) — staying on the line you are already on
* [Major upgrade — RPM](/installation/rpm/rpm-upgrade/major-upgrade.md) — the same move, on an RPM deployment
* [Back up and restore](/installation/kubernetes/back-up-and-restore.md) — the five-part backup this depends on

*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/major-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.