External Metadata Database Configuration

Audience: System Administrators

Content Summary: This page outlines how to configure an external metadata database for Immuta instead of using Immuta's built-in PostgreSQL Metadata Database that runs in Kubernetes.

Helm Chart Version

Update to the latest Helm Chart before proceeding any further.

Overview

The Metadata Database can optionally be configured to run outside of Kubernetes, which eliminates the variability introduced by the Kubernetes scheduler and/or scaler without compromising high-availability. This is the preferred configuration, as it offers infrastructure administrators a greater level of control in the event of disaster recovery.

Helm Configuration

PostgreSQL Version incompatibilities

PostgreSQL versions 12 through 16 are only supported when Query Engine rehydration is enabled; otherwise, the PostgreSQL version must be pinned at 12. PostgreSQL abstraction layers such as AWS Aurora are not supported.

1. Enable an external metadata database by setting database.enabled=false in the immuta-values.yaml file and passing the connection information for the PostgreSQL instance under the key externalDatabase.

2. Set queryEngine.rehydration.enabled=true. If set to false, then externalDatabase.superuser.username and externalDatabase.superuser.password must be provided.

database:
  enabled: false
externalDatabase:
  enabled: true
  host: <fqdn>
  username: <username>
  password: <password>
  dbname: <database name>
queryEngine:
  rehydration:
    enabled: true
backup:
  restore:
    enabled: false

External Database Object

Superuser Role

Prior to Helm Chart 4.13, declaring externalDatabase.superuser.username and externalDatabase.superuser.password was a required field. This requirement has since been made optional when Query Engine rehydration is enabled. If a superuser is omitted, then the chart will no longer manage the database backup/restore process. In this configuration, customers are responsible for backing up their external metadata database.

The externalDatabase object is detailed below and in the Immuta Helm Chart Options.

Property	Description	Default Value
host (required)	Hostname of the external PostgreSQL database instance.	nil
port	Port of the external PostgreSQL database instance.	5432
sslmode (required)	The mode for the database connection. Supported values are disable, require, verify-ca, and verify-fully.	nil
superuser.username	Username for the superuser used to initialize the PostgreSQL instance.	nil
superuser.password	Password for the superuser used to initialize the PostgreSQL instance.	nil
username	Username that Immuta creates and uses for the application.	bometa
password (required)	Password associated with username.	nil
dbname	Database name that Immuta uses.	bometadata

Additionally, it is possible to use existingSecret instead of setting externalDatabase.password in the Helm values. These passwords map to the same keys that are used for the built-in database. For example,

apiVersion: v1
kind: Secret
metadata:
  name: immuta-secret
data:
  databasePassword: <password>

First-Time PostgreSQL Setup

Role Creation

The role's password set below should match Helm value externalDatabase.password.

Azure Database for PostgreSQL

During restore the built-in database's backup expects role postgres to exist. This role is not present by default, and must be created when using Azure Database for PostgreSQL.

CREATE ROLE postgres WITH LOGIN ENCRYPTED PASSWORD '<password>';

1. Log in to the external metadata database as a user with the superuser role attribute (such as the postgres user) using your preferred tool (e.g., psql, pgAdmin).

2. Connect to database postgres, and execute the following SQL.

DROP DATABASE bometadata;
CREATE ROLE bometa WITH LOGIN CREATEDB ENCRYPTED PASSWORD '<password>';
GRANT bometa TO CURRENT_USER;
CREATE DATABASE bometadata OWNER bometa;
GRANT ALL ON DATABASE bometadata TO bometa;
ALTER ROLE bometa SET search_path TO bometadata,public;

3. Connect to database bometadata that was created in the previous step, and execute the following SQL. Azure Database for PostgreSQL: Extensions must be configured in the web portal.

CREATE EXTENSION pgcrypto;

Migrating from Immuta's Built-In PostgreSQL Database to External Metadata Database

Helm Releases

Run helm list to view all existing Helm releases. Refer to the Helm docs to learn more.

For existing deployments, you can migrate from the built-in database to an external database. To migrate, backups must be configured. Reach out to your Immuta representative for instructions.

1. (Optional) Set default namespace:

   kubectl config set-context --current --namespace <namespace>

2. Trigger manual backup:

kubectl create job adhoc-backup --from cronjob/<release>-immuta-backup

3. Validate backup succeeded:

kubectl get --no-headers pods --output name | grep "adhoc-backup" | xargs kubectl logs --container database-backup

4. Follow the steps outlined in section First-Time PostgreSQL Setup.

5. Edit immuta-values.yaml to enable the external metadata database and restore.

   database:
     enabled: false
   externalDatabase:
     enabled: true
     host: <fqdn>
     username: <username>
     password: <password>
     dbname: <database-name>
   backup:
     enabled: true
     restore:
       enabled: true

6. Apply the immuta-values.yaml changes made in the previous step:

   helm upgrade <release> immuta/immuta --values immuta-values.yaml

7. Wait until the Kubernetes resources become ready.

   kubectl get all

8. Edit immuta-values.yaml to enable Query Engine rehydration and disable backup/restore.

   backup:
     enabled: false
     restore:
       enabled: false
   queryEngine:
     rehydration:
       enabled: true

9. Rerun the previous helm upgrade command to apply the latest immuta-values.yaml changes.

10. Connect to database postgres, and execute the following SQL. Azure Database for PostgreSQL: Delete the previously created role by running DROP ROLE postgres;

ALTER ROLE bometa WITH NOCREATEDB;
ALTER DATABASE bometadata OWNER TO CURRENT_USER;