Skip to content

You are viewing documentation for Immuta version 2020.3.

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

cancel

Single Node Docker Upgrades

Audience: System Administrators

Content Summary: This guide provides two methods for upgrading single-node Docker installations of Immuta. The first is for basic upgrades of the images involved. The second is a more involved method that is needed when major updates or changes have occurred between versions.

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.

Single Node Docker Upgrade Process

  1. Confirm current functionality and back up Immuta installation.
  2. Stop and remove existing containers.

  3. Select upgrade path:

    • Method A
    • Method B

  4. Start Immuta.

  5. Test and verify Immuta.

1 - Confirm Current Functionality and Back Up Immuta Installation

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.

As always, please ensure you have a current backup of your Immuta instance before continuing.

2 - Stop and Remove Existing Containers

From within your IMMUTA_HOME directory (by default /opt/immuta), run docker-compose down:

cd ${IMMUTA_HOME}
docker-compose down

3 - Select Upgrade Path

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., 2.4.1 to 2.4.2) 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 to 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 2.4 to 2.5) require this type of upgrade. Please see the release notes associated with the version you are moving to to see if this method is required of your upgrade.

Method A

A.1 - Update the Immuta Version in docker-compose.yml

Edit your docker-compose.yml and change the image versions to reflect the version your are upgrading to, including the full release value (i.e., 2020.3.6):

version: '2'
services:
  db:
    image: registry.immuta.com/immuta/immuta-db:<INSERT VERSION HERE>

...

  service:
    image: registry.immuta.com/immuta/immuta-service:<INSERT VERSION HERE>

...

  fingerprint:
    image: registry.immuta.com/immuta/immuta-fingerprint:<INSERT VERSION HERE>

A.2 - Ensure TLS cert locations are up to date

Versions 2.8.0+ of Immuta include some changes to certificate ownership expectations. Follow these steps to ensure your certs locations are compliant with these expectations.

A.2.1 - Update/Migrate certs

Execute the script shown at Docker Single Node Installation, Step 3.3.

A.2.2 - Ensure docker-compose.yml is referencing the updated locations

Look through your docker-compose.yml to determine if volumes for these certs are mounted from ${IMMUTA_HOME}/tls/external and ${IMMUTA_HOME}/tls/internal, for example:

  volumes:
  - /opt/immuta/tls/internal/immuta-ca.crt:/etc/immuta/tls/ca.crt
  - /opt/immuta/tls/external/immuta.crt:/etc/immuta/tls/postgresql.crt
  - /opt/immuta/tls/external/immuta.key:/etc/immuta/tls/postgresql.key

In this case an update is required so each container mounts its own copy of the cert files. The easiest way to do this is to regenerate the docker-compose.yml by ensuring your Immuta environment variables are set and following the steps in Docker Single Node Installation, Step 7.

Alternatively, you can also do this by using the patch below - either manually edited in place or via the patch Linux command line tool.

--- a/docker-compose.yml    2020-03-31 18:11:14.396448044 -0400
+++ b/docker-compose.yml    2020-03-31 18:11:11.599411373 -0400
@@ -25,9 +25,9 @@
    # Set to true to enable database backup restoration
    - DB_RESTORE_ENABLED=false
    volumes:
-    - /opt/immuta/tls/internal/immuta-ca.crt:/etc/immuta/tls/ca.crt
-    - /opt/immuta/tls/external/immuta.crt:/etc/immuta/tls/postgresql.crt
-    - /opt/immuta/tls/external/immuta.key:/etc/immuta/tls/postgresql.key
+    - /opt/immuta/tls/db/immuta-ca.crt:/etc/immuta/tls/ca.crt
+    - /opt/immuta/tls/db/immuta.crt:/etc/immuta/tls/postgresql.crt
+    - /opt/immuta/tls/db/immuta.key:/etc/immuta/tls/postgresql.key
    - db:/var/lib/immuta/postgresql/data:z
    # Uncomment the line below to enable database backup restoration
    # - ./volumes/db/restore:/var/lib/immuta/postgresql/restore
@@ -54,9 +54,9 @@
        aliases:
        - service.immuta
    volumes:
-    - /opt/immuta/tls/internal/immuta.key:/etc/immuta/tls/service.key
-    - /opt/immuta/tls/internal/immuta.crt:/etc/immuta/tls/service.crt
-    - /opt/immuta/tls/internal/immuta-ca.crt:/etc/immuta/tls/ca.crt
+    - /opt/immuta/tls/service/immuta.key:/etc/immuta/tls/service.key
+    - /opt/immuta/tls/service/immuta.crt:/etc/immuta/tls/service.crt
+    - /opt/immuta/tls/service/immuta-ca.crt:/etc/immuta/tls/ca.crt
    - /opt/immuta/volumes/config:/etc/immuta/config:z
  fingerprint:
    image: registry.immuta.com/immuta/immuta-fingerprint:2.8.2
