Skip to content

You are viewing documentation for Immuta version 2023.1.

For the latest version, view our documentation for Immuta SaaS or the latest self-hosted version.

cancel

Single Node Docker Upgrades

Rocky Linux 9

Review the potential impacts of Immuta's Rocky Linux 9 upgrade to your environment before proceeding.

Warning

Before doing any upgrade, please ensure you have a full backup of your current Immuta installation. Steps for completing this backup can be found at Docker Single Node Backups.

No Rollback

Immuta's migrations to your database are one way; this means that there is no way to revert back to an earlier version of the software. If you must rollback, you will need to backup and delete what you have and then proceed to restore from the backup to the appropriate version of the software.

Installation Methods

Use the descriptions below to determine whether you should use Method A or Method B to upgrade:

  • Method A: Basic Docker Image Upgrade: This is the basic upgrade method and is perfect for updating between "point releases" (i.e., 2020.3.5 to 2020.3.6) or releases that do not contain major technology changes (such as a Postgres database version upgrade). Please see the release notes for the version of Immuta you are upgrading to and determine if this basic method is usable. If not, please use Method B.
  • Method B: Full Backup/Restore Upgrade: During major version upgrades, Immuta may make changes that require a full backup and restore procedure. This occurs, for example, when Immuta upgrades underlying major components, such as Postgres versions. Many major release changes (i.e., upgrading from 2020.3 to 2020.4) require this type of upgrade. Please see the release notes associated with the version you are moving to and see if this method is required of your upgrade.
Note

Introduced in 2020.4.0, immuta-snd is the new way to install and manage single node instances of Immuta. If you haven't already, perform the following steps:

Method A: Basic Docker Image Upgrade

A.1 - Confirm Current Functionality and Back Up Your Existing Immuta Installation

  1. Create a current backup of your Immuta instance before continuing.

  2. Before upgrading, check the health of your data sources. A data source reporting "Unhealthy" post-upgrade may raise concern if it was reporting "Healthy" prior. Noting what was unhealthy before the upgrade helps identify potential issues.

A.2 - Set Immuta Environment Variables

export IMMUTA_HOME="/opt/immuta"
export IMMUTA_SND_CONF="/etc/opt/immuta/immuta.toml"
Note

If your toml configuration file is located elsewhere be sure to update the IMMUTA_SND_CONF environment variable with the absolute path to your immuta.toml.

A.3 - Stop and Remove Your Existing Containers

Depending on your current Immuta version, stopping the containers differs. Run the commands that are applicable to your version:

/usr/local/bin/immuta-snd down

docker-compose --file "${IMMUTA_HOME:?}/docker-compose.yml" down

A.4 - Update the Immuta Version

Edit your immuta.toml ( i.e, vi $IMMUTA_SND_CONF ) and update toml key version to the desired release (i.e., 2023.1.2):

[immuta]

version = 2023.1.2

A.5 - Initialize Immuta

Docker Registry Authentication

Reach out to your Immuta support professional for your Immuta Docker registry credentials.

You will only need to provide your Docker registry credentials the first time using immuta-snd. Passing in --docker-registry-password and --docker-registry-username on consecutive installs is not necessary as Docker will cache your credentials.

Create new containers based on the updated images and mounting in your existing volumes and settings:

/usr/local/bin/immuta-snd init
Tip

If you wish to issue a new certificate and certificate authority append --internal-tls-generate to the above command. Otherwise any existing certificates will be carried over.

A.6 - Start Immuta

Start new containers with the updated images:

/usr/local/bin/immuta-snd start

A.7 - Test and Verify Immuta

Your Immuta upgrade should now be complete. Confirm you are running the desired version by looking at the footer text at the Immuta login screen. Please access your instance and verify the system is working as expected.

Method B: Full Backup/Restore Upgrade

B.1 - Confirm Current Functionality

  1. Before upgrading, look through your current Immuta instance and take note of things like any data sources that are reporting "Unhealthy." Such a find post-upgrade may raise concern if you believe that same data source was "Healthy" before. Noting what was unhealthy before the upgrade avoids potential concern over that later.

B.2 Back Up Your Existing Immuta Installation

Follow the steps detailed at Docker Single Node Backups to create a current backup.

Run the following command:

    IMMUTA_HOME="/opt/immuta" COMPOSE_INTERACTIVE_NO_CLI=1 /usr/local/bin/docker-compose --file "${IMMUTA_HOME:?}/docker-compose.yml" exec -T --user 1000 db backup-immuta.sh

For additional details refer to the backup documentation.

B.3 - Set Immuta Environment Variables

Note

If upgrading from a version prior to 2020.4.0 run the following command:

while read _var; do unset $_var; done < <(set -o posix; set | grep '^IMMUTA_' | sed 's/=.*//g'; set +o posix)

The above command unsets all environment variables prefixed with IMMUTA_. This is necessary to ensure immuta-env variables configured in the older <2020.4.0 docker-compose installation method do not persist.

export IMMUTA_HOME="/opt/immuta"
export IMMUTA_SND_CONF="/etc/opt/immuta/immuta.toml"
Note

