Skip to main content

Home

Upgrading Unravel from version 4.7.x to 4.7.9.x

This topic provides instructions to upgrade Unravel from version v4.7.0.x, v4.7.1.x, v4.7.2.x, 4.7.3.x, 4.7.4.x, v4.7.5.x to v4.7.9.x for the on-prem platforms (single cluster and multi-cluster deployments):

  • Cloudera Distribution of Apache Hadoop (CDH)

  • Cloudera Data Platform (CDP)

  • Hortonworks Data Platform (HDP)

The following upgrade paths are supported:

  • 4.7.5.x → 4.7.9.x

  • 4.7.5.x Hot fix → 4.7.9.x

  • 4.7.4.x → 4.7.9.x

  • 4.7.3.x → 4.7.9.x

  • 4.7.2.x → 4.7.9.x

  • 4.7.1.x → 4.7.9.x

  • 4.7.0.x → 4.7.9.x

  • 4.6.1.9  → 4.7.9.x

  • 4.6.1.8 or earlier → 4.6.1.9 → 4.7.9.x

Before you upgrade Unravel for on-prem platforms (CDH, CDP, HDP)

  • Backup the data directory

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

    Note

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

    For more such troubleshooting issues, refer to the Troubleshooting guide.

  • Configure custom JDK, if you have a different version of JDK installed

    Unravel requires Java Runtime Environment (JRE), and hence it is shipped with OpenJDK version 17.0.1. If you have a different version of JDK installed, you must configure Unravel to access the corresponding jre directory in that JDK. For instructions, refer to Configuring custom JDK.

    In a multi-cluster deployment, you must configure the jre directory on both the edge and the core nodes.

  • Remove ondemand_flask_1 enty from unravel.yaml file

    If you have configured custom ports and you want to upgrade from v4.7.4.3 to 4.7.9.1 version, ensure to remove the ondemand_flask_1 entry from the <unravel_installation_directory>/unravel/data/conf/unravel.yaml file.

          notebook_1:       
        config:
          network:
            port: 55004
      ondemand_flask_1:
        config:
          port: 55014

    If you do not remove this entry, then the following error message is displayed:

    Skipping unknown entry for host 'host_main’

    You can also do this step post-upgrade.

Upgrade Unravel for on-prem platforms (v4.7.x to v4.7.9.x)

You can upgrade Unravel for the single cluster as well as multi-cluster deployments. Refer to the following:

Important

Ensure to perform the post-upgrade steps. Refer to Post upgrade steps for on-prem platforms (v4.7.x to v4.7.9.x).

Upgrade Unravel in a single cluster deployment (v4.7.x to v4.7.9.x)

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

  2. Select and 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.x.tar.gz -C /opt

    Note

    The default installation directory is /usr/local for RPM installation. This might have changed during the initial deployment. Make sure that you use the same installation directory when you upgrade Unravel.

  4. Stop Unravel.

    <Unravel installation directory>/unravel/manager stop

  5. Activate Unravel version 4.7.9.x

    <Unravel installation directory>/unravel/manager activate <version>

    Note

    For on-prem platforms (CDH, CDP, HDP, or MapR), If you have used an automatic Hadoop configuration, run auto-configuration and refresh to reload the updates automatically.

    <unravel_installation_directory>/unravel/manager config auto --refresh

  6. Set Unravel license. Changing the license is mandatory. Contact Unravel Customer Support to get a new license file.

    <Unravel installation directory>/unravel/manager config license set <path to license file>

    For example:

    Example: /opt/unravel/manager config license set /tmp/license.txt

    For more information about setting the license file, see Setting Unravel license.

  7. Apply the changes.

    <unravel_installation_directory>/unravel/manager config apply

  8. Start all the services.

    <unravel_installation_directory>/unravel/manager start

  9. 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.

  10. Validate the JAVA version that Unravel is using now.

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

Upgrade Unravel in multi-cluster deployment (v4.7.x to v4.7.9.x)

