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.

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.
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

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).

Role Creation

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

Connect to database postgres, and execute the following SQL.

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>';

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;

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

For existing deployments, you can migrate from the built-in database to an external database. To migrate, backups must be configured.

(Optional) Set default namespace:

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

Trigger manual backup:

Helm Releases

Run helm list to view all existing Helm releases. Refer to the Helm docs to learn more.
```
kubectl create job adhoc-backup --from cronjob/<release>-immuta-backup
```

Validate backup succeeded:

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

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

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

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

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

Wait until the Kubernetes resources become ready.
```
kubectl get all
```

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

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

Rerun the previous helm upgrade command to apply the latest immuta-values.yaml changes.
Connect to database postgres, and execute the following SQL.
Azure Database for PostgreSQL

Delete the previously created role.
```
DROP ROLE postgres;
```
```
ALTER ROLE bometa WITH NOCREATEDB;
ALTER DATABASE bometadata OWNER TO CURRENT_USER;
```