Moving authentik from Docker Compose to Kubernetes

Moving authentik from Docker Compose to Kubernetes is mostly a data and cutover job

If your authentik runs on one Compose host and you now need high availability or cluster operations, the move is a re-platform of the same application, not a new build. The core work is moving the PostgreSQL database to an externally managed instance, carrying over uploaded files, keeping the existing AUTHENTIK_SECRET_KEY so sessions and encrypted values continue to work, and running the same authentik version on both sides before any traffic moves. The Kubernetes installation guide uses Helm and notes that the bundled PostgreSQL is intended for demonstration and test use, so plan a production database as a separate workstream from the first day.

Effort depends on a few variables you should measure before asking for a quote: how large the PostgreSQL database is and how long a consistent dump and restore takes in your environment, how many outposts are deployed and where they run, which custom files sit in /data, /certs, /custom-templates or /blueprints, and how much session disruption and DNS change your users and applications can tolerate. Each of these shifts the cutover window in a different direction. Ask any partner for a written scope that names these inputs, and treat any duration given without them as an assumption to challenge.

Confirm the exact release on the Compose host before you start, then pick a Kubernetes target that runs the same version. The authentik Kubernetes installation guide describes the chart, and the authentik backup and restore documentation lists what to move. Rehearse the restore into a staging cluster, log in with a test account, and check outposts and DNS records against a written cutover runbook before you schedule the production switch.

What carries over from Compose and what needs rework

This table maps each Docker Compose component of an authentik deployment to its Kubernetes counterpart and marks what moves as is and what needs new design. Read the right-hand column as the work list: anything marked as rework needs a decision before cutover, not after.

Component	Docker Compose today	Kubernetes target and rework
Server (core and embedded outpost)	Server container running core plus the embedded outpost	Deployment installed with the Helm chart. The same image and version must be pinned in both environments, and the embedded outpost is reached through the new ingress.
Worker	Separate worker container for background tasks	Separate worker Deployment. Confirm it runs the same version as the server and scale it separately.
PostgreSQL	Database container, often with a local volume	Use a separately managed PostgreSQL for production. The chart's bundled PostgreSQL is for demonstration and test environments only, so plan a dump and restore into the new database.
Redis	Not required from 2025.10 onward, but older Compose files may still define a Redis service	Remove it from the migrated design. Caching, tasks, sessions and WebSocket functions run on PostgreSQL, so plan for roughly 50% more PostgreSQL connections after upgrading (2025.10 release notes).
Mounted files (/data, /certs, /custom-templates, /blueprints)	Bind mounts or named volumes on the host	Persistent volumes or ConfigMaps, depending on the file. Confirm which paths your deployment uses before copying anything.
Environment variables and secret key	Values in the Compose file or .env, including AUTHENTIK_SECRET_KEY	Kubernetes Secrets and ConfigMaps. Keep the existing secret key value so sessions and encrypted data stay valid, and restrict Secret access with RBAC.
Outposts (LDAP, proxy, RAC)	Outposts connect back to the server using the Compose hostname	Each outpost needs a new endpoint and token configuration. Verify the connection and redeploy them after DNS changes.
External connections (SSO clients, LDAP sources, SMTP, reverse proxy)	Configured against the Compose host name and IP	Update redirect URIs, source endpoints and proxy targets to the new hostnames. Confirm each with the application owner before the DNS switch.

How the migration sequence runs from inventory to decommission

The sequence moves a running authentik from a single Docker Compose host to Kubernetes in stages, so each step produces a checked result and a known rollback point before anything users depend on is switched. Compose stays in place and untouched until the Kubernetes deployment has passed its checks.