To upgrade Unravel in a multi-cluster environment, you must upgrade all the edge nodes, upgrade the core node, and pull all the edge node updates to the core node.

  1. Edge nodes

    Run the following steps to upgrade Unravel on the edge nodes involved in Unravel monitoring.

    1. Go to the Download page.

    2. Click the Unravel version you want to upgrade to and run the commands provided 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.x.tar.gz -C /opt

      Note

      The default installation directory is /usr/local for RPM installation. This might have changed during the initial deployment. Make sure that you use the same installation directory when you upgrade Unravel.

    4. Stop Unravel.

      <Unravel installation directory>/unravel/manager stop

    5. Activate the version that you want to upgrade. 

      <Unravel installation directory>/unravel/manager activate <version>

      Caution

      You may get a Network port failed precheck error if you run the manager activate command immediately after executing the manager stop command.

      To avoid this precheck error, stop Unravel and wait a minute or two before executing the manager activate command.

      Retry the manager activate command in case of the Network port failed precheck error.

    6. Set Unravel license. Changing the license is mandatory. Contact Unravel Customer Support to get a new license file.

      <Unravel installation directory>/unravel/manager config license set <path to license file>

      For example:

      Example: /opt/unravel/manager config license set /tmp/license.txt

      For more information about setting the license file, see Setting Unravel license.

    7. If you have used an automatic Hadoop configuration, run auto-configuration and refresh to reload the updates automatically.

      <unravel_installation_directory>/unravel/manager config auto --refresh

    8. Apply the changes. 

      <unravel_installation_directory>/unravel/manager config apply

    9. Start all the services.

      <unravel_installation_directory>/unravel/manager start

    10. Check the status of 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. Restarts will be attempted 10 times.

    11. Validate the JAVA version that Unravel is using now.

  2. Core node

    Run the following steps only on the core node.

    1. Download Unravel.

    2. 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.x.tar.gz -C /opt

    3. Stop Unravel.

      <Unravel installation directory>/unravel/manager stop

    4. Activate the version that you want to upgrade.

      <Unravel installation directory>/unravel/manager activate <version>

    5. Set Unravel license. Changing the license is mandatory. Contact Unravel Customer Support to get a new license file.

      <Unravel installation directory>/unravel/manager config license set <path to license file>

      For example:

      Example: /opt/unravel/manager config license set /tmp/license.txt

      For more information about setting the license file, see Setting Unravel license.

    6. Run auto-configuration on the core node and refresh to reload the updates automatically. Run this command only if you have previously run the config auto command on the cluster. This is an optional step. 

      <unravel_installation_directory>/unravel/manager config auto --refresh

      Caution

      If you have NOT run the manager config auto earlier on the core node, an error will be displayed, which you can ignore.

    7. Find the edge key using the manager config edge show command, keep it handy, and run the following command for each configured edge node. This refreshes the configurations on the edge nodes. Provide the edge key when prompted: 

      <unravel_installation_directory>/unravel/manager config edge auto --refresh

      For example:

      /opt/unravel/manager config edge auto --refresh
-- Running: config edge auto --refresh
2021-09-22 03:32:25 Archiving configuration ... Ok
Edge key: edge-tnode39

    8. The Hive metastore database password can be recovered automatically only for a cluster manager with an administrative account. Otherwise, you must manually set the password as follows:

      1. Run the manager config edge show command to get the <EDGE_KEY>, <HIVE_KEY>, and <CLUSTER_KEY>, which must be provided when you set the Hive metastore password.

        • <EDGE_KEY> is the label you provide to identify the edge node when you add the edge node in Step 3.

        • CLUSTER_KEY is the name of the cluster where you set the Hive configurations.

        • <HIVE_KEY> is the definition of the Hive service. In the manager config edge show command output, this is shown as the <SERVICE_KEY> for Hive. 

        -- Running: config edge show
