Update Alation to 2021.1¶

Customer Managed Applies to customer-managed instances of Alation

2021.1 Update Version Dependencies¶

Alation supports the update to version 2021.1 from the following previous versions:

2020.4.x

2020.3.x

V R7 (5.12.x)

Use the instructions appropriate for your current version.

Releases older than V R7 (5.12.x)¶

Direct update to 2021.1 is not supported. First, update Alation to a version that supports the update to 2021.1 and then perform a second update to 2021.1.

Update from 2021.1 LA to 2021.1 GA¶

Note

This information is only relevant if you are updating a test instance with 2021.1 LA to 2021.1 GA.

If you have Tableau sources configured to use SSL connections, after the update from 2021.1 LA to 2021.1 GA, reload the SSL certificates on the Tableau source Settings page and test the connection.

2021.1 Release-Specific Information¶

Elasticsearch 1.4 removal from the Alation server
Internal codebase upgrade to Python 3
A new version of Alation Analytics V2
A new version of Alation Connector Manager
The Snowflake data source built-in driver updated to version 3.12.14
The Labs tab in Admin Settings renamed to Feature Configuration
The Domains feature with a dedicated feature switch in Admin Settings > Server Admin > Feature Configuration > Data Domains
The Group Role assignment feature with a dedicated feature switch in Admin Settings > Catalog Admin > Groups > Use Custom Groups to assign user roles

For more details on new features, improvements, and bug fixes, see Release Notes 2021.1 (General Availability).

2021.1 Update Known Issue¶

This information only applies if in your instance of Alation, the internal Alation database is protected by a password:

Update to 2021.1.x requires that the Postgres password should be cleared before the update to 2021.1.x and set back after the update is completed. Please contact Alation Support to guide you through the update process if you have a password set for the internal Alation database.

Backup Check¶

Before performing any update actions, ensure that you have the latest valid Alation backup and take and store a backup or a system image, if necessary.

Update 2020.4 To 2021.1¶

STEP 1: Perform Encryption Key Rotation¶

Important

Update to 2021.1 cannot be done if key rotation has never been performed on the instance. The 2021.1 update command will stop with a “key rotation required” warning.

Please plan your Alation upgrade to 2021.1 so that the schedule accommodates for this preparatory step.

If you have not recently done so, perform the encryption key rotation on the Alation Server. On large installations, if key rotation has never been performed before, the initial key rotation may take some time to complete.

Key Rotation on HA Pair¶

Key rotation should be done on the Primary server.

If you plan to update the HA Pair with splitting the cluster, perform key rotation on Primary before splitting the Pair.

After key rotation on the Primary is completed, allow some time for replication to happen between Primary and Secondary. The cluster should be in sync before you update or split and update.

On how to perform key rotation: Encryption Key Rotation

STEP 2: Take an Additional Backup¶

It is highly recommended to take an additional Alation backup after successfully performing key rotation. This backup is required if you have to restore using a 2021.1 build. You cannot restore data that did not have at least one key rotation.

STEP 3: Run a Postgres Scan¶

This step is optional but recommended.

After the encryption key rotation and before updating Alation, scan the internal Postgres database for corrupted indexes. If the scan finds corrupted indexes in Postgres, contact Alation Support to resolve the Postgres problems before updating Alation.

On how to scan Postgres: How to Scan Postgres For Corrupted Indexes

STEP 4: Update Alation To 2021.1¶

Proceed to update the Alation application using the appropriate update instructions:

Manual Software Update for Standalone Systems

Update on the HA Pair:

with splitting the HA cluster: Update HA Pair with Cluster Splitting

without splitting the cluster: Update HA Pair Configuration (4.7 and above)

STEP 5: Perform Post-Update Steps¶

If relevant to your Alation instance:

Perform this step only if using Alation Analytics V2: Update Alation Analytics V2
Perform this step only if using OCF Framework: Update Alation Connector Manager
On instances using the HA Pair configuration: if before the update you had the Backup V2 feature enabled, check the corresponding feature flag after the update. The flag value is reset to the default when the HA cluster is rebuilt. If you use the update scenario with splitting and rebuilding the cluster, you need to re-enable the Backup V2 feature on the Primary instance after updating and rebuilding the HA. On how to enable Backup V2: Enable or Disable Backup V2.

