Zitadel v3 to v4 upgrade

The setup step runs before any v4 service starts because the database has to match what the new runtime expects before it reads or writes anything. When v3 and v4 share one PostgreSQL database, there is a window in which the schema or stored state is being prepared for the new release while older processes may still be connected. Running setup first, as a deliberate and separate step, keeps the new services from starting against an unprepared database and makes the cutover order explicit. It also gives the team one checkpoint: if setup fails, no v4 process has taken traffic yet. The exact protection depends on what the target release changes, so the team should read the upgrade notes for that release and confirm what they say about the database.

The command, its place in the sequence and whether it can be run again safely are defined by the official self-hosting documentation for your deployment method. Zitadel documents binaries, Docker Compose and Kubernetes with the official Helm chart, and each one wires the setup step differently. Confirm the exact invocation for the release you are moving to, the required configuration and database credentials, and whether it must complete before the new service definition is applied. Ask specifically whether the step is idempotent, meaning a second run on an already prepared database is harmless, because that decides how a failed run is retried. Confirm also that your PostgreSQL major version falls within the 14 to 18 range the database documentation supports. Record the answers in the runbook along with the documentation version you read, so a reviewer can check them later.

Setup changes shared state, so it is an operational event in its own right. Take a full database backup before it runs and verify that it can be restored, because an untested backup is only an assumption. Back up the configuration and secrets the v3 deployment uses, since both the new runtime and any rollback depend on them. Keep the v3 container images, binaries or Helm release revision available so the old runtime can be started again. Confirm in the documentation whether a v3 runtime can run against a database after setup has changed it. If it cannot, a database restore is the only rollback path, and the team must plan for that outcome before the window opens.

Agree the rollback point before the first v4 process starts, in writing, with named decision makers. The record should state which backup identifier is the restore point, who has authority to declare a rollback, which signals trigger that decision, and how writes from users and integrations are paused or replayed if a restore is needed. Decide whether the gap between backup and cutover is short enough that data written in it can be reconciled, and document how that reconciliation would work. Make sure the on-call engineers and the application owners who depend on the identity service have reviewed the plan. A rollback point that exists only in one engineer's memory will not hold up during an incident.

Rehearse the sequence on a copy of production data before the real window. Illustrative example: a team restores the latest backup into a staging environment running the same PostgreSQL major version, runs setup, runs it a second time to test idempotency, and then starts the v4 services against that copy. Each step produces a log entry and a check that the team can compare with the production run. The rehearsal also shows how long the backup and restore take in your environment, which is the figure to use when scheduling the window. Record the result in the cutover runbook, and ask your DeployOpen team or internal engineers to sign off on each step before the production change is approved.

Before cutover, the team must test the hosted login experience on the Zitadel v4 runtime, because end users reach Login V2 directly and a fault there blocks sign-in for every organization that depends on it. The hosted login covers four areas that users encounter in sequence: sign-in, passkeys with password fallback, federated identity provider buttons, and branding. Each area has its own code path and its own failure modes, so each needs explicit test cases. Treat a passing v3 setup as a starting point only. Confirm in the Zitadel v4 documentation which login and branding behaviors are documented for v4 before you write the test plan.

The core of the test plan is a matrix. The rows are the instances and organizations you run, because Zitadel separates tenants into instances and places organizations inside them, and each customer organization may have its own branding and its own identity provider. The rows also include each federated identity provider configured for those organizations, such as Entra ID, Okta or Google. The columns are the flows a user can take: first passkey enrollment, sign-in with a passkey, fallback to password when a passkey is unavailable, password reset, and the error pages for wrong credentials, disabled accounts and a failed upstream provider. Ask the platform owner to list which cells are actually in production use, and test those first.

Branding needs its own verification step because settings may not move between versions in the same form. Build an inventory of every branding setting in the v3 configuration for each instance and organization, including logos, colors, text and any per-organization overrides. For each item, use the v4 documentation to decide whether it carries over automatically, needs manual re-entry, or changed meaning. Record that decision in the plan with the source page you used. Then apply the v4 configuration to a staging copy of the production data and compare the rendered login pages against approved screenshots for each organization. Do not assume a visually similar page means the setting was applied correctly.

Browser and device coverage determines whether passkey tests mean anything. Passkey prompts, platform authenticators and password manager behavior differ between desktop browsers and between iOS and Android devices, so enrollment and sign-in should be tested on each browser and device class your users run, not only on the engineering laptop. Confirm the browsers and platforms the v4 documentation lists as supported for Login V2, and record any combination you test outside that list as a known risk. Include at least one session where a user switches between a passkey and a password on the same account, because that switch is where fallback defects tend to appear.

Set the exit criteria before testing starts. Name who signs off each organization's login and branding results, what counts as a blocking defect, and what happens if a check fails close to the cutover date. Write down the rollback path for the login layer, including who can make the call and how users are told. Your quote from DeployOpen should list the number of organizations, identity providers, browsers and devices in scope, since those counts drive most of the testing effort. Ask for the matrix to be reviewed by your identity team and by any customer owner who manages branding for their own organization.

Decide whether Service Ping stays enabled before production cutover, and write the decision down. Before making that call, the team has to establish from the Zitadel v4 documentation what the setting is, whether any data is sent to Zitadel, how the setting is switched on or off in the configuration, and whether it can be disabled entirely. This page does not describe what Service Ping collects. The team should take that from the official documentation for the exact release it deploys. Record the answer to each of those questions in the upgrade ticket so the decision rests on the vendor's own text, not on memory or a secondhand summary.

The security and data protection owners should test the decision against two commitments: the outbound traffic policy and data residency. Ask the platform team to show the destination the instance would contact, the protocol, the direction of traffic, and the network path that would carry it. If the instance runs in a restricted or air-gapped network, an outbound call may be impossible to allow, and the team needs to know that before the cutover window. Confirm also whether any data sent could identify tenants, organizations or users, because that answer determines whether the data protection lead needs a formal assessment before approval.

Name one accountable approver, usually the security or platform owner with input from data protection, and state who may change the setting later. Keep the record where auditors can reach it. It should include the setting value in each environment, the documentation version consulted, the date, the approver and the reason for the choice. A short, dated decision record that quotes the exact configuration key or environment variable is more useful to an assessor than a general statement that telemetry was reviewed. Pair the record with an export of the effective configuration from the running instance, not only the intended configuration in source control.

Make the decision in staging first, using the same configuration template that production will use. Confirm the effective value after setup and after the first restart in each environment, since the value the instance reads is what matters, not the value the team meant to write. Schedule a review of the decision whenever the deployment changes in a way that affects outbound access or data handling, such as a new network path, a change in hosting region, a move to a different deployment method, or a change to the outbound policy. Note in the record that this review is a standing trigger, not a one-time sign-off.