Skip to main content

Home

Upgrading Unravel Databricks to 4.7.9.6 version

This topic provides instructions to upgrade Unravel Databricks to version4.7.9.6.

The following upgrade paths are supported:

Note

For Databricks v4.7.9.6, the latest Unravel version you can upgrade from is v4.7.9.5.

  • 4.7.x (Databricks release) → 4.7.9.6

Before you upgrade to v 4.7.9.6

Before you upgrade to Unravel (Cloud), do the following:

Backup the data directory

Take a backup of the data directory and the external database if you use one. For backup and recovery, refer to Backing up and recovering Unravel.

Note

If an upgrade fails, you can roll back the upgrade to the release from which you had upgraded. For information, see Rollback after a failed upgrade. For this rollback to work, you must ensure to take a backup of the data directory and the external database before you upgrade.

Upgrading Unravel to v 4.7.9.6

  1. Go to the Download section. The complete list of Unravel downloads is available in this section.

  2. Download the Unravel version that you want to upgrade. The section provides the details and necessary instructions to download Unravel.

  3. Extract the Unravel binaries of the Unravel version you want to upgrade.

    tar zxf unravel-<version>tar.gz -C </path/to/installation/directory>

    For example: tar zxf unravel-4.7.9.5.tar.gz -C /opt

  4. Stop Unravel.

    <Unravel installation directory>/unravel/manager stop

  5. Activate Unravel version 4.7.9.6.

    <Unravel installation directory>/unravel/manager activate 4.7.9.6

  6. Start all the services.

    <unravel installation directory>/unravel/manager start

  7. Check the status of the services.

    <unravel_installation_directory>/unravel/manager report

    The following service statuses are reported:

    • OK: Service is up and running.

    • Not Monitored: Service is not running. (Has stopped or has failed to start)

    • Initializing: Services are starting up.

    • Does not exist: The process unexpectedly disappeared. A restart will be attempted 10 times.

  8. Delete the previous installation directory from unravel/versions/<THE.OLD.VERSION>.

Important

Ensure to perform the post-upgrade steps. Refer to Post upgrade steps .

Post upgrade steps

After you upgrade Unravel, do the following:

Set the public hostname/IP for your Unravel server

By default, unravel uses the server name and unravel's UI ports and TLS configuration when generating URLs, this allows you to specify a different name, port or generating https URLs without enabling TLS on the unravel side. To set the public hostname/IP for your Unraver server, run the following manager command:

Note

This is an optional step and is only needed if the default setup doesn't work.

manager config set public_hostname {host} {port} {--tls} {--no-tls}

Here:

{host}: The public hostname or IP address.

{port}: The port number on which the server will accept connections.

{--tls}: Use this if you want TLS to be terminated in front of the Unravel server without enabling TLS on the Unravel side.

{--no-tls}: Use this if you do not want TLS termination.

For example:

manager config set public_hostname unravel.example.com 1234 --tls

With this, unravel will generate URL like: https://unravel.example.com:1234.

Replacing the existing cost files

  1. Go to {unravel_install_dir}/versions/{unravel_version}/core/etc/dbx/cost.

  2. Copy the following files:

    • prices_workload_tier_aws.tsv

    • prices_workload_tier_azure.tsv

  3. Paste the copied files and replace the existing files in this location:

    {unravel_install_dir}/data/conf/cost

Enabling the Global init script

Global init is deployed automatically on the Workspace and needs to be enabled manually from the location shown in the following image:

Global-init.png

You can now find the Global initialization script in your workspace at this path: /Workspace/Unravel/install-unravel.sh

dbx-new-4780hf-globalinit-script.png

This script is copied as the Global init script for new installations, upgrades, or when you add a new workspace. If it does not copy automatically, you can manually copy it from this file: Unravel/install-unravel.sh

Configuring the cluster init script

You can now configure the cluster init script from the workspace by following these steps.

  1. Go to Unravel UI, and click Manage > Workspaces, and select the Workspace URL.

  2. Sign in to the workspace.

  3. Access the required cluster you want to monitor through Unravel.

  4. Set the path as: /unravel/install-unravel.sh.

    dbx-new-4780hf-cluster-level-init-script.png

    Note

    Prior to configuring the new cluster-level init script, ensure you remove any existing cluster-level init script configurations that are pointing to the DBFS location. For cluster-level init script setup, make sure to configure it using the workspace file path: /unravel/install-unravel.sh.

Managing tokens for workspace access

If you have a premium workspace and the workspace access control is enabled, you must provide the appropriate tokens when adding a workspace. The type of token required depends on whether the workspace is an Admin workspace or a read-only (RO) workspace.

  • Admin workspaces

    • Admin access token

    • Token of a user who has Can Manage permission on Workspace

  • Read-only (RO) workspaces

    Navigate to Workspace Settings > Access Tokens > Manage Tokens and generate a Read-Only Access Token.

Setting the backward compatibility for init scripts

To maintain the backward compatibility of your init scripts, run the following command:

<Installation_directory>/unravel/manager config databricks copy-to-dbfs --id <workspace-id> --unsafe-copy-init-to-dbfs