Update V R7 (5.12.x) or 2020.3 To 2021.1¶

This update scenario skips release 2020.4.x which includes a number of major changes to the Alation application. The changes in 2020.4 cause a number of additional checks and steps in the process of updating Alation.

If you have chosen to skip the 2020.4.x release and update to 2021.1 from V R7 or 2020.3, do the following before the upgrade:

Inform yourself on the changes in 2020.3 and 2020.4:
Make a list of post-upgrade steps that may be relevant to your instance in the releases you skip (2020.3 and 2020.4). You will need to address those after the update as well:
- Post-Upgrade Steps 2020.4
- For 2020.3, refer to 2020.3 Release Specific Information
Create an update schedule that accommodates for the required pre-update steps, such as Postgres re-indexing and encryption key rotation (see below) and the post-update steps relevant to your instance.
Make sure you have the latest valid Alation backup.

To update Alation from V R7 or 2020.3 to 2021.1, follow these steps:

STEP 1: Required Checks¶

Internal PostgreSQL upgrade to 9.6 is required
To check your current Postgres version, from the Alation shell, run:

alation_psql
If not 9.6, you need to first Upgrade Internal PostgreSQL Instances from 9.3 to 9.6.
Elasticsearch migration from 1.4 to 7.4 should be complete
To check the Elasticsearch version that is currently in use on your instance, from the Alation shell, run:
alation_conf elasticsearch.backend_mode
It should be set to 2. If you see a different value, you will not be able to update as Elasticsearch migration may not have happened. In this case, contact Alation Support to assist with the update.

STEP 2: Perform Encryption Key Rotation¶

Important

Update to 2021.1 cannot be done if key rotation has never been performed on the instance.

If you have not recently done so, perform the encryption key rotation on the Alation Server. On large instances, if key rotation has never been performed before, the initial key rotation may take up to a week to complete. Please plan your Alation upgrade to 2021.1 so that the schedule accommodates for this preparatory step.

In case of HA Pair configuration, key rotation should be done on the Primary server.

It is recommended to take an Alation backup after performing key rotation.

On how to perform key rotation: Encryption Key Rotation

STEP 3: Take an Additional Backup¶

It is highly recommended to take an additional Alation backup after successfully performing key rotation. This backup is required if you have to restore using a 2021.1 build. You cannot restore data that did not have at least one key rotation.

STEP 4: Run Pre-Upgrade Reindexing Script¶

Running of the re-indexing script is required because of the changes in release 2020.4.

Note

On HA Pair, the reindexing script should be run on the Primary instance.

Copy and save the following script as preupgrade_reindexing.py to /opt/alation/alation/opt/alation/ on the Alation host (path outside the Alation shell): Pre-Update Reindexing Script for 2020.4
Is it recommended to run the script in a Screen session. To start a Screen session:
screen -S reindex_db

From the Alation shell, change user to Alation:

sudo /etc/init.d/alation shell
sudo su alation

Update the permissions on the preupgrade_reindexing.py script so that it can be executed by user alation:

cd /opt/alation/
sudo chown alation:alation preupgrade_reindexing.py
chmod 755 preupgrade_reindexing.py

Run the script from /opt/alation/ (inside the Alation shell) with the command given below. This script stops all Alation services except Postgres. Do not start any of the services while the script is running as this can result in an inconsistent state of the data.
python preupgrade_reindexing.py

The script prints its output to the console and to /opt/alation/site/site_data/pre_upgrade_reindex_rosemeta_db.log (path inside the shell).

Warning

In case the script execution fails, do not proceed with the update. Contact Alation Support to troubleshoot and assist with the next steps.

The time required for reindexing to complete depends on the size of the internal database. During the update, Alation will run a second re-indexing. The update time will be increased by approximately this amount of time when the second reindexing runs automatically during the update.

After the reindexing script completes, proceed to step 5.

STEP 5: Update Alation To 2021.1¶