Update Alation to 2022.3

Customer Managed Applies to customer-managed instances of Alation

2022.3 Update Version Dependencies

Alation supports a direct update to version 2022.3 from the following previous versions:

  • 2022.2.x

  • 2022.1.x

  • 2021.4.x

Version 2021.3.x and Older

Direct update to 2022.3 is not supported from version 2021.3 and older versions. First, update Alation to a version that supports the update to 2022.3 and then perform a second update to 2022.3. Use the update instructions specific to your release.

2022.3 Release-Specific Information

Postgres Upgrade

The internal Alation server database (Postgres) was updated from version 13.1 to version 13.6. No manual actions are required from Alation admins as the database version upgrade happens automatically during the Alation application update.

Elasticsearch Upgrade

The Elasticsearch component of the Alation application was updated to a newer minor version of version 7.17. No manual actions are required from Alation admins as the version upgrade happens automatically during the Alation update.

Case Insensitive Usernames

From version 2022.3, usernames in Alation become case insensitive. This means that usernames differing only in the use of the uppercase or lowercase letters are now considered identical. For example, usernames john.doe and John.Doe are considered identical usernames. The switch-over between case sensitive and case insensitive usernames happens during the update to 2022.3.

With 2022.3, Alation provides a special script for you to ensure there are no duplicate usernames on your instance. The information about the script is included into the update steps below in this guide.

Note

  1. After the update to 2022.3, users will not be able to log in using any of the duplicate usernames. For users to log in, an admin has to de-duplicate their usernames using the script.

  2. If for some reason you want to allow case sensitive usernames, you can explicitly enable username case sensitivity on your instance. After the update, set the alation_conf flag enable_username_case_insensitivity to False to allow case sensitive usernames. On how to use alation_conf, see Using alation_conf.

Alation Server Runs on UTC

The Alation server now runs on UTC. Previously, some of the log files, such as alation-backup.log, used PDT to capture the logs. From this release, the server captures all logs on UTC. The catalog users will continue scheduling extraction, ingestion, queries, and other scheduled processes as before using their local time zone. The server uses the UTC offset to run the jobs on the set schedules.

User Interface for Authentication to Data Sources

In 2022.3, we added a user interface for the configuration of authentication to data sources that goes through AuthService. It is now possible to create AWS, OAuth, and Azure Key Vault plug-in configuration objects in Alation. If you previously set up such configurations on the backend of your Alation instance, they will become viewable in Admin Settings > Authentication > Data Source Authentication Configuration Methods.

Note

The full list of new features is available in Release Notes 2022.3 (General Availability).

Job Schedule Fix

In the 2022.3 release, we introduced a bug that caused the schedule for certain jobs to be shifted eight hours earlier. See Fix Job Schedules after 2022.3 Upgrade for details on how to fix the issue.

Update Alation from 2022.1.x and 2022.2.x to 2022.3

Step 1: Scan Postgres

We recommend using the scan_postgres action to validate that the internal Postgres database is in a healthy state before the update. For steps, see How to Scan Postgres for Corrupted Indexes.

Note

If in your instance the Postgres scan runs on a schedule, you can check the scan-postgres.log file in /opt/alation/site/logs inside the Alation shell to check the Postgres state.

Step 2: Update the Alation Application

Update instructions:

Step 3: Update Alation Analytics V2

Use the steps in Update Alation Analytics V2 to update Alation Analytics V2.

Step 4: Update Alation Connector Manager

Update Alation Connector Manager using the steps in Update Alation Connector Manager.

Step 5: De-duplicate Mixed Case Usernames

After updating the Alation application, validate that your instance does not have mixed case duplicate usernames. From 2022.3, usernames in Alation are treated as case insensitive. To check for duplicates, run a one-off script on the Alation server. For information on how to run the script, refer to De-duplicate Mixed Case Usernames.

Update Alation from 2021.4.x to 2022.3

This update path skips releases 2022.1 and 2022.2. Release 2022.1 includes a number of important changes. Make sure to review the information specific to release 2022.1 and the release notes for 2022.2 to inform yourself on the new features in these releases.

To update Alation:

Step 1: Scan Postgres

We recommend using the scan_postgres action to validate that the internal Postgres database is in a healthy state before the update. For steps, see How to Scan Postgres for Corrupted Indexes.

Note

If in your instance the Postgres scan runs on a schedule, you can check the scan-postgres.log file in /opt/alation/site/logs inside the Alation shell to check the Postgres state.

Step 2: Update the Value of Parameter elasticsearch.env.es_java_opts

Perform this step if you are updating from a version of 2021.1 that is older than 2021.4.4. If you are updating from 2021.4.4 or a newer patch of 2021.1 and have already done this, skip this step. You may have previously changed the value of the alation_conf parameter elasticsearch.env.es_java_opts based on the recommendation in the initial Log4j 2 Security Advisory from December 10, 2021. Before updating Alation, clear the value -Dlog4j2.formatMsgNoLookups=true from elasticsearch.env.es_java_opts and set a new value. See instructions in Validating the Value of Parameter elasticsearch.env.es_java_opts to set the required value.

Step 3: Update the Alation Application

Update instructions:

Step 4: Update Alation Analytics V2

Use the steps in Update Alation Analytics V2 to update Alation Analytics V2.

Step 5: Reset the ETL Checkpoints for Users on Alation Analytics

After updating Alation Analytics, reset the ETL checkpoint for user data to reconcile the existing records due to a fix to the extraction query from the public.users table. This step applies if you are updating from a 2022.1.x version older than 2022.1.4 or a 2021.4.x version older than 2021.4.10. See Resetting ETL Checkpoint for User Data.

Step 6: Update Alation Connector Manager

Update Alation Connector Manager using the steps in Update Alation Connector Manager.

Step 7: De-duplicate Mixed Case Usernames

After updating the Alation application, validate that your instance does not have mixed case duplicate usernames. From 2022.3, usernames in Alation are treated as case insensitive. To check for duplicates, run a one-off script on the Alation server. For information on how to run the script, refer to De-duplicate Mixed Case Usernames.