From 8eff4c7e0b1dbcc43d7886f52c79b8a88e053819 Mon Sep 17 00:00:00 2001 From: Dominic R Date: Fri, 1 May 2026 11:54:37 -0400 Subject: [PATCH] website/docs: document air-gapped upgrades (#21972) * website/docs: document air-gapped upgrades Explain how to prepare mirrored artifacts for air-gapped upgrades. Closes: https://github.com/goauthentik/authentik/issues/21376 * Update website/docs/install-config/air-gapped.mdx Co-authored-by: Tana M Berry Signed-off-by: Dominic R --------- Signed-off-by: Dominic R Co-authored-by: Tana M Berry --- website/docs/install-config/air-gapped.mdx | 65 ++++++++++++++++++++++ website/docs/install-config/upgrade.mdx | 2 + 2 files changed, 67 insertions(+) diff --git a/website/docs/install-config/air-gapped.mdx b/website/docs/install-config/air-gapped.mdx index 948af09938..d108534906 100644 --- a/website/docs/install-config/air-gapped.mdx +++ b/website/docs/install-config/air-gapped.mdx @@ -86,6 +86,71 @@ For Helm deployments, ensure access to the following repository. In an air-gappe - https://charts.goauthentik.io +## Upgrades + +Before upgrading an air-gapped deployment, review the [release notes](../../releases/) for the target version and mirror the required resources for that version into your internal registry or artifact repository. The air-gapped upgrade itself uses the same upgrade commands as a connected deployment, but those commands must reference the mirrored images and chart artifacts. + + + + +On a system with internet access, download the target release's `compose.yml` file, then mirror the authentik server image that is referenced by that file. If you use managed outposts, mirror the matching outpost images as well. + +After transferring the updated `compose.yml` into the air-gapped environment, update your `.env` file to point to the mirrored authentik image repository and target tag: + +```shell +AUTHENTIK_IMAGE=registry.company/authentik/server +AUTHENTIK_TAG=2026.2.0 +AUTHENTIK_OUTPOSTS__CONTAINER_IMAGE_BASE=registry.company/authentik/%(type)s:%(version)s +``` + +Replace the registry path and version with your mirrored image location and target authentik version. If the air-gapped environment can pull from an internal registry, run the normal Docker Compose upgrade commands: + +```shell +docker compose pull +docker compose up -d +``` + +If you transfer images as archives instead of using an internal registry, load the images on the Docker host first, then run `docker compose up -d`. + + + + +On a system with internet access, pull the target authentik Helm chart and mirror the authentik server image and any outpost images you use. + +For example, `helm pull` creates the chart archive that you can transfer into the air-gapped environment: + +```shell +helm repo update +helm pull authentik/authentik --version +``` + +Transfer the resulting `authentik-.tgz` file into the air-gapped environment, then update your separate `values.yaml` file to point to the mirrored images: + +```yaml +global: + image: + repository: registry.company/authentik/server + tag: 2026.2.0 + +authentik: + outposts: + container_image_base: registry.company/authentik/%(type)s:%(version)s +``` + +Replace the registry path and version with your mirrored image location and target authentik version. Then upgrade from the local chart archive: + +```shell +helm upgrade --install authentik ./authentik-.tgz -f values.yaml +``` + + + + ## Network requirements ### Required ports diff --git a/website/docs/install-config/upgrade.mdx b/website/docs/install-config/upgrade.mdx index 59f68d7d03..7ad93150b5 100644 --- a/website/docs/install-config/upgrade.mdx +++ b/website/docs/install-config/upgrade.mdx @@ -24,6 +24,8 @@ Always upgrade to the latest minor version (`.x`) within each `major.minor` vers **Outposts**: The version of the authentik server and all authentik outposts must match. Ensure that all [outposts are upgraded](../add-secure-apps/outposts/upgrading.md) at the same time as the core authentik instance. +**Air-gapped environments**: Before upgrading an air-gapped deployment, mirror the target release's required images and artifacts. For details, see [Air-gapped environments](./air-gapped.mdx#upgrades). + ## Upgrade authentik import TabItem from "@theme/TabItem";