Immuta helps you achieve the following outcomes in your data platform:

• Simplify Operations: Immuta’s dynamic access control and policy management require 93x fewer data policies to manage access control in your data platform according to the GigaOm study. It is simple and scalable, which improves change management and lowers the total cost of ownership of cloud data management.

• Improve data security: Immuta helps prove compliance with rules and regulations, even when securing hundreds of thousands of tables. An Immuta customer, Swedbank, migrated all critical analytics workloads to the cloud in less than 12 months, including over 100 terabytes from more than 2,500 sources.

• Unlock data’s value: Immuta helps organizations get access to more data 100x faster, which translates to improved productivity. An Immuta customer, Thomson Reuters enabled faster access to data, resulting in a 60x increase in data usage and greater productivity.

How does Immuta do it?

Immuta provides three modules to create a full data security platform suite.

Sensitive data discovery and classification: Immuta Discover

Discover sensitive data from millions of fields without manual effort. With over 60 pre-built and domain-specific identifiers, you can tailor data classification to your unique business needs based on your desired confidence level.

Continuous data security monitoring: Immuta Detect

Leverage timely insights into data access and user activity with anomaly indicators for faster analysis and proactive actions.

Data security and access control: Immuta Secure

Immuta’s attribute-based access control (ABAC) delivers scalable data access without role explosion, and dynamic data masking ensures the right users can access the right data.

How to get started

After installing Immuta, begin with Immuta Detect. This section will guide you through Immuta configuration and leverage the capabilities of Immuta Discover to provide insights into where you have gaps in security and a complete understanding of your data ecosystem.

From there, you can move on to Immuta Secure to mitigate (and constantly mitigate) those findings from Immuta Detect. This section includes three separate use cases, which are common across customers and includes recommendations for how to best solve those use cases. Consult the use cases to determine which path is best for you.

The guides in this section illustrate how to install and deploy Immuta in your Kubernetes environment. 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

• Immuta in an air-gapped environment

This guide demonstrates how to configure TLS termination for an Ingress resource.

Prerequisite

The Ingress configuration must be completed before proceeding.

Ingress-NGINX Controller

1. Edit immuta-values.yaml to include the following Helm values.

2. Create a TLS secret from a given public/private PEM formatted key pair.

3. Perform a Helm upgrade to apply the changes made to immuta-values.yaml.

Refer to the Ingress-Nginx Controller documentation for further assistance.

GKE Ingress Controller

1. Edit immuta-values.yaml to include the following Helm values.

2. Perform a Helm upgrade to apply the changes made to immuta-values.yaml.

Refer to the GKE Ingress Controller documentation for further assistance.

AWS Load Balancer Controller

1. Edit immuta-values.yaml to include the following Helm values.

2. Perform a Helm upgrade to apply the changes made to immuta-values.yaml.

Refer to the AWS Load Balancer Controller documentation for further assistance.

AKS Application Gateway Ingress Controller

1. Edit immuta-values.yaml to include the following Helm values.

2. Perform a Helm upgrade to apply the changes made to immuta-values.yaml.

Refer to the Application Gateway Ingress Controller documentation for further assistance.

Traefik

1. Edit immuta-values.yaml to include the following Helm values.

2. Create a TLS secret from a given public/private PEM formatted key pair.

3. Perform a Helm upgrade to apply the changes made to immuta-values.yaml.

Refer to the Traefik documentation for further assistance.

This guide demonstrates how to configure an external key-value cache (such as Redis or Memcached) with the Immuta Enterprise Helm chart (IEHC).

Prerequisite

The Immuta in production guide must be completed before proceeding.

Redis

1. Edit secret immuta-secret that was created in the Immuta in production guide.

2. Add key-value IMMUTA_SERVER_CACHE_PROVIDER_OPTIONS_PASSWORD: <cache-password>.

Edit Helm values

Edit the immuta-values.yaml file to include the relevant Helm values listed below. Update all placeholder values with your own values.

Redis

Memcached

Apply Helm values

Perform a Helm upgrade to apply the changes made to immuta-values.yaml.

This guide demonstrates how to configure a private container registry with the Immuta Enterprise Helm chart (IEHC).

Helm values

1. Examine the default Helm values in the chart; this will include all relevant values required to override the registry and images.

   Copy

   helm show values oci://ocir.immuta.com/stable/immuta-enterprise --version 2024.2.16

2. Edit the immuta-values.yaml to include the following Helm values. Update all placeholder values with your own values.

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

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

All application state is stored in the PostgreSQL metadata database; therefore, recovering from a disaster event only entails restoring the aforementioned PostgreSQL database. Consult each cloud provider's point-in-time recovery (PITR) documentation for guidance:

• Amazon RDS for PostgreSQL

• Azure Database for PostgreSQL

• Google Cloud SQL for PostgreSQL

For more details about point-in-time recovery, see the PostgreSQL documentation.

The following conventions are used throughout the installation material.

Angle brackets ( < and > )

Phrases wrapped in angle brackets (i.e., <, >) are placeholders used to indicate values that must be substituted with user-provided values. Placeholders are typically written in either kebab case, or snake case; the following placeholders are equivalent:

• <the-quick-brown-fox>

• <the_quick_brown_fox>

Example

Input

Output

Immuta Enterprise Helm chart

2024.2.0

Added

• Initial release of the chart.

2024.2.1

Changed

• Updated to 2024.2.1

Immuta integrates with your data platforms and external catalogs so you can register your data and effectively manage access controls on that data.

This section includes concept, reference, and how-to guides for configuring your data platform integration, registering data sources, and connecting your external catalog so that you can discover, monitor, and protect sensitive data.

Integrations

• Immuta integrations: This reference guide outlines the features, policies, and audit capabilities supported by each integration.

• Snowflake: This section includes how-to and reference guides for Snowflake and how it integrates with Immuta.

• Databricks Unity Catalog: This section includes how-to and reference guides for Databricks Unity Catalog and how it integrates with Immuta.

• Databricks Spark: This section includes how-to and reference guides for Databricks Spark and how it integrates with Immuta.

• Starburst (Trino): This section includes how-to and reference guides for Starburst (Trino) and how it integrates with Immuta.

• Redshift: This section includes how-to and reference guides for Redshift and how it integrates with Immuta.

• Azure Synapse Analytics: This section includes how-to and reference guides for Azure Synapse Analytics and how it integrates with Immuta.

• Amazon S3: This page includes how-to and reference content for Amazon S3 and how it integrates with Immuta.

• Google BigQuery: This page includes how-to and reference content for Google BigQuery and how it integrates with Immuta.

Registering data

This section covers concepts related to registering your data with Immuta.

Catalogs

This section covers the various data catalogs Immuta integrates with.

Tags

This section covers concepts related to tags and how to use them in Immuta.

To migrate from the private preview version of table grants (available before September 2022) to the GA version, complete the steps below.

1. Navigate to the App Settings page.

2. Click Integration Settings in the left panel, and scroll to the Global Integrations Settings section.

3. Uncheck the Snowflake Table Grants checkbox to disable the feature.

4. Click Save. Wait for about 1 minute per 1000 users. This gives time for Immuta to drop all the previously created user roles.

5. Use the Enable Snowflake table grants tutorial to re-enable the feature.

1. Click the App Settings icon in the sidebar and scroll to the Global Integration Settings section.

2. Click the Enable Snowflake Low Row Access Policy Mode checkbox to enable the feature.

3. Confirm to allow Immuta to automatically disable impersonation for the Snowflake integration. If you do not confirm, you will not be able to enable Snowflake low row access policy mode.

4. Click Save.

Configure your Snowflake integration

If you already have a Snowflake integration configured, you don't need to reconfigure your integration. Your Snowflake policies automatically refresh when you enable Snowflake low row access policy mode.

1. Configure your Snowflake integration. Note that you will not be able to enable project workspaces or user impersonation with Snowflake low row access policy mode enabled.

2. Click Save.

Prerequisites

This upgrade step is necessary if you meet both of the following criteria:

• You have the Snowflake low row access policy mode enabled in private preview.

• You have user impersonation enabled.

If you do not meet this criteria, follow the instructions on the configuration guide.

Upgrade to Snowflake low row access policy mode

To upgrade to the generally available version of the feature, disable your Snowflake integration on the app settings page and then re-enable it.

Immuta is compatible with Snowflake Secure Data Sharing. Using both Immuta and Snowflake, organizations can share the policy-protected data of their Snowflake database with other Snowflake accounts with Immuta policies enforced in real time. This integration gives data consumers a live connection to the data and relieves data providers of the legal and technical burden of creating static data copies that leave their Snowflake environment.

Requirements:

• Snowflake Enterprise Edition or higher

• Immuta's table grants feature

Configuration

This method requires that the data consumer account is registered as an Immuta user with the Snowflake user name equal to the consuming account.

