mirror of
https://github.com/goauthentik/authentik
synced 2026-04-27 18:07:15 +02:00
b96c477b6a
* Clean up PostgreSQL documentation * Overview * SSL wording * Conn age * Schema text * Replica line * Direct tip * Backup text * Restore text * Access text * Copy text * Issue text * Sentence case * Section intro * Primary reads * Username text * Password text * TLS modes * Health checks * Replica case * Replica intro * Backup guides * Docker intro * Stop stack * Stop wording * Backup alt * Dump wording * Remove alt * Network note * Verify login * Dump safety * Log names
171 lines
4.5 KiB
Markdown
171 lines
4.5 KiB
Markdown
---
|
|
title: Upgrading PostgreSQL on Kubernetes
|
|
---
|
|
|
|
This guide walks through a manual PostgreSQL major-version upgrade for an authentik Kubernetes deployment. The process requires downtime while the database is exported, recreated, and restored.
|
|
|
|
:::info
|
|
For this guide, we assume the PostgreSQL pod is named `authentik-postgresql-0`, which is the default name in the authentik Helm chart.
|
|
:::
|
|
|
|
## Before you start
|
|
|
|
- `kubectl` access with permissions to `scale` deployments and `exec` into pods
|
|
- the `values.yaml` file used for your authentik deployment
|
|
- enough storage for a SQL dump and a copy of the old database files
|
|
- a maintenance window long enough to export and restore the database
|
|
|
|
Review [Backup and restore](../../sys-mgmt/ops/backup-restore.md) before proceeding.
|
|
|
|
## Overview
|
|
|
|
The upgrade flow is:
|
|
|
|
1. Stop authentik services
|
|
2. Back up the database
|
|
3. Prepare the data directory
|
|
4. Upgrade PostgreSQL
|
|
5. Restore database content
|
|
6. Restart authentik services
|
|
|
|
## 1. Stop authentik services
|
|
|
|
Scale down authentik so nothing accesses PostgreSQL during the upgrade:
|
|
|
|
```shell
|
|
kubectl scale deploy --replicas 0 authentik-server
|
|
kubectl scale deploy --replicas 0 authentik-worker
|
|
```
|
|
|
|
## 2. Back up the database
|
|
|
|
Connect to the PostgreSQL pod:
|
|
|
|
```shell
|
|
kubectl exec -it authentik-postgresql-0 -- bash
|
|
```
|
|
|
|
After you are connected, execute these commands to create a database backup:
|
|
|
|
```shell
|
|
# Navigate to the PostgreSQL data directory
|
|
cd /bitnami/postgresql/
|
|
|
|
# Set the PostgreSQL password from environment variable
|
|
export PGPASSWORD=$(cat $POSTGRES_PASSWORD_FILE)
|
|
|
|
# Create a full database dump
|
|
pg_dump -U $POSTGRES_USER $POSTGRES_DATABASE > /bitnami/postgresql/dump.sql
|
|
```
|
|
|
|
:::tip
|
|
Copy the dump file to a safe location outside of the pod before continuing:
|
|
|
|
```shell
|
|
# From a separate terminal
|
|
kubectl cp authentik-postgresql-0:/bitnami/postgresql/dump.sql ./authentik-db-backup.sql
|
|
```
|
|
|
|
Keeping an external copy protects you if the pod or persistent volume is recreated unexpectedly.
|
|
:::
|
|
|
|
## 3. Prepare the data directory
|
|
|
|
While still connected to the pod, prepare the data directory:
|
|
|
|
```shell
|
|
# Ensure you're in the PostgreSQL data directory
|
|
cd /bitnami/postgresql/
|
|
|
|
# Verify the SQL dump exists and has content
|
|
ls -lh dump.sql
|
|
|
|
# Preserve the existing data by renaming the directory
|
|
mv data data-old
|
|
```
|
|
|
|
:::caution
|
|
Do not delete `data-old` yet. It provides a rollback path if the restore fails.
|
|
:::
|
|
|
|
## 4. Upgrade PostgreSQL
|
|
|
|
Update `values.yaml` with the new PostgreSQL image tag:
|
|
|
|
```yaml
|
|
postgresql:
|
|
image:
|
|
tag: <NEW_VERSION>
|
|
```
|
|
|
|
Apply the change with Helm using your normal deployment command.
|
|
|
|
When the pod restarts with the new image, PostgreSQL initializes a new empty `data` directory because the previous one was renamed to `data-old`.
|
|
|
|
## 5. Restore database content
|
|
|
|
Connect to the PostgreSQL pod again:
|
|
|
|
```shell
|
|
kubectl exec -it authentik-postgresql-0 -- bash
|
|
```
|
|
|
|
Restore your database from the backup:
|
|
|
|
```shell
|
|
# Navigate to the PostgreSQL directory
|
|
cd /bitnami/postgresql/
|
|
|
|
# Verify your dump file is still there
|
|
ls -lh dump.sql
|
|
|
|
# Set the PostgreSQL password
|
|
export PGPASSWORD=$(cat $POSTGRES_PASSWORD_FILE)
|
|
|
|
# Import the database dump
|
|
psql -U $POSTGRES_USER $POSTGRES_DATABASE < dump.sql
|
|
```
|
|
|
|
## 6. Restart authentik services
|
|
|
|
After the restore completes successfully, scale authentik back up or re-run your Helm deployment so the server and worker return to their normal replica counts.
|
|
|
|
## 7. Verify the upgrade
|
|
|
|
After everything starts again:
|
|
|
|
- confirm the PostgreSQL pod is healthy
|
|
- check the PostgreSQL, server, and worker logs for startup or migration errors
|
|
- log in to authentik through the UI to verify the application is functioning normally
|
|
|
|
## Troubleshooting
|
|
|
|
If you encounter issues during the upgrade process:
|
|
|
|
- Check PostgreSQL logs:
|
|
```shell
|
|
kubectl logs authentik-postgresql-0
|
|
```
|
|
- Verify the values in your `values.yaml` file match the recommended settings
|
|
- Ensure you have sufficient storage available for both the database dump and the database itself
|
|
|
|
### Dump file not found
|
|
|
|
If `dump.sql` is missing after the restart:
|
|
|
|
- You may need to restore from the external backup if you copied it out of the pod
|
|
- The volume might have been recreated if you're using ephemeral storage
|
|
|
|
### Restoring the original database
|
|
|
|
If you need to roll back to the old PostgreSQL data directory:
|
|
|
|
```shell
|
|
kubectl exec -it authentik-postgresql-0 -- bash
|
|
cd /bitnami/postgresql/
|
|
mv data data-new-failed
|
|
mv data-old data
|
|
```
|
|
|
|
Then restart PostgreSQL with the original version in your `values.yaml`.
|