Introduced in 2024.2, the Immuta Enterprise Helm chart (IEHC) is an entirely new Helm chart used to deploy Immuta. Unlike the previous Immuta Helm chart (IHC), the IEHC shares the same version as the Immuta product. Each version of the chart supports a singular version of Immuta. Upgrading the Immuta version now entails upgrading the underlying Helm chart. Failure to do so will lead to an unsupported configuration.

This section provides upgrade guides for two scenarios:

• Upgrade to Immuta v2024.2 LTS: Follow this guide if you are upgrading from Immuta 2024.1.x or older. Since these older versions of Immuta use the legacy IHC, this page instructs you to upgrade from the IHC to the IEHC.

• Upgrade Immuta: Follow this guide if you are upgrading from the 2024.2 LTS to a newer version. This page instructs you to upgrade the IEHC.

This guide demonstrates how to upgrade an existing Immuta deployment installed with the Immuta Helm chart (IHC) to the latest LTS release using the newer Immuta Enterprise Helm chart (IEHC).

Prerequisites

Create a PostgreSQL database

1. The PostgreSQL instance has been provisioned and is actively running.

2. The PostgreSQL instance's hostname/FQDN is resolvable from within the Kubernetes cluster.

3. The PostgreSQL instance is accepting connections.

For additional information, consult the Deployment requirements.

Validate the Helm release

1. Fetch the metadata for the Helm release associated with Immuta.

   Copy

   helm get metadata --output yaml <helm-release-name>

2. Review the output from the previous step and verify the following:

   • The Immuta version (appVersion) is

     • The last LTS (2022.5.x) or 2024.1 or newer

     • Less than 2024.2

   • The Immuta Helm chart (version) is greater than or equal to 4.13.5

   • The Immuta Helm chart name (chart) is immuta

3. If any of the criteria is not met, it's first necessary to perform a Helm upgrade using the IHC.

Metadata database

The new IEHC no longer supports deploying a Metadata database (PostgreSQL) inside the Kubernetes cluster. Before transitioning to the new IEHC, it's first necessary to externalize the Metadata database.

Built-in

The following demonstrates how to take a database backup and import the data into each cloud provider's managed PostgreSQL service.

Create backup of old database

1. Get the metadata database pod name.

   Copy

   kubectl get pod --selector "app.kubernetes.io/component=database" --output name

2. Spawn a shell inside the running metadata database pod.

   Copy

   kubectl exec --stdin --tty <metadata-database-pod-name> -- sh

3. Perform a database backup.

   Copy

   pg_dump --dbname=bometadata --file=/tmp/bometadata.dump --format=custom --no-owner --no-privileges

4. Type exit, and then press Enter to exit the shell prompt.

5. Copy file bometadata.dump from the pod to the host's working directory.

   Copy

   kubectl cp <metadata-database-pod-name>:/tmp/bometadata.dump .

Setup new database

1. Create a pod named immuta-setup-db and spawn a shell.

   Copy

   kubectl run immuta-setup-db --stdin --tty --rm --image docker.io/bitnami/postgresql:latest -- sh

2. Connect to the new PostgreSQL database as a superuser. Depending on the cloud provider, the default superuser name (postgres) might differ.

   Copy

   psql --host <postgres-fqdn> --username postgres --port 5432 --password

3. Create an immuta role and database.

   Copy

   CREATE ROLE immuta with login encrypted password '<postgres-password>';
   GRANT immuta TO CURRENT_USER;
   
   CREATE DATABASE immuta OWNER immuta;
   
   GRANT all ON DATABASE immuta TO immuta;
   ALTER ROLE immuta SET search_path TO bometadata,public;
   REVOKE immuta FROM CURRENT_USER;

4. Type \q, and then press Enter to exit the psql prompt.

5. Authenticate as the immuta user and create the pgcrypto extension.

   Copy

   psql --host <postgres-fqdn> --username immuta --port 5432 --password
   CREATE EXTENSION pgcrypto;

6. Type \q, and then press Enter to exit the psql prompt.

Restore backup to new database

1. Create a pod named immuta-restore-db and spawn a shell.

   Copy

   kubectl run immuta-restore-db --image docker.io/bitnami/postgresql:latest -- sleep infinity

2. Copy file bometadata.dump from the host's working directory to pod immuta-restore-db.

   Copy

   kubectl cp bometadata.dump immuta-restore-db:/tmp

3. Spawn a shell inside pod immuta-restore-db.

   Copy

   kubectl exec immuta-restore-db --stdin --tty -- sh

4. Perform a database restore while authenticated as role immuta. Refer to the value substituted for <postgres-password> when prompted to enter a password.

   Copy

   pg_restore --host=<postgres-fqdn> --port=5432 --username=immuta --password --dbname=immuta --no-owner --role=immuta < /tmp/bometadata.dump

5. Type exit, and then press Enter to exit the shell prompt.

6. Delete pod immuta-restore-db that was previously created.

   Copy

   kubectl delete pod/immuta-restore-db

External

No additional work is required. The existing database can be reused with the new IEHC.

Helm values

1. Rename the existing immuta-values.yaml Helm values file used by the IHC.

   Copy

   mv immuta-values.yaml immuta-values.ihc.yaml

2. Follow a cloud provider-specific installation guide to complete the upgrade. If your distribution is not listed below (such as K3s or RKE2), follow the generic installation instructions:

   • Managed public cloud: This guide includes instructions for

     • Amazon Elastic Kubernetes Service (EKS)

     • Google Kubernetes Engine (GKE)

     • Microsoft Azure Kubernetes Service (AKS)

   • Red Hat OpenShift

   • Generic installation

This guide demonstrates how to upgrade Immuta. The Immuta Enterprise Helm chart (IEHC) shares the same version with the Immuta product, so upgrading the Immuta version entails upgrading the IEHC. Failure to upgrade the underlying Helm chart will lead to an unsupported configuration.

Immuta Enterprise Helm chart

Upgrade Immuta.