At that point, the user that represents the account being shared with can have the appropriate attributes and groups assigned to them, relevant to the data policies that need to be enforced. Once that user has access to the share in the consuming account (not managed by Immuta), they can query the share with the data policies from the producer account enforced because Immuta is treating that account as if they are a single user in Immuta.

For a tutorial on this workflow, see the Using Snowflake Data Sharing page.

Benefits

Using Immuta with Snowflake Data Sharing allows the sharer to

• Only need limited knowledge of the context or goals of the existing policies in place: Because the sharer is not editing or creating policies to share their data, they only need a limited knowledge of how the policies work. Their main responsibility is making sure they properly represent the attributes of the data consumer (the account being shared to).

• Leave policies untouched.

While you're onboarding Snowflake data sources and designing policies, you don't want to disrupt your Snowflake users' existing workflows. Instead, you want to gradually onboard Immuta through a series of successive changes that will not impact your existing Snowflake users.

A phased onboarding approach to configuring the Snowflake integration ensures that your users will not be immediately affected by changes as you add data sources and configure policies.

Several features allow you to gradually onboard data sources and policies in Immuta:

• Subscription policy of “None” by default: By default, no policy is applied at registration time; instead of applying a restrictive policy immediately upon registration, the table is registered in Immuta and waits for a policy to be applied, if ever.

  There are several benefits to this design:

  • All existing roles maintain access to the data and registration of the table or view with Immuta has zero impact on your data platform.

  • It gives you time to configure tags on the Immuta registered tables and views, either manually or through automatic means, such as Immuta’s sensitive data detection (SDD), or an external catalog integration to include Snowflake tags.

  • It gives you time to assess and validate the sensitive data tags that were applied.

  • You can build only row and column controls with Immuta and let your existing roles manage table access instead of using Immuta subscription policies for table access.

• Snowflake table grants coupled with Snowflake low row access policy mode: With these features enabled, Immuta manages access to tables (subscription policies) through GRANTs. This works by assigning each user their own unique role created by Immuta and all table access is managed using that single role.

  Without these two features enabled, Immuta uses a Snowflake row access policy (RAP) to manage table access. A RAP only allows users to access rows in the table if they were explicitly granted access through an Immuta subscription policy; otherwise, the user sees no rows. This behavior means all existing Snowflake roles lose access to the table contents until explicitly granted access through Immuta subscription policies. Essentially, roles outside of Immuta don't control access anymore.

  By using table grants and the low row access policy mode, users and roles outside Immuta continue to work.

  There are two benefits to this approach:

  • All pre-existing Snowflake roles retain access to the data until you explicitly revoke access (outside Immuta).

  • It provides a way to test that Immuta GRANTs are working without impacting production workloads.

Requirements

The following configuration is required for phased Snowflake onboarding:

• Impersonation is disabled

• Project workspaces are disabled

If either of these capabilities is necessary for your use case, you cannot do phased Snowflake onboarding as described below.

Next

See the Getting started page for step-by-step guidance to implement phased Snowflake onboarding.

This integration allows you to manage and access data in your Databricks account across all of your workspaces. With Immuta’s Databricks Unity Catalog integration, you can write your policies in Immuta and have them enforced automatically by Databricks across data in your Unity Catalog metastore.

Getting started

This getting started guide outlines how to integrate Databricks Unity Catalog with Immuta.

How-to guides

• Databricks Unity Catalog configuration: Configure the Databricks Unity Catalog integration.

• Migrate to Databricks Unity Catalog: Migrate from the legacy Databricks integrations to the Databricks Unity Catalog integration.

Reference guide

Databricks Unity Catalog integration reference guide: This guide describes the design and components of the integration.

When you enable Unity Catalog, Immuta automatically migrates your existing Databricks data sources in Immuta to reference the legacy hive_metastore catalog to account for Unity Catalog's three-level hierarchy. New data sources will reference the Unity Catalog metastore you create and attach to your Databricks workspace.

Because the hive_metastore catalog is not managed by Unity Catalog, existing data sources in the hive_metastore cannot have Unity Catalog access controls applied to them. Data sources in the Hive Metastore must be managed by the Databricks Spark integration.

To allow Immuta to administer Unity Catalog access controls on that data, move the data to Unity Catalog and re-register those tables in Immuta by completing the steps below. If you don't move all data before configuring the integration, metastore magic will protect your existing data sources throughout the migration process.

1. Ensure that all Databricks clusters that have Immuta installed are stopped and the Immuta configuration is removed from the cluster. Immuta-specific cluster configuration is no longer needed with the Databricks Unity Catalog integration.

2. Move all data into Unity Catalog before configuring Immuta with Unity Catalog. Existing data sources will need to be re-created after they are moved to Unity Catalog and the Unity Catalog integration is configured.

3. Enable Unity Catalog.

The immuta database on Immuta-enabled clusters allows Immuta to track Immuta-managed data sources separately from remote Databricks tables so that policies and other security features can be applied. However, Immuta supports raw tables in Databricks, so table-backed queries do not need to reference this database. When configuring a Databricks cluster, you can hide immuta from any calls to SHOW DATABASES so that users are not confused or misled by that database.

Hide the immuta Database

When configuring a Databricks cluster, hide immuta by using the following environment variable in the Spark cluster configuration:

IMMUTA_SPARK_SHOW_IMMUTA_DATABASE=false

Then, Immuta will not show this database when a SHOW DATABASES query is performed.

This page outlines the configuration for setting up project UDFs, which allow users to set their current project in Immuta through Spark. For details about the specific functions available and how to use them, see the Use Project UDFs (Databricks) page.

Web Service and On-Cluster Caches

Immuta caches a mapping of user accounts and users' current projects in the Immuta Web Service and on-cluster. When users change their project with UDFs instead of the Immuta UI, Immuta invalidates all the caches on-cluster (so that everything changes immediately) and the cluster submits a request to change the project context to a web worker. Immediately after that request, another call is made to a web worker to refresh the current project.

To allow use of project UDFs in Spark jobs, raise the caching on-cluster and lower the cache timeouts for the Immuta Web Service. Otherwise, caching could cause dissonance among the requests and calls to multiple web workers when users try to change their project contexts.

Recommended Configuration

1 - Lower Web Service Cache Timeout

1. Click the App Settings icon in the left sidebar and scroll to the HDFS Cache Settings section.

2. Lower the Cache TTL of HDFS user names (ms) to 0.

3. Click Save.

2 - Raise Cache Timeout On-Cluster

In the Spark environment variables section, set the IMMUTA_CURRENT_PROJECT_CACHE_TIMEOUT_SECONDS and IMMUTA_PROJECT_CACHE_TIMEOUT_SECONDS to high values (like 10000).

Note: These caches will be invalidated on cluster when a user calls immuta.set_current_project, so they can effectively be cached permanently on cluster to avoid periodically reaching out to the web service.

Blocking UDFs

If your compliance requirements restrict users from changing projects within a session, you can block the use of Immuta's project UDFs on a Databricks Spark cluster. To do so, configure the immuta.spark.databricks.disabled.udfs option as described on the Databricks environment variables page.

Local or remote mode

Immuta supports the use of external metastores in local or remote mode , following the same configuration detailed in the Databricks documentation.

Configure external Hive metastore

Download the metastore jars and point to them as specified in Databricks documentation. Metastore jars must end up on the cluster's local disk at this explicit path: /databricks/hive_metastore_jars.

If using DBR 7.x with Hive 2.3.x, either

• Set spark.sql.hive.metastore.version to 2.3.7 and spark.sql.hive.metastore.jars to builtin or