------------ | ---------------------------------------- | ------------
    EDGE KEY | - edge-a                                 | Enabled
             |     Cluster manager:                     | Enabled
             |     Clusters:                            | 
 CLUSTER KEY |       - Cluster_Name                     | Enabled
             |           HBASE:                         | 
 SERVICE KEY |             - hbase                      | Enabled
             |           HDFS:                          | 
 SERVICE KEY |             - hdfs                       | Enabled
             |           HIVE:                          | 
 SERVICE KEY |             - hive                       | Enabled
 SERVICE KEY |             - hive2                      | Enabled
             |           IMPALA:                        | 
 SERVICE KEY |             - impala                     | Enabled
 SERVICE KEY |             - impala2                    | Enabled
             |           KAFKA:                         | 
 SERVICE KEY |             - kafka                      | Enabled
 SERVICE KEY |             - kafka2                     | Enabled
             |           SPARK_ON_YARN:                 | 
 SERVICE KEY |             - spark_on_yarn              | Enabled
             |           YARN:                          | 
 SERVICE KEY |             - yarn                       | Enabled
             |           ZOOKEEPER:                     | 
 SERVICE KEY |             - zookeeper                  | Enabled
------------ | ---------------------------------------- | ------------
-- OK

      2. In a multi-cluster deployment, where edge nodes are monitoring, set the password on the core node as follows:

        <Unravel installation directory>/unravel/manager config edge hive metastore password <EDGE_KEY> <CLUSTER-KEY> <HIVE-KEY> <password> 
##Example: /opt/unravel/manager config edge hive metastore password local-node cluster1 hive password

        In case the core node is monitoring the Hadoop cluster directly, run the following command from the core node. 

        <Unravel installation directory>/unravel/manager config hive metastore password <CLUSTER_KEY> <HIVE_KEY> <password> 
##Example: /opt/unravel/unravel/manager config edge hive metastore password cluster1 hive P@SSw0rd

    9. Apply the changes. 

      <unravel_installation_directory>/unravel/manager config apply

    10. Start all the services.

      <unravel_installation_directory>/unravel/manager start

    11. Check the status of services.

      <unravel_installation_directory>/unravel/manager report

    12. Delete the old install directory from unravel/versions/<THE.OLD.VERSION>.

Important

Ensure to perform the post-upgrade steps. Refer to Post upgrade steps for on-prem platforms (v4.7.x to v4.7.9.x).

Post upgrade steps for on-prem platforms (v4.7.x to v4.7.9.x)

After you upgrade Unravel, set the following:

Upgrade Unravel sensors

Refer to Upgrading sensors.

Important

In a multi-cluster deployment, upgrading the core node is mandatory before upgrading the sensors on the edge node.

Validate the JAVA version of Unravel

If you have configured the custom JDK, then after upgrading, validate the JAVA version of Unravel.

  1. Go to Unravel node and sign in as unravel user. In the case of multi-cluster, go to Unravel edge node.

  2. Run the following command:

    ps -ef | grep unravel | grep java

    For example, the following output is shown:

    unravel 26871 1 1 Jul05 ? 00:30:43 /tmp/jdk1.8.0_112/jre/bin/java -server -Dident=unravel_taw_1 -Dunravel.log.dir=/opt/unravel/logs -Dhadoop.version= -Djdbc.driver.jar=com.mysql.jdbc.Driver -Dhadoop.conf.dir=/etc/hadoop/conf -Djava.awt.headless=true -Djava.net.preferIPv4Stack=true -Dnetworkaddress.cache.ttl=30 -Dsun.net.inetaddr.ttl=30 -Xmx6g -Xms1g -Dvertx.cacheDirBase=/opt/unravel/tmp/ver

    In the above example, Unravel has selected the Java version /tmp/jdk1.8.0_112/jre/bin/java.

  3. You can further validate the Java version. For example, run the following command: 

    /tmp/jdk1.8.0_112/jre/bin/java -version
Enable Migration reports (Optional)

If you had migrations reports on CDH or CDP clusters, you must run the following steps to continue using the migration reports.

  1. Stop Unravel.

    <Unravel installation directory>/unravel/manager stop

  2. Enable the Migration reports as an admin user. Run the following command:

    <Unravel installation directory>/unravel/manager config ondemand cloud-migration enable

  3. Apply changes. 

    <Unravel installation directory>/unravel/manager config apply

  4. Start Unravel.

    <Unravel installation directory>/unravel/manager start

    The Migration tab will be visible on the Unravel UI. Also, refer to the Migrations topics for more details.Migrations

Enable SSL/TLS support for external MySQL

After you upgrade, you can set the SSL/TLS support for external MySQL.

Important

You can enable the SSL/TLS support only for MySQL version 8.

  1. Stop Unravel.

    <Unravel installation directory>/unravel/manager stop

  2. Use an editor to open <Installation_directory>/unravel/data/conf/unravel.yaml file.

  3. In the unravel.yaml file, change tls value to true. 

    database:
    external: true
    hostname: <hostname>
    port: 'port'
    schema: unravel_db_prod
    tls: true
    type: mysql
    username: <username>
    password: <encrypted password>

  4. Apply the changes. 

    <Unravel installation directory>/unravel/manager config apply

  5. Start Unravel.

    <Unravel installation directory>/unravel/manager start
Re-configure the custom ports after upgrading from versions before v4.6.1.9

In case, for an Unravel version prior to v4.6.1.9, you have a customized UI port, for example, 4000, then after the upgrade, this port reverts to the default 3000. Hence, after you upgrade to 4.7.9.x, you must reconfigure the custom port.

  1. Stop Unravel.

    <Unravel installation directory>/unravel/manager stop

  2. Display the list of ports and keys.

    <Unravel installation directory>/unravel/manager config ports show

  3. Set the port using the following command with the port and port key.

    <Unravel installation directory>/unravel/manager config ports set <port key> <port>

    For example, if you run the following command, NGUI listens on port 1234.

    <Unravel installation directory>/unravel/manager config ports set /hosts/host_main/instances/ngui_1/config/network/port 1234

    Note

    • Run manager config ports unset <port key> command to return the ports to their default values. 

      <Unravel installation directory>/unravel/manager config ports unset /hosts/host_main/instances/appstore_1/config/flask/port

  4. Apply the changes.

    <Unravel installation directory>/unravel/manager config apply

  5. Start Unravel.

    <Unravel installation directory>/unravel/manager start

Refer to Custom ports for more details. Custom ports

Unset/set properties on the HDP to CDP migrated cluster

After you have migrated from an Hortonworks Data Platform (HDP) to a Cloudera Data Platform (CDP) cluster, there are some properties you must unset and new properties that you must set on an edge node of the migrated cluster.

Single-cluster (HDP to CDP migration)

  1. On the edge node, set the following property: 

    <Unravel installation directory>/unravel/manager config properties set com.unraveldata.cluster.type CDP

    In case HBase was configured earlier, then set the following property: 

    <Unravel installation directory>/unravel/manager config properties set com.unraveldata.hbase.source.type=CDP

  2. Unset the following properties: 

    <Unravel installation directory>/unravel/manager config properties unset com.unraveldata.ambari.manager.url
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.ambari.manager.username
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.ambari.manager.password
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.yarn.timeline-service.webapp.address
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.yarn.timeline-service.port
<Unravel Installation Directory>/unravel/manager config properties unset yarn.resourcemanager.webapp.address

  3. Run the manager config auto command to pull in all the Hadoop configurations automatically. You will be prompted to provide the location and credentials for the CDP Cloudera manager URL.

    <Unravel installation directory>/unravel/manager config auto

    If there are more than one clusters that the CDP Cloudera manager handles, you are prompted to enable the cluster you want to monitor. Run the following command to enable a cluster:

    <Unravel installation directory>/unravel/manager config cluster enable <CLUSTER KEY>

    Example: /opt/unravel/manager config cluster enable cluster1

  4. Apply the changes.

    <Unravel installation directory>/unravel/manager config apply

  5. Start Unravel.

    <Unravel installation directory>/unravel/manager start

  6. Ensure to make the following changes in the Cloudera manager:

    • HDP/CDH has hive hooks under HIVE service, but for CDP, it is under HIVE_ON_TEZ. Hence, you must update the properties accordingly.

    • Update CDP Version for sensor parcel in Parcel Repository & Network from Cloudera Manager to https://xxx.unraveldata.com:3000/parcels/cdh7.1/.

    • Check for new parcels and distribute them.

