Why an authentik upgrade path cannot skip versions
If your self-managed authentik is several releases behind, the work ahead is upgrading through each release in turn, because authentik's upgrade guidance says versions must not be skipped. Each release can run database migrations that assume the previous release's schema and data have already been applied. Jumping from an old version straight to the newest one means those migrations run in an order the project did not test against your data, and a failed or inconsistent migration is harder to recover from than a failed step in a sequence. Treat the sequence as a plan you write down before touching production, with one target per step. Each step should land on the latest patch of that major.minor release, not the first patch, because the patch level carries fixes to the upgrade itself. Before every step, take a PostgreSQL backup, since authentik stores all configuration and data in PostgreSQL except uploaded files, and PostgreSQL is what you restore if a step goes wrong. Downgrades are not supported, so a backup and restore is the only way back. Check the current authentik security policy before you set your end point. It lists 2026.5.x and 2026.8.x as the supported lines receiving security fixes, and the project announces security releases at least 24 hours in advance. If your running version is outside those lines, the sequence is also a security matter, so confirm the target line and the timing of your change window with your own security team early in the plan.
What changed between releases and what each change asks of you
This table lists the release changes that the supplied facts confirm and what each one asks of your upgrade plan. Read it before you choose a target version, then open the sibling release page for each version you will cross. The main takeaway is that the 2025.10 Redis removal is a database capacity change, not only a configuration edit.
| Change | Impact | Action needed |
|---|---|---|
| Redis removed in 2025.10 | authentik no longer uses Redis. Caching, tasks, sessions and WebSocket functions move to PostgreSQL. | Remove Redis settings from your configuration and confirm PostgreSQL handles the new load before you cross this release. |
| More PostgreSQL connections after 2025.10 | The 2025.10 release notes warn of roughly 50% more PostgreSQL connections after upgrading. | Size PostgreSQL connection limits and any pooler before the upgrade, and check connection counts after it. Confirm the figure against the release notes. |
| Background tasks use PostgreSQL | Worker activity and session handling now depend on the database. | Check database availability, backup timing and monitoring of the database during the upgrade window. |
| Supported security release lines | The security policy lists 2026.5.x and 2026.8.x as receiving security fixes. | If you run an older line, plan a path into a supported line rather than patching in place. |
| Latest release at time of writing | The GitHub releases page shows 2026.8.4 published on October 14, 2026 as the latest release. | Confirm the current latest patch on the releases page before you set your target version. |
| Per-version breaking changes | Each later release carries its own configuration, API and integration changes. | Read the sibling release page for every version between your current and target release. Do not rely on this table alone. |
| Outposts and worker containers | Outposts and the worker container must match the core version after each step. | Plan outpost and worker image updates together with each core step. |
How to step through each release without a downgrade
The sequence moves an outdated authentik deployment one release at a time, so each migration runs on a known state and every step has a verified restore point. The result is a current version reached without skipped migrations or downgrades.
Confirm the current version and the target path
Record the authentik version the server and worker containers currently run, using the version shown in the admin interface and the image tags in your Compose file or Helm values. List every release between that version and your target, and identify the latest patch of each major.minor release in turn. Your platform owner signs off the path before any change is made, because the path determines how many upgrade cycles you will run. The step is done when the list is written down and agreed.
Take and verify a PostgreSQL backup
Take a PostgreSQL backup before touching the running stack, since authentik stores its configuration and data in PostgreSQL and a restore is the only way back from a failed migration. Store the backup outside the host or cluster being upgraded and record its timestamp and checksum. Confirm the backup restores into a scratch database if your team has a practice for that. The step is done when the backup file exists in a second location and the restore procedure has been written down for the on-call engineer.
Upgrade to the latest patch of the first release
Change the server and worker image tags to the latest patch of the first release in your path, then pull the images and restart the stack in the order your deployment method requires. Do not change any other settings in the same window, so that a failure can be traced to one change. Wait for the containers to report healthy before moving to the checks. The step is done when the new containers are running on the intended image tag.
Check version, logs and login health
Confirm that the version shown in the admin interface has changed to the release you just deployed. Search server logs and worker logs for migration inconsistency messages, and treat any match as a stop condition. Sign in with a test account, and check that outposts such as LDAP, RADIUS, proxy or RAC report healthy and on the matching version if you run them. The step is done when the version has changed, no inconsistency appears in either log, and login and outpost health checks pass.
Restore the backup if the version does not change
If the version display does not change, or the logs show migration inconsistency, stop the stack and restore the PostgreSQL backup taken before this release. Authentik does not support downgrades, so restoring the database is the rollback point at every step, and the image tags should match the restored data before the stack starts. After the restore, return to the upgrade sequence from the same release and resolve the error before continuing. The step is done when the restored deployment shows the pre-upgrade version and passes the login check.
Repeat the cycle for each release in order
Once a release passes every check, take a fresh PostgreSQL backup at that point, then move to the latest patch of the next release on the list. Each cycle repeats the backup, upgrade and verification steps, so the restore point always sits at the most recent successful version. Do not skip a release, even if a later release appears to contain the same changes. The step is done when every release in the path has been deployed and verified in sequence.
Confirm the final state and record the result
After the last release, confirm the running version, outpost versions and login health, and check that the server and worker logs are free of migration errors. Review the release notes for each step in the path against your integrations, since some releases change provider behavior, redirect URIs or configuration keys. Record the version history, backup identifiers and check results in your change record. The step is done when the change record shows a verified final version and the next backup schedule is confirmed.
Backups and inventory before the first upgrade step
The backup that matters most is the PostgreSQL database, because authentik's architecture documentation states that PostgreSQL stores all configuration and data except uploaded files. Users, providers, applications, flows, policies, tokens and audit history all live there, so a backup of the containers or the code alone does not protect your deployment. Take a logical or physical PostgreSQL backup and confirm it is restorable before any version changes. Uploaded media, such as application icons and branding files, sits outside the database and must be backed up separately from the storage path your deployment uses. Confirm with your own configuration where those files are kept, since the path has changed in past releases and the upgrade guide for each step is the authority.
Build the inventory before the first step, because a sequential upgrade touches every version boundary and each one can break something you have customized. List every custom blueprint, the reverse proxy configuration in front of authentik, all environment variables set for the server and worker containers, and every outpost with its image tag and the integration that manages it. Record the current version of each component. Store this inventory in version control or another controlled location so the next team can rebuild the deployment without guessing. Confirm the exact release notes for each intermediate version as you plan, because blueprint syntax, environment variable names and proxy headers have changed between releases.
Restore is the only revert path, because authentik does not support downgrades. Treat the production backup as the rollback point for the whole project and rehearse it: restore the backup into a separate test environment with the same versions, proxy settings and outposts, then run the upgrade steps there first. Use the test environment to check sign-in for each provider type your users depend on, and to review server logs after each step for migration inconsistency messages. If the test run shows problems, you can restore and retry without touching production. Ask your team who approves the cutover and how long a restore takes on your storage, because that time sets how far a failed production step can be reversed.
What to prepare before you start the upgrade
A sequential upgrade multiplies the number of times you touch a live identity service, so preparation matters more than usual. The six items below cover what you must have in hand before the first step: a proven restore, a current inventory, a matching test environment, an agreed window, aligned outposts and a checked database connection setup.
Backup and restore rehearsal
authentik's upgrade guide says to back up PostgreSQL before each upgrade and to restore from backup to revert, because downgrades are not supported. A backup you have never restored is an assumption, not a rollback plan. Confirm that you can restore the dump into a clean instance, start the matching authentik version, and log in with a test account before you begin. Record how long the restore took in your own environment.
Configuration and integration inventory
Several releases in a row can change provider behavior, redirect URIs, group handling and custom code that calls the API. List every provider, application, flow, policy, source, outpost and custom script that depends on authentik, along with the owner of each. Note which ones have been changed by hand since the last deployment. This inventory tells you which release notes apply to your tenant and which integrations need a retest after each step.
Test environment parity
Build a non-production copy from a recent production backup, pinned to the same starting version and deployed the same way, with Docker Compose or Kubernetes as used in production. Run the full sequence of version steps there first and time each one. Differences in reverse proxy, external PostgreSQL or the presence of outposts can hide problems that only appear in production. Confirm that the test copy also covers your real integrations, not just the admin login.
Maintenance window and communication
A multi-step upgrade means several restarts, and each step should be followed by checks that the version changed and that server logs show no migration inconsistency. Agree a window with the application owners who sign in through authentik, and name who decides to stop or roll back. Publish the expected impact, including any forced re-login, so help desk staff are prepared. Ask your team how many steps the window can absorb if a check fails partway.
Outpost version alignment
LDAP, RADIUS, proxy and RAC outposts run separately from the core and must match its version. Before the first step, list every outpost, where it runs, and whether it updates automatically through an integration or needs a manually changed image tag. Plan to bring outposts up to each intermediate version in the same order as the core, so that no step leaves an outpost behind. Confirm the health and version each outpost reports in the admin interface after every step.
PostgreSQL sizing and TLS
Some intermediate releases change how authentik connects to PostgreSQL, and the 2025.10 release notes warned of roughly 50% more connections after the upgrade. Check your PostgreSQL connection limit, pooler settings and any Redis configuration that should now be removed. Confirm whether your database requires TLS and whether the connection options in your settings still match the current documentation. Verify these against the release notes for each version you pass through, not only the final target.
How to spot a migration inconsistency error
The documented signal is simple: after you run an upgrade, check the running version. If it has not changed, the upgrade did not complete, and authentik's upgrade guide tells you to search the server logs for a migration inconsistency. Do not keep restarting the containers or re-pulling images to see if it resolves itself. Check the version the server reports, then check the logs for the server container and the worker container, since either can hold the failure. Because the exact wording of the log entries can change between releases, confirm the search strings against the authentik upgrade guide for the release you are moving to before you rely on a text search.
Before you change anything, capture the evidence. Save the full server and worker logs covering the upgrade window, record the exact image tags that were running before and after the attempt (including any digest pins), and note the PostgreSQL version and the authentik configuration values you changed. Keep these records with the backup you took before the upgrade. Engineers under pressure often overwrite the failing containers or pull a newer tag, and the evidence that explains the failure is lost. A written record also lets an outside partner or your vendor support contact reproduce the sequence without guessing.
If the logs confirm a migration inconsistency, the documented response is to restore the PostgreSQL backup, which returns the database to its pre-upgrade state, since downgrades are not supported. Then upgrade again, this time stepping through each release in sequence and running each latest patch before moving on, rather than jumping to the newest image. Treat a repeat failure at a specific step as a finding about that step: stop, preserve the logs for that version, and escalate with the version pair involved. Plan a maintenance window that includes restore time, because a retry is a full cycle, not a quick fix.
Testing and rollback by deployment type
The Compose installation guide positions Compose for test setups and small-scale production and calls for at least 2 CPU cores and 2 GB of RAM. On this layout the server, the worker and PostgreSQL usually share one host, so each upgrade step changes the same stack you test and back up. Your rollback path is the PostgreSQL backup taken before the first step, because authentik does not support downgrades.
- Pre-step backup: Take a logical PostgreSQL dump and a copy of the data volumes before each version step, and record the image tags in use.
- Sign-in flows: After each step, test a password login, MFA enrollment, logout and password recovery with a dedicated test user.
- Provider endpoints: Fetch the OIDC discovery document for each OAuth2 provider and the SAML metadata for each SAML provider, then compare issuers and redirect URIs with what applications expect.
- Restore drill: Restore the dump into a separate host or stack, start authentik against it, and confirm users, applications and providers are present before you rely on that backup.
- Headroom check: Confirm the host exceeds the stated minimum if you run the restore drill on the same hardware, so the drill does not compete with production load.
Before you move to the next version, confirm the version string changed and search the server logs for migration inconsistency errors.
The Kubernetes installation guide installs with Helm and states that the PostgreSQL bundled with the chart is for demonstration and test environments. It recommends a separately managed PostgreSQL for production, which means the database, its backups and its version have their own owners outside the release. Treat a Helm rollback as a change to the pods only. The database keeps the migrated schema, so the route back is still a restore from backup.
- Managed database backup: Use the database provider's backup or point-in-time mechanism, plus a logical dump taken immediately before the upgrade, and confirm you can restore it into a separate instance.
- Rehearsal namespace: Run the same version sequence in a non-production namespace against a restored copy of the database before you touch production.
- Ingress and TLS: Verify that the hostname, certificate and reverse proxy headers still match the new release, and that applications receive the expected issuer.
- Server and worker rollout: Confirm the server and worker deployments reach a ready state at the new version and that the migration job completes without errors in its logs.
- Sign-in and provider checks: Log in as an administrator and a standard user, check OIDC discovery and SAML metadata, and confirm MFA for a test account.
Record the chart version, image tags and database version at every step so a restore drill can rebuild the exact sequence.
Outposts such as LDAP, RADIUS, proxy and RAC run alongside the core and must stay on the same version as it. Their checks focus on what applications and network clients experience, so they are separate from the core checks on either platform. Outpost upgrades can be automatic through integrations or manual through image tags, and the admin interface shows each outpost's health and version. Plan these checks for both Compose and Helm deployments.
- Version match: After every step, confirm each outpost reports the same version as the core in the admin interface.
- LDAP bind and search: Test a bind and a search from a client using a test account, including a group membership lookup.
- RADIUS and VPN: Authenticate one test session through RADIUS or the VPN path, including MFA where the protocol allows it.
- Forward-auth applications: Load a protected application, confirm the login redirect, and check that the upstream receives the identity headers it expects.
- Post-restore reconnect: After a restore, confirm each outpost reconnects and reports healthy, then repeat the checks above.
Check outposts after the core reports the target version and the core sign-in flows pass, and follow the upgrade guide for the order of steps.
What makes an authentik catch-up upgrade take longer
This table lists the factors that stretch a multi-version authentik upgrade and why each one adds work. Read each row as a question to answer about your own deployment before you ask a partner or your team for a plan. The main takeaway is that the number of releases between your version and the target is only one driver, and the blueprints, providers, outposts and restore path often decide how long the work runs.
| Driver | Why it adds effort | What to ask for |
|---|---|---|
| Number of releases skipped | Upgrades cannot skip versions, so each intermediate release needs its latest patch applied, checked and backed up before the next step. | A written list of every intermediate release, the patch used for each, and a check point after each step. |
| Custom blueprints and flows | Blueprints and custom flows and policies are tied to the schema and behavior of a release, so changes in later releases can break them mid-path. | An inventory of blueprints, custom flows and policies, and which ones are tested against each intermediate version. |
| OAuth2/OIDC and SAML providers | Redirect URIs, issuers and token claims can change between releases, so each provider may need review after several steps. | A list of providers by type with owners, and the release notes that touch each one. |
| LDAP, RADIUS and RAC providers | Clients outside the browser depend on outposts and bind or session behavior, so failures may show only after the core is upgraded. | A test plan for each protocol client, run after every step on the path. |
| Proxy providers and forward auth | Reverse proxy headers, trusted proxy settings and path changes can need coordinated edits at several release points. | Current reverse proxy configuration and any path or header changes the team must make. |
| SCIM and Google Workspace or Entra ID integrations | Provisioning filters and group handling changed in some releases, so sync can drift or stop without an obvious error. | Confirmation of which provisioning integrations are active and how sync results are checked after each step. |
| Outposts | Each outpost must match the core version, so every core step can require matching outpost updates or image tag changes. | A list of deployed outposts, their versions and whether they upgrade automatically or by image tag. |
| Database size and restore time | A full PostgreSQL backup is required before each step, and the restore path is the rollback, so larger databases lengthen every checkpoint. | Measured backup and restore times on a copy of production data, and confirmation that restores have been tested. |
| Compose versus Kubernetes | Compose uses a single host and manual steps, while Kubernetes adds chart values, rollout order and separately managed PostgreSQL to coordinate. | The deployment method in use, the chart or Compose file versions, and the rollout order the team will follow. |
| Number of environments to rebuild | Each environment that cannot be upgraded in place, such as a staging copy or a rebuilt cluster, repeats the full path before production. | A count of environments, which are rebuilt rather than upgraded, and the order in which they will be brought current. |
Common questions about catching up an authentik upgrade
Can we skip authentik versions and jump straight to the latest release?
No. authentik upgrades must not skip versions. The upgrade guide says to upgrade to the latest patch of each major.minor release in turn, so a deployment several versions behind moves through each intermediate release before reaching the target. Skipping a step means the database migrations for the skipped release never run, which is the most common reason a catch-up upgrade fails. Downgrades are not supported either, so the backup you take before each step is your only way back. Plan the route as an ordered list of versions before anyone touches production, and confirm the current latest patch of each release on the authentik releases page at the time you work.
What does a catch-up upgrade cost and what drives the price?
Cost comes from the number of intermediate releases, the amount of custom configuration, and the number of integrations that depend on authentik. Each release can carry its own breaking changes, so the more steps in the chain, the more review, testing and sign-off you need. Costs are mostly one-time, but the platform you run afterward carries recurring work: staying on a supported version line, which the security policy lists as 2026.5.x and 2026.8.x, and applying security releases, which the project announces at least 24 hours in advance. If you engage a partner, request a fixed-scope written quote that lists each release in the path, the environments covered, the backup and restore tests, and the verification steps. DeployOpen does not publish a price list, so the quote follows from that written scope.
How long does a catch-up upgrade take?
The duration depends on how many releases sit between your current version and the target, how large the PostgreSQL database is, how many environments you update, and how much testing your integrations need. Each step needs a fresh backup, the upgrade itself, a check that the version changed, and a review of the release notes for that version. Treat the number of steps as the main driver and ask for a timeline in the written scope rather than relying on a general estimate. Confirm with your own environment how long a backup and restore takes, since that sets the minimum time for each rollback point.
What do we need to provide before an upgrade partner starts?
Start with the inputs an engineer needs to plan the path:
- The current authentik version and the deployment method, such as Docker Compose or Kubernetes with Helm.
- Access to PostgreSQL, a verified backup method and a restore environment that matches production.
- A list of integrations, outposts, custom code and reverse proxy settings that reference authentik.
- Change windows, rollback approval and the people who can confirm that each application still signs users in.
The upgrade guide's requirement to back up PostgreSQL first is non-negotiable, so confirm that your team can take and restore that backup before work begins.
Can our own team run a catch-up upgrade without a partner?
Yes, if your team has the skills and time to follow the sequence exactly. The core method is simple to state: back up, upgrade to the latest patch of one release, verify, and repeat. The hard parts are reading each release's breaking changes, checking integrations after every step, and keeping outposts on matching versions. Teams that take this on in-house should assign one owner for the sequence, run it first in a non-production copy, and record the result of each step. A partner can take on that planning and testing as a fixed-scope engagement, which is useful when internal staff are committed elsewhere.
What should we do if the version does not change or a migration fails?
If the version does not change after an upgrade, search the server logs for migration inconsistency errors. The upgrade guide says that if you find one, restore the backup and upgrade through each version in sequence again. Do not try to force the migration forward or repair the schema by hand on a running system, because downgrades are not supported and a partial migration can leave the database in a state the next release cannot read. Keep the pre-upgrade backup until the target version is verified and stable, and rehearse the restore before the change window so the rollback is a known procedure rather than an improvised one.
How DeployOpen scopes and delivers an authentik upgrade
DeployOpen plans an authentik catch-up upgrade as a written, sequenced project: each intermediate release is identified, tested in a staging copy, and checked against the backup and restore path before production is touched. The work runs inside your own infrastructure, with the target version, rollback point and verification steps agreed before the first change.
How we scope
- Inventory the current authentik version, deployment type, PostgreSQL version and any outposts before quoting.
- List every intermediate release between your version and the target, with the latest patch of each named in the plan.
- Record the breaking changes that apply to your configuration, providers and integrations in the written scope.
- Agree the backup, restore test and log-review checkpoints that gate each step, since engagements are fixed-scope.
How we build
- Rehearse the full sequence on a staging copy restored from a recent PostgreSQL backup of production.
- Confirm the version after each step and search server logs for migration inconsistency before moving on.
- Adjust reverse proxy settings, environment variables and integration configuration as each release requires.
- Test sign-in for representative applications, LDAP or RADIUS clients and outposts at each checkpoint.
How we hand over
- Deliver a runbook with the exact sequence, versions reached, commands run and checks passed at each stage.
- Document the backup and restore procedure used as the rollback path, since downgrades are not supported.
- Hand over a list of open items, such as outpost versions to align or configuration to review, with owners named.
- Walk your operations team through the logs and health checks they should watch after go-live.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer if you want help with later releases.
- Track security advisories for supported versions so future catch-up work starts from a known position.
- Confirm current supported release lines with the authentik security policy before planning the next upgrade cycle.
- Agree in the written scope who performs post-upgrade monitoring and who escalates to DeployOpen.
