Update Alation to 2024.1 - 2024.1.3¶
Customer Managed Applies to customer-managed instances of Alation
Warning
If you are updating to version 2024.1.4, use Update Alation to 2024.1.4. The information on this page is only for upgrades to the previous releases 2024.1 - 2024.1.3.
2024.1 Update Version Dependencies¶
Alation supports a direct update to version 2024.1.3 from the following previous versions:
2023.3.x
2023.1.x
Upgrade from Version 2022.4.x or Older¶
Direct update to 2024.1 is not supported from version 2022.4 and older versions. First, update Alation to a version that supports the direct update to 2024.1 and then perform a second update to 2024.1. Use the update instructions specific to your release.
2024.1 Release-Specific Information¶
Note
The full list of new features is available in Release Notes 2024.1 (General Availability).
The Django Component Upgrade to Version 4.2¶
In version 2024.1.3, we have upgraded our software infrastructure to Django 4.2, replacing the end-of-support Django 2.x. This new version contains enhancements that improve the robustness, security, and performance of the Alation application.
Note
ACTION REQUIRED
The Django upgrade impacts the SAML authentication configuration in Microsoft Entra ID (former Azure Active Directory) and Active Directory Federation Service (AD FS) as identity providers (IdPs). The default value of the Name Format property of SAML attributes on the Alation server has been changed to unspecified
from the previous value of URI
. This creates a requirement to explicitly set the Name Format property to URI
or Basic
in the SAML application in Microsoft Entra ID, as it also defaults to Omitted (default)
.
Customers who use Entra ID or AD FS as IdPs must perform an additional configuration in their SAML application before upgrading to version 2024.1.3. Refer to the advisory Important Advisory - SAML authentication failure with Azure/Microsoft IDP and Microsoft ADFS after upgrade to 2024.1.3 on Alation Community for specific details.
PostgreSQL Upgrade to Version 13.13¶
In version 2024.1, Alation’s internal database and the Alation Analytics database were upgraded to version 13.13 to take advantage of new features and to fix vulnerabilities. The upgrade happens automatically during the update to version 2024.1. No additional action is required.
Update Known Issues¶
Reset Postgres Password¶
If you have a password set on the internal PostgreSQL database (Rosemeta), the update 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
The update process 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.
Update Alation to 2024.1¶
Use the steps in this section to update Alation to 2024.1 from versions 2023.3.x and 2023.1.x.
Note
If you are updating from release 2023.1.x and skipping release 2023.3.x, review the information specific to release 2023.3 in the corresponding release notes.
Follow the steps below to update. You may need to perform more or fewer steps depending on the release you are updating from. If a step is Alation version dependent, this is called out in the instructions.
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:
Update on the HA pair:
With splitting the HA cluster: Update HA Pair with Cluster Splitting
Note
See Use Cluster Splitting for HA Pair Update under Update Known Issues for this release.
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: Rebuild Search Index¶
Rebuild your search index if:
Your search index hasn’t been updated since version 2022.4. Even if you’ve updated Alation from version 2023.3.x, the index may still be using the old search schemas.
Determine if Search Index Requires Rebuilding¶
To determine if your search index requires rebuilding:
Use SSH to connect to the Alation server.
Enter the Alation shell using the following command:
sudo /etc/init.d/alation shell
Run the following command to inspect the schema of your search index:
curl localhost:9200/live/_mappings | grep dbtype.
In the output, look for the
dbtype
field output:If you’ve determined that an index rebuild is required, proceed to index rebuilding.
Rebuild Search Index¶
Rebuilding the search index aligns it with the latest search schemas of version 2023.3.5 and can be performed without downtime. For detailed steps, see How to Rebuild Search Index Without Downtime.