Multi-cluster (HDP to CDP migration)

In case of a multi-cluster environment, do the following:

  1. Log in to the core node as an Unravel user.

  2. Unset the following properties on the core node:

    <Unravel installation directory>/unravel/manager config properties unset com.unraveldata.cluster.type
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.ambari.manager.url
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.ambari.manager.username
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.ambari.manager.password
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.ambari.manager.<EDGE KEY>.url
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.ambari.manager.<EDGE KEY>.username
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.ambari.manager.<EDGE KEY>.password
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.ambari.manager.list

    Tip

    Run the following commands to obtain the <EDGE KEY> and <CLUSTER KEY>

    <unravel_installation_directory>/unravel/manager config edge show

    Note

    For a multi-cluster environment, if your cluster name changes after the migration from HDP to CDP, you must unset the following properties on the core node:

    <Unravel installation directory>/unravel/manager config properties unset javax.jdo.option.<EDGE KEY>_<CLUSTER KEY>_HIVE.ConnectionURL
<Unravel installation directory>/unravel/manager config properties unset javax.jdo.option.<EDGE KEY>_<CLUSTER KEY>_HIVE.ConnectionDriverName
<Unravel installation directory>/unravel/manager config properties unset javax.jdo.option.<EDGE KEY>_<CLUSTER KEY>_HIVE.ConnectionUserName
<Unravel installation directory>/unravel/manager config properties unset javax.jdo.option.<EDGE KEY>_<CLUSTER KEY>_HIVE.ConnectionPassword
<Unravel installation directory>/unravel/manager config properties unset hive.metastore.<EDGE KEY>_<CLUSTER KEY>_HIVE.cluster.ids
<Unravel installation directory>/unravel/manager config properties unset hive.metastore.<EDGE KEY>_<CLUSTER KEY>_HIVE.cluster.ids
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.hive.metastore.list

  3. Run the following command:

    <Unravel installation directory>/unravel/manager config edge auto <EDGE KEY>
<Unravel installation directory>/unravel/manager config edge auto refresh

  4. Apply the changes.

    <Unravel installation directory>/unravel/manager config apply

  5. Start Unravel.

    <Unravel installation directory>/unravel/manager start

  6. Do the following on the edge node:

    1. Set the following property: 

      <Unravel installation directory>/unravel/manager config properties set com.unraveldata.cluster.type CDP

      In case HBase was configured earlier, then set the following property: 

      <Unravel installation directory>/unravel/manager config properties set com.unraveldata.hbase.source.type=CDP

    2. Unset the following properties: 

      <Unravel installation directory>/unravel/manager config properties unset com.unraveldata.ambari.manager.url
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.ambari.manager.username
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.ambari.manager.password
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.yarn.timeline-service.webapp.address
<Unravel installation directory>/unravel/manager config properties unset com.unraveldata.yarn.timeline-service.port
<Unravel Installation Directory>/unravel/manager config properties unset yarn.resourcemanager.webapp.address

    3. Run manager config auto command to pull in all the Hadoop configurations automatically. You will be prompted to provide the location and credentials for the CDP Cloudera manager URL.

      <Unravel installation directory>/unravel/manager config auto

      If there are more than one clusters that the CDP Cloudera manager handles, you are prompted to enable the cluster you want to monitor. Run the following command to enable a cluster:

      <Unravel installation directory>/unravel/manager config cluster enable <CLUSTER KEY>

      Example: /opt/unravel/manager config cluster enable cluster1

    4. Apply the changes.

      <Unravel installation directory>/unravel/manager config apply

    5. Start Unravel.

      <Unravel installation directory>/unravel/manager start

    6. Ensure to make the following changes in the Cloudera manager:

      • HDP/CDH has hive hooks under the HIVE service, but for CDP, it is under HIVE_ON_TEZ. Hence, you must update the properties accordingly.

      • Update CDP Version for sensor parcel in Parcel Repository & Network from Cloudera Manager to https://xxx.unraveldata.com:3000/parcels/cdh7.1/.

      • Check for new parcels and distribute them.

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
In this section: