Update Alation to 2023.3 (On premise only)

2023.3 Update Version Dependencies

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

  • 2023.1.x

  • 2022.4.x

Version 2022.3.x and Older

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

2023.3 Release-Specific Information

Note

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

Postgres Upgrade

The Postgres component (the internal PostgreSQL database) was upgraded from version 13.8 to version 13.11 to take advantage of improvements and bug fixes in the newer version. No manual action is required from Alation admins as the database version upgrade happens automatically during the Alation update.

Alation Analytics PostgreSQL Upgrade

The Alation Analytics database was upgraded from version 13.8 to version 13.11. No additional manual actions are required from Alation admins as the Alation Analytics database version upgrade happens automatically during the update of the Alation Analytics application.

Support for Larger Volumes of Metadata

We’ve made some updates to the Alation database schema to support larger volumes of metadata. This means you can now ingest more metadata on a frequent basis without running into issues with integer overflow. Note that the migrations during the upgrade could add an additional 30 minutes depending on the volume of your metadata.

Update Known Issues

Reset Postgres Password

If you have a password set on the internal PostgreSQL database (Rosemeta), the update to 2023.1 will result in an error similar to the following:

WARN: unable to check pg-1: [DbConnectError] unable to connect to 'dbname='postgres' port=5432':
FATAL: password authentication failed for user "postgres"
password retrieved from file "/home/postgres/.pgpass"
ERROR: [056]: unable to find primary cluster - cannot proceed

Update to 2023.1 requires that the password on the internal PostgreSQL database should be cleared for the time of the update. The password can be set again after the update is completed. On how to set the Postgres password, see Set Password for Internal PostgreSQL Instances.

Use Cluster Splitting for HA Pair Update

The Alation update of an HA pair without splitting the cluster fails. We recommend upgrading HA instances using the cluster splitting upgrade method until this issue is resolved.

Index Row Size Error

If during the upgrade you run into the error below, refer to this troubleshooting article in Alation’s Knowledge Base. Contact Alation Support if you require help with this issue or if you have questions about any of the troubleshooting steps.

psycopg2.errors.ProgramLimitExceeded: index row size 2712 exceeds
btree version 4 maximum 2704 for index "rosemeta_attributevalue_attr_id_value_5fee90cc_uniq"
DETAIL:  Index row references tuple (304577,3) in relation "rosemeta_attributevalue".
HINT:  Values larger than 1/3 of a buffer page cannot be indexed.
Consider a function index of an MD5 hash of the value, or use full text indexing.

Update Alation to 2023.3

Use the steps in this section to update Alation to 2023.3 from versions 2023.1.x and 2022.4.x.

Note

If you are updating from release 2022.4.x and skipping release 2023.1, review the information specific to release 2023.1 in the corresponding release notes.

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: Verify Backup Availability

Ensure you have a valid latest Alation backup.

Step 3: Update the Alation Application

Update instructions:

Step 4: Update Alation Connector Manager

This step applies if you are using Open Connector Framework (OCF) and OCF connectors.

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

Step 5: Update Alation Analytics

This step applies if you are using the Alation Analytics application.

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

Step 6: Take a Full Manual Backup

This step applies if you have updated Alation from 2022.4.x to 2023.3. The upgrade from 2022.4.x skips release 2023.1, where the default backup tool was changed to pgBackRest. If you have updated Alation from 2023.1 to 2023.3, this section does not apply and you can skip it.

Take a full manual backup to ensure that you have the first full backup of the updated instance taken with pgBackRest.

Step 7: Run Alation Analytics Scripts

This step applies if you are using Alation Analytics and have updated Alation and Alation Analytics from 2022.4.x to 2023.3. If you have updated Alation and Alation Analytics from 2023.1 to 2023.3, this section does not apply and you can skip it.

