Database - Zitadel — ContextQMD

PostgreSQL

Zitadel requires PostgreSQL 14 or later. The chart supports multiple ways to connect to PostgreSQL depending on your security requirements.

Connecting Without TLS (Not Recommended)

This method connects to PostgreSQL without encryption. Only use this for testing or when the database is on a private network with no risk of interception.

Store the DSN in a Kubernetes Secret and pass it as an environment variable:

bash

kubectl create secret generic zitadel-db-credentials \
  --from-literal=dsn="postgresql://zitadel:[email protected]:5432/zitadel?sslmode=disable"

yaml

zitadel:
  env:
    - name: ZITADEL_DATABASE_POSTGRES_DSN
      valueFrom:
        secretKeyRef:
          name: zitadel-db-credentials
          key: dsn

The sslmode=disable setting turns off TLS entirely. Traffic between Zitadel and PostgreSQL is unencrypted.

Connecting with Credentials and TLS

This method connects to PostgreSQL with TLS encryption but without certificate verification. Use this when you trust the network path but want encryption in transit.

bash

kubectl create secret generic zitadel-db-credentials \
  --from-literal=dsn="postgresql://zitadel:[email protected]:5432/zitadel?sslmode=require"

yaml

zitadel:
  env:
    - name: ZITADEL_DATABASE_POSTGRES_DSN
      valueFrom:
        secretKeyRef:
          name: zitadel-db-credentials
          key: dsn

The sslmode=require setting enforces TLS but does not verify the server certificate. This protects against passive eavesdropping but not against man-in-the-middle attacks.

Connecting with Certificates

This method connects to PostgreSQL with full TLS verification using certificates. Use this for production deployments where you need to verify the database server's identity.

yaml

zitadel:
  env:
    - name: ZITADEL_DATABASE_POSTGRES_DSN
      valueFrom:
        secretKeyRef:
          name: zitadel-db-credentials
          key: dsn
  dbSslCaCrt: "ca.crt"
  dbSslCaCrtSecret: "postgres-ca-cert"

Create a secret containing the CA certificate:

bash

kubectl create secret generic postgres-ca-cert \
  --from-file=ca.crt=/path/to/your/ca-certificate.crt

Create a secret containing the DSN with full verification:

bash

kubectl create secret generic zitadel-db-credentials \
  --from-literal=dsn="postgresql://zitadel:[email protected]:5432/zitadel?sslmode=verify-full&sslrootcert=/db-ssl-ca-crt/ca.crt"

The sslmode=verify-full setting enforces TLS and verifies that the server certificate is signed by the CA and that the server hostname matches the certificate. This provides full protection against eavesdropping and man-in-the-middle attacks. The dbSslCaCrtSecret references the Kubernetes Secret containing the CA certificate, and dbSslCaCrt specifies the key within that secret.