Inventory versions, files and outposts
The platform owner records the running authentik version, the PostgreSQL version and the image tags for the server and worker containers. They list every bind-mounted or volume-backed path in the Compose file, including /data, /certs, /custom-templates and /blueprints, and note which are actually in use. They also list every outpost, its type and the host it runs on, plus any reverse proxy routes and DNS records that point at the Compose host. The step is done when the team has a written inventory that another engineer could use to rebuild the environment without asking questions.
Build the Kubernetes target at the matching version
The platform team installs authentik on the Kubernetes cluster with the Helm chart, pinned to the same authentik version as the Compose host so the schema and configuration match. The chart's bundled PostgreSQL is used only for testing, so the team points the deployment at a separately managed PostgreSQL instance. Ingress, TLS certificates and the outpost deployments are configured but kept off public DNS. The step is done when the pods report healthy, the admin interface loads on a test hostname, and the version shown matches the Compose host.
Take a backup and record a rollback point
The operator runs a backup using the documented authentik backup procedure on the Compose host, covering the PostgreSQL database and any file paths identified in the inventory. The team stores the database dump and file archives in a location separate from the Compose host and records the AUTHENTIK_SECRET_KEY value in the secrets vault, since sessions depend on it. The Compose stack stays running and is the defined rollback target until the DNS switch. The step is done when a restore of the backup has been confirmed to be readable and the rollback point is documented.
Rehearse a pilot restore on Kubernetes
The team restores the backup into the Kubernetes environment's test database and starts the authentik deployment against it. They confirm that the applications, providers, flows, users and blueprints appear as expected, that logins succeed for test accounts, and that the outposts connect to the core service. Any mismatch in file paths, secret handling or database connection limits is corrected in the Helm values and the restore is repeated from the same backup. The step is done when a clean restore completes with no manual edits left undocumented.
Run a parallel environment with a copied database
The team sets up the Kubernetes deployment against a fresh copy of production data and keeps it reachable only on internal or test hostnames. Test users sign in to representative applications through both environments, and the team compares audit events, group memberships and outpost behavior. Because two copies now exist, the team does not let changes made in one reach the other. The step is done when the test sign-ins and outpost checks pass against the copy and the differences found have been either fixed or accepted in writing.
Freeze writes and run the final sync
The change owner announces a window, stops administrative changes on the Compose host, and takes a final backup using the same documented procedure. The final backup is restored into the Kubernetes PostgreSQL database and the Kubernetes deployment is confirmed against it. The team verifies the restored configuration and user count against the Compose host before proceeding. The step is done when the final restore matches the frozen source and the checks from the pilot pass again.
Switch DNS and watch the cutover
The operator lowers the time-to-live on the authentik hostname before the window, then points the record at the Kubernetes ingress and confirms the new certificate is served. The team signs in with several test accounts from different applications, checks outposts reconnect and confirms that new sessions are issued by the Kubernetes deployment. The Compose host is kept running but idle during an agreed observation period. The step is done when the hostname resolves to Kubernetes, sign-ins succeed, and no application reports errors.
Decommission the Compose host
After the observation period ends without rollback, the team stops the Compose stack and retains the final backup, the inventory and the migration record under the organization's retention rules. They remove the Compose host's DNS references, outpost registrations pointing at it and any scheduled jobs. The Compose host is only deleted once the retention requirement is confirmed by the data owner. The step is done when the record shows no remaining component depends on the old host and the retained backup has been verified as restorable.

Why the secret key and PostgreSQL copy must match at cutover

The secret key and the database must move together. PostgreSQL holds authentik's configuration and data, so the copy you restore into the Kubernetes cluster has to be a consistent snapshot taken while the Docker Compose stack is stopped or quiesced, not a series of files copied at different times. Plan the database dump, the restore and the check that the new server reads the expected users, providers and applications before any DNS change. The authentik backup and restore documentation also lists /data, /certs, /custom-templates and /blueprints as paths that may need to move, depending on how your deployment uses them. Inventory which of these you actually mount, because a missing custom template or certificate will fail only after traffic arrives.

The AUTHENTIK_SECRET_KEY value is the other half of this continuity. Rotating it invalidates all sessions, so every signed-in user would be forced to authenticate again at cutover, and the authentik hardening guide advises rotating it only when it has leaked. Carry the existing value over unchanged. Before the migration, confirm where the current key is defined: an .env file, a Compose environment block or a secret manager. Then decide how the Kubernetes side will hold it, typically as a Kubernetes Secret referenced by the server and worker pods, with access restricted by least-privilege RBAC.

Kubernetes Secrets are stored unencrypted in etcd by default, according to the Kubernetes secrets good practices guidance. Unless your cluster has encryption at rest configured for Secrets, anyone who can read the etcd data or the backups of it can recover the key and the database credentials. Ask your platform team whether encryption at rest is enabled, and whether etcd backups are encrypted and access-controlled, before you place the key in the cluster. An external store through the Secrets Store CSI Driver is another option to evaluate. Document who can read the Secret and verify the value in the new pods matches the old one before you retire the Compose host.