In 2023.1, we optimized the migrations of the database which were slowing down the upgrade of the Alation Analytics app. To apply the change, run the two scripts described below. In case of the HA pair configuration, run the scripts on the primary server.

  1. Enter the Alation shell. You should be in the Alation shell to tail the log files and to run the scripts.

    sudo /etc/init.d/alation shell

  2. Make sure that the Alation Analytics ETL process is not running. The scripts should not be executed when the ETL process is running. You can check this by logging in to Alation, navigating to Admin Settings > Monitor > Active Tasks and making sure that the Alation Analytics ETL (alation_analytics_v2.tasks.etl_manager.ETLManager) job is not listed as an active task. Alternatively, you can use the tail command on the celery-alationanalytics_error.log file from the Alation shell. If Alation Analytics ETL is running, the log will be printing messages similar to the following:

    {"message": "ETL job manager has been triggered to run.", "timestamp": "2023-08-25T09:50:31.644434Z", "level": "INFO"}
{"message": "Created channel=1", "timestamp": "2023-08-25T09:50:31.651979Z", "level": "INFO"}
{"message": "Starting TimePeriodExtractJob", "timestamp": "2023-08-25T09:50:31.654666Z", "level": "INFO"}
{"message": "Starting UserExtractJob", "timestamp": "2023-08-25T09:50:31.685582Z", "level": "INFO"}
{"message": "Starting AlationGroupExtractJob", "timestamp": "2023-08-25T09:50:31.725311Z", "level": "INFO"}
{"message": "Starting UserGroupMembershipExtractJob", "timestamp": "2023-08-25T09:50:31.761310Z", "level": "INFO"}

To tail the log:

tail -f /opt/alation/site/logs/celery-alationanalytics_error.log

After ensuring that the ETL process is not running, from the Alation shell, change the user to alation.

sudo su alation

  1. Navigate to the directory /opt/alation/django/alation_analytics_v2/one_off_scripts/.

    cd /opt/alation/django/alation_analytics_v2/one_off_scripts/

  2. Run the flags script with the command below. The logs will be redirected to the reconcile_flag.log file.

    nohup python -u reconcile_flag.pyc >> reconcile_flag.log &

  3. This command will launch a process with a PID. Save the PID value as you may need it. You can monitor this process by either tailing the corresponding log inside of the Alation shell or checking on the corresponding PID outside of the Alation shell.

    5.1 To use the log for monitoring, in a separate Terminal window, from the Alation shell, tail the reconcile_flag.log file. When the script run is completed, you should see a message that the flags have been reconciled and the number of flags. Execution errors, should any occur, will be printed to the log too. Contact Alation Support if the script execution ends in an error.

    tail -f /opt/alation/django/alation_analytics_v2/one_off_scripts/reconcile_flag.log

    5.2 To check if the process is still active, in a Terminal window connected to the Alation host, outside of the Alation shell, use the command below to list the current processes and check if there is a process with the corresponding PID.

    ps -a

  4. After completing the flags script, in a similar way, run the script to reconcile tags. The script should also be run from the directory /opt/alation/django/alation_analytics_v2/one_off_scripts/ in the Alation shell and as user alation.

    nohup python -u reconcile_tags.pyc >> reconcile_tags.log &

  5. This command will launch a process with a PID. Save the PID value as you may need it. You can monitor this process by either tailing the corresponding log inside of the Alation shell or checking on the corresponding PID outside of the Alation shell.

    7.1 To use the log for monitoring, in a separate Terminal window, from the Alation shell, tail the reconcile_tags.log file. When the script run is completed, you should see a message that the tags have been reconciled and the number of tags. Execution errors, should any occur, will be printed to the log too. Contact Alation Support if the script execution ends in an error.

    tail -f /opt/alation/django/alation_analytics_v2/one_off_scripts/reconcile_tags.log

    7.2 To check if the process is still active, in a Terminal window connected to the Alation host, outside of the Alation shell, use the command below to list the current processes and check if there is a process with the corresponding PID.

    ps -a

  6. After completing the scripts, to exit from the user alation, use the exit command.

Important

Depending on whether or not you have to perform other post-upgrade actions, consider taking a second full backup after running these scripts.

If none of the next steps apply to your instance, we recommend creating a second backup after running the Alation Analytics scripts. If your instance is large and this requirement is not feasible, you can plan to take the next backup on your schedule. However, if there is a need to restore from a backup that was taken before applying the scripts, you’ll need to run the scripts again on the restored instance.

If you have more scripts to run after the update, consider taking a second full backup after running all the scripts.