• Download the metastore jars and set spark.sql.hive.metastore.jars to /databricks/hive_metastore_jars/* as before.

Configure AWS Glue Data Catalog

To use AWS Glue Data Catalog as the metastore for Databricks, see the Databricks documentation.

In this configuration, Immuta is able to rely on Databricks-native security controls, reducing overhead. The key security control here is the enablement of process isolation. This prevents users from obtaining unintentional access to the queries of other users. In other words, masked and filtered data is consistently made accessible to users in accordance with their assigned attributes. This Immuta cluster configuration relies on Py4J security being enabled.

Many Python ML classes (such as LogisticRegression, StringIndexer, and DecisionTreeClassifier) and dbutils.fs are unfortunately not supported with Py4J security enabled. Users will also be unable to use the Databricks Connect client library. Additionally, only Python and SQL are available as supported languages.

For full details on Databricks’ best practices in configuring clusters, please read their governance documentation.

In this configuration, you are able to rely on the Databricks-native security controls. The key security control here is the enablement of process isolation. This prevents users from obtaining unintentional access to the queries of other users. In other words, masked and filtered data is consistently made accessible to users in accordance with their assigned attributes.

Like the Python & SQL configuration, Py4j security is enabled for the Python & SQL & R configuration. However, because R has been added Immuta enables the SecurityManager, in addition to Py4j security, to provide more security guarantees. For example, by default all actions in R execute as the root user; among other things, this permits access to the entire filesystem (including sensitive configuration data), and, without iptable restrictions, a user may freely access the cluster’s cloud storage credentials. To address these security issues, Immuta’s initialization script wraps the R and Rscript binaries to launch each command as a temporary, non-privileged user with limited filesystem and network access and installs the Immuta SecurityManager, which prevents users from bypassing policies and protects against the above vulnerabilities from within the JVM.

Consequently, the cost of introducing R is that the SecurityManager incurs a small increase in performance overhead; however, average latency will vary depending on whether the cluster is homogeneous or heterogeneous. (In homogeneous clusters, all users are at the same level of groups/authorizations; this is enforced externally, rather than directly by Immuta.)

Many Python ML classes (such as LogisticRegression, StringIndexer, and DecisionTreeClassifier) and dbutils.fs are unfortunately not supported with Py4J security enabled. Users will also be unable to use the Databricks Connect client library.

When users install third-party Java/Scala libraries, they will be denied access to sensitive resources by default. However, cluster administrators can specify which of the installed Databricks libraries should be trusted by Immuta.

For full details on Databricks’ best practices in configuring clusters, please read their governance documentation.

This configuration does not rely on Databricks-native Py4j security to secure the cluster, while process isolation is still enabled to secure filesystem and network access from within Python processes. On an Immuta-enabled cluster, once Py4J security is disabled the Immuta SecurityManager is installed to prevent nefarious actions from Python in the JVM. Disabling Py4J security also allows for expanded Python library support, including many Python ML classes (such as LogisticRegression, StringIndexer, and DecisionTreeClassifier) and dbutils.fs.

By default, all actions in R will execute as the root user. Among other things, this permits access to the entire filesystem (including sensitive configuration data). And without iptable restrictions, a user may freely access the cluster’s cloud storage credentials. To properly support the use of the R language, Immuta’s initialization script wraps the R and Rscript binaries to launch each command as a temporary, non-privileged user. This user has limited filesystem and network access. The Immuta SecurityManager is also installed to prevent users from bypassing policies and protects against the above vulnerabilities from within the JVM.

The SecurityManager will incur a small increase in performance overhead; average latency will vary depending on whether the cluster is homogeneous or heterogeneous. (In homogeneous clusters, all users are at the same level of groups/authorizations; this is enforced externally, rather than directly by Immuta.)

When users install third-party Java/Scala libraries, they will be denied access to sensitive resources by default. However, cluster administrators can specify which of the installed Databricks libraries should be trusted by Immuta.

A homogeneous cluster is recommended for configurations where Py4J security is disabled. If all users have the same level of authorization, there would not be any data leakage, even if a nefarious action was taken.

For full details on Databricks’ best practices in configuring clusters, please read their governance documentation.

Where Scala language support is needed, this configuration can be used in the Custom access mode.

According to Databricks’ cluster type support documentation, Scala clusters are intended for single users only. However, nothing inherently prevents a Scala cluster from being configured for multiple users. Even with the Immuta SecurityManager enabled, there are limitations to user isolation within a Scala job.

For a secure configuration, it is recommended that clusters intended for Scala workloads are limited to Scala jobs only and are made homogeneous through the use of project equalization or externally via convention/cluster ACLs. (In homogeneous clusters, all users are at the same level of groups/authorizations; this is enforced externally, rather than directly by Immuta.)

For full details on Databricks’ best practices in configuring clusters, please read their governance documentation.

Overview

In Immuta, a Databricks data source is considered ephemeral, meaning that the compute resources associated with that data source will not always be available.

Ephemeral data sources allow the use of ephemeral overrides, user-specific connection parameter overrides that are applied to Immuta metadata operations.

When a user runs a Spark job in Databricks, Immuta plugins automatically submit ephemeral overrides for that user to Immuta for all applicable data sources to use the current cluster as compute for all subsequent metadata operations for that user against the applicable data sources.

Example Query and Ephemeral Override Request

1. A user runs a query on cluster B.

2. The Immuta plugins on the cluster check if there is a source in the Metastore with a matching database, table name, and location for its underlying data. Note: If tables are dynamic or change over time, users can disable the comparison of the location of the underlying data by setting immuta.ephemeral.table.path.check.enabled to false; disabling this configuration allows users to avoid keeping the relevant data sources in Immuta up-to-date (which would require API calls and automation).

3. The Immuta plugins on the cluster detect that the user is subscribed to data sources 1, 2, and 3 and that data sources 1 and 3 are both present in the Metastore for cluster B, so the plugins submit ephemeral override requests for data sources 1 and 3 to override their connections with the HTTP path from cluster B.

4. Since data source 2 is not present in the Metastore, it is marked as a JDBC source.

If the user attempts to query data source 2 and they have not enabled JDBC sources, they will be presented with an error message telling them to do so:

com.immuta.spark.exceptions.ImmutaConfigurationException: This query plan will cause data to be pulled over JDBC. This spark context is not configured to allow this. To enable JDBC set immuta.enable.jdbc=true in the spark context hadoop configuration.

Immuta Operations that Use Ephemeral Overrides

Ephemeral overrides are enabled by default because Immuta must be aware of a cluster that is running to serve metadata queries. The operations that use the ephemeral overrides include

• Visibility checks on the data source for a particular user. These checks assess how to apply row-level policies for specific users.

• Stats collection triggered by a specific user.

• Validating a custom WHERE clause policy against a data source. When owners or governors create custom WHERE clause policies, Immuta uses compute resources to validate the SQL in the policy. In this case, the ephemeral overrides for the user writing the policy are used to contact a cluster for SQL validation.

• High Cardinality Column detection. Certain advanced policy types (e.g., minimization and randomized response) in Immuta require a High Cardinality Column, and that column is computed on data source creation. It can be recomputed on demand and, if so, will use the ephemeral overrides for the user requesting computation.

However, ephemeral overrides can be problematic in environments that have a dedicated cluster to handle maintenance activities, since ephemeral overrides can cause these operations to execute on a different cluster than the dedicated one.

Configure Overrides in Immuta-Enabled Clusters

To reduce the risk that a user has overrides set to a cluster (or multiple clusters) that aren't currently up,

• direct all clusters' HTTP paths for overrides to a cluster dedicated for metadata queries or

• disable overrides completely.

Disable Ephemeral Overrides

To disable ephemeral overrides, set immuta.ephemeral.host.override in spark-defaults.conf to false.

• Error Message: py4j.security.Py4JSecurityException: Constructor <> is not whitelisted

• Explanation: This error indicates you are being blocked by Py4j security rather than the Immuta Security Manager. Py4j security is strict and generally ends up blocking many ML libraries.

• Solution: Turn off Py4j security on the offending cluster by setting IMMUTA_SPARK_DATABRICKS_PY4J_STRICT_ENABLED=false in the environment variables section. Additionally, because there are limitations to the security mechanisms Immuta employs on-cluster when Py4j security is disabled, ensure that all users on the cluster have the same level of access to data, as users could theoretically see (policy-enforced) data that other users have queried.

It is most secure to leverage an equalized project when working in a Scala cluster; however, it is not required to limit Scala to equalized projects. This document outlines security recommendations for Scala clusters and discusses the security risks involved when equalized projects are not used.

Recommendations

There are limitations to isolation among users in Scala jobs on a Databricks cluster, even when using Immuta’s SecurityManager. When data is broadcast, cached (spilled to disk), or otherwise saved to SPARK_LOCAL_DIR, it's impossible to distinguish between which user’s data is composed in each file/block. If you are concerned about this vulnerability, Immuta suggests that Scala clusters

• be limited to Scala jobs only.

• use project equalization, which forces all users to act under the same set of attributes, groups, and purposes with respect to their data access.

Context for Security: Why Project Equalization is Recommended

When data is read in Spark using an Immuta policy-enforced plan, the masking and redaction of rows is performed at the leaf level of the physical Spark plan, so a policy such as "Mask using hashing the column social_security_number for everyone" would be implemented as an expression on a project node right above the FileSourceScanExec/LeafExec node at the bottom of the plan. This process prevents raw data from being shuffled in a Spark application and, consequently, from ending up in SPARK_LOCAL_DIR.

This policy implementation coupled with an equalized project guarantees that data being dropped into SPARK_LOCAL_DIR will have policies enforced and that those policies will be homogeneous for all users on the cluster. Since each user will have access to the same data, if they attempt to manually access other users' cached/spilled data, they will only see what they have access to via equalized permissions on the cluster. If project equalization is not turned on, users could dig through that directory and find data from another user with heightened access, which would result in a data leak.

Configuration for Requiring Equalized Projects with Scala

To require that Scala clusters be used in equalized projects and avoid the risk described above, change the immuta.spark.require.equalization value to true in your Immuta configuration file when you spin up Scala clusters:

Once this configuration is complete, users on the cluster will need to switch to an Immuta equalized project before running a job. (Remember that when working under an Immuta Project, only tables within that project can be seen.) Once the first job is run using that equalized project, all subsequent jobs, no matter the user, must also be run under that same equalized project. If you need to change a cluster's project, you must restart the cluster.

This page describes how the Security Manager is disabled for Databricks clusters that do not allow R or Scala code to be executed. Databricks Administrators should place the desired configuration in the Spark environment variables (recommended) or immuta_conf.xml (not recommended).

Automatic Disabling of the Security Manager

The Immuta Security Manager is an essential element of the Databricks deployment that ensures users can't perform unauthorized actions when using Scala and R, since those languages have features that allow users to circumvent policies without the Security Manager enabled. However, the Security Manager must inspect the call stack every time a permission check is triggered, which adds overhead to queries. To improve Immuta's query performance on Databricks, Immuta disables the Security Manager when Scala and R are not being used.

The cluster init script checks the cluster’s configuration and automatically removes the Security Manager configuration when

• spark.databricks.repl.allowedlanguages is a subset of {python, sql}

• IMMUTA_SPARK_DATABRICKS_PY4J_STRICT_ENABLED is true

When the cluster is configured this way, Immuta can rely on Databricks' process isolation and Py4J security to prevent user code from performing unauthorized actions.

Note: Immuta still expects the spark.driver.extraJavaOptions and spark.executor.extraJavaOptions to be set and pointing at the Security Manager.

Beyond disabling the Security Manager, Immuta will skip several startup tasks that are required to secure the cluster when Scala and R are configured, and fewer permission checks will occur on the Driver and Executors in the Databricks cluster, reducing overhead and improving performance.

Caveats

• There are still cases that require the Security Manager; in those instances, Immuta creates a fallback Security Manager to check the code path, so the IMMUTA_INIT_ALLOWED_CALLING_CLASSES_URI environment variable must always point to a valid calling class file.

• Databricks’ dbutils.fs is blocked by their PY4J security; therefore, it can’t be used to access scratch paths.

CDF shows the row-level changes between versions of a Delta table. The changes displayed include row data and metadata that indicates whether the row was inserted, deleted, or updated.

Immuta does not support applying policies to the changed data, and the CDF cannot be read for data source tables if the user does not have access to the raw data in Databricks. However, the CDF can be read if the querying user is allowed to read the raw data and one of the following statements is true:

• the table is in the current workspace,

• the table is in a scratch path,

• non-Immuta reads are enabled AND the table does not intersect with a workspace under which the current user is not acting, or

• non-Immuta reads are enabled AND the table is not part of an Immuta data source.

Configure Change Data Feed

There are no configuration changes necessary to use this feature.

Limitation

Immuta does not support reading changes in streaming queries.

In this integration, Immuta policies are translated into Starburst rules and permissions and applied directly to tables within users’ existing catalogs.

Getting started

This guide outlines how to integrate Starburst with Immuta.

How-to guides

• Starburst (Trino) integration configuration guide: Configure the integration in Immuta.

• Map read and write access policies to Starburst (Trino) privileges: Configure how read and write access subscription policies translate to Starburst (Trino) privileges and apply to Starburst (Trino) data sources.

Reference guide

Starburst (Trino) integration reference guide: This guide describes the design and components of the integration.

In this integration, Immuta generates policy-enforced views in your configured Redshift schema for tables registered as Immuta data sources.

Getting started

This guide outlines how to integrate Redshift with Immuta.

How-to guides

• Redshift integration configuration: Configure the integration in Immuta.

• Redshift Spectrum configuration: Configure Redshift Spectrum in Immuta.

Reference guide

Redshift integration reference guide: This guide describes the design and components of the integration.

This section illustrates how to install Immuta on Kubernetes using the Immuta Enterprise Helm chart.

Getting started

This how-to guide includes instructions and links for installing Immuta in any Kubernetes environment.

Requirements

This reference guide provides an overview of the Immuta Enterprise Helm chart version requirements and infrastructure recommendations.

Install

The guides in this section illustrate how to install and deploy Immuta in your Kubernetes environment. 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)

Configure

The guides in this section illustrate how to configure your Immuta Enterprise Helm chart for various scenarios, including optimizing your deployment for production environments.

Upgrade

The guides in this section illustrate how to upgrade the Immuta Enterprise Helm chart:

• Upgrading to Immuta v2024.2 LTS: Upgrade from Immuta v2024.1.x or older to Immuta v2024.2 LTS.

• Upgrade Immuta: Upgrade from Immuta v2024.2 LTS or newer.

Disaster recovery

This guide provides links to additional resources for disaster recovery strategies.

Troubleshooting

This page provides troubleshooting guidance and outlines frequently asked questions for the Immuta installation.

Release notes

This guide outlines the updates and bug fixes to the Immuta Enterprise Helm chart.

The instructions and how-to guides on this page illustrate how to install Immuta in your Kubernetes environment. If you are upgrading Immuta, navigate to the Upgrade section instead.

Prerequisites and requirements

• Use a supported version of Kubernetes.

• Use Helm 3.2.0 or newer (When using a Helm version older than 3.8.0, enable OCI experimental mode by exporting environment variable HELM_EXPERIMENTAL_OCI=1.)

• Deploy the services listed on the Deployment requirements guide. See the recommendations table for guidance for specific cloud providers.

• Grant RBAC permissions to create Kubernetes resources in the cluster.

Pull the Helm chart

Consult the upgrade overview if unsure which Helm chart to use.

ocir.immuta.com

Copy the snippet below and replace the placeholder text with the credentials provided to you by your Immuta support professional:

echo <token> | helm registry login --password-stdin --username <username> ocir.immuta.com

Install Immuta

Immuta can be installed on any Kubernetes cluster. Select a guide below that corresponds to your Kubernetes distribution to install Immuta. 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)

Configure Ingress

To complete your installation and access the Immuta application, configure Ingress.

Additional recommendations

The configure section includes guidance for various scenarios you may encounter during and post-deployment. Below are several guides from that section that most customers follow to complete their deployment of Immuta, but none of these is a requirement for the Immuta installation to work.

• TLS configuration: Secure your Ingress by specifying a Secret that contains a TLS private key and certificate.

• Immuta in production: Follow these best practices for configuring your deployment for a production environment.

• External cache configuration: The Immuta Enterprise Helm chart manages its own Memcached deployment inside the cluster. However, you can opt to externalize the key-value cache post-installation.

Immuta comprises three core services (Secure, Discover, and Detect) that rely on PostgreSQL and Elasticsearch to store their states. The illustration below shows the relationships among these services.

The Immuta Enterprise Helm chart (IEHC) (represented by the yellow box above) does not deploy PostgreSQL or Elasticsearch, so you must deploy and manage them separately.

Although Immuta recommends using Elasticsearch because it supports several new Immuta features and services, you can deploy Immuta without Elasticsearch. The table below outlines the Immuta features supported with and without Elasticsearch and the dependencies you must deploy and manage yourself.

For guidance on how to configure the IEHC to deploy Immuta with or without Elasticsearch, see one of the guides below:

• Deploy Immuta with Elasticsearch

• Deploy Immuta without Elasticsearch

For more information about legacy features and services no longer enabled in the recommended deployment of Immuta, see the Legacy features and services section.

Version requirements

Kubernetes versions

• Kubernetes 1.29 to 1.32

Metadata database (PostgreSQL)

• PostgreSQL 15.0 or newer

• The pgcrypto extension must be enabled

Elasticsearch

• Elasticsearch v7 API or newer

• AWS OpenSearch Service compatible with Elasticsearch v7 API or newer

  • AWS OpenSearch Serverless is not supported

OpenSearch user

The user provided during the install must have the following permissions:

• cluster:monitor/health

• indices:data/write/bulk*

• indices:data/write/bulk

• indices:data/read/search

• indices:admin/exists

• indices:admin/create

• indices:admin/delete

• indices:admin/settings/update

• indices:admin/get

• indices:data/write/delete/byquery

• indices:data/write/index

• indices:admin/mapping/put

• indices:data/write/bulk

• indices:data/write/bulk*

Follow OpenSearch documentation to create the user and add permissions.

Cache (Redis/Memcached)

• Redis 7.0 or newer

• Memcached 1.6 or newer

Infrastructure recommendations

Legacy features and services

Some legacy services and features are no longer enabled in the recommended configuration of the IEHC. The table below lists these features and provides links to documentation that outlines how to enable them in Immuta.

Next step

Follow the Getting started guide to install Immuta.

This is a guide on how to deploy Immuta on Kubernetes in the following managed public cloud providers:

• Amazon Web Services (AWS)

• Microsoft Azure

• Google Cloud Platform (GCP)

Prerequisites

The following cloud-managed services must be provisioned before proceeding:

Validation

PostgreSQL

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

2. The PostgreSQL instance is accepting connections.

3. The Helm chart only supports username/password authentication for PostgreSQL. At this time, other authentication mechanisms are not supported.

Elasticsearch

1. The Elasticsearch instance's hostname/FQDN is resolvable from within the Kubernetes cluster.

2. The Elasticsearch instance is accepting connections.

3. The user must have the required permissions.

4. The Helm chart only supports username/password authentication for Elasticsearch. At this time, other authentication mechanisms are not supported.

Authenticate with OCI registry

Copy the snippet below and replace the placeholder text with the credentials provided to you by your customer success manager:

echo <token> | helm registry login --password-stdin --username <username> ocir.immuta.com

Setup

1. Create a Kubernetes namespace named immuta for Immuta.

   Copy

   kubectl create namespace immuta

2. Switch to namespace immuta.

   Copy

   kubectl config set-context --current --namespace=immuta

3. Create a container registry pull secret. Your credentials to authenticate with ocir.immuta.com can be viewed in your user profile at support.immuta.com.

   Copy

   kubectl create secret docker-registry immuta-oci-registry \
       --docker-server=https://ocir.immuta.com \
       --docker-username="<username>" \
       --docker-password="<token>" \
       [email protected]

PostgreSQL

1. Connect to the database as superuser (postgres) by creating an ephemeral container inside the Kubernetes cluster. A shell prompt will not be displayed after executing the kubectl run command outlined below. Wait 5 seconds, and then proceed by entering a password.

   Copy

   kubectl run pgclient \
       --stdin \
       --tty \
       --rm \
       --image docker.io/bitnami/postgresql -- \
       psql --host <postgres-fqdn> --username <postgres-admin> --dbname postgres --port 5432 --password

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

3. Revoke privileges from CURRENT_USER as they're no longer required.

4. Enable the pgcrypto extension.

5. Type \q, and then press Enter to exit.

Install Immuta

This section demonstrates how to deploy Immuta using the Immuta Enterprise Helm chart once the prerequisite cloud-managed services are configured.

1. Create a Helm values file named immuta-values.yaml with the following content:

   Copy

   global:
     imageRegistry: ocir.immuta.com
     imagePullSecrets:
       - name: immuta-oci-registry
     imageRepositoryMap:
       immuta/immuta-service: stable/immuta-service
       immuta/immuta-db: stable/immuta-db
       immuta/immuta-fingerprint: stable/immuta-fingerprint
       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:
     ingress:
       enabled: false
       tls: false
     extraEnvVars:
       - name: FeatureFlag_AuditService
         value: "true"
       - name: FeatureFlag_detect
         value: "true"
       - name: FeatureFlag_auditLegacyViewHide
         value: "true"
   
     postgresql:
       host: <postgres-fqdn>
       port: 5432
       database: immuta
       username: immuta
       password: <postgres-password>
       ssl: true

2. Update all placeholder values in the immuta-values.yaml file.

1. Deploy Immuta.

   Copy

   helm install immuta oci://ocir.immuta.com/stable/immuta-enterprise \
       --values immuta-values.yaml \
       --version 2024.2.20

Validation

1. Wait for all pods in the namespace to become ready.

   Copy

   kubectl wait --for=condition=Ready pods --all

2. Determine the name of the Secure service.

   Copy

   kubectl get service --selector "app.kubernetes.io/component=secure" --output name

3. Listen on local port 8080, forwarding TCP traffic to the Secure service's port named http.

   Copy

   kubectl port-forward service/<name> 8080:http

Next steps

This is an OpenShift-specific guide on how to deploy Immuta with the following managed services:

• Cloud-managed PostgreSQL

• Cloud-managed Redis

• Cloud-managed Elasticsearch

Prerequisites

Review the following criteria before proceeding with deploying Immuta.

PostgreSQL

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.

4. The Helm chart only supports username/password authentication for PostgreSQL. At this time, other authentication mechanisms are not supported.

Redis

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

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

3. The Redis instance is accepting connections.

Elasticsearch

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

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

3. The Elasticsearch instance is accepting connections.

4. The user must have the .

5. The Helm chart only supports username/password authentication for Elasticsearch. At this time, other authentication mechanisms are not supported.

Authenticate with OCI registry

Copy the snippet below and replace the placeholder text with the credentials provided to you by your customer success manager:

echo <token> | helm registry login --password-stdin --username <username> ocir.immuta.com

Setup

1. Create a new OpenShift project named immuta for Immuta.

   Copy

   oc new-project immuta

2. Get the UID range allocated to the project. Each running container's UID must fall within this range. This value will be referenced later on.

   Copy

   oc get project immuta --output template='{{index .metadata.annotations "openshift.io/sa.scc.uid-range"}}{{"\n"}}'

3. Get the GID range allocated to the project. Each running container's GID must fall within this range. This value will be referenced later on.

   Copy

   oc get project immuta --output template='{{index .metadata.annotations "openshift.io/sa.scc.supplemental-groups"}}{{"\n"}}'

4. Switch to project immuta.

5. Create a container registry pull secret. Your credentials to authenticate with ocir.immuta.com can be viewed in your user profile at .

Cloud-managed PostgreSQL

1. Connect to the database as superuser (postgres) by creating an ephemeral container inside the Kubernetes cluster. A shell prompt will not be displayed after executing the oc run command outlined below. Wait 5 seconds, and then proceed by entering a password.

   Copy

   oc run pgclient \
       --stdin \
       --tty \
       --rm \
       --image docker.io/bitnami/postgresql -- \
       psql --host <postgres-fqdn> --username <postgres-admin> --dbname postgres --port 5432 --password

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

3. Revoke privileges from CURRENT_USER as they're no longer required.

4. Enable the pgcrypto extension.

5. Type \q, and then press Enter to exit.

Install Immuta

This section demonstrates how to deploy Immuta using the Immuta Enterprise Helm chart once the prerequisite cloud-managed services are configured.

1. Create a Helm values file named immuta-values.yaml with the content below. Because the Ingress resource will be managed by an OpenShift route you will create when configuring Ingress and not the Immuta Enterprise Helm chart, ingress is set to false below. TLS comes pre-configured with OpenShift, so tls is also set to false.

   Copy

   global:
     imageRegistry: ocir.immuta.com
     imagePullSecrets:
       - name: immuta-oci-registry
     imageRepositoryMap:
       immuta/immuta-service: stable/immuta-service
       immuta/immuta-db: stable/immuta-db
       immuta/immuta-fingerprint: stable/immuta-fingerprint
       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>@pg-db-postgresql.immuta.svc.cluster.local:5432/immuta?schema=audit
       elasticsearchEndpoint: http://es-db-elasticsearch.immuta.svc.cluster.local:9200
       elasticsearchUsername: <elasticsearch-username>
       elasticsearchPassword: <elasticsearch-password>
   
     deployment:
       podSecurityContext:
         # A number that is within the project range:
         #   oc get project <project-name> --output template='{{index .metadata.annotations "openshift.io/sa.scc.uid-range"}}{{"\n"}}'
         runAsUser: <user-id>
         # A number that is within the project range:
         #   oc get project <project-name> --output template='{{index .metadata.annotations "openshift.io/sa.scc.supplemental-groups"}}{{"\n"}}'
         runAsGroup: <group-id>
         seccompProfile:
           type: RuntimeDefault
         
       containerSecurityContext:
         allowPrivilegeEscalation: false
         capabilities:
           drop:
             - ALL
   
   discover:
     deployment:
       podSecurityContext:
         # A number that is within the project range:
         #   oc get project <project-name> --output template='{{index .metadata.annotations "openshift.io/sa.scc.uid-range"}}{{"\n"}}'
         runAsUser: <user-id>
         # A number that is within the project range:
         #   oc get project <project-name> --output template='{{index .metadata.annotations "openshift.io/sa.scc.supplemental-groups"}}{{"\n"}}'
         runAsGroup: <group-id>
         seccompProfile:
           type: RuntimeDefault
         
       containerSecurityContext:
         allowPrivilegeEscalation: false
         capabilities:
           drop:
             - ALL
   
   secure:
     extraEnvVars:
       - name: FeatureFlag_AuditService
         value: "true"
       - name: FeatureFlag_detect
         value: "true"
       - name: FeatureFlag_auditLegacyViewHide
         value: "true"
   
     ingress:
       enabled: false
       tls: false
   
     postgresql:
       host: <postgres-fqdn>
       port: 5432
       database: immuta
       username: immuta
       password: <postgres-password>
       ssl: false
   
     web:
       podSecurityContext:
         # A number that is within the project range:
         #   oc get project <project-name> --output template='{{index .metadata.annotations "openshift.io/sa.scc.uid-range"}}{{"\n"}}'
         runAsUser: <user-id>
         # A number that is within the project range:
         #   oc get project <project-name> --output template='{{index .metadata.annotations "openshift.io/sa.scc.supplemental-groups"}}{{"\n"}}'
         runAsGroup: <group-id>
         seccompProfile:
           type: RuntimeDefault
         
       containerSecurityContext:
         allowPrivilegeEscalation: false
         capabilities:
           drop:
             - ALL
   
     backgroundWorker:
       podSecurityContext:
         # A number that is within the project range:
         #   oc get project <project-name> --output template='{{index .metadata.annotations "openshift.io/sa.scc.uid-range"}}{{"\n"}}'
         runAsUser: <user-id>
         # A number that is within the project range:
         #   oc get project <project-name> --output template='{{index .metadata.annotations "openshift.io/sa.scc.supplemental-groups"}}{{"\n"}}'
         runAsGroup: <group-id>
         seccompProfile:
           type: RuntimeDefault
         
       containerSecurityContext:
         allowPrivilegeEscalation: false
         capabilities:
           drop:
             - ALL

2. Update all placeholder values in the immuta-values.yaml file.

1. Deploy Immuta.

   Copy

   helm install immuta oci://ocir.immuta.com/stable/immuta-enterprise \
       --values immuta-values.yaml \
       --version 2024.2.20

Validation

1. Wait for all pods in the namespace to become ready.

   Copy

   oc wait --for=condition=Ready pods --all

2. Determine the name of the Secure service.

   Copy

   oc get service --selector "app.kubernetes.io/component=secure" --output name

3. Listen on local port 8080, forwarding TCP traffic to the Secure service's port named http.

   Copy

   oc port-forward service/<name> 8080:http

Next steps

• Configure Ingress to complete your installation and access your Immuta application.

• Learn more about best practices for Immuta in Production.

This is a generic guide that demonstrates how to deploy Immuta into any Kubernetes cluster without dependencies on any particular cloud provider.

Considerations

For the purposes of this guide, the following state stores are deployed in Kubernetes using third-party Helm charts maintained by Bitnami:

• Elasticsearch

• PostgreSQL

• Operational overhead: Managing PostgreSQL and Elasticsearch on Kubernetes requires expertise in deploying, maintaining, and scaling these databases and search engines effectively. This involves tasks like setting up monitoring, configuring backups, managing updates, and ensuring high availability. Cloud-managed services abstract much of this operational burden away, allowing teams to focus on application development rather than infrastructure management.

• Resource allocation and scaling: Kubernetes requires careful resource allocation and scaling decisions to ensure that PostgreSQL and Elasticsearch have sufficient CPU, memory, and storage. Properly sizing these resources can be challenging and may require continuous adjustments as workload patterns change. Managed services typically handle this scaling transparently and can automatically adjust based on demand.

• Data integrity and high availability: PostgreSQL and Elasticsearch deployments need robust strategies for data integrity and high availability. Kubernetes can facilitate high availability through pod replicas and distributed deployments, but ensuring data consistency and durability across database instances and search indexes requires careful consideration and often additional tooling.

• Performance: Kubernetes networking and storage configurations can introduce performance overhead compared to native cloud services. For latency-sensitive applications or high-throughput workloads, these factors become critical in maintaining optimal performance.

• Observability: Troubleshooting issues in a Kubernetes environment, especially related to database and search engine performance, can be complex. Managed services typically come with built-in monitoring, logging, and alerting capabilities tailored to the specific service, making it easier to identify and resolve issues.

• Security and compliance: Kubernetes environments require careful attention to security best practices, including network policies, access controls, and encryption. Managed services often come pre-configured with security features and compliance certifications, reducing the burden on teams to implement and maintain these measures.

Authenticate with OCI registry

Copy the snippet below and replace the placeholder text with the credentials provided to you by your customer success manager:

echo <token> | helm registry login --password-stdin --username <username> ocir.immuta.com

Setup

1. Create a Kubernetes namespace named immuta for Immuta and its third-party dependencies.

   Copy

   kubectl create namespace immuta

2. Switch to namespace immuta.

   Copy

   kubectl config set-context --current --namespace=immuta

3. Create a container registry pull secret. Your credentials to authenticate with ocir.immuta.com can be viewed in your user profile at support.immuta.com.

   Copy

   kubectl create secret docker-registry immuta-oci-registry \
       --docker-server=https://ocir.immuta.com \
       --docker-username="<username>" \
       --docker-password="<token>" \
       [email protected]

Elasticsearch

1. Create a Helm values file named es-values.yaml with the following content:

   Copy

   master:
       masterOnly: false
       replicaCount: 1
   
   data:
       replicaCount: 0
   
   coordinating:
       replicaCount: 0
   
   ingest:
       replicaCount: 0

2. Deploy Elasticsearch.

   Copy

   helm install es-db oci://registry-1.docker.io/bitnamicharts/elasticsearch \
       --values es-values.yaml

PostgreSQL

1. Create a Helm values file named pg-values.yaml with the following content:

   Copy

   auth:
       database: immuta
       username: immuta
       password: <postgres-password>

2. Update all placeholder values in the pg-values.yaml file.

3. Deploy PostgreSQL.

   Copy

   helm install pg-db oci://registry-1.docker.io/bitnamicharts/postgresql \
       --values pg-values.yaml

4. Wait for all pods in the namespace to become ready.

5. Determine the name of the PostgreSQL database pod. This will be referenced in a subsequent step.

6. Exec into the PostgreSQL database pod using the psql command and immuta user to configure the PostgreSQL user used by Immuta.

7. Alter the search_path for the immuta user.

8. Enable the pgcrypto extension.

9. Type \q then press Enter to exit.

Install Immuta

This section demonstrates how to deploy Immuta using the Immuta Enterprise Helm chart once the prerequisite local services are configured.

1. Create a Helm values file named immuta-values.yaml with the following content:

   Copy

   global:
     imageRegistry: ocir.immuta.com
     imagePullSecrets:
       - name: immuta-oci-registry
     imageRepositoryMap:
       immuta/immuta-service: stable/immuta-service
       immuta/immuta-db: stable/immuta-db
       immuta/immuta-fingerprint: stable/immuta-fingerprint
       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:
       # Each Kubernetes Service has a DNS record associated with it. See: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/
       # The anatomy of a domain name is as follows:
       #   <service>.<namespace>.svc.<cluster-domain>
       #
       # Where the default cluster domain is: cluster.local
       databaseConnectionString: postgres://immuta:<postgres-password>@pg-db-postgresql.immuta.svc.cluster.local:5432/immuta?schema=audit
       elasticsearchEndpoint: http://es-db-elasticsearch.immuta.svc.cluster.local:9200
       elasticsearchUsername: <elasticsearch-username>
       elasticsearchPassword: <elasticsearch-password>
   
   secure:
     ingress:
       enabled: false
     extraEnvVars:
       - name: FeatureFlag_AuditService
         value: "true"
       - name: FeatureFlag_detect
         value: "true"
       - name: FeatureFlag_auditLegacyViewHide
         value: "true"
   
     postgresql:
       # Each Kubernetes Service has a DNS record associated with it. See: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/
       # The anatomy of a domain name is as follows:
       #   <service>.<namespace>.svc.<cluster-domain>
       #
       # Where the default cluster domain is: cluster.local
       host: pg-db-postgresql.immuta.svc.cluster.local
       port: 5432
       database: immuta
       username: immuta
       password: <postgres-password>

2. Update all placeholder values in the immuta-values.yaml file.

1. Deploy Immuta.

   Copy

   helm install immuta oci://ocir.immuta.com/stable/immuta-enterprise \
       --values immuta-values.yaml \
       --version 2024.2.20

Validation

1. Wait for all pods in the namespace to become ready.

   Copy

   kubectl wait --for=condition=Ready pods --all

2. Determine the name of the Secure service.

   Copy

   kubectl get service --selector "app.kubernetes.io/component=secure" --output name

3. Listen on local port 8080, forwarding TCP traffic to the Secure service's port named http.

   Copy

   kubectl port-forward service/<name> 8080:http

4. Navigate to http://localhost:8080 in a web browser.

Next steps

• Configure Ingress to complete your installation and access your Immuta application.

• Configure TLS to secure your Ingress by specifying a Secret that contains a TLS private key and certificate.

• Learn more about best practices for Immuta in Production.

This page provides one possible way to download and package Immuta artifacts for consumption on a separate network with no Internet access.

export IMMUTA_VERSION=2024.2.20
export IMMUTA_IMAGES="audit-service audit-export-cronjob cache classify-service immuta-service"
export IMMUTA_LEGACY_IMAGES="immuta-db immuta-fingerprint"
for image in ${IMMUTA_IMAGES} ${IMMUTA_LEGACY_IMAGES}; do
  skopeo copy docker://ocir.immuta.com/stable/${image}:${IMMUTA_VERSION} docker-archive://${PWD}/${image}-${IMMUTA_VERSION}.tar;
done

1. Copy the snippet below and replace the placeholder text with the credentials provided by your Immuta representative:

   Copy

   echo <token> | helm registry login --password-stdin --username <username> ocir.immuta.com

2. Download the IEHC for the current Immuta release:

   Copy

   helm pull oci://ocir.immuta.com/stable/immuta-enterprise --version 2024.2.20

export PRIVATE_REGISTRY=your.private-registry.com
export IMMUTA_VERSION=2024.2.20
export IMMUTA_IMAGES="audit-service audit-export-cronjob cache classify-service immuta-service"
export IMMUTA_LEGACY_IMAGES="immuta-db immuta-fingerprint"
for image in ${IMMUTA_IMAGES} ${IMMUTA_LEGACY_IMAGES}; do
  skopeo copy docker-archive://${PWD}/${image}-${IMMUTA_VERSION}.tar docker://${PRIVATE_REGISTRY}/immuta/${image}:${IMMUTA_VERSION};
done

helm upgrade --install immuta ./immuta-enterprise-2024.2.20.tgz -f immuta-values.yaml

Prerequisite

Checklist

Skopeo

• Skopeo is authenticated with Immuta's registry on the networked machine.

• Skopeo is authenticated with the private registry on the air-gapped machine.

Helm

• Helm is authenticated with Immuta's registry on the networked machine.

Download artifacts

This section demonstrates how to download the Helm chart and container images to your local machine. These artifacts will be packaged and transferred to the air-gapped environment later.

1. Create a directory named offline-kit.

   Copy

   mkdir ./offline-kit

2. Download the Helm chart into directory offline-kit.

   Copy

   helm pull oci://ocir.immuta.com/stable/immuta-enterprise --destination ./offline-kit --version 2024.3.9

3. Extract file DIGESTS.md from the Helm chart archive.

   Copy

   tar --extract --gzip --strip-components=1 --directory=./offline-kit --file=./immuta-enterprise-*.tgz immuta-enterprise/DIGESTS.md

4. Open file ./offline-kit/DIGESTS.md. This file includes the name and digest of every container image referenced by the Helm chart.

5. Download each image listed in file DIGESTS.md using . Each image will be saved to directory offline-kit with the filename<name>-<tag>.tar.

Transfer artifacts

This section demonstrates how to push the previously archived container images to a private registry that's accessible from within your air-gapped environment.

1. Transfer directory offline-kit (created in the previous section) onto a machine that's within your air-gapped environment.

2. Push each image to your private registry using skopeo.

   Copy

   skopeo copy docker-archive:offline-kit/<name>-<tag>.tar docker://<private-registry-fqdn>/immuta/<name>:<tag>

Chart installation

Edit the immuta-values.yaml to reference the private container registry and images.

The guides below outline how to deploy Immuta without Elasticsearch.

echo <token> | helm registry login

Introduced in 2024.2, the Immuta Enterprise Helm chart (IEHC) is an entirely new Helm chart used to deploy Immuta. This section guides you through configuring the IEHC to finish and prepare your installation for a production environment.

Cosign verification

Verify artifacts hosted on the ocir.immuta.com OCI registry.

Ingress configuration

Configure Ingress to complete your installation and access your Immuta application.

TLS configuration

Configure TLS termination for an Ingress resource.

Immuta in production

Follow these best practices when deploying Immuta in your production environment.

External cache configuration

Configure an external key-value cache (such as Redis or Memcached) with the Immuta Enterprise Helm chart.

Rotating credentials

Update the credentials referenced in the Immuta Enterprise Helm chart.

Enabling legacy query engine and fingerprint

Enable these legacy services for your deployment if they are required for your business use case:

• If you are using any of the data platforms below, you must enable the query engine:

  • Amazon Redshift

  • Azure Synapse Analytics

  • Google BigQuery

• If you are using the legacy sensitive data discovery (SDD) feature, you must enable the query engine and fingerprint services.

This guide demonstrates how to configure Ingress. Ingress can be configured in numerous ways. Configurations for the most popular controllers are outlined below.

The Immuta web service listens on the following ports:

Ingress NGINX Controller

1. Edit the immuta-values.yaml file to include the following Helm values.

   Copy

   secure:
     ingress:
       hostname: <immuta-fqdn>
       ingressClassName: nginx
       annotations:
         nginx.ingress.kubernetes.io/force-ssl-redirect: 'true'
         nginx.ingress.kubernetes.io/proxy-body-size: '64m'

2. Perform a Helm upgrade to apply the changes made to immuta-values.yaml.

   Copy

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

Refer to the Ingress-Nginx Controller documentation for further assistance.

GKE Ingress Controller

1. Edit immuta-values.yaml to include the following Helm values.

   Copy

   secure:
     ingress:
       hostname: <immuta-fqdn>
       annotations:
         # Determines which type of load balancer is provisioned
         #   gce-internal
         #   gce
         kubernetes.io/ingress.class: gce
         # Listen on both 80 and 443
         kubernetes.io/ingress.allow-http: 'true'
         # Redirect traffic from 80 to 443
         cloud.google.com/frontend-config: immuta

2. Create a file named frontendconfig.yaml with the following content.

   Copy

   apiVersion: networking.gke.io/v1beta1
   kind: FrontendConfig
   metadata:
     name: immuta
   spec:
     redirectToHttps:
       enabled: true
       responseCodeName: RESPONSE_CODE

3. Apply the FrontendConfig CRD.

   Copy

   kubectl apply -f frontendconfig.yaml

4. Perform a to apply the changes made to immuta-values.yaml.

Refer to the Google Cloud documentation for further assistance.

AWS Load Balancer Controller

1. Edit immuta-values.yaml to include the following Helm values.

   Copy

   secure:
     ingress:
       hostname: <immuta-fqdn>
       ingressClassName: alb
       annotations:
         # Determines which type of load balancer is provisioned
         #   internal
         #   internet-facing
         alb.ingress.kubernetes.io/scheme: internet-facing
         alb.ingress.kubernetes.io/target-type: ip
         # Listen on both 80 and 443
         alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80}, {"HTTPS":443}]'
         # Redirect traffic from 80 to 443
         alb.ingress.kubernetes.io/ssl-redirect: '443'

2. Perform a Helm upgrade to apply the changes made to immuta-values.yaml.

   Copy

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

Refer to the AWS Load Balancer Controller documentation for further assistance.

AKS Application Gateway Ingress Controller

1. Edit immuta-values.yaml to include the following Helm values.

   Copy

   secure:
     ingress:
       hostname: <immuta-fqdn>
       ingressClassName: webapprouting.kubernetes.azure.com
       # https://azure.github.io/application-gateway-kubernetes-ingress/annotations/
       annotations:
         appgw.ingress.kubernetes.io/ssl-redirect: 'true'

2. Perform a Helm upgrade to apply the changes made to immuta-values.yaml.

   Copy

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

Refer to the Application Gateway Ingress Controller documentation for further assistance.

Traefik

1. Edit immuta-values.yaml to include the following Helm values.

   Copy

   secure:
     ingress:
       hostname: <immuta-fqdn>
       ingressClassName: traefik
       annotations:
         # Listen on ports 80 and 443
         traefik.ingress.kubernetes.io/router.entrypoints: web,websecure
         # Redirect HTTP to HTTPS
         # When referencing middleware you must prefix the name with its namespace
         # <namespace>-<middleware-name>@kubernetescrd
         traefik.ingress.kubernetes.io/router.middlewares: immuta-https-redirectscheme@kubernetescrd

2. Create a file named middleware.yaml with the following content.

   Copy

   apiVersion: traefik.containo.us/v1alpha1
   kind: Middleware
   metadata:
     name: https-redirectscheme
   spec:
     redirectScheme:
       scheme: https
       permanent: true

3. Apply the Middleware CRD.

   Copy

   kubectl apply -f middleware.yaml

4. Perform a to apply the changes made to immuta-values.yaml.

Refer to the Traefik documentation for further assistance.

OpenShift Ingress Operator

1. Edit immuta-values.yaml to include the following Helm values. Because the Ingress resource will be managed by the OpenShift route you create and not the Immuta Enterprise Helm chart, ingress is set to false below.

   Copy

   secure:
     ingress:
       enabled: false

2. Get the service name for Secure.

   Copy

   oc get service --selector "app.kubernetes.io/component=secure" --output template='{{ .metadata.name }}'

3. Create a file named route.yaml with the following content. Update all with your own values.

4. Apply the Route CRD.

5. Perform a to apply the changes made to immuta-values.yaml.

Refer to the Red Hat OpenShift documentation for further assistance.

This guide highlights best practices when deploying Immuta in a production environment.

Helm values

Back up or source control your immuta-values.yaml Helm values file.

Kubernetes resource requests and limits

Assign memory resource limits to pods.

Edit Helm values

Edit immuta-values.yaml to include the following recommended resource requests and limits for most Immuta deployments.

audit:
  worker:
    replicaCount: 1
    resources:
      requests:
        cpu: 1000m
        memory: 1024Mi
      limits:
        cpu: 1000m
        memory: 2048Mi  
  deployment:
    replicaCount: 1
    resources:
      requests:
        cpu: 1000m
        memory: 4096Mi
      limits:
        cpu: 3000m
        memory: 8192Mi
secure:
  backgroundWorker:
    replicaCount: 2
    resources:
      requests:
        cpu: 1000m
        memory: 4096Mi
      limits:
        cpu: 4000m
        memory: 4096Mi  
  web:
    replicaCount: 2 
    resources:
      requests:
        cpu: 1000m
        memory: 4096Mi
      limits:
        cpu: 4000m
        memory: 4096Mi
discover:
  deployment:
    replicaCount: 1
    resources:
      requests:
        cpu: 500m
        memory: 4096Mi
      limits:
        cpu: 3000m
        memory: 4096Mi
cache:
  deployment:
    replicaCount: 1
    resources:
      requests:
        cpu: 500m
        memory: 512Mi
      limits:
        cpu: 1000m
        memory: 512Mi

Kubernetes secrets

Use Kubernetes secrets in the immuta-values.yaml file instead of passwords and tokens. The following section demonstrates how to create a secret and reference it in the Helm values file.

Create secret

1. Create a file named secret-data.env with the following content.

   Copy

   # audit
   ELASTICSEARCH_USERNAME=<elasticsearch-username>
   ELASTICSEARCH_PASSWORD=<elasticsearch-password>
   
   # PostgreSQL connection string used by audit for the metadata database
   #   postgresql://<user>:<password>@<postgres-fqdn>:5432/<database>?schema=audit
   #
   # More info
   #   https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING
   DATABASE_CONNECTION_STRING=postgresql://immuta:<postgres-password>@<postgres-fqdn>:5432/immuta?schema=audit
   
   # secure
   IMMUTA_DATABASES_IMMUTA_CONNECTIONS_IMMUTADB_PASSWORD=<postgres-password>

2. Create secret named immuta-secret from file secret-data.env.

   Copy

   kubectl create secret generic immuta-secret --from-env-file=secret-data.env

3. Delete file secret-data.env, as it's no longer needed.

Edit Helm values

1. Edit immuta-values.yaml to include the following Helm values.

   Copy

   audit:
     #...
     deployment:
       existingSecret: immuta-secret
     export:
       cronJob:
         existingSecret: immuta-secret
   
   secure:
     #...
     existingSecret:
       name: immuta-secret
       # Optional. Map expected keys with keys in existing secret
       # keyMapping: {}

2. Remove any sensitive key-value pairs from the immuta-values.yaml Helm values that were made redundant after the secret was created.

Apply Helm values

Perform a Helm upgrade to apply the changes made to immuta-values.yaml.

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

This guide demonstrates how to update credentials referenced in the Immuta Enterprise Helm chart (IEHC).

Kubernetes secrets

Edit secrets

1. Validate that secret immuta-secret exists in the current namespace.

   Copy

   kubectl get secret/immuta-secret

2. Edit secret immuta-secret in place.

   Copy

   kubectl edit secret/immuta-secret

3. Edit secret immuta-legacy-secret in place. Skip this step if the legacy query engine and fingerprint services are disabled (the default).

   Copy

   kubectl edit secret/immuta-legacy-secret

4. Restart pods.

   Copy

   kubectl rollout restart deployment --all --selector "app.kubernetes.io/component=audit,app.kubernetes.io/component=secure"

Legacy query engine

1. Validate that secret immuta-legacy-secret exists in the current namespace.

   Copy

   kubectl get secret/immuta-legacy-secret

2. Get the query engine replica count, this value will be referenced in subsequent step(s).

   Copy

   kubectl get statefulset --selector "app.kubernetes.io/component=query-engine" --output name

3. Scale the replica count down to 1.

   Copy

   kubectl scale statefulset --all --replicas 1 --selector "app.kubernetes.io/component=query-engine"

4. Get the query engine pod name, this value will be referenced in subsequent step(s).

5. Update the with a query engine superuser password.

6. Update the with a query engine replication password.

7. Update the with a query engine feature password.

8. Scale the replica count back up to the previous value by updating the .

Apply Helm values

1. Update credentials in the immuta-values.yaml file.

2. Perform a Helm upgrade to apply the changes made to immuta-values.yaml. Update the placeholder value with your own release name.

   Copy

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

The query engine and fingerprint services are no longer installed by default. This guide demonstrates how to enable the query engine and fingerprint services using the Immuta Enterprise Helm chart (IEHC).

If you are using any of the data platforms below, you must enable the query engine:

• Amazon Redshift

• Azure Synapse Analytics

• Google BigQuery

• Any legacy database

If you are using the legacy sensitive data discovery (SDD) feature, you must enable the query engine and fingerprint services.

Prerequisites

• The Immuta in production guide must be completed before proceeding.

• Validate that secret immuta-secret exists in the current namespace.

  Copy

  kubectl get secret/immuta-secret

Create Kubernetes secret

1. Create a file named secret-data.env with the following content.

   Copy

   # query-engine
   IMMUTA_FEATURE_PASSWORD=<immuta-feature-password>
   PATRONI_SUPERUSER_PASSWORD=<patroni-superuser-password>
   PATRONI_REPLICATION_PASSWORD=<patroni-replication-password>
   PATRONI_RESTAPI_PASSWORD=<patroni-api-password>

2. Create secret named immuta-legacy-secret from file secret-data.env

   Copy

   kubectl create secret generic immuta-legacy-secret --from-env-file=secret-data.env

3. Delete file secret-data.env, as it's no longer needed.

Edit Helm values

1. Edit the immuta-values.yaml file to include the following Helm values.

   Copy

   legacy:
     enabled: true
   
     queryEngine:
       statefulset:
         extraEnvVars:
         - name: IMMUTA_FEATURE_PASSWORD
           valueFrom:
             secretKeyRef:
               name: immuta-legacy-secret
               key: IMMUTA_FEATURE_PASSWORD
         - name: PATRONI_SUPERUSER_PASSWORD
           valueFrom:
             secretKeyRef:
               name: immuta-legacy-secret
               key: PATRONI_SUPERUSER_PASSWORD
         - name: PATRONI_REPLICATION_PASSWORD
           valueFrom:
             secretKeyRef:
               name: immuta-legacy-secret
               key: PATRONI_REPLICATION_PASSWORD
         - name: PATRONI_RESTAPI_PASSWORD
           valueFrom:
             secretKeyRef:
               name: immuta-legacy-secret
               key: PATRONI_RESTAPI_PASSWORD
   
       postgres:
         # Query Engine feature user
         # Instead use queryEngine.statefulset.extraEnvVars[].name[IMMUTA_FEATURE_PASSWORD]
         # password: <immuta-feature-password>
   
         # Query Engine superuser user
         # Instead use queryEngine.statefulset.extraEnvVars[].name[PATRONI_SUPERUSER_PASSWORD]
         # superuserPassword: <patroni-superuser-password>
   
         # Query Engine replication user
         # Instead use queryEngine.statefulset.extraEnvVars[].name[PATRONI_REPLICATION_PASSWORD]
         # replicationPassword: <patroni-replication-password>
   
         # Query Engine patroni api user
         # Instead use queryEngine.statefulset.extraEnvVars[].name[PATRONI_RESTAPI_PASSWORD]
         # patroniApiPassword: <patroni-api-password>
       immutaSecurity:
         # Each Kubernetes Service has a DNS record associated with it. See: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/
         # The anatomy of a domain name is as followed:
         #   <service>.<namespace>.svc.<cluster-domain>
         #
         # Where the default cluster domain is: cluster.local
         authEndpoint: "http://immuta-secure.immuta.svc.cluster.local:8823"
   
   secure:
     extraEnvVars:
     - name: IMMUTA_DATABASES_IMMUTA_CONNECTIONS_FEATURESTOREDB_PASSWORD
       valueFrom:
         secretKeyRef:
           name: immuta-legacy-secret
           key: IMMUTA_FEATURE_PASSWORD
   
     extraConfig:
       queryEngineRehydration:
         enabled: true
       disableFeatureStore: false
       databases:
         immuta:
           connections:
             featureStoreDb:
               # Each Kubernetes Service has a DNS record associated with it. See: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/
               # The anatomy of a domain name is as followed:
               #   <service>.<namespace>.svc.<cluster-domain>
               #
               # Where the default cluster domain is: cluster.local
               host: "immuta-legacy-query-engine-service.immuta.svc.cluster.local"
               port: 5432
               ssl: false
               # Query Engine feature user
               # Instead use secure.extraEnvVars[].name[IMMUTA_DATABASES_IMMUTA_CONNECTIONS_FEATURESTOREDB_PASSWORD]
               # password: <immuta-feature-password>
       fingerprints:
         # Each Kubernetes Service has a DNS record associated with it. See: https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/
         # The anatomy of a domain name is as follows:
         #   <service>.<namespace>.svc.<cluster-domain>
         #
         # Where the default cluster domain is: cluster.local
         uri: "http://immuta-legacy-fingerprint-service.immuta.svc.cluster.local:5001/"
         queryEngineHost: "immuta-legacy-query-engine-service.immuta.svc.cluster.local"
         queryEnginePort: 5432

2. Update all placeholder values in the immuta-values.yaml file.

Apply Helm values

Perform a Helm upgrade to apply the changes made to immuta-values.yaml.

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

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

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.

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

   Copy

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

3. Create an immuta role and database.

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

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

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.

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

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

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

External

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

Helm values