@@ -71,9 +71,9 @@
        aliases:
        - fingerprint.immuta
    volumes:
-    - /opt/immuta/tls/internal/immuta.key:/etc/fingerprint/tls/tls.key
-    - /opt/immuta/tls/internal/immuta.crt:/etc/fingerprint/tls/tls.crt
-    - /opt/immuta/tls/internal/immuta-ca.crt:/etc/fingerprint/tls/ca.crt
+    - /opt/immuta/tls/fingerprint/immuta.key:/etc/fingerprint/tls/tls.key
+    - /opt/immuta/tls/fingerprint/immuta.crt:/etc/fingerprint/tls/tls.crt
+    - /opt/immuta/tls/fingerprint/immuta-ca.crt:/etc/fingerprint/tls/ca.crt
    - /opt/immuta/volumes/fingerprint/config.yml:/etc/fingerprint/config.yml
  proxy:
    image: registry.immuta.com/nginx:1.13-alpine
@@ -89,9 +89,9 @@
    - "443:443"
    volumes:
    - /opt/immuta/volumes/proxy/nginx.conf:/etc/nginx/nginx.conf:ro
-    - /opt/immuta/tls/external/immuta.key:/etc/nginx/proxy.key
-    - /opt/immuta/tls/external/immuta.crt:/etc/nginx/proxy.crt
-    - /opt/immuta/tls/internal/immuta-ca.crt:/etc/nginx/ca.crt
+    - /opt/immuta/tls/proxy/immuta.key:/etc/nginx/proxy.key
+    - /opt/immuta/tls/proxy/immuta.crt:/etc/nginx/proxy.crt
+    - /opt/immuta/tls/proxy/immuta-ca.crt:/etc/nginx/ca.crt
    networks:
      immuta:
        aliases:

Method B

B.1 - Back Up (Relocate) Your IMMUTA_HOME Directory

Now back up your current IMMUTA_HOME directory. Assuming you would like to reuse the directory location, a recommended approach is to simply move the directory to a different location.

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

   mv /opt/immuta /opt/immuta-backup-2.4

B.2 - Initialize the New Immuta Installation

With your old IMMUTA_HOME relocated, complete Step 1 of the new installation procedures as documented at Docker Single Node Installation, Step 1. This will generate a new IMMUTA_HOME directory as well as the Immuta environment variables set in immuta-env.

Before moving to Step 2 of those instructions, update the passwords in the newly-generated immuta-env to match the passwords used previously. These passwords must match your previous installation for your upgraded installation to access its database properly.

Once the passwords have been copied in, complete Step 2 of the new installation procedures to source those variables into the environment.

B.3 - Generate New Config Materials, Merge in Customizations, and Prepare for Restoration

Complete Steps 3 - 8 as documented in Docker Single Node Installation, Step 3 to create brand new config files for your updated install.

Now that new config files have been generated, go back and merge into them any customizations that were made as part of your environment. Specifically, note the following:

  • Step 8 of the installation instructions should have resulted in your backup tarball (called immuta-<datestamp>.tar.gz) being staged for restoration in the db/restore/ directory.
  • If you wish to use the same certs collection, please replace the current tls directory with a copy of the tls directory from your backup.
  • Ensure you merge in any required changes to volumes/config/config.yml.
  • Ensure you merge in any required changes to volumes/proxy/nginx.conf.

When finished, the final structure for your IMMUTA_HOME directory should be

.
+-- docker-compose.yml
+-- immuta-env
+-- tls
|   +-- external
|       +-- immuta.crt
|       +-- immuta.key
|   +-- internal
|       +-- immuta-ca.crt
|       +-- immuta-ca.key
|       +-- immuta-ca.srl
|       +-- immuta.crt
|       +-- immuta.csr
|       +-- immuta.key
+-- volumes
|   +-- config
|       +-- config.yml
|   +-- db
|       +-- restore
|           +-- immuta-<datestamp>.tar.gz
|   +-- fingerprint
|       +-- config.yml
|   +-- proxy
|       +-- nginx.conf

4 - Start Immuta

Now restart Immuta to create new containers based on the updated images and mounting in your existing volumes and settings:

    docker-compose up -d

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