Cloudera Enterprise 6.0 Beta | Other versions

Upgrading to CDH 6.x Using Parcels

Minimum Required Role: Cluster Administrator (also provided by Full Administrator)

This topic describes how to upgrade CDH from any version of CDH 5.x to CDH 6.x using Cloudera Manager and parcels. If the CDH cluster you are upgrading was installed using packages, you can upgrade it using parcels, and the upgraded version of CDH will then use parcels for future upgrades or changes. You can also migrate your cluster from using packages to using parcels before starting the upgrade. The minor version of Cloudera Manager you use to perform the upgrade must be equal to or greater than the CDH minor version. To upgrade Cloudera Manager, see Overview of Upgrading Cloudera Manager.

To upgrade CDH using parcels:

Step 1: Collect Upgrade Information

Before starting an upgrade, collect the following information:
  1. Host credentials. You must have SSH access and be able to log in using a root account or an account that has password-less sudo permission.
  2. The version of Cloudera Manager used in your cluster. Go to Support > About.
  3. The version of the JDK deployed in the cluster. Go to Support > About.
  4. The version of CDH. The CDH version number displays next to the cluster name on the Home page.
  5. Whether the cluster was installed using parcels or packages. This information displays next to the CDH version on the Home page of Cloudera Manager.
  6. The services enabled in your cluster. Go to Clusters > Cluster name.
  7. Operating system type and version. Go to Hosts and click on a hostname in the list. The operating system type and version displays in the Distribution row in the Details section.
  8. Database information for the databases used by Sqoop, Oozie, Hue, Hive Metastore, and Sentry Server (information is only required if theses services are enabled in the cluster).
    Gather the following information:
    • Type of database (PostgreSQL, Embedded PostgreSQL, MySQL, MariaDB, or Oracle)
    • Hostnames of the databases
    • Credentials for the databases
    To locate database information:
    • Sqoop, Oozie, and Hue – Go to Cluster Name > Configuration > Database Settings.
    • Hive Metastore – Go to the Hive service, select Configuration, and select the Hive Metastore Database category.
    • Sentry – Go to the Sentry service, select Configuration, and select the Sentry Server Database category.

Step 2: Complete Pre-Upgrade Steps

Step 3: Back Up Databases

  Note: Backing up databases requires that you stop some services, which may make them unavailable during backup.
Back up the databases for any of the following services that are deployed in your cluster:
Table 1. Service Databases to Back Up
Service Where to find database information
Sqoop Go to Clusters > Cluster Name > Sqoop service > Configuration and select the Database category.
Hue Go to Clusters > Cluster Name > Hue service > Configuration and select the Database category.
Oozie Go to Clusters > Cluster Name > Oozie service > Configuration and select the Database category.
Cloudera Navigator Audit Server Go to Clusters > Cloudera Management Service > Configuration and select the Database category.
Cloudera Navigator Metadata Server Go to Clusters > Cloudera Management Service > Configuration and select the Database category.
Activity Monitor Go to Clusters > Cloudera Management Service > Configuration and select the Database category.
Reports Manager Go to Clusters > Cloudera Management Service > Configuration and select the Database category.
Sentry Server Go to Clusters > Cluster Name > Sentry service > Configuration and select the Sentry Server Database category.
Hive Metastore Go to Clusters > Cluster Name > Hive service > Configuration and select the Hive Metastore Database category.
To back up the databases:
  1. If not already stopped, stop the service:
    1. On the Home > Status tab, click to the right of the service name and select Stop.
    2. Click Stop in the next screen to confirm. When you see a Finished status, the service has stopped.
  2. Back up the database. See Backing Up Databases for detailed instructions for each supported type of database.
  3. Restart the service:
    1. On the Home > Status tab, click to the right of the service name and select Start.
    2. Click Start that appears in the next screen to confirm. When you see a Finished status, the service has started.

Step 4: Establish Access to the Software

