Use external PostgreSQL database

6.4. Use external PostgreSQL database#

This section describes, how you can use an external PostgreSQL database management system for all services. Use this configuration, if you have a PostgreSQL database cluster already in place, with redundancy and failover mechanisms.

Important

You need to ensure that your PostgreSQL database is at least version 12.

6.4.1. Prepare external PostgreSQL database#

Before you can use an external PostgreSQL database, you need to prepare it properly.

  1. Create a PostgreSQL user for each of the following services:

    • Guardian

    • Keycloak

    • Keycloak Extensions

    • Notifications API

    • Self Service

    • UMC Session

  2. Create a database for each of the services listed in the preceding step. Nubus uses the following default database names.

    • guardian

    • keycloak

    • keycloak_extensions

    • notificationsapi

    • selfservice

    • umcsession

    If you want to define custom database names, see Define custom database names.

    Important

    You need to follow the lexical structure for identifiers and keywords for PostgreSQL database names. Otherwise, the database setup fails, which has subsequent consequences for the Nubus deployment. Database names are identifiers. See Identifiers and Key Words in PostgreSQL 15.8 Documentation [4].

6.4.2. Configure external PostgreSQL database#

To configure an external PostgreSQL database, you need to provide the connection details in the Helm Chart configuration in your custom_values.yaml values file as outlined in Listing 6.6.

  1. Add the connection parameters for your external PostgreSQL database as shown in Listing 6.6 to your custom_values.yaml values file.

    global.postgresql.connection.host

    The hostname of the external PostgreSQL database management system.

    global.postgresql.connection.port

    The port number of the external PostgreSQL database management system.

    keycloak.postgresql.auth.database

    The database name for the Keycloak.

    nubusGuardian.postgresql.auth.database

    The database name for the Guardian.

    nubusKeycloakExtensions.postgresql.auth.database

    The database name for the Keycloak Extensions.

    nubusNotificationsApi.postgresql.auth.database

    The database name for the Notifications API.

    nubusUmcServer.postgresql.authSession.auth.database

    The database name for the UMC session.

    nubusStackDataUms.nubusUmcServer.postgresql.auth.database

    The database name for the Self Service.

    Listing 6.6 Example for custom_values.yaml values file to configure external PostgreSQL database#
    global:
  postgresql:
    connection:
      host: "postgres.db.example.com"
      port: 5432
postgresql:
  enabled: false

keycloak:
  postgresql:
    auth:
      database: "<keycloak-database>"

nubusGuardian:
  postgresql:
    auth:
      database: "<guardian-database>"

nubusKeycloakExtensions:
  postgresql:
    auth:
      database: "<keycloak-extensions-database>"

nubusNotificationsApi:
  postgresql:
    auth:
      database: "<notificationsapi-database>"

nubusUmcServer:
  postgresql:
    authSession:
      auth:
        database: "<umcsession-database>"

nubusStackDataUms:
  nubusUmcServer:
    postgresql:
      auth:
        database: "<selfservice-database>"

  2. Add the credentials for each of the PostgreSQL users you created in Prepare external PostgreSQL database.

    Custom credential configuration

    Add the content from Listing 6.7 to your custom_values.yaml values file. The listing uses the following Helm Chart values:

    Listing 6.7 Add PostgreSQL user credentials for external PostgreSQL database#
    keycloak:
  postgresql:
    auth:
      username: "<keycloak-user>"
      password: "<keycloak-password>"

nubusGuardian:
  postgresql:
    auth:
      username: "<guardian-user>"
      password: "<guardian-password>"

nubusKeycloakExtensions:
  postgresql:
    auth:
      username: "<keycloak-extensions-user>"
      password: "<keycloak-extensions-password>"

nubusNotificationsApi:
  postgresql:
    auth:
      username: "<notifications-api-user>"
      password: "<notifications-api-password>"

nubusUmcServer:
  postgresql:
    selfservice:
      auth:
        password: "<selfservice-password>"
    authSession:
      auth:
        username: "<umcsession-user>"
        password: "<umcsession-password>"

nubusStackDataUms:
  nubusUmcServer:
    postgresql:
      auth:
        username: "<selfservice-user>"
    Kubernetes secrets for credentials configuration

    Use the example in Listing 6.8 if you want to use existing Kubernetes Secrets. The listing uses the following Helm Chart values:

    Listing 6.8 Use existing Kubernetes Secrets for PostgreSQL user credentials for external PostgreSQL database#
    keycloak:
  postgresql:
    auth:
      username: "<keycloak-user>"
      existingSecret:
        name: "<keycloak-secret-name>"
        keyMapping:
          password: "<keycloak-password-key>"

nubusGuardian:
  postgresql:
    auth:
      username: "<guardian-user>"
      existingSecret:
        name: "<guardian-secret-name>"
        keyMapping:
          password: "<guardian-password-key>"

nubusKeycloakExtensions:
  postgresql:
    auth:
      username: "<keycloak-extensions-user>"
      existingSecret:
        name: "<keycloak-extensions-secret-name>"
        keyMapping:
          password: "<keycloak-extensions-password-key>"

nubusNotificationsApi:
  postgresql:
    auth:
      username: "<notifications-api-user>"
      existingSecret:
        name: "<notifications-api-secret-name>"
        keyMapping:
          password: "<notifications-api-secret-password-key>"

nubusUmcServer:
  postgresql:
    selfservice:
      auth:
        existingSecret:
          name: "<selfservice-secret-name>"
          keyMapping:
            password: "<selfservice-password-key>"
    authSession:
      auth:
        username: "<umcsession-user>"
        existingSecret:
          name: "<umcsession-secret-name>"
          keyMapping:
            password: "<umcsession-password-key>"

nubusStackDataUms:
  nubusUmcServer:
    postgresql:
      auth:
        username: "<selfservice-user>"

6.4.3. Define custom database names#

To define custom database names, add the content from Listing 6.9 to your custom_values.yaml. Replace custom_name_for_* with your respective values for the database name.

Listing 6.9 Define custom database names for PostgreSQL databases used by Nubus#
nubusGuardian:
  postgresql:
    auth:
      database: "custom_name_for_guardian"

keycloak:
  postgresql:
    auth:
      database: "custom_name_for_keycloak"

nubusKeycloakExtensions:
  postgresql:
    auth:
      database: "custom_name_for_keycloak_extensions"

nubusNotificationsApi:
  postgresql:
    auth:
      database: "custom_name_for_notifications_api"

nubusUmcServer:
  postgresql:
    selfservice:
      auth:
        database: "custom_name_for_selfservice"
    authSession:
      auth:
        database: "custom_name_for_umcsession"

Tip

To lookup the database names in your cluster:

  1. Render the Helm Chart template as described in Render Helm Chart template.

  2. Look for the ConfigMap with metadata.name: "release-name-postgresql-provisioning".

  3. You find the list of database names in the ConfigMap data.databases.list.

On this page