Choosing the target cluster and database setup

Building the cluster yourself with kubeadm gives full control over the control plane layout, but it also makes your team responsible for etcd, certificates, load balancing and upgrades. The kubeadm high availability guide describes two topologies: a stacked control plane, where etcd runs on the same nodes as the control plane, and an external etcd cluster, where etcd runs on separate hosts. Either way, plan for at least three control plane nodes and a TCP load balancer in front of kube-apiserver on port 6443.

Stacked etcd: fewer hosts and simpler to build, but each control plane node failure also removes an etcd member.
External etcd: isolates etcd from control plane load, at the cost of more hosts to patch and back up.
etcd member count: use an odd number of members, and the Kubernetes documentation recommends five members in production.
etcd backups: define the snapshot schedule with etcdctl snapshot save and test restores with etcdutl before cutover.
Load balancer: confirm the TCP load balancer is itself highly available, or it becomes the single entry point for every client.

Before you commit, confirm which team owns certificate rotation, etcd recovery and control plane patching after the migration.

Which documented tools and paths move the data

Can pg_dump or pg_dumpall move authentik's PostgreSQL database to Kubernetes?

Yes, a logical dump and restore is the simplest documented path when the PostgreSQL major version stays the same. Because PostgreSQL holds all authentik configuration and data except uploaded files, the dump carries users, providers, applications, flows and policies. Stop the authentik server and worker first so no writes happen during the dump, then restore into the target database and confirm that the restored version matches the source. Dump size, network path and downtime depend on how much data the database holds, so measure a test restore before the cutover window. Confirm the exact commands with the PostgreSQL documentation for your version before running them.

Does pg_upgrade or logical replication help when the PostgreSQL version changes?

They are the documented options when the source and target PostgreSQL major versions differ. The PostgreSQL upgrading documentation describes pg_upgrade, pg_dumpall with restore, and logical replication for major upgrades. Logical replication works between different major versions and can keep downtime to several seconds at cutover, which suits a database that must stay close to current. The PostgreSQL 18 release announcement notes that pg_upgrade keeps planner statistics and adds parallel jobs and a --swap option. Check which PostgreSQL major version your authentik release supports before choosing a path, and check the PostgreSQL versioning policy for end-of-life dates on the source version.

Does continuous archiving let us recover authentik to a point in time?

Continuous archiving with point-in-time recovery is the PostgreSQL mechanism for restoring the database to a chosen moment, such as just before a bad configuration change during the migration. It requires a base backup plus archived write-ahead log files, stored where the target cluster can reach them. Set this up on the source before cutover so you have a recovery point if the first restore goes wrong. Test the restore into a separate environment, because an archive that has never been restored is not a proven backup. Your database team should own the retention and storage design, and the PostgreSQL continuous archiving documentation is the reference for the procedure.

How do we move authentik's uploaded files and mounted directories?

Follow the authentik backup and restore documentation, which lists the paths that may need moving depending on your use: /data, /certs, /custom-templates and /blueprints. PostgreSQL does not store uploaded files, so these directories must be copied separately. Identify which paths your deployment mounts from the Compose file, then copy them to persistent volumes that the Kubernetes deployment mounts at the same locations. Check file ownership and permissions after the copy, because the container user must still be able to read and write them. Blueprints and custom templates should be reviewed for anything that depends on the old host paths.

Which Helm install steps should we use for the Kubernetes target?

The authentik Kubernetes guide installs the platform with Helm, and that is the documented starting point for the target. The chart bundles PostgreSQL, but the guide says that bundled database is for demonstration and test environments and recommends a separately managed PostgreSQL for production. So the Helm values should point at the database you restored into, and the secret key must match the source deployment (the hardening guide notes that rotating AUTHENTIK_SECRET_KEY invalidates all sessions). Install into a staging namespace first, confirm login works against the restored data, and then plan the DNS switch. Confirm chart version and values with the Kubernetes installation page for the release you target.

Which version must the Kubernetes target run to match the Compose source?

