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 thedb/restore/
directory. - If you wish to use the same certs collection, please replace the current
tls
directory with a copy of thetls
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.