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
- Confirm current functionality and back up Immuta installation.
- Stop and remove existing containers.
-
- Method A
- Method B
- 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 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
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.