Match the authentik version exactly before you restore, then upgrade in the documented order after the data is in place. Your source and target should run the same authentik release so that the schema and configuration match the restored data. The authentik security policy lists 2026.5.x and 2026.8.x as supported lines, and releases are named by year and month, so check your running version against the GitHub releases page before choosing the target image. Outposts and worker containers must also be aligned with the server version. Plan any upgrade as a separate step with its own rollback point rather than combining it with the move.

Is third-party backup or migration tooling covered by these documented paths?

No, third-party tooling is out of scope for this page unless its vendor and its compatibility with your authentik and PostgreSQL versions are confirmed. The paths above rely on the authentik backup and restore documentation, the PostgreSQL upgrading and continuous archiving documentation, and the Kubernetes installation guide. Before adopting a backup product, migration script or database operator, ask the vendor for written confirmation that it supports your versions, restores authentik's files as well as its database, and preserves the secret key. Treat any tool that cannot show a successful test restore as unproven for this move.

What drives the effort and timing of this move

Six factors shape how long the move takes and how much risk it carries. Figures for your deployment come from a written scope after these questions are answered, not from this page.

Database size and write rate

PostgreSQL holds nearly everything authentik stores, so its size and write activity set the length of the cutover window and the dump or replication approach. A large database with steady login and audit writes needs a longer, rehearsed import. Ask for the current database size, the peak connection count and how many days of logs and events you want to carry over.

Outposts and their placement

Each outpost, such as an LDAP or proxy outpost, has its own deployment, token and network path. Outposts reached over the old hostname or running beside Compose services must be repointed and retested one by one. Inventory every outpost type and where it runs before estimating the cutover.

Custom templates and blueprints

Files in /custom-templates and /blueprints must move with the database and must be checked against the target version. Blueprints that reference hostnames, file paths or secrets need edits before they apply cleanly. Count the custom templates and blueprint files and note which ones were written by hand.

External integrations pointing at the old hostname

Every application, LDAP client, SAML metadata file and OIDC redirect URI that references the current hostname is a change to plan. Some clients cache metadata or keep a fixed issuer, so a DNS switch alone may not finish the move. List each integration, its owner and whether it can be updated in a planned window.

Tolerance for session loss and downtime

Keeping the secret key unchanged preserves sessions, but any change to it signs out every user. Decide how long logins may fail during the switch and whether users can accept re-authentication. A short maintenance window with a rehearsed cutover usually carries less risk than a long parallel run that splits traffic between two stacks.

Team Kubernetes experience

Running the Helm release, managing secrets, ingress, persistent storage and upgrades on Kubernetes is ongoing work after the move. A team new to the platform needs more time for review, runbooks and failure drills. Ask who will operate the cluster after handover and how much of the build they will pair on.

Questions buyers ask before moving authentik to Kubernetes

What does it cost to move authentik from Docker Compose to Kubernetes?

The cost depends on the work scope agreed in writing before the move starts, and no supplied figure sets it. The main components are the discovery of your current Compose stack, the design of the Kubernetes target (chart values, storage, networking, secrets), the PostgreSQL move, the cutover window and the verification afterward. Some of this is one-time project effort. Ongoing costs are your own cluster, database and staff time, plus any support retainer you choose. Ask any quote to itemize each component, state which items are one-time and which recur, and list what your team must supply. Authentik's Enterprise features are licensed separately from the open-source edition, so confirm your edition before you price the target.

How long does an authentik move to Kubernetes take?

Duration is set by the size of your deployment, the number of applications that depend on it, how much PostgreSQL work is involved, and how many change windows your organization allows. No supplied fact gives a duration, so treat any number you hear as a question to test against your own inventory. The fastest path is a small instance with one database, few outposts and a clear DNS owner. The slowest is a multi-application estate with outposts, custom templates and strict change control. Ask for a schedule that lists discovery, a rehearsal on a copy of production data, the cutover window and a post-cutover check.

What must our team provide before the move starts?

Your team must provide access and ownership, because the move touches systems you control. Expect to supply access to the current Compose host and its PostgreSQL database, a target Kubernetes cluster with the namespaces and storage classes you approve, and credentials for your container registry. You also need named owners for DNS records, TLS certificates and the reverse proxy, plus a change window that the business accepts. Confirm which team owns each outpost, because outposts must match the core version. Agree the rollback owner and the decision point before cutover so that no one is waiting on approval during an incident.