If your toml configuration file is located elsewhere be sure to update the IMMUTA_SND_CONF environment variable with the absolute path to your immuta.toml.

B.4 - Stop and Remove Your Existing Containers and Volumes

Depending on the version of your current Immuta installation, stopping the containers differs. Run the commands that are applicable to your version:

/usr/local/bin/immuta-snd down --volumes
Note

Immuta versions prior to 2020.4.0 depended on docker-compose.

docker-compose --file "${IMMUTA_HOME:?}/docker-compose.yml" down -v

B.5 - Relocate the Existing IMMUTA_HOME Directory

Back up your current IMMUTA_HOME directory. Assuming you would like to reuse the directory location, the recommended approach is to move the directory to an alternative location.

For example, assuming your IMMUTA_HOME is set to /opt/immuta:

mv "${IMMUTA_HOME:?}" "${IMMUTA_HOME:?}/../immuta-bak"

B.6 - Update the Immuta Version

Edit your immuta.toml ( i.e, vi $IMMUTA_SND_CONF ) and update toml key version to the desired release (i.e., 2023.1.2):

[immuta]

version = 2023.1.2

B.7 Select Backup

Set shell variable my_backup to a desired backup file that you wish to restore from. Depending on the version of your current Immuta installation, the file location differs:

Warning

Ensure variable my_backup is updated with a valid path. Replace immuta-<timestamp>.tar.gz with your desired backup file.

my_backup="${IMMUTA_HOME:?}/../immuta-bak/volumes/immuta-db/backups/immuta-<timestamp>.tar.gz"

my_backup="${IMMUTA_HOME:?}/../immuta-bak/volumes/db/backups/immuta-<timestamp>.tar.gz"

B.8 - Initialize the New Immuta Installation

Create new containers based on the updated images and mounting in your existing volumes and settings:

Carrying Over Passwords

To preserve custom passwords across upgrades it is necessary to create a passwords.txt file and pipe the password values into the stdin of immuta-snd while using option --passwords-stdin. Refer to the password configuration instructions for additional details.

cat ${HOME:?}/passwords.txt | /usr/local/bin/immuta-snd init --passwords-stdin --restore "${my_backup:?}"
Docker Registry Authentication

Reach out to your Immuta support professional for your Immuta Docker registry credentials.

You will only need to provide your Docker registry credentials the first time using immuta-snd. Passing in --docker-registry-password and --docker-registry-username on consecutive installs is not necessary as Docker will cache your credentials.

B.9 - (Optional) Transfer TLS Certificates from Prior Install

Migrate all TLS Certificates from prior install (/opt/immuta-bak):

cp --recursive --force --archive "${IMMUTA_HOME:?}/../immuta-bak/tls" "${IMMUTA_HOME:?}/tls"
Warning

Version 2020.4.0 of Immuta included changes to volume and TLS certificate paths. If you're upgrading from an older version of Immuta and wish to preserve any existing TLS certificates run the following commands:

mv --force "${IMMUTA_HOME:?}/tls/_generated" "${IMMUTA_HOME:?}/tls/.internal"
mv --force "${IMMUTA_HOME:?}/tls/_external" "${IMMUTA_HOME:?}/tls/.external" || true
mv --force "${IMMUTA_HOME:?}/tls/proxy" "${IMMUTA_HOME:?}/tls/immuta-proxy"
mv --force "${IMMUTA_HOME:?}/tls/db" "${IMMUTA_HOME:?}/tls/immuta-db"
mv --force "${IMMUTA_HOME:?}/tls/fingerprint" "${IMMUTA_HOME:?}/tls/immuta-fingerprint"
mv --force "${IMMUTA_HOME:?}/tls/service" "${IMMUTA_HOME:?}/tls/immuta-service"

B.10 - Validate TLS Certificates

Verify the ${IMMUTA_HOME}/tls file hierarchy is as follows:

├── tls
    ├── .internal
    │   ├── immuta-ca.crt
    │   ├── immuta-ca.key
    │   ├── immuta-ca.srl
    │   ├── immuta.crt
    │   ├── immuta.csr
    │   └── immuta.key
    ├── immuta-db
    │   ├── immuta-ca.crt
    │   ├── immuta.crt
    │   └── immuta.key
    ├── immuta-fingerprint
    │   ├── immuta-ca.crt
    │   ├── immuta.crt
    │   └── immuta.key
    ├── immuta-proxy
    │   ├── immuta-ca.crt
    │   ├── immuta.crt
    │   └── immuta.key
    └── immuta-service
        ├── immuta-ca.crt
        ├── immuta.crt
        └── immuta.key
Note

If you've previously configured an external cert you'll also have a .external directory.

B.11 - Start Immuta

Start new containers with the updated images:

/usr/local/bin/immuta-snd start

B.12 - Test and Verify Immuta

Your Immuta upgrade should now be complete. Confirm you are running the desired version by looking at the footer text at the Immuta login screen. Please access your instance and verify the system is working as expected.

B.13 - (Optional) Post Verification

You may now delete the following files/directories:

  • /opt/immuta-bak
  • ${HOME}/passwords.txt