mirror of
https://github.com/goauthentik/authentik.git
synced 2026-06-17 19:09:11 +03:00
website/docs: Clean up PostgreSQL documentation (#21131)
* 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
This commit is contained in:
Dominic R
GitHub
@@ -63,27 +63,60 @@ To check if your config has been applied correctly, you can run the following co
|
||||
|
||||
</Tabs>
|
||||
|
||||
## PostgreSQL Settings
|
||||
## PostgreSQL settings
|
||||
|
||||
authentik requires a PostgreSQL database to store its configuration and data. Below are the settings to configure the database connection.
|
||||
authentik requires PostgreSQL for application data, configuration, sessions, and background task coordination.
|
||||
|
||||
Use the settings in this section to configure:
|
||||
|
||||
- the primary PostgreSQL connection
|
||||
- TLS/SSL settings for PostgreSQL
|
||||
- connection behavior and pooler compatibility
|
||||
- optional read replicas
|
||||
|
||||
For more information, see the PostgreSQL upgrade guides for [Docker Compose](../../troubleshooting/postgres/upgrade_docker.md) and [Kubernetes](../../troubleshooting/postgres/upgrade_kubernetes.md). For backup guidance, see [Backup and restore](../../sys-mgmt/ops/backup-restore.md).
|
||||
|
||||
### Connection settings
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__HOST`: Hostname or IP address of your PostgreSQL server.
|
||||
- `AUTHENTIK_POSTGRESQL__PORT`: Port on which PostgreSQL is listening. Defaults to the standard PostgreSQL port `5432`.
|
||||
- `AUTHENTIK_POSTGRESQL__USER`: Username that authentik will use to authenticate with PostgreSQL.
|
||||
- `AUTHENTIK_POSTGRESQL__PASSWORD`: Password for PostgreSQL authentication. If not set, it defaults to the value of the `POSTGRES_PASSWORD` environment variable (this fallback is specific to the default Docker Compose setup).
|
||||
- `AUTHENTIK_POSTGRESQL__NAME`: The name of the database for authentik to use.
|
||||
These settings define the primary database connection used for writes and reads, unless you've set up read replicas.
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__HOST`
|
||||
|
||||
Hostname or IP address of the PostgreSQL server.
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__PORT`
|
||||
|
||||
Port on which PostgreSQL is listening.
|
||||
|
||||
Default: `5432`
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__USER`
|
||||
|
||||
PostgreSQL username used by authentik to authenticate.
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__PASSWORD`
|
||||
|
||||
PostgreSQL password used by authentik to authenticate.
|
||||
|
||||
If unset, authentik falls back to `POSTGRES_PASSWORD`. This fallback exists for the default Docker Compose setup and should not be relied on in more complex deployments.
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__NAME`
|
||||
|
||||
Name of the PostgreSQL database to use.
|
||||
|
||||
:::info Hot-reloading
|
||||
The `AUTHENTIK_POSTGRESQL__HOST`, `AUTHENTIK_POSTGRESQL__PORT`, `AUTHENTIK_POSTGRESQL__USER`, and `AUTHENTIK_POSTGRESQL__PASSWORD` settings support hot-reloading and can be changed without restarting authentik. However, adding or removing read replicas requires a restart.
|
||||
:::
|
||||
|
||||
### SSL/TLS settings
|
||||
### TLS/SSL settings
|
||||
|
||||
Configure SSL/TLS to secure the connection to your PostgreSQL server.
|
||||
Use these settings when your PostgreSQL server requires TLS/SSL or mutual TLS.
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__SSLMODE`: Controls the SSL verification mode. Defaults to `verify-ca`.
|
||||
- `AUTHENTIK_POSTGRESQL__SSLMODE`
|
||||
|
||||
Controls how TLS/SSL is used and verified for PostgreSQL connections.
|
||||
|
||||
Default: `verify-ca`
|
||||
- `disable`: No SSL is used.
|
||||
- `allow`: Use SSL if available, but don't perform verification.
|
||||
- `prefer`: Attempt an SSL connection first, fall back to non-SSL if it fails.
|
||||
@@ -91,27 +124,52 @@ Configure SSL/TLS to secure the connection to your PostgreSQL server.
|
||||
- `verify-ca`: Require SSL and verify that the server certificate is signed by a trusted CA.
|
||||
- `verify-full`: Require SSL, verify the CA, and verify that the server hostname matches the certificate.
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__SSLROOTCERT`: Path to the CA certificate file for verifying the server's certificate. Required for `verify-ca` and `verify-full` modes.
|
||||
- `AUTHENTIK_POSTGRESQL__SSLROOTCERT`
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__SSLCERT`: Path to the client SSL certificate file. Required if the PostgreSQL server is configured for mutual TLS and requires client certificates.
|
||||
Path to the CA certificate file used to verify the PostgreSQL server certificate.
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__SSLKEY`: Path to the private key for the client certificate (`SSLCERT`).
|
||||
Required for `verify-ca` and `verify-full` modes.
|
||||
|
||||
For more details, see [Django's PostgreSQL documentation](https://docs.djangoproject.com/en/stable/ref/databases/#postgresql-connection-settings) or the [PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION).
|
||||
- `AUTHENTIK_POSTGRESQL__SSLCERT`
|
||||
|
||||
Path to the client certificate file.
|
||||
|
||||
Required only if PostgreSQL is configured for mutual TLS and requires client certificates.
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__SSLKEY`
|
||||
|
||||
Path to the private key corresponding to `AUTHENTIK_POSTGRESQL__SSLCERT`.
|
||||
|
||||
For more detail, see [Django's PostgreSQL documentation](https://docs.djangoproject.com/en/stable/ref/databases/#postgresql-connection-settings) and the [PostgreSQL `libpq` SSL documentation](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION).
|
||||
|
||||
### Connection management
|
||||
|
||||
These settings control connection persistence and behavior, which is particularly important when using a connection pooler like PgBouncer.
|
||||
These settings control connection persistence and behavior, which is particularly important when using a connection pooler like PgBouncer or Pgpool.
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`: The maximum age of a database connection in seconds.
|
||||
- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`
|
||||
|
||||
Maximum age of a database connection in seconds.
|
||||
- `0` (default): Connections are closed after each request.
|
||||
- greater than `0`: Enables persistent connections, with the value defining the maximum lifetime.
|
||||
- `None`: Unlimited persistence. Use with caution, especially with connection poolers.
|
||||
See [Django's documentation on persistent connections](https://docs.djangoproject.com/en/stable/ref/databases/#persistent-connections) for more details.
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__CONN_HEALTH_CHECKS`: Enables health checks on persistent connections before reuse. Defaults to `false`. This helps prevent errors from stale connections that may have been terminated by the database or a pooler. See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/settings/#conn-health-checks) for details.
|
||||
In session pool mode, if the pooler drops its backend connection while the client connection remains open, the connection may not be released as expected. See [Django's documentation on persistent connections](https://docs.djangoproject.com/en/stable/ref/databases/#persistent-connections).
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`: Disables server-side cursors. Defaults to `false`. Server-side cursors can improve performance for large result sets but are incompatible with connection poolers in transaction pooling mode (like PgBouncer). **Set this to `true` if you use a transaction-based pooler or encounter cursor-related errors.** See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/databases/#transaction-pooling-and-server-side-cursors) for more details.
|
||||
- `AUTHENTIK_POSTGRESQL__CONN_HEALTH_CHECKS`
|
||||
|
||||
Enables health checks on persistent connections before reuse.
|
||||
|
||||
Default: `false`
|
||||
|
||||
This helps avoid errors caused by stale connections that were closed by PostgreSQL, a proxy, or a connection pooler. See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/settings/#conn-health-checks).
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`
|
||||
|
||||
Disables server-side cursors.
|
||||
|
||||
Default: `false`
|
||||
|
||||
Set this to `true` when using transaction-based pooling, or when you encounter cursor-related errors behind a pooler. Server-side cursors maintain state across queries and are not compatible with transaction pooling. See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/databases/#transaction-pooling-and-server-side-cursors).
|
||||
|
||||
### Advanced Settings
|
||||
|
||||
@@ -119,22 +177,29 @@ These settings control connection persistence and behavior, which is particularl
|
||||
|
||||
The name of the database schema for authentik to use. Defaults to `public`.
|
||||
|
||||
This can only be set before authentik is started for the first time. If you specify a custom schema, it must already exist in the database, and the user that authentik connects with must have permissions to access it. The `search_path` for the database user must also be configured to include this schema.
|
||||
This can only be set before authentik starts for the first time. If you use a custom schema:
|
||||
- the schema must already exist
|
||||
- the PostgreSQL user must have permission to use it
|
||||
- the user's `search_path` must include that schema
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__CONN_OPTIONS`
|
||||
|
||||
Arbitrary `libpq` parameter keywords for the database connection. A list of parameter keywords can be found [in the PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS).
|
||||
Additional `libpq` connection parameters for the primary database connection.
|
||||
|
||||
A list of supported parameter keywords can be found in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS).
|
||||
- Parameters passed with this setting will override those passed with other settings.
|
||||
- These parameters are not applied to read replicas.
|
||||
- Parameter keywords should be formatted as a base64-encoded JSON dictionary.
|
||||
- The value must be a base64-encoded JSON dictionary.
|
||||
|
||||
### Read Replicas
|
||||
### Read replicas
|
||||
|
||||
You can configure additional read replica databases to distribute database load and improve performance. When read replicas are configured, authentik automatically routes query operations between the primary database (for writes) and read replica databases (for queries). By default, the primary database won't be used for queries when read replicas are available. If you want the primary database to also handle queries, add it as a read replica.
|
||||
You can configure additional read replica databases to distribute database load and improve performance. When read replicas are configured, authentik automatically routes query operations between the primary database (for writes) and read replica databases (for queries).
|
||||
|
||||
To configure authentik to use read replicas, add the settings below to your [configuration file](./configuration.mdx#set-your-environment-variables). If you have multiple read replicas, add settings for each one by using a unique index starting from `0` (e.g., `0`, `1`, `2`, etc.).
|
||||
By default, the primary database won't be used for queries when read replicas are available. If you want the primary database to also handle queries, add it as a read replica.
|
||||
|
||||
The same PostgreSQL settings as described above are used for each read replica. For example, for the first read replica (index `0`):
|
||||
Each replica uses the same setting structure as the primary connection, but under `READ_REPLICAS`.
|
||||
|
||||
For the first replica, use index `0`:
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__HOST`
|
||||
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__NAME`
|
||||
@@ -150,32 +215,54 @@ The same PostgreSQL settings as described above are used for each read replica.
|
||||
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__DISABLE_SERVER_SIDE_CURSORS`
|
||||
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__CONN_OPTIONS`
|
||||
|
||||
Additionally, you can set arbitrary connection parameters on all read replicas with:
|
||||
Use index `1`, `2`, and so on for additional replicas.
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__REPLICA_CONN_OPTIONS`
|
||||
|
||||
Arbitrary `libpq` parameter keywords for all read replicas database connections. A list of options can be found [in the PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS).
|
||||
Additional `libpq` connection parameters for all read replica connections.
|
||||
|
||||
A list of supported keywords can be found in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS).
|
||||
- Parameters passed with this setting will override those passed with other settings.
|
||||
- Parameter keywords should be formatted as a base64-encoded JSON dictionary.
|
||||
- The value must be a base64-encoded JSON dictionary.
|
||||
|
||||
### Using a PostgreSQL Connection Pooler
|
||||
|
||||
When your PostgreSQL databases are running behind a connection pooler (like PgBouncer or PgPool), you need to adjust several settings to ensure compatibility:
|
||||
If authentik connects through a pooler such as PgBouncer or Pgpool, review these settings carefully:
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`:
|
||||
- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`
|
||||
|
||||
A connection pooler running in session pool mode (which is the default for PgBouncer) can be incompatible with unlimited persistent connections (`null` setting). When the connection from the pooler to the database is dropped, the pooler will wait for the client to disconnect before releasing the connection. However, this will _never_ happen as authentik keeps the connection indefinitely.
|
||||
Session-based pooling can behave poorly with unlimited persistent connections (`null`). If the pooler drops its backend connection while the client connection remains open, the connection may not be released as expected.
|
||||
|
||||
To address this incompatibility, either configure the connection pooler to run in transaction pool mode or set this value lower than any timeout that might cause the connection to be dropped (down to `0` to disable persistent connections).
|
||||
To avoid this, either:
|
||||
- use transaction pooling, or
|
||||
- set `CONN_MAX_AGE` lower than the timeout that causes backend connections to be dropped, including `0` to disable persistent connections
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`:
|
||||
- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`
|
||||
|
||||
When using a connection pooler in transaction pool mode (e.g., PgPool, or PgBouncer in transaction or statement pool mode), you must set this option to `true`. This is required because server-side cursors maintain state across multiple queries, which is incompatible with transaction-based pooling where connections may change between queries.
|
||||
When using transaction pooling, set this to `true`. Server-side cursors keep state across queries and will break when subsequent queries are sent over different backend connections.
|
||||
|
||||
### Recommended starting points
|
||||
|
||||
These are good starting points for common deployments:
|
||||
|
||||
- Direct PostgreSQL connection:
|
||||
- leave `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE` as `0`
|
||||
- leave `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS` as `false`
|
||||
- PgBouncer or Pgpool in transaction mode:
|
||||
- set `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS=true`
|
||||
- keep `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE=0` unless you have a reason to change it
|
||||
- TLS-secured PostgreSQL:
|
||||
- keep `AUTHENTIK_POSTGRESQL__SSLMODE=verify-ca` or use `verify-full` if hostname verification is available
|
||||
|
||||
### Deprecated Settings
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__USE_PGBOUNCER`: Adjusts the database configuration to support connections to a PgBouncer connection pooler. This setting is deprecated and will be removed in a future version. Instead, use the configuration described in the [Using a PostgreSQL Connection Pooler](#using-a-postgresql-connection-pooler) section.
|
||||
- `AUTHENTIK_POSTGRESQL__USE_PGPOOL`: Adjusts the database configuration to support connections to a Pgpool connection pooler. This setting is deprecated and will be removed in a future version. Instead, use the configuration described in the [Using a PostgreSQL Connection Pooler](#using-a-postgresql-connection-pooler) section.
|
||||
- `AUTHENTIK_POSTGRESQL__USE_PGBOUNCER`
|
||||
|
||||
Deprecated. Use the settings described in [Using a PostgreSQL Connection Pooler](#using-a-postgresql-connection-pooler) instead.
|
||||
|
||||
- `AUTHENTIK_POSTGRESQL__USE_PGPOOL`
|
||||
|
||||
Deprecated. Use the settings described in [Using a PostgreSQL Connection Pooler](#using-a-postgresql-connection-pooler) instead.
|
||||
|
||||
## Cache settings
|
||||
|
||||
|
||||
@@ -22,7 +22,12 @@ PostgreSQL provides high availability through _replication_ and _clustering_.
|
||||
|
||||
Refer to the [PostgreSQL High Availability, Load Balancing, and Replication documentation](https://www.postgresql.org/docs/current/high-availability.html) for more details.
|
||||
|
||||
authentik also has built-in support for [PostgreSQL Read Replicas](../configuration/#read-replicas) and using [PostgreSQL Connection Poolers](../configuration/#using-a-postgresql-connection-pooler) like PgBouncer or PgPool.
|
||||
authentik also supports:
|
||||
|
||||
- [PostgreSQL read replicas](./configuration/configuration.mdx#read-replicas) for query offloading
|
||||
- [PostgreSQL connection poolers](./configuration/configuration.mdx#using-a-postgresql-connection-pooler) such as PgBouncer or Pgpool
|
||||
|
||||
Use the [PostgreSQL configuration reference](./configuration/configuration.mdx#postgresql-settings) to configure primary connections, TLS, replicas, and pooler compatibility.
|
||||
|
||||
## Active-passive authentik deployment
|
||||
|
||||
|
||||
@@ -46,7 +46,7 @@ import Tabs from "@theme/Tabs";
|
||||
|
||||
## Generate PostgreSQL password and secret key
|
||||
|
||||
If this is a fresh authentik installation, you need to generate a PostgreSQL password and a secret key. Use a secure password generator of your choice such as `pwgen`, or you can use `openssl` as below.
|
||||
If this is a fresh authentik installation, generate a PostgreSQL password and an authentik secret key. Use a secure password generator of your choice such as `pwgen`, or use `openssl` as shown below.
|
||||
|
||||
Run the following commands to generate a PostgreSQL password and secret key and write them to your `.env` file:
|
||||
|
||||
@@ -57,7 +57,7 @@ echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
|
||||
```
|
||||
|
||||
:::info
|
||||
Because of a PostgreSQL limitation, only passwords up to 99 chars are supported. See: https://www.postgresql.org/message-id/09512C4F-8CB9-4021-B455-EF4C4F0D55A0@amazon.com
|
||||
Because of a PostgreSQL limitation, passwords longer than 99 characters are not supported. See the [PostgreSQL mailing list discussion](https://www.postgresql.org/message-id/09512C4F-8CB9-4021-B455-EF4C4F0D55A0@amazon.com).
|
||||
:::
|
||||
|
||||
To enable error reporting, run the following command:
|
||||
|
||||
@@ -78,11 +78,17 @@ See all configurable values on [ArtifactHub](https://artifacthub.io/packages/hel
|
||||
|
||||
## PostgreSQL production setup
|
||||
|
||||
The PostgreSQL database that is created by default during installation is only intended for demonstration and testing purposes. For production instances, you should use another installation method using one of the following operators:
|
||||
The PostgreSQL database installed by default with the Helm chart is intended for demonstration and test environments.
|
||||
|
||||
For production deployments, use a separately managed PostgreSQL installation instead of relying on the chart's bundled database.
|
||||
|
||||
Common options include:
|
||||
|
||||
- [CloudNativePG](https://github.com/cloudnative-pg/cloudnative-pg)
|
||||
- [Zalando Postgres Operator](https://github.com/zalando/postgres-operator)
|
||||
|
||||
After you provision PostgreSQL externally, configure authentik to use it with the settings in the [PostgreSQL configuration reference](../configuration/configuration.mdx#postgresql-settings).
|
||||
|
||||
## Email configuration (optional but recommended)
|
||||
|
||||
It is also recommended to configure global email settings. These are used by authentik to notify administrators about alerts, configuration issues and new releases. They can also be used by [Email stages](../../add-secure-apps/flows-stages/stages/email/index.mdx) to send verification/recovery emails.
|
||||
|
||||
@@ -12,7 +12,7 @@ authentik does not support downgrading. Make sure to back up your database in ca
|
||||
|
||||
**Preview the release notes**: Be sure to carefully read the [Release Notes](../../releases/) for the specific version to which you plan to upgrade. The release might have special requirements or actions, or contain breaking changes.
|
||||
|
||||
**Database backup**: Before upgrading, make a backup of your PostgreSQL database. You can create a backup by dumping your existing database. For detailed instructions, refer to the relevant guide for your deployment method ([Docker Compose](../troubleshooting/postgres/upgrade_docker.md) or [Kubernetes](../troubleshooting/postgres/upgrade_kubernetes.md)).
|
||||
**Database backup**: Before upgrading, make a backup of your PostgreSQL database. For general guidance, see [Backup and restore](../sys-mgmt/ops/backup-restore.md). For deployment-specific PostgreSQL guides, refer to the relevant guide for your deployment method ([Docker Compose](../troubleshooting/postgres/upgrade_docker.md) or [Kubernetes](../troubleshooting/postgres/upgrade_kubernetes.md)).
|
||||
|
||||
**Upgrade sequence**: Upgrades must follow the sequence of major releases; **do not skip** directly from an older major version to the most recent version.
|
||||
|
||||
|
||||
@@ -7,20 +7,28 @@ This guide outlines the critical components to back up and restore in authentik.
|
||||
|
||||
## PostgreSQL database
|
||||
|
||||
The PostgreSQL database is the most important part of an authentik backup. Without it, authentik cannot be restored to a usable state.
|
||||
|
||||
### Backup
|
||||
|
||||
- **Role:** Stores all persistent data (users, policies, configurations, etc.).
|
||||
- **Impact of Loss:** Complete data loss, requiring full restoration to recover functionality.
|
||||
- **Backup Guidance:**
|
||||
- Use PostgreSQL's native tools ([`pg_dump`](https://www.postgresql.org/docs/current/app-pgdump.html), [`pg_dumpall`](https://www.postgresql.org/docs/current/app-pg-dumpall.html), or [continuous archiving](https://www.postgresql.org/docs/current/continuous-archiving.html)).
|
||||
- Exclude system databases: `template0` and `template1`.
|
||||
- **Official Documentation:** [PostgreSQL Backup and Restore](https://www.postgresql.org/docs/current/backup.html)
|
||||
- The PostgreSQL database stores all persistent authentik data, including users, policies, flows, and configuration.
|
||||
- Loss of this database means full application data loss.
|
||||
- Use PostgreSQL-native tooling such as [`pg_dump`](https://www.postgresql.org/docs/current/app-pgdump.html), [`pg_dumpall`](https://www.postgresql.org/docs/current/app-pg-dumpall.html), or [continuous archiving](https://www.postgresql.org/docs/current/continuous-archiving.html).
|
||||
- Exclude the PostgreSQL system databases `template0` and `template1`.
|
||||
- Keep backups somewhere other than the database host when possible.
|
||||
|
||||
### Restore
|
||||
|
||||
- **Restoration Importance:** Essential for full recovery; authentik will not function without it.
|
||||
- **Restoration Guidance:**
|
||||
- Use PostgreSQL's [`pg_restore`](https://www.postgresql.org/docs/current/app-pgrestore.html) or other official methods.
|
||||
- Restore the PostgreSQL database before bringing authentik back into service.
|
||||
- Use PostgreSQL-native restore tooling such as [`pg_restore`](https://www.postgresql.org/docs/current/app-pgrestore.html) or `psql`, depending on how the backup was created.
|
||||
- Verify that the restored database is complete before reconnecting authentik.
|
||||
|
||||
For deployment-specific PostgreSQL upgrade guides, see:
|
||||
|
||||
- [Upgrade PostgreSQL on Docker Compose](../../troubleshooting/postgres/upgrade_docker.md)
|
||||
- [Upgrading PostgreSQL on Kubernetes](../../troubleshooting/postgres/upgrade_kubernetes.md)
|
||||
|
||||
For PostgreSQL connection settings, TLS, replicas, and pooler compatibility, see the [PostgreSQL configuration reference](../../install-config/configuration/configuration.mdx#postgresql-settings).
|
||||
|
||||
## Static directories
|
||||
|
||||
|
||||
@@ -2,46 +2,121 @@
|
||||
title: Upgrade PostgreSQL on Docker Compose
|
||||
---
|
||||
|
||||
### Dump your database
|
||||
This guide describes a manual PostgreSQL major-version upgrade for the default authentik Docker Compose deployment.
|
||||
|
||||
Dump your existing database with `docker compose exec postgresql pg_dump -U authentik -d authentik -cC > upgrade_backup_12.sql`.
|
||||
It assumes the PostgreSQL service is named `postgresql` and the authentik database is named `authentik`. If your Compose file uses different names, adjust the commands accordingly.
|
||||
|
||||
Before continuing, ensure the SQL dump file (`upgrade_backup_12.sql`) includes all your database content.
|
||||
## Before you start
|
||||
|
||||
### Stop your authentik stack
|
||||
- Make sure you have enough free disk space for:
|
||||
- a SQL dump of the database
|
||||
- a copy of the existing PostgreSQL data directory or volume
|
||||
- the newly initialized PostgreSQL data directory
|
||||
- Expect downtime while the database is exported, recreated, and restored.
|
||||
- Review the [Backup and restore](../../sys-mgmt/ops/backup-restore.md) guidance before proceeding.
|
||||
|
||||
Stop all services with `docker compose down`.
|
||||
## 1. Create a logical backup
|
||||
|
||||
### Backup your existing database
|
||||
Create a database dump:
|
||||
|
||||
If you use Docker volumes you can run the following command: `docker volume create authentik_database_backup && docker run --rm -v authentik_database:/from -v authentik_database_backup:/to alpine sh -c 'cd /from && cp -a . /to'`. You can find the name of the `authentik_database` volume with `docker volume ls`.
|
||||
```shell
|
||||
docker compose exec postgresql pg_dump -U authentik -d authentik -cC > authentik-postgres-backup.sql
|
||||
```
|
||||
|
||||
If your data is a file path: `cp -a /path/to/v12-data /path/to/v12-backup`
|
||||
Before continuing, confirm that `authentik-postgres-backup.sql` exists and contains the expected database objects.
|
||||
|
||||
### Delete your old database
|
||||
## 2. Stop your authentik stack
|
||||
|
||||
Stop all services with this command:
|
||||
|
||||
```shell
|
||||
docker compose down
|
||||
```
|
||||
|
||||
## 3. Back up the PostgreSQL data directory
|
||||
|
||||
Back up the existing PostgreSQL data before replacing it.
|
||||
|
||||
If you use Docker volumes:
|
||||
|
||||
```shell
|
||||
docker volume create authentik_database_backup
|
||||
docker run --rm -v authentik_database:/from -v authentik_database_backup:/to alpine sh -c 'cd /from && cp -a . /to'
|
||||
```
|
||||
|
||||
You can find the exact name of the PostgreSQL volume with `docker volume ls` if it differs from `authentik_database`.
|
||||
|
||||
Alternatively, if your PostgreSQL data is stored on the host filesystem:
|
||||
|
||||
```shell
|
||||
cp -a /path/to/postgres-data /path/to/postgres-data-backup
|
||||
```
|
||||
|
||||
## 4. Remove the old data directory
|
||||
|
||||
:::danger
|
||||
Do not execute this step without checking that the backup (previous step) completed successfully.
|
||||
Do not continue unless both the database dump and the filesystem or volume backup completed successfully.
|
||||
:::
|
||||
|
||||
If you use Docker volumes: `docker volume rm -f authentik_database`.
|
||||
If you use Docker volumes:
|
||||
|
||||
If your data is a file path: `rm -rf /path/to/v12-data`
|
||||
```shell
|
||||
docker volume rm -f authentik_database
|
||||
```
|
||||
|
||||
### Modify your compose.yml file
|
||||
Alternatively, if your PostgreSQL data is stored on the host filesystem:
|
||||
|
||||
Update the PostgreSQL service image from `docker.io/library/postgres:12-alpine` to `docker.io/library/postgres:16-alpine`.
|
||||
```shell
|
||||
rm -rf /path/to/postgres-data
|
||||
```
|
||||
|
||||
Add `network_mode: none` to prevent connections being established to the database during the upgrade.
|
||||
## 5. Update the PostgreSQL image
|
||||
|
||||
### Recreate the database container
|
||||
Edit your `compose.yml` and update the PostgreSQL image tag to the new major version.
|
||||
|
||||
Pull new images and re-create the PostgreSQL container: `docker compose pull && docker compose up --force-recreate -d postgresql`
|
||||
For example, change:
|
||||
|
||||
Apply your backup to the new database: `cat upgrade_backup_12.sql | docker compose exec -T postgresql psql -U authentik`
|
||||
```yaml
|
||||
image: docker.io/library/postgres:12-alpine
|
||||
```
|
||||
|
||||
Remove the network configuration setting `network_mode: none` that you added to the Compose file in the previous step.
|
||||
to:
|
||||
|
||||
### Recreate authentik
|
||||
```yaml
|
||||
image: docker.io/library/postgres:16-alpine
|
||||
```
|
||||
|
||||
Start authentik again: `docker compose up --force-recreate -d`
|
||||
Temporarily add `network_mode: none` to the PostgreSQL service to prevent connections being established to the database during the upgrade.
|
||||
|
||||
## 6. Recreate PostgreSQL and restore the database
|
||||
|
||||
Pull images and start only PostgreSQL:
|
||||
|
||||
```shell
|
||||
docker compose pull
|
||||
docker compose up --force-recreate -d postgresql
|
||||
```
|
||||
|
||||
Restore the logical backup:
|
||||
|
||||
```shell
|
||||
cat authentik-postgres-backup.sql | docker compose exec -T postgresql psql -U authentik
|
||||
```
|
||||
|
||||
After the restore succeeds, remove the temporary `network_mode: none` setting from `compose.yml`.
|
||||
|
||||
## 7. Start authentik again
|
||||
|
||||
Start the full stack:
|
||||
|
||||
```shell
|
||||
docker compose up --force-recreate -d
|
||||
```
|
||||
|
||||
## 8. Verify the upgrade
|
||||
|
||||
After the stack is healthy again:
|
||||
|
||||
- confirm that authentik loads normally
|
||||
- check the server, worker, and postgresql logs for startup or migration errors
|
||||
- log in to authentik through the UI to verify the application is functioning normally
|
||||
|
||||
@@ -2,21 +2,24 @@
|
||||
title: Upgrading PostgreSQL on Kubernetes
|
||||
---
|
||||
|
||||
This guide walks you through upgrading PostgreSQL in your authentik Kubernetes deployment. The process requires a brief downtime period while the database is migrated.
|
||||
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.
|
||||
:::
|
||||
|
||||
## Prerequisites
|
||||
## Before you start
|
||||
|
||||
- `kubectl` access with permissions to `scale` deployments and `exec` into pods
|
||||
- Your existing `values.yaml` file used for authentik deployment
|
||||
- Basic understanding of Kubernetes and Helm commands
|
||||
- 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
|
||||
|
||||
## Overview of workflow
|
||||
Review [Backup and restore](../../sys-mgmt/ops/backup-restore.md) before proceeding.
|
||||
|
||||
The basic steps to upgrade PostgreSQL on Kubernetes are:
|
||||
## Overview
|
||||
|
||||
The upgrade flow is:
|
||||
|
||||
1. Stop authentik services
|
||||
2. Back up the database
|
||||
@@ -25,18 +28,18 @@ The basic steps to upgrade PostgreSQL on Kubernetes are:
|
||||
5. Restore database content
|
||||
6. Restart authentik services
|
||||
|
||||
## Stop authentik services
|
||||
## 1. Stop authentik services
|
||||
|
||||
Begin by scaling down authentik services to prevent database access during the migration:
|
||||
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
|
||||
```
|
||||
|
||||
## Back up the database
|
||||
## 2. Back up the database
|
||||
|
||||
Connect to your PostgreSQL pod:
|
||||
Connect to the PostgreSQL pod:
|
||||
|
||||
```shell
|
||||
kubectl exec -it authentik-postgresql-0 -- bash
|
||||
@@ -56,19 +59,19 @@ pg_dump -U $POSTGRES_USER $POSTGRES_DATABASE > /bitnami/postgresql/dump.sql
|
||||
```
|
||||
|
||||
:::tip
|
||||
Consider copying the dump file to a safe location outside the pod:
|
||||
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
|
||||
```
|
||||
|
||||
This ensures you have a backup even if something goes wrong with the pod or storage.
|
||||
Keeping an external copy protects you if the pod or persistent volume is recreated unexpectedly.
|
||||
:::
|
||||
|
||||
## Prepare the data directory
|
||||
## 3. Prepare the data directory
|
||||
|
||||
While still connected to the PostgreSQL pod, prepare the data directory for the upgrade:
|
||||
While still connected to the pod, prepare the data directory:
|
||||
|
||||
```shell
|
||||
# Ensure you're in the PostgreSQL data directory
|
||||
@@ -82,12 +85,12 @@ mv data data-old
|
||||
```
|
||||
|
||||
:::caution
|
||||
Do not delete the old data directory immediately. Keeping it as `data-old` allows for recovery if the upgrade encounters issues.
|
||||
Do not delete `data-old` yet. It provides a rollback path if the restore fails.
|
||||
:::
|
||||
|
||||
## Upgrade PostgreSQL
|
||||
## 4. Upgrade PostgreSQL
|
||||
|
||||
Now update your `values.yaml` to specify the new PostgreSQL version:
|
||||
Update `values.yaml` with the new PostgreSQL image tag:
|
||||
|
||||
```yaml
|
||||
postgresql:
|
||||
@@ -95,11 +98,11 @@ postgresql:
|
||||
tag: <NEW_VERSION>
|
||||
```
|
||||
|
||||
Apply these changes using Helm to deploy the updated configuration.
|
||||
Apply the change with Helm using your normal deployment command.
|
||||
|
||||
This will restart the PostgreSQL pod with the new image. When the pod starts, PostgreSQL will initialize a new, empty data directory since the previous directory was renamed.
|
||||
When the pod restarts with the new image, PostgreSQL initializes a new empty `data` directory because the previous one was renamed to `data-old`.
|
||||
|
||||
## Restore database content
|
||||
## 5. Restore database content
|
||||
|
||||
Connect to the PostgreSQL pod again:
|
||||
|
||||
@@ -123,11 +126,17 @@ export PGPASSWORD=$(cat $POSTGRES_PASSWORD_FILE)
|
||||
psql -U $POSTGRES_USER $POSTGRES_DATABASE < dump.sql
|
||||
```
|
||||
|
||||
## Restart authentik services
|
||||
## 6. Restart authentik services
|
||||
|
||||
After the database restoration completes successfully, restart authentik using Helm with your updated configuration.
|
||||
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.
|
||||
|
||||
This will scale your authentik server and worker deployments back to their original 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
|
||||
|
||||
@@ -142,14 +151,14 @@ If you encounter issues during the upgrade process:
|
||||
|
||||
### Dump file not found
|
||||
|
||||
If your dump file is missing after upgrading:
|
||||
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
|
||||
|
||||
For persistent problems, you can restore from the `data-old` directory if needed:
|
||||
If you need to roll back to the old PostgreSQL data directory:
|
||||
|
||||
```shell
|
||||
kubectl exec -it authentik-postgresql-0 -- bash
|
||||
|
||||
Reference in New Issue
Block a user