Upgrade from ZITADEL v3 to 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 before moving to v4.

Prerequisites

Database backup
PostgreSQL version compatible with your target v4 release (database requirements)

Recommended path

Upgrade to the latest v3.4.x (at least v3.4.1).
Soak until legacy-signed JWTs/sessions have expired (see A-10017).
Upgrade to v4.x:
- Existing installs: prefer zitadel setup then zitadel start, or start-from-setup
- Details: Update and Scale

ZITADEL_FIRSTINSTANCE_* and ZITADEL_DEFAULTINSTANCE_* apply only when an instance is created. Changing them and restarting does not update existing instances.

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.

Helm

Follow the Helm chart README 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.