mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-08 23:25:12 +00:00
8395d4326e
<!-- Please inform yourself about the contribution guidelines on submitting a PR here: https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr. Take note of how PR/commit titles should be written and replace the template texts in the sections below. Don't remove any of the sections. It is important that the commit history clearly shows what is changed and why. Important: By submitting a contribution you agree to the terms from our Licensing Policy as described here: https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions. --> # Which Problems Are Solved - Operators upgrading from ZITADEL v3 to v4 lacked a clear, docs-backed upgrade path covering web keys (A-10017), Login V1 vs Login V2 expectations, and post-upgrade options. - There was no standalone guide for adopting Login V2 after already running on v4. - Related ops/docs pages did not consistently point readers to the upgrade and Login V2 adoption material. - Kubernetes/Helm operators upgrading to a chart that ships ZITADEL v4 had no ops-page section linking the advisory, upgrade guide, optional Login V2 deferral (`login.enabled: false`), and chart README upgrade notes. # How the Problems Are Solved - Adds technical advisory **A-10017** documenting OIDC web key staging requirements before upgrading to v4. - Adds an **upgrade-v3-to-v4** guide with the recommended upgrade path (Login V1 remains supported; Login V2 is optional at upgrade time). - Adds a **v4-only adopt-login-v2** guide for teams adopting Login V2 later, with steps and caveats separate from the version upgrade. - Adds an **Upgrading to ZITADEL v4** subsection under `self-hosting/deploy/kubernetes/operations.mdx` that links to A-10017, the upgrade guide, Adopt Login V2, notes `login.enabled: false` when not adopting Login V2 yet, and points to the [Helm chart README](https://github.com/zitadel/zitadel-charts/blob/main/charts/zitadel/README.md) for chart-specific breaking changes. # Additional Changes - Registers new docs in the sidebar and wires Related / cross-links from upgrade and ops pages so the advisory and guides are discoverable together. - Aligns language so upgrade vs. Login V2 adoption are clearly separated concerns. - Light cross-link updates on troubleshooting / updating-scaling / login-client pages where related. # Additional Context - Related: A-10017 (web keys advisory) - Docs paths introduced/updated: - `apps/docs/content/support/advisory/a10017.mdx` - `apps/docs/content/self-hosting/manage/upgrade-v3-to-v4.mdx` - `apps/docs/content/self-hosting/manage/adopt-login-v2.mdx` - `apps/docs/content/self-hosting/deploy/kubernetes/operations.mdx` (new "Upgrading to ZITADEL v4" section) - Sidebar and Related / cross-links - Companion Helm chart README PR: https://github.com/zitadel/zitadel-charts/pull/608 --------- Co-authored-by: Cursor <[email protected]>
55 lines
2.5 KiB
Plaintext
55 lines
2.5 KiB
Plaintext
---
|
|
title: Upgrade from ZITADEL v3 to v4
|
|
description: "Recommended path for upgrading self-hosted ZITADEL from v3 to v4"
|
|
sidebar_label: Upgrade v3 → v4
|
|
---
|
|
|
|
## Summary
|
|
|
|
Upgrading from v3 to v4 is a normal ZITADEL upgrade: run **setup** (migrations), then **start**.
|
|
Existing instances keep working with their current login setup. Switching to Login V2 is optional and can be done later.
|
|
|
|
The main behavioral risk on this upgrade is OIDC signing keys. Follow [A-10017](/support/advisory/a10017) before moving to v4.
|
|
|
|
## Prerequisites
|
|
|
|
- Database backup
|
|
- PostgreSQL version compatible with your target v4 release ([database requirements](/self-hosting/manage/database))
|
|
|
|
## Recommended path
|
|
|
|
1. Upgrade to the latest **v3.4.x** (at least **v3.4.1**).
|
|
2. Soak until legacy-signed JWTs/sessions have expired (see [A-10017](/support/advisory/a10017)).
|
|
3. Upgrade to **v4.x**:
|
|
- Existing installs: prefer `zitadel setup` then `zitadel start`, or `start-from-setup`
|
|
- Details: [Update and Scale](/self-hosting/manage/updating_scaling)
|
|
|
|
<Callout type="info">
|
|
`ZITADEL_FIRSTINSTANCE_*` and `ZITADEL_DEFAULTINSTANCE_*` apply only when an instance is created.
|
|
Changing them and restarting does not update existing instances.
|
|
</Callout>
|
|
|
|
## After the upgrade
|
|
|
|
OIDC applications that already use your ZITADEL issuer usually need no changes.
|
|
|
|
**Staying on Login V1 is fine.** Existing instances keep Login V1, and you do not need to switch for a successful v4 upgrade.
|
|
Adopt Login V2 only if you specifically need it (for example features or flows that depend on Login V2 / Actions V2).
|
|
A switch can involve more than deploying the new UI — especially if you use **Actions V1**, which typically need to be reworked for **Actions V2**, and not every Login V1 customization maps one-to-one.
|
|
|
|
When you decide to move, see [Adopt Login V2 on an existing installation](/self-hosting/manage/adopt-login-v2).
|
|
|
|
## Helm
|
|
|
|
Follow the [Helm chart README](https://github.com/zitadel/zitadel-charts/blob/main/charts/zitadel/README.md) upgrade notes for the ZITADEL app version (for example chart v8 → v9 when moving to ZITADEL v4).
|
|
|
|
Newer charts may deploy a Login V2 workload by default. That does **not** enable Login V2 for existing instances.
|
|
If you are not adopting Login V2 yet, set `login.enabled: false` to omit the login Deployment.
|
|
|
|
## Related
|
|
|
|
- [A-10017: Web keys and v4 upgrades](/support/advisory/a10017)
|
|
- [Update and Scale](/self-hosting/manage/updating_scaling)
|
|
- [Adopt Login V2](/self-hosting/manage/adopt-login-v2)
|
|
- [Troubleshoot](/self-hosting/deploy/troubleshooting/troubleshooting)
|