Upgrading IEHC

This guide demonstrates how to upgrade an existing 2024.2+ Immuta deployment installed with the Immuta Enterprise Helm chart (IEHC) to the latest Immuta release.

Requirements

Temporal

Temporal's upgrade mechanism utilizes SQL command CREATE EXTENSION when managing database schema changes. However, in cloud-managed PostgreSQL offerings, this command is typically restricted to roles with elevated privileges to protect the database and maintain the stability of the cloud environment.

To ensure Temporal can successfully manage its schema, an administrator role must be granted temporarily. The role name varies depending on the cloud-managed service:

• Amazon RDS: rds_superuser

• Azure Database: azure_pg_admin

• Google Cloud SQL: cloudsqlsuperuser

Starting in IEHC 2024.3, a Temporal server is included in the chart and requires two databases to store state. You can expand the existing PostgreSQL database in use for Immuta by creating Temporal databases like so:

1. Grant administrator privileges to the Postgres database role. Upon successfully completing this installation guide, you can optionally revoke this role grant:

   GRANT <admin-role> TO <postgres-user>;

2. Grant the Postgres user role to the current user. Upon successfully completing this installation guide, you can optionally revoke this role grant:

   GRANT <postgres-user> TO CURRENT_USER;

3. Create the new temporal databases and additional privileges for the Postgres user specified:

   CREATE DATABASE temporal WITH OWNER <postgres-user>;
   CREATE DATABASE temporal_visibility WITH OWNER <postgres-user>;
   
   GRANT ALL PRIVILEGES ON DATABASE temporal TO <postgres-user>;
   GRANT ALL PRIVILEGES ON DATABASE temporal_visibility TO <postgres-user>;

4. Connect to the new Temporal databases and run the following GRANT statements:

   \c temporal
   GRANT CREATE ON SCHEMA public TO <postgres-user>;
   
   \c temporal_visibility
   GRANT CREATE ON SCHEMA public TO <postgres-user>;
   CREATE EXTENSION btree_gin;

Enabling Temporal

To enable the Temporal deployment, set the following values. Include the tls settings if using a Cloud database that requires TLS:

temporal:
  enabled: true
  schema:
    createDatabase:
      enabled: false
  server:
    config:
      persistence:
        default:
          sql:
            database: temporal
            tls:
              # Set to true if Postgres Database uses TLS
              enabled: true
        visibility:
          sql:
            database: temporal_visibility
            tls:
              # Set to true if Postgres Database uses TLS
              enabled: true

Helm values

To improve the experience using the IEHC, two Helm value changes have been introduced. Before deploying the IEHC, you must perform the Helm value changes below.

PostgreSQL configuration

IEHC 2024.3.x and newer adds support for global and component-level PostgreSQL connection details. This means you only need to specify the PostgreSQL connection information once in the global scope and apply overrides (if necessary) at a component level.

If you installed IEHC 2024.2 LTS using our install guides, your immuta-values.yaml file probably looks something like this to configure your PostgreSQL connection for multiple components:

global:
  imageRepositoryMap:
    immuta/immuta-service: stable/immuta-service
    immuta/immuta-db: stable/immuta-db
    immuta/audit-service: stable/audit-service
    immuta/audit-export-cronjob: stable/audit-export-cronjob
    immuta/classify-service: stable/classify-service
    immuta/cache: stable/cache
#...
audit:
  config:
    databaseConnectionString: postgres://immuta:<postgres-password>@<postgres-fqdn>:5432/immuta?schema=audit
    elasticsearchEndpoint: <elasticsearch-endpoint>
    elasticsearchUsername: <elasticsearch-username>
    elasticsearchPassword: <elasticsearch-password>
#...
secure:
  postgresql:
    host: <postgres-fqdn>
    port: 5432
    database: immuta
    username: immuta
    password: <postgres-password>
    ssl: true
#...

Now, with PostgreSQL configuration in the global scope, your immuta-values.yaml file can look like this to specify the PostgreSQL connection:

global:
#...
  postgresql:
    host: <postgres-fqdn>
    port: 5432
    username: immuta
    password: <postgres-password>
#...
audit:
  postgresql:
    database: immuta
  config:
    elasticsearchEndpoint: <elasticsearch-endpoint>
    elasticsearchUsername: <elasticsearch-username>
    elasticsearchPassword: <elasticsearch-password>
#...
secure:
  postgresql:
    database: immuta
    ssl: true

Feature flags

Feature flags have moved from environment variables in IEHC 2024.3.x and newer as well. You may now set feature flags globally, and then the IEHC will properly configure all applications for you. Migrate all feature flags from secure.extraEnvVars to global.featureFlags.

# Feature Flags may now be set as global boolean values
global:
#...
  featureFlags:
    exampleFlag: false

# Remove flags being set via extraEnvVars
#
# secure:
#  extraEnvVars:
#    - name: exampleFlag
#      value: "false"

If you fail to migrate the values from secure.extraEnvVars to global.featureFlags , then Helm will display warnings similar to below:

Upgrade Immuta

After updating your immuta-values.yaml file to include any of the changes for the updates above, you can upgrade Immuta with the following command:

helm upgrade <release-name> oci://ocir.immuta.com/stable/immuta-enterprise --values immuta-values.yaml --version 2025.1.0