Skip to content

You are viewing documentation for Immuta version 2.8.

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

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 go to Method B: Full Backup/Restore Upgrade.

Step 1: Confirm Current Functionality and Back Up Your Existing Immuta

Before upgrading, it is always a good idea to 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 before continuing.

Step 2: Stop and Remove Your Existing Containers

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

cd ${IMMUTA_HOME}
docker-compose down

Step 3: Update the Immuta Version in docker-compose.yml

Update the desired Immuta version

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., 2.8.3):

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>

Step 4: 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.

Step 4(a): Update/Migrate certs

Execute the script shown at Docker Single Node Installation, Step 3(c)

Step 4(b): 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:

Step 5: Start Immuta

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

docker-compose up -d

Step 6: 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 and Restore

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.

Step 1: Confirm Current Functionality and Back Up Your Existing Immuta

Before upgrading, it is always a good idea to 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.

This method requires a full backup of your Immuta to be taken in order to preserve your configuration. Please follow the steps detailed at Docker Single Node Backups to create a current backup.

Ensure that backup is safely stored, as it will be required during the forthcoming restoration process.

Step 2: Stop and Remove Your Existing Containers and Volumes

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

    cd ${IMMUTA_HOME}
    docker-compose down --volumes

Step 3: 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

Step 4: 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 in your previous. These passwords MUST match your previous in order for your upgraded install 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.

Step 5: 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

Step 6: Start Immuta

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

    docker-compose up -d

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