Update Alation Analytics V2

Customer Managed Applies to customer-managed instances of Alation

Use the steps on this page to update Alation Analytics except for versions listed in the warning below.

Warning

If you are updating from a version that requires the Alation Analytics PostgreSQL database upgrade from version 13 or older to version 16.2 or 16.4, use Update Alation Analytics Database to 16.2 or 16.4 and a Compatible Release. This is relevant to the following updates:

  • From 2023.3.x to 2024.3.1 or 2024.3.2 (upgrade to version 16.4)

  • From 2023.3.x to 2024.3 (upgrade to version 16.2)

  • From 2023.3.x to 2024.1.5 (upgrade to version 16.2)

  • From 2023.3.x to 2024.1.4 (upgrade to version 16.2)

  • From 2024.1.0, 2024.1.1, 2024.1.2.x, or 2024.1.3.x to 2024.3.1 or 2024.3.2 (upgrade to version 16.4)

  • From 2024.1.0, 2024.1.1, 2024.1.2.x, or 2024.1.3.x to 2024.3 (upgrade to version 16.2)

  • From 2024.1.0, 2024.1.1, 2024.1.2.x, or 2024.1.3.x to 2024.1.5 (upgrade to version 16.2)

  • From 2024.1.0, 2024.1.1, 2024.1.2.x, or 2024.1.3.x to 2024.1.4 (upgrade to version 16.2)

The information on this page is for upgrades that do not include the PostgreSQL database upgrade to a newer major version and are not listed above.

The steps below require the role of the Server Admin.

How Do I Know if There is an Update for Alation Analytics V2?

After updating the Alation catalog to a newer version, check the Alation Analytics V2 Settings page in Admin Settings > Alation Analytics. If a newer version of Alation Analytics V2 is available, you will see a warning message that Alation Analytics V2 requires an update: “Your Alation Analytics Version is Outdated”.

../../_images/AAV2_13.png

Note

If the Alation Analytics V2 version becomes outdated, Server Admins will receive an email notification that it requires an update when the next scheduled Alation Analytics V2 ETL is attempted by Alation.

When the Alation Analytics version becomes outdated after the Alation catalog update, the ETL process is stopped until the Alation Analytics component is updated to the same version as the catalog.

Steps to Update Alation Analytics V2

Each Alation release comes bundled with a compatible Alation Analytics V2 package which also includes the update files. To update Alation Analytics, download the new Alation Analytics V2 bundle and then run the Alation Analytics V2 installer with the update option.

Starting from version 2021.3, Alation Analytics V2 installer supports assigning a user to own the Alation Analytics V2 directories, config file, and logs. In earlier versions, the ownership was assigned to the root user by default. Now, it can be assigned to any user on the Alation Analytics V2 host.

Assigning ownership to a user other than the default root is an explicit choice. It can be done when the username flag -w is passed with the installer commands.

Note

The user who is assigned Alation Analytics V2 ownership will have access to:

  • The Alation Analytics V2 installation directory and all its subdirectories except the Postgres data directory (default: /opt/alation-analytics)

  • The environment file /etc/default/alation-analytics

  • The logs directory /var/log/alation-analytics

  • Permissions to run the docker commands such as docker ps or docker logs.

Follow the steps below to update your Alation Analytics V2 components:

  1. Open a Terminal window and SSH to your Alation Analytics V2 host.

  2. Create a temporary directory, for example, tmp/update-analytics:

    sudo mkdir /tmp/update-analytics

    Note

    Do not use the installation directory /opt/alation-analytics/ to create a temporary directory and extract the update package. Create a custom temporary directory that is located elsewhere and not at /opt/alation-analytics/.

  3. In your browser, log in to the Alation Catalog and go to Admin Settings > Alation Analytics. There will be a warning message on top of the page when Alation Analytics V2 requires an update.

  4. In step 1 of the installation instructions on the Settings page, copy the Curl command for downloading the newer version and paste it into the Terminal window that is already SSH’ed into the Alation Analytics V2 host.

  5. Untar the downloaded Alation Analytics V2 .tar file into the temporary directory that you created in the previous step:

    sudo tar -C /tmp/update-analytics -xzf ./alation-analytics-<version>.tar

  6. Determine whether you need to use one of the available installation flags:

    Flag

    Description

    -w

    Available in 2021.3 and newer

    Lets you specify which system user will own the installed files, configs, and logs.

    Without this flag, ownership will be assigned to the root user.

    -b

    Available in 2023.1.4 and newer

    Traffic to the Postgres and RabbitMQ containers will be bound to a specific IP address. The address will be stored in /etc/default/alation-analytics.env.

    Without this flag, the Postgres and RabbitMQ containers are exposed on all network interfaces (0.0.0.0) in the host.

  7. Run the installer script with the update flag -u to update Alation Analytics V2. Run the installer as the root user (if you installed rootless Docker during the original installation) or using sudo. The installer stops the current Alation Analytics V2 Docker containers and Alation Analytics Manager, removes the outdated images from Docker, moves the contents of the new images and Manager to the installation directory, and registers and starts the new images and Manager.

    • To update with no additional flags:

      sudo /tmp/update-analytics/alation-analytics-<version>/alation-analytics-installer-<version> -u

      Example:

      sudo /tmp/update-analytics/alation-analytics-1.1.0.139590/alation-analytics-installer-v-1.0.18 -u

    • Applies to version 2021.3 and newer: To update and change the ownership to a different user, run the update command with the flag -w, as shown below, and follow the prompts in the console to provide a new username.

      sudo /tmp/update-analytics/alation-analytics-<version>/alation-analytics-installer-v-x.x.x -u -w <username>

      Example:

      sudo /tmp/update-analytics/alation-analytics-<version>/alation-analytics-installer-v-x.x.x -u -w aav2_admin

    • Applies to version 2023.1.4 and newer: To update and bind incoming traffic to a specific IP address, run the update command with the flag -b:

      sudo /tmp/update-analytics/alation-analytics-<version>/alation-analytics-installer-v-x.x.x -u -b <ip_address>

      Example:

      sudo /tmp/update-analytics/alation-analytics-<version>/alation-analytics-installer-v-x.x.x -u -b 10.13.14.108

  1. Applies to version 2023.3.2 and newer: The RabbitMQ component requires basic authentication. If you haven’t set a RabbitMQ password yet, the Alation Analytics updater will automatically generate one for you and display it in the console when you run the update command. Copy and securely store this password. You’ll need to set it in alation_conf in a subsequent step of this instruction.

    ../../_images/AA_V2_Update_RMQ_Password.png

  2. If the RabbitMQ password was generated for your instance during the update, then after the update, use alation_conf to set it in the parameter alation_analytics-v2.rmq.config.password:

    1. On the Alation server, enter the Alation shell.

      sudo /etc/init.d/alation shell

    2. Change to the alation user.

      sudo su alation

    3. Set the value in alation_conf.

      alation_conf alation_analytics-v2.rmq.config.password -s 'your_password'

    4. Restart the Celery and Web components.

      alation_supervisor restart celery:* web:*

    Note

    For more details about alation_conf, refer to Using alation_conf.

  3. Go back to the web browser with the Alation Analytics Settings page. In the Alation Analytics installation instructions section, click the Initiate Analytics Database button to run the migration and finalize the update. The new version will be displayed on the Alation Analytics Settings page as Current installed version.

    Note

    The aamanager service may not start automatically after the update of Alation Analytics.

    To check the status of aamanager, on the Alation Analytics host, use the command sudo service aamanager status.

    To start it manually, use the command: sudo service aamanager start.