Can our in-house team move authentik to Kubernetes without a partner?

Yes, an in-house team can do this if it has Kubernetes operations skills, PostgreSQL administration experience and authentik knowledge. The authentik Kubernetes guide installs with Helm and states that the chart's bundled PostgreSQL is for demonstration and test environments, with a separately managed PostgreSQL recommended for production. That means your team must choose and run a production database, and must plan the database migration carefully. Key gaps usually appear in secret key handling, outpost versioning and DNS cutover. Ask a partner, or your own reviewers, to check the plan against your inventory before the first production move.

Do users have to log in again after authentik moves to Kubernetes?

Users may need to log in again, depending on whether the AUTHENTIK_SECRET_KEY stays the same. Rotating that key invalidates all sessions, and the authentik hardening guide advises rotating it only if it leaks. Keep the same key value in the Kubernetes secret so existing sessions remain valid. Also check that the hostname and TLS certificate do not change during cutover, because a new hostname can break cookies and redirect URIs for connected applications. If your plan requires a key change, schedule a sign-in window and tell users in advance.

How does rollback work if the Kubernetes cutover fails?

Rollback is possible only if the original Compose stack and its PostgreSQL data remain intact until you confirm success. Before cutover, take a backup of the database and the data paths your deployment uses. The authentik backup documentation notes that PostgreSQL holds all configuration and data, while /data, /certs, /custom-templates and /blueprints may also need moving. Keep the Compose host stopped but not deleted, and keep DNS changes reversible with a short time-to-live set in advance. If you change the database during cutover, rollback means restoring the old database or pointing DNS back to the old host, so test that path during rehearsal.

Do outposts need to be upgraded during the Kubernetes move?

Outposts must run a version that matches the authentik core, so plan their upgrade as part of the cutover. Some outposts may run as separate containers, and the Kubernetes guide covers deploying them on your cluster. Before the move, list every outpost, its protocol (for example proxy, LDAP or RADIUS) and the clients that depend on it. Upgrade or redeploy each outpost after the core is running, and confirm that each one reconnects. Test LDAP and RADIUS clients separately, because they do not use a browser flow to verify access.

Should we check the Kubernetes version and PostgreSQL version before we move?

Yes, check both, because each sets a support window. Kubernetes maintains the three most recent minor releases, and the Kubernetes version skew policy requires you to upgrade the API server one minor version at a time. For PostgreSQL, supported versions as of the research date include 14 (to November 12, 2026) and 18 (final release November 14, 2030). Choose a target version that remains supported for the planned life of the platform, and confirm the current support tables on the vendor sites before you commit.

How DeployOpen scopes and delivers this migration

DeployOpen is a Chainscore Labs company that plans, implements and supports self-hosted open-source platforms inside the client's own infrastructure, including their cloud accounts, data centers or air-gapped networks. For a move from Docker Compose to Kubernetes, that means the work happens in your clusters, your PostgreSQL service and your DNS zone, with your team holding the credentials. Most engagements are fixed-scope, so the written scope fixes the components in play: the server and worker containers, the PostgreSQL cutover, the AUTHENTIK_SECRET_KEY handling, each outpost, the DNS switch and the rollback path. A quote follows from that scope rather than from a generic template.

To make the scope precise, DeployOpen works through a short set of questions before any quote: which authentik version runs today, how large the PostgreSQL database and its file directories are, which outposts and providers are in use, how many applications resolve through the current hostname, and which Kubernetes distribution and PostgreSQL service will host the target. Each answer changes the work. Cost components usually include discovery, cutover rehearsal, the production cutover window and post-cutover verification, and the written scope should state which of these DeployOpen performs and which your staff perform. Ask any partner, including DeployOpen, to name those responsibilities and the acceptance checks for each deliverable.

Ongoing work after cutover, such as upgrades to later authentik releases, outpost updates, backup verification and monitoring tuning, can be covered by a retainer rather than a new project each time. A retainer suits teams that expect regular authentik releases, since each one needs its own review. DeployOpen does not publish a price list and does not issue audit reports, attestations or certifications, so any compliance evidence from this migration is prepared for your independent auditors. Confirm the retainer scope, response expectations and exclusions in writing before work starts.

Moving authentik from Docker Compose to Kubernetes