In order to upgrade CDH, Cloudera Manager needs access to a repository that contains the updated parcels. By default, Cloudera Manager selects the most recent version of CDH for the upgrade. If you want to upgrade to a different version, or Cloudera Manager does not have access to the Internet, you must set up a local repository. See Creating and Using a Parcel Repository for Cloudera Manager

Step 5: Run the Upgrade Wizard

  Note: If Cloudera Manager detects a failure while upgrading CDH, Cloudera Manager displays a dialog box where you can create a diagnostic bundle to send to Cloudera Support so they can help you recover from the failure. The cluster name and time duration fields are pre-populated to capture the correct data.
  1. If your cluster has Kudu 1.4.0 (or lower) installed, deactivate the existing Kudu parcel. Starting with Kudu 1.5.0 / CDH 5.13, Kudu is part of the CDH parcel and does not need to be installed separately.
  2. If your cluster has Spark 2.0 or Spark 2.1 installed and you want to upgrade to CDH 5.13 or higher, you must first upgrade to Spark 2.1 release 2 or later before upgrading CDH. To install these versions of Spark, do the following before running the CDH Upgrade Wizard:
    1. Install the Custom Service Descriptor (CSD) file. See
    2. Download, distribute, and activate the Parcel for the version of Spark that you are installing:
      • Spark 2.1 release 2: The parcel name includes "cloudera2" in its name.
      • Spark 2.2 release 1: The parcel name includes "cloudera1" in its name.
      See Managing Parcels.
  3. If your cluster is running any of the following services, stop the services and delete the services before upgrading the cluster:
    • Accumulo
    • MapReduce 1
    • Sqoop 2
  4. From the Home > Status tab, click next to the cluster name and select Upgrade Cluster.

    The Getting Started page of the upgrade wizard displays.

  5. If the option to pick between packages and parcels displays, select Use Parcels.
  6. If you previously installed the GPLEXTRAS parcel, download and distribute the version of the GPLEXTRAS parcel that matches the version of CDH that you are upgrading to.
  7. In the Choose CDH Version (Parcels) field, select the CDH version. If no qualifying parcels are listed, or you want to upgrade to a different version (see Step 4: Establish Access to the Software ):
    1. Click the Modify the Remote Parcel Repository URLs link to go to the configuration page for Remote Parcel Repository URLs
    2. Click the + icon and add the URL to the configuration.
    3. Click the Cloudera Manager logo to return to the Home page.
    4. Click next to the cluster name and select Upgrade Cluster. See Parcel Configuration Settings for information about entering the correct URL for parcel repositories.
    5. Click Continue.

    The Check Status page displays. The page displays some warnings that apply your upgrade. Click the check boxes to indicate that you are of the warnings.

    This page also displays problems you may need to correct before proceeding, and may also propose some changes. Correct any errors before continuing. You may need to restart the Upgrade Wizard:
    1. Click the Cloudera Manager logo to return to the Home page.
    2. Click next to the cluster name and select Upgrade Cluster. See Parcel Configuration Settings for information about entering the correct URL for parcel repositories.
  8. Read the notices for steps you must complete before upgrading, click the Yes, I ... checkboxes after completing the steps, and click Continue. If you downloaded a new version of the GPLEXTRAS parcel, the Upgrade Wizard displays a message that the GPLEXTRAS parcel conflicts with the version of the CDH parcel, similar to the following:

    Select the option to resolve the conflicts automatically and click Continue.

    Cloudera Manager deactivates the old version of the GPLEXTRAS parcel and activates the new version.

  9. Click Continue.

    Cloudera Manager verifies that agents and services are properly installed.

  10. Click Continue.

    The selected parcels are downloaded and distributed.

  11. Click Continue.

    The Host Inspector runs and displays the CDH version on the hosts.

  12. Click Continue.

    The Restart Cluster screen displays.

  13. Click Continue to restart the cluster.

    The Upgrade Cluster Command screen displays the result of the commands run by the wizard as it shuts down all services, activates the new parcel, upgrades services, deploys client configuration files, and restarts services. If any of the steps fail, correct any reported errors and click the Retry button. If you click the Abort button, the Retry button at the top right is enabled.

    Click Retry to retry the step and continue the wizard, or click the Cloudera Manager logo to return to the Home > Status tab and manually perform the failed step and all following steps.

  14. Click Continue.

    The Summary page displays and reports the result of the upgrade.

    If your cluster was previously installed or upgraded using packages, the wizard may indicate that some services cannot start because their parcels are not available.

  15. Click Finish to return to the Home page.

