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+) orpostgres
(< 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
If upgrading from Immuta < 2.6
If you get an error like:
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
-------------
yum remove
the offending package (i.e., yum remove immuta
in the case above.)
Note
The immuta-query-engine service may start automatically following the package upgrade. If so,
please stop it prior to running the following commands (as root
).
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
Warning
Though Immuta will import existing ODBC drivers, the drivers may not work if the newer version of Immuta requires a newer version of the ODBC driver than what may have been used before. If the driver does not work simply use the Immuta App Settings UI to re-upload the proper version of the ODBC driver.
5.) Upgrade Web Node(s)
The following commands must be run as
root
:
yum upgrade immuta immuta-fingerprint
If upgrading from Immuta < 2.6
If you needed to uninstall any of these packages in order to install immuta-query-engine
,
please yum install
those packages instead.
-
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.
Example Output
[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.