This command copies the init scripts to the DBFS (Databricks File System) location, specifically the dbin folder. By default, during workspace addition, updates, or Unravel upgrades, the dbin folder can be removed. However, running this command prevents its removal and guarantees that it is also transferred to the DBFS.

For example:

/opt/unravel/manager config databricks copy-to-dbfs --id 6679977360960347 --unsafe-copy-init-to-dbfs

Alternatively, you can use the --all option in the command instead of specifying --id for a single workspace. This streamlined approach ensures that the same step is applied to all currently registered or added workspaces in Unravel.

For example:

/opt/unravel/manager config databricks copy-to-dbfs

Start the Insights Service

  1. Run the following command to download the insights_service binary.

    wget https://preview.unraveldata.com/unravel/RPM/insights_service/release/hotfix_4.7.9.6/insights_service.zip

  2. Extract the binary to the apps directory.

    unzip insights_service.zip -d /opt/unravel/data/apps

  3. Create a logs directory. Ensure that the logs directory exists inside the insights_service directory:

    mkdir /opt/unravel/data/apps/insights_service/logs

  4. Run the start-insights-service.sh script.

    Update the parameters as shown in the following example:

    • Java Home: /opt/unravel/versions/4.7.9.6-hotfix.8609/java

    • Log Location: /opt/unravel/data/apps/insights_service/logs

    • Unravel Properties Location: /opt/unravel/data/conf/unravel.properties

    Script example:

    ./start-insights-service.sh /opt/unravel/versions/4.7.9.6-hotfix.8609/java /opt/unravel/data/apps/insights_service/logs /opt/unravel/data/conf/unravel.properties

  5. Stop the Insights Service.

    ./stop-insights-service.sh

Update the ROI template

After upgrading to Unravel 4796-hotfix, you must run the update_roi_template.sh script to update the ROI template.

  1. Navigate to the script location.

    cd <unravel_installation_directory>/services/insights_worker_1_1/

  2. Run the update_roi_template.sh script.

    Pass the following two parameters to the script:

    For example: 

    ./update_roi_template.sh localhost 4171

    Make sure to replace localhost and 4171 with the actual values from your Unravel properties file.

    • ES_host: The Elasticsearch host from unravel.properties (com.unraveldata.elasticsearch.url).

    • ES_port: The Elasticsearch port from unravel.properties (com.unraveldata.es.port).

Deprecate and Clean Up Non-Actionable Events

After upgrading, deprecated events must be cleaned up to ensure the insights function properly. This script should be run after all the services are up and running.

  1. Navigate to the path /opt/unravel/services/insights_worker_1_1.

  2. Run the script deprecate_events.sh to clean up the deprecated events:

    cd /opt/unravel/services/insights_worker_1_1
./deprecate_events.sh

Regrouping multiple Spark worker instances for enhanced performance (Optional)

Caution

The following task requires planning and should be performed only in collaboration with Unravel support team. This is a one-time task.

Spark worker is multi-threaded from Unravel version 4.7.8.0. After installation or upgrade, you can migrate a setup with multiple Spark worker instances with consumers to a setup with a single Spark Worker with multiple consumers.

When you run the following command, the number of Spark workers and the number of consumers configured get regrouped under a single Spark worker with an equivalent number of consumers.

In the following illustrated example, three Spark workers with three consumers each get regrouped into one Spark worker with nine consumers.

Spark-coaelse.png

Caution

To avoid out-of-memory issues, you must review the memory configuration and ensure that you have sufficient memory.

To regroup multiple Spark worker instances with consumers, do the following:

  1. Stop Unravel on the worker node. 

    /<unravel_installation_directory>/unravel/manager stop

  2. Check the number of Spark workers that are configured. 

    /<unravel_installation_directory>/unravel/manager config worker show

  3. Check the status of memory.

    /<unravel_installation_directory>/unravel/manager config memory show

  4. Run the following command: 

    <unravel_installation_directory>/unravel/manager config worker coalesce spark_worker

  5. Apply the changes.

    <Unravel installation directory>/unravel/manager config apply

  6. Check the status of memory again to ensure that the total memory for the Spark worker is sufficient. If you want to set more memory per consumer, refer to Set memory for Spark worker per consumer.

    /<unravel_installation_directory>/unravel/manager config memory show

  7. Start Unravel on the Spark worker node. 

    /<unravel_installation_directory>/unravel/manager start

Troubleshooting

PostgreSQL fails while upgrading

PostgreSQL is upgraded to 15.5 from Unravel version 4.7.9.4 onwards. However, if the PostgreSQL fails during the upgrade, do any of the following based on the urgency:

  • Roll forward with the upgrade

    This is the recommended method.

  • Rollback the upgrade

    Caution

    You can perform a rollback to troubleshoot the PostgreSQL upgrade failure only with Unravel support assistance. The preferred solution is to fix the upgrade issues and roll forward. The rollback should only be done if the upgrade issue cannot be resolved in a timely manner, and Unravel must be brought back online.

In this section: