Upgrading Cloudera Data Science Workbench 1.6.x Using Cloudera Manager

  1. Before you begin the upgrade process, make sure you read the Cloudera Data Science Workbench Release Notes relevant to the version you are upgrading to/from.

  2. Depending on the version you are upgrading from, perform one of the following steps to stop Cloudera Data Science Workbench:
    • (Required for Upgrades from CDSW 1.4.2 or lower) Safely stop Cloudera Data Science Workbench. To avoid running into the data loss issue described in TSB-346, run the cdsw_protect_stop_restart.sh script on the master host and follow the sequence of steps as instructed by the script.

      The script will first back up your project files to the specified target folder. It will then temporarily move your project files aside to protect against the data loss condition. At that point, it is safe to stop the CDSW service in Cloudera Manager.

      After Cloudera Data Science Workbench has stopped, press enter to continue running the script as instructed. It will then move your project files back into place.

      OR

    • (Upgrading from CDSW 1.4.3 or higher) Stop the Cloudera Data Science Workbench service in Cloudera Manager.

  3. (Strongly Recommended) On the master host, backup all your application data that is stored in the /var/lib/cdsw directory.
    To create the backup, run the following command on the master host:
    tar cvzf cdsw.tar.gz /var/lib/cdsw/*
  4. (Required for Upgrades from CDSW 1.4.0 - RedHat only) Cloudera Data Science Workbench 1.4.2 (and higher) includes a fix for a slab leak issue found in RedHat kernels. To have this fix go into effect, RedHat users must reboot all Cloudera Data Science Workbench hosts before proceeding with an upgrade from CDSW 1.4.0.

    As a precaution, consult your cluster/IT administrator before you start rebooting hosts.

  5. Deactivate the existing Cloudera Data Science Workbench parcel. Go to the Cloudera Manager Admin Console. In the top navigation bar, click Hosts > Parcels.

    Locate the current active CDSW parcel and click Deactivate. On the confirmation pop-up, select Deactivate Only and click OK.

  6. Download and save the latest Cloudera Data Science Workbench CSD to the Cloudera Manager Server host.
    1. Download the latest Cloudera Data Science Workbench CSD.
      Version Link to CSD
      Cloudera Data Science Workbench 1.6.1

      CDH 6 - CLOUDERA_DATA_SCIENCE_WORKBENCH_CDH6_1.6.1.jar

      CDH 5 - CLOUDERA_DATA_SCIENCE_WORKBENCH_CDH5_1.6.1.jar

      Cloudera Data Science Workbench 1.6.0

      CDH 6 - CLOUDERA_DATA_SCIENCE_WORKBENCH_CDH6_1.6.0.jar

      CDH 5 - CLOUDERA_DATA_SCIENCE_WORKBENCH_CDH5_1.6.0.jar

    2. Log on to the Cloudera Manager Server host, and place the CSD file under /opt/cloudera/csd, which is the default location for CSD files.
    3. Delete any CSD files belonging to older versions of Cloudera Data Science Workbench from /opt/cloudera/csd.

      This is required because older versions of the CSD will not work with the latest Cloudera Data Science Workbench parcel. Make sure your CSD and parcel are always the same version.

    4. Set the CSD file ownership to cloudera-scm:cloudera-scm with permission 644.
    5. Restart the Cloudera Manager Server:
      service cloudera-scm-server restart
    6. Log into the Cloudera Manager Admin Console and restart the Cloudera Management Service.
      1. Select Clusters > Cloudera Management Service.
      2. Select Actions > Restart.
  7. Distribute and activate the new parcel on your cluster.
    1. Log into the Cloudera Manager Admin Console.
    2. Click Hosts > Parcels in the main navigation bar.
    3. If the latest CDSW parcel is already available in this list, you can skip this step.
      Add the Cloudera Data Science Workbench parcel repository URL to Cloudera Manager.
      1. On the Parcels page, click Configuration.
      2. In the Remote Parcel Repository URLs list, click the addition symbol to create a new row.
      3. Enter the path to the repository.
        Version Remote Parcel Repository URL
        Cloudera Data Science Workbench 1.6.1 https://archive.cloudera.com/cdsw1/1.6.1/parcels/
        Cloudera Data Science Workbench 1.6.0 https://archive.cloudera.com/cdsw1/1.6.0/parcels/
      4. Click Save Changes.
    4. Go back to the Hosts > Parcels page. The latest parcel should now appear in the set of parcels available for download. Click Download. Once the download is complete, click Distribute to distribute the parcel to all the CDH hosts in your cluster. Then click Activate. For more detailed information on each of these tasks, see Managing Parcels.
  8. Run the Prepare Node command on all Cloudera Data Science Workbench hosts.
    1. Before you run Prepare Node, you must make sure that the command is allowed to install all the required packages on your cluster. This is controlled by the Install Required Packages property.

      1. Navigate to the CDSW service.
      2. Click Configuration.
      3. Search for the Install Required Packages property. If this property is enabled, you can move on to the next step and run Prepare Node.
        However, if the property has been disabled, you must either enable it or manually install the following packages on all Cloudera Data Science Workbench gateway hosts.
        nfs-utils
        libseccomp
        lvm2
        bridge-utils
        libtool-ltdl
        iptables   
        rsync 
        policycoreutils-python 
        selinux-policy-base 
        selinux-policy-targeted 
        ntp 
        ebtables 
        bind-utils 
        nmap-ncat  
        openssl 
        e2fsprogs 
        redhat-lsb-core 
        conntrack-tools
        socat
    2. Run the Prepare Node command.
      1. In Cloudera Manager, navigate to the Cloudera Data Science Workbench service.
      2. Click the Instances tab.
      3. Use the checkboxes to select all host instances and click Actions for Selected (x).
      4. Click Prepare Node. Once again, click Prepare Node to confirm the action.
  9. Log into the Cloudera Manager Admin Console and restart the Cloudera Data Science Workbench service.
    1. On the Home > Status tab, click to the right of the CDSW service and select Restart from the dropdown.
    2. Confirm your choice on the next screen. Note that a complete restart of the service will take time. Even though the CDSW service status shows Good Health, the application itself will take some more time to get ready.
  10. Upgrade Projects to Use the Latest Base Engine Images

    If the release you have just upgraded to includes a new version of the base engine image (see release notes), you will need to manually configure existing projects to use the new engine. Cloudera recommends you do so to take advantage of any new features and bug fixes included in the newly released engine. For example:

    • Container Security

      Security best practices dictate that engine containers should not run as the root user. Engines (v7 and lower) briefly initialize as the root user and then run as the cdsw user. Engines v8 (and higher) now follow the best practice and run only as the cdsw user. For more details, see Restricting User-Created Pods.

    • CDH 6 Compatibility

      The base engine image you use must be compatible with the version of CDH you are running. This is especially important if you are running workloads on Spark. Older base engines (v6 and lower) cannot support the latest versions of CDH 6. If you want to run Spark workloads on CDH 6, you must upgrade your projects to base engine 7 (or higher).

    • Editors

      Engines v8 (and higher) ships with the browser-based IDE, Jupyter, preconfigured and can be selected from the Start Session menu.

    To upgrade a project to the new engine, go to the project's Settings > Engine page and select the new engine from the dropdown. If any of your projects are using custom extended engines, you will need to modify them to use the new base engine image.

  11. (GPU-enabled Deployments) Remove nvidia-docker1 and Upgrade NVIDIA Drivers to 410.xx or higher
    Perform the following steps to make sure you can continue to leverage GPUs for workloads on Cloudera Data Science Workbench 1.6 (and higher).
    1. Remove nvidia-docker1. Cloudera Data Science Workbench 1.6 ships with nvidia-docker2 installed by default.
      yum remove nvidia-docker
      Perform this step on all hosts that have GPUs attached to them.
    2. Upgrade your NVIDIA driver to version 410.xx (or higher). This must be done because nvidia-docker2 does not support lower versions of NVIDIA drivers.

      1. Stop Cloudera Data Science Workbench.

        Depending on your deployment, either stop the CDSW service in Cloudera Manager (for CSDs) or run cdsw stop on the Master host (for RPMs).

      2. Reboot the GPU-enabled hosts.
      3. Install a supported version of the NVIDIA driver (410.xx or higher) on all GPU-enabled hosts.
      4. Start Cloudera Data Science Workbench.

        Depending on your deployment, either start the CDSW service in Cloudera Manager (for CSDs) or run cdsw start on the Master host (for RPMs).