Step 6: Recover from Failed Steps or Perform a Manual Upgrade

The actions performed by the upgrade wizard are listed in Performing Upgrade Wizard Actions Manually. If any of the steps in the Upgrade Cluster Command screen fail, complete the steps as described in that section before proceeding.

Step 7: Remove the Previous CDH Version Packages and Refresh Symlinks (Required if previous installation used packages.)

[Not required for CDH maintenance release upgrades.]

Skip this step if your previous installation or upgrade used parcels.

If your previous installation of CDH was done using packages, remove those packages on all hosts where you installed the parcels and refresh the symlinks so that clients will run the new software versions.

  1. If your Hue service uses the embedded SQLite database, back up /var/lib/hue/desktop.db to a location that is not /var/lib/hue because this directory is removed when the packages are removed.
  2. Uninstall the CDH packages on each host:
    • Not including Impala and Search
      RHEL
      sudo yum remove bigtop-utils bigtop-jsvc bigtop-tomcat hue-common sqoop2-client
      SLES
      sudo zypper remove bigtop-utils bigtop-jsvc bigtop-tomcat hue-common sqoop2-client
      Ubuntu or Debian
      sudo apt-get purge bigtop-utils bigtop-jsvc bigtop-tomcat hue-common sqoop2-client
    • Including Impala and Search
      RHEL
      sudo yum remove 'bigtop-*' hue-common impala-shell solr-server sqoop2-client hbase-solr-doc avro-libs crunch-doc avro-doc solr-doc
      SLES
      sudo zypper remove 'bigtop-*' hue-common impala-shell solr-server sqoop2-client hbase-solr-doc avro-libs crunch-doc avro-doc solr-doc
      Ubuntu or Debian
      sudo apt-get purge 'bigtop-*' hue-common impala-shell solr-server sqoop2-client hbase-solr-doc avro-libs crunch-doc avro-doc solr-doc
  3. Restart all the Cloudera Manager Agents to force an update of the symlinks to point to the newly installed components on each host: 
    sudo service cloudera-scm-agent restart
  4. If your Hue service uses the embedded SQLite database, restore the database you backed up:
    1. Stop the Hue service.
    2. Copy the backup from the temporary location to the newly created Hue database directory, /var/lib/hue.
    3. Start the Hue service.

Step 8: Finalize the HDFS Metadata Upgrade

[Not required for CDH maintenance release upgrades.]

The steps in this section are required for all upgrade from CDH 5.x to CDH 6.x.

To determine if you can finalize, run important workloads and ensure that they are successful. Once you have finalized the upgrade, you cannot roll back to a previous version of HDFS without using backups. Verifying that you are ready to finalize the upgrade can take a long time.

Make sure you have enough free disk space, keeping in mind that the following behavior continues until the upgrade is finalized:
  • Deleting files does not free up disk space.
  • Using the balancer causes all moved replicas to be duplicated.
  • All on-disk data representing the NameNodes metadata is retained, which could more than double the amount of space required on the NameNode and JournalNode disks.
To finalize the metadata upgrade:
  1. Go to the HDFS service.
  2. Click the Instances tab.
  3. Select the NameNode instance. If you have enabled high availability for HDFS, select NameNode (Active).
  4. Select Actions > Finalize Metadata Upgrade and click Finalize Metadata Upgrade to confirm.

Step 9: Exit Maintenance Mode

If you entered maintenance mode during this upgrade, exit maintenance mode.

Page generated March 7, 2018.