# Upgrade to Immuta 2024.2 LTS

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

{% hint style="warning" %}
**Helm chart deprecation notice**

As of Immuta version 2024.2, the IHC has been deprecated in favor of the IEHC. The `immuta-values.yaml` Helm values files are not cross-compatible.
{% endhint %}

## 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](https://documentation.immuta.com/2024.2/troubleshooting#common).
3. The PostgreSQL instance is [accepting connections](https://documentation.immuta.com/2024.2/troubleshooting#postgresql).

For additional information, consult the Deployment requirements.

### Validate the Helm release

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

   ```shell
   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. Contact your Immuta representative for guidance.

## Metadata database

{% hint style="warning" %}
**Azure prerequisites**

If using an Azure flexible server as an external database source, ensure that the pgcrypto server extension is enabled in the Azure server parameters UI before proceeding.
{% endhint %}

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.

   ```shell
   kubectl get pod --selector "app.kubernetes.io/component=database" --output name
   ```
2. Spawn a shell inside the running metadata database pod.

   ```shell
   kubectl exec --stdin --tty <metadata-database-pod-name> -- sh
   ```
3. Perform a database backup.

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

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

#### Setup new database

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

   ```shell
   kubectl run immuta-setup-db --stdin --tty --rm --image docker.io/bitnami/postgresql:latest -- sh
   ```
2. Press `enter` when the prompt appears and connect to the new PostgreSQL database as a superuser. Depending on the cloud provider, the default superuser name (`postgres`) might differ.

   ```sh
   psql --host <postgres-fqdn> --username <postgres-admin> --dbname postgres --port 5432 --password
   ```
3. Create an `immuta` role and database.

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

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

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

   ```shell
   kubectl cp bometadata.dump immuta-restore-db:/tmp
   ```
3. Spawn a shell inside pod `immuta-restore-db`.

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

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

   ```shell
   kubectl delete pod/immuta-restore-db
   ```

### External

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

## Helm values

{% hint style="info" %}
**Helm values file compatibility**

The `immuta-values.yaml` Helm values file used by the IHC is not compatible with the new IEHC.
{% endhint %}

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

   ```sh
   mv immuta-values.yaml immuta-values.ihc.yaml
   ```
2. **Legacy audit records**: If you want to be able to view audit records from before the 2024.2 upgrade, set `FeatureFlag_auditLegacyViewHide` to `false` in your Helm values file.
3. Follow a cloud provider-specific installation guide to complete the upgrade. If your distribution is not listed below (such as [K3s](https://k3s.io/) or [RKE2](https://docs.rke2.io/)), follow the generic installation instructions:
   * [Managed public cloud](https://documentation.immuta.com/2024.2/self-managed-deployment/install/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](https://documentation.immuta.com/2024.2/self-managed-deployment/install/red-hat-openshift)
   * [Generic installation](https://documentation.immuta.com/2024.2/self-managed-deployment/install/generic-installation)