Upgrading to 2.8.x

Audience: System Administrators

Content Summary: This section covers the steps needed to upgrade Immuta to 2.8.x.

Please note that in several places, there are selectors for choosing the version you are upgrading from. These selectors and drop-downs adjust the commands according to your previous version.

1.) Update Yum configuration to include the updated Immuta artifacts

Get the latest Immuta RPM packages from https://archives.immuta.com/rpm. (If you need login information, please visit https://download.immuta.com.) Load those artifacts into your YUM repository, or follow the instructions here to set up a local YUM repository.

2.) Capture a Current Backup

While this process will not require a database restoration, taking a backup of your Immuta Metadata and Query Engine is always recommended.

The following commands must be run as immutaqe (2.6+) or postgres (< 2.6):

mkdir -p /var/lib/immutaqe/postgresql/backups
/opt/immuta/bin/backup-immuta -r bometadata,immuta -d /var/lib/immutaqe/postgresql/backups

mkdir -p /var/lib/pgsql/backups
/usr/share/immuta/backup-immuta.sh -r bometadata,immuta -d /var/lib/pgsql/backups

mkdir -p /var/lib/pgsql/backups
/usr/share/immuta-security/backup-immuta.sh -r bometadata,immuta -d /var/lib/pgsql/backups

3.) Stop Services on All Nodes

Web Node(s)

service immuta stop
service immuta-fingerprint stop

Database Primary Node

service immuta-query-engine stop

service postgresql-11 stop
chkconfig postgresql-11 off

service postgresql-9.6 stop
chkconfig postgresql-9.6 off

Database Replica Node(s)

service immuta-query-engine stop

service postgresql-11 stop
chkconfig postgresql-11 off

service postgresql-9.6 stop
chkconfig postgresql-9.6 off

4.) Upgrade Primary Database Node

Install/upgrade the immuta-query-engine package

The following commands must be run as root:

yum upgrade immuta-query-engine

yum install immuta-query-engine

yum install immuta-query-engine

Transaction check error:
  file /opt/immuta/lib from install of immuta-query-engine-2.8.2-20200313.el7.x86_64 conflicts
  with file from package immuta-2.5.1-20190625.el7.x86_64

Error Summary
-------------

systemctl stop immuta-query-engine

Now run the database migrations to complete the upgrade process. Choose one of the following options.

Option A) In-place upgrade (>= 2.6 ONLY!)

The following commands must be run as immutaqe:

pg_ctl start -w -D"${PGDATA}" -o "-c listen_addresses='localhost' -c allow_system_table_mods=on"
init_db.sh -s -m -r bometadata,immuta -p env
pg_ctl stop -w -m fast

Option B) Restore from backup

First, ensure your backup is properly staged for restoration with the current version.

The following commands must be run as root:

## confirm backups are already staged in /var/lib/immutaqe/postgresql/backups

cp -R /var/lib/pgsql/backups/ /var/lib/immutaqe/postgresql/
chown -R immutaqe:immutaqe /var/lib/immutaqe/postgresql/backups

cp -R /var/lib/pgsql/backups/ /var/lib/immutaqe/postgresql/
chown -R immutaqe:immutaqe /var/lib/immutaqe/postgresql/backups

Now run the restoration process.

The following commands must be run as immutaqe:

pg_ctl init -o'-U postgres -E UTF8 --locale=en_US.utf8'
pg_ctl start -w -D"${PGDATA}" -o "-c listen_addresses='localhost' -c allow_system_table_mods=on"
restore-immuta -r bometadata,immuta -d /var/lib/immutaqe/postgresql/backups
init_db.sh -s -m -r bometadata,immuta -p env
pg_ctl stop -w -m fast

Merge configuration settings

Now update the contents of your postgresql.conf and pg_hba.conf files to take full advantage of the updated features provided in the upgrades. The current defaults for these files are shown below. Be sure to keep any necessary customizations in your config files!

2.8-series Default /var/lib/immutaqe/postgresql/data/postgresql.conf

(Changes from 2.6 noted with # <- NEW comments, older may require other alterations.)

listen_addresses = '*'
port = 5432
ssl = 'on'
max_connections = 250
shared_preload_libraries = 'immuta_sql_fdw'
idle_in_transaction_session_timeout = 60000                # <- NEW
lock_timeout = 5000
immuta_security.user_auth_endpoint = '{YOUR IMMUTA_BASE_URL}'
immuta_security.ca_file = '{YOUR PATH_TO_CA}'
immuta_security.ssl_peer_verification = true
immuta_security.ssl_host_verification = true
immuta_fdw.show_remote_sql_explain = false
immuta_fdw.advanced_pushdown = true
immuta_fdw.window_pushdown = true
immuta_fdw.driver_iseriesdb2_max_page_queries = 0
immuta_fdw.driver_mariadb_window_pushdown = false
immuta_fdw.driver_mysql_window_pushdown = false
immuta_fdw.driver_sybase_ase_window_pushdown = false
immuta_fdw.driver_kdb_window_pushdown = false
immuta_fdw.driver_kdb_advanced_pushdown = false
immuta_fdw.driver_kdb_max_page_queries = 0
immuta_fdw.driver_elastic_window_pushdown = false
immuta_fdw.driver_elastic_max_page_queries = 0
immuta_fdw.driver_postgresql_connection_sharing = true
immuta_fdw.driver_staging_directory = '/var/lib/immutaqe/odbc/install/'
immuta_fdw.driver_install_directory = '/var/lib/immutaqe/odbc/drivers/'

2.8-series /var/lib/immutaqe/postgresql/data/pg_hba.conf

(Changes from 2.6 noted with # <- NEW comments.)

local all postgres trust
host bometadata bometa 0.0.0.0/0 md5
host bometadata bometa ::/0 md5
host immuta feature_service,+bodata_user,+bodata_impersonate_user 0.0.0.0/0 md5
host immuta feature_service,+bodata_user,+bodata_impersonate_user ::/0 md5

Check TLS certificates

The TLS certificates for PostgreSQL should already be in place. If they aren't, copy the TLS certificates into the data directory, and assign them to the immutaqe user.

The following commands must be run as root:

## server.crt & server.key should be in /var/lib/immutaqe/postgresql/data/

cp -a /var/lib/pgsql/11/data/server.{key,crt} /var/lib/immutaqe/postgresql/data/
chown immutaqe:immutaqe /var/lib/immutaqe/postgresql/data/server.{key,crt}

cp -a /var/lib/pgsql/9.6/data/server.{key,crt} /var/lib/immutaqe/postgresql/data/
chown immutaqe:immutaqe /var/lib/immutaqe/postgresql/data/server.{key,crt}

Install/update ODBC drivers

Finally, install provided and inherited ODBC drivers.

The following command must be run as immutaqe:

immuta-odbc-install

5.) Upgrade Web Node(s)

The following commands must be run as root:

yum upgrade immuta immuta-fingerprint

• A new file /etc/sysconfig/immuta.rpmsave may be created containing your original Immuta configuration. If that occurs, the /etc/sysconfig/immuta will now contain the latest configuration defaults. It is critical that you diff that against your saved values and apply any changes as necessary before starting services.

• A new file /etc/immuta/config.yml.rpmsave may be created containing your original Immuta configuration. If that occurs, the /etc/immuta/config.yml will now contain the latest configuration defaults. It is critical that you diff that against your saved values and apply any changes as necessary before starting services.

6.) Upgrade the Web Load Balancer Node (if used)

Immuta version 2.8 introduces a built-in query-editor component. This component requires websockets to function properly. Such connections need to be supported through any network infrastructure between the Web Service and Query Engine nodes, including Immuta's Web Load Balancer Node (if used). To enable, simply update /etc/nginx/nginx.conf to match the template provided in the instructions for setting up the Web Load Balancer found at Web Load Balancer.

Then, restart the Nginx service (as root):

service nginx restart

7.) Upgrade Database Replica(s)

For this step, simply upgrade the immuta-query-engine package.

The following commands must be run as root:

yum upgrade immuta-query-engine

yum install immuta-query-engine

yum install immuta-query-engine

Then follow the instructions at Database Replication to fully re-initialize the replica.

8.) Start Services

Database Primary Node

chkconfig immuta-query-engine on
service immuta-query-engine start

Database Replica Node(s)

chkconfig immuta-query-engine on
service immuta-query-engine start

Web Node(s)

chkconfig immuta-fingerprint on
service immuta-fingerprint start
chkconfig immuta on
service immuta start

9.) Upgrade Verification

Once the upgrade is complete you should verify that the components report the expected version number.

Web Node Upgrade Verification

For the Web Node, upgrade verification can be done using curl. From the Web Service node, run the following command:

curl http://localhost:8080/version

To test TLS connectivity through the Immuta Web Load Balancer, run the following command:

curl -k https://<your Immuta URL>/version

In either case, confirm that the immutaVersion key in the JSON response corresponds to the version that you upgraded to.

Query Engine Upgrade Verification

For the Query Engine, a SQL query can be run against the immuta database to verify the version of the Immuta extension:

Switch users to the immutaqe user, and execute:

psql -d immuta

Then:

select extname, extversion from pg_extension where extname = 'immuta_sql_fdw';

Verify that the extversion value corresponds to the version that you are upgrading to and exit.

[immutaqe@26onel6-2 ~]$ psql -d immuta
psql (11.6)
Type "help" for help.

immuta=# select extname, extversion from pg_extension where extname = 'immuta_sql_fdw';
    extname     | extversion
----------------+------------
immuta_sql_fdw | 2.8.3
(1 row)

immuta=# \q

Lastly, you should also verify the extension versions in the control files:

cat /opt/immuta/postgres-11/share/extension/immuta_sql_fdw.control | grep version

Verify that the default_version values corresponds to the version that you are upgrading to.

10.) Confirm Successful Upgrade

At this point, the upgrade is complete. Confirm full functionality through basic usage of Immuta.