This is the documentation for Cloudera Manager 4.8.5.
Documentation for other versions is available at Cloudera Documentation.

Upgrade Cloudera Manager 3.7.x to the Latest Cloudera Manager

  Important: Cloudera Manager version 3.x and CDH3 have reached End of Maintenance (EOM) as of June 20, 2013. Cloudera will not support or provide patches for any of the Cloudera Manager version 3.x and CDH3 releases. Even though Cloudera Manager 4.x will continue to support CDH3, it is strongly recommended that you upgrade to CDH4. See Upgrading existing installations of CDH3 to CDH4 for more details.

Upgrading from Cloudera Manager 3.7 (either Free or Enterprise Edition) to the latest version of Cloudera Manager involves upgrading Cloudera Manager Server packages, and updating the Cloudera manager agents on all cluster hosts. If you are upgrading a Free Edition version, the upgrade also includes adding databases for the management services supported as of Cloudera Manager 4.6.

Upgrading from Cloudera Manager 3.7.x to Cloudera Manager 4.6 involves the following broad steps.

Review Warnings and Notes

Before beginning the upgrade, follow the guidelines described in Database Considerations for Cloudera Manager Upgrades .

  Warning: Cloudera Manager 4.x can manage CDH3 and CDH4, but cannot manage CDH4.0 beta. If you upgrade to Cloudera Manager 4.x, you must upgrade any existing installations of CDH4.0 beta, as well.

When upgrading from a version of Cloudera Manager prior to 4.5, Cloudera Manager automatically creates new Hive service(s) to capture the previous implicit Hive dependency from Hue and Impala. Your previous services will continue to function without impact.

Note that if Hue was using a Hive metastore of type Derby, then the newly created Hive service will also use Derby. But since Derby does not allow concurrent connections, Hue will continue to work, but the new Hive Metastore Server will fail to run. The failure is harmless (because nothing uses this new Hive Metastore Server at this point) and intentional, to preserve the set of cluster functionality as it was before upgrade. Cloudera discourages the use of a Derby metastore due to its limitations. You should consider switching to a different supported database type.

Cloudera Manager provides a Hive configuration option to bypass the Hive Metastore Server. When this configuration is enabled, Hive clients, Hue, and Impala connect directly to the Hive Metastore database. Prior to Cloudera Manager 4.5, Hue and Impala talked directly to the Hive Metastore database, so bypass mode is enabled by default when upgrading to Cloudera Manager 4.5 or later. This is to ensure the upgrade doesn't disrupt your existing setup. You should plan to disable bypass mode, especially when using CDH 4.2 or later. Using the Hive Metastore Server is the recommended configuration and the WebHCat Server role requires the Hive Metastore Server to not be bypassed. To disable bypass mode, see Disabling Bypass Mode.

Cloudera Manager 4.5 or later also supports HiveServer2 with CDH4.2. HiveServer2 is not added by default, but can be added as a new role under the Hive service (see Adding Role Instances).

  Important: After completing the upgrade from Cloudera Manager 3.7.x to Cloudera Manager 4.6, as described in this topic, all required updates to database schemas and service data is completed automatically. You do not need to complete any additional database updates or data migration. However, you must restart your clusters after you have finished the Cloudera Manager upgrade.
  • As of Cloudera Manager 4.6, the former Cloudera Manager Free Edition is now known as Cloudera Standard, and includes a number of features that were previously available only with Cloudera Manager Enterprise Edition. Specifically, service and activity monitoring features are now available, and require databases to be set up for their use. Thus, upon upgrading to Cloudera Manager 4.6, you will be asked for database information for these services. (You will have the option to use the embedded PostgreSQL database for this).
  • If you were using the Enterprise Edition of Cloudera Manager, Cloudera Manager 4 adds an optional Host Monitor, which requires an additional database. If you intend to deploy Host Monitor or any other additional agents, you must establish a database for them. For information on establishing databases for agents such as Host Monitor, see Installing and Configuring Databases.

Stop the Cloudera Management Service

The Cloudera Manager Service must be stopped before upgrades can occur.

To stop the Cloudera Management Service

  1. Click the Services tab in Cloudera Manager Admin Console.
  2. Choose Stop on the Actions menu for the Cloudera Management Services.

Upgrade Cloudera Manager Server

This process involves stopping running Cloudera Manager service, downloading and applying updates to Cloudera Manager, and restarting the Cloudera Manager service. Valid licenses from Cloudera Manager 3.7.x continue to work with Cloudera Manager 4.

You can use package management software to download and apply updates from Cloudera's software repository. The default name of the repo file is cloudera-manager. This name is also typically in square brackets on the first line of the Cloudera Manager repo file. For example, you could view the contents of the repo file, including the repo name in brackets. This file might be at /etc/yum.repos.d/cloudera-manager.repo and its contents could be viewed using the more command as follows:

[user@system yum.repos.d]$ more cloudera-manager.repo

The location of the repo files varies by operating system and package management solution.

  • For yum the repo file is at /etc/yum.repos.d/cloudera-manager.repo.
  • For zypper the repo file is at /etc/zypp/repos.d/cloudera-manager.repo.

Find Cloudera's repo file for your distribution by starting at and navigating to the directory that matches your operating system. For example, for Red Hat 6, you would navigate to Within that directory, find the repo file that contains information including the repository's base URL and gpgkey. In the preceding example, the contents of the cloudera-manager.repo file might appear as follows:

# Packages for Cloudera Manager, Version 4, on RedHat or CentOS 5 x86_64
name=Cloudera Manager
gpgkey = 
gpgcheck = 1

Copy this repo file to the configuration location for the package management software for your system. Continuing with the preceding example, on Red Hat 6, you would copy the cloudera-manager.repo file to /etc/yum.repos.d/.

Before beginning the upgrade process, it can be best to clean all yum's cache directories using the command yum clean all. Doing so ensures that you download and install the latest versions of the packages. If your system is not up to date, and any underlying system components need to be upgraded before this yum update can succeed, yum will tell you what those are.

To upgrade to the new server

  1. Stop the server on the 3.7.x Server host:
    $ sudo service cloudera-scm-server stop
  2. If you are using the embedded PostgreSQL database, stop cloudera-manager-server-db on the host on which it is running:
    $ sudo service cloudera-scm-server-db stop
  3. Install the new version of the server. You can run commands on the Cloudera Manager Server host to update only the Cloudera Manager components.

    For a Red Hat system:

    To upgrade from Cloudera's repository run the following commands on the Cloudera Manager Server host:

    $ sudo yum clean all
    $ sudo yum update 'cloudera-*' 

    On a SLES system:

    Use the following commands to clean the cached repository information and update only the Cloudera Manager components:

    $ sudo zypper clean --all
    $ sudo zypper up -r

    At the end of this process you should have the 4.5 versions of the following packages installed on the host that will become the Cloudera Manager Server host. For example,

    $ rpm -qa 'cloudera-manager-*'

    You may also see additional packages for plugins, depending on what was previously installed on the Server host.

  4. Start the server. If you are using the embedded PostgreSQL database, start cloudera-scm-server-db on the Cloudera Manager Sever host:
    $ sudo service cloudera-scm-server-db start

    You will see it upgrade and create tables and databases. On the Cloudera Manager Server host (the system on which you installed the cloudera-manager-server package) do the following:

    $ sudo service cloudera-scm-server start

    You should see the following:

    Starting cloudera-scm-server:                              [  OK  ]
      Note: If you have problems starting the server, such as database permissions problems, you can use the server's log /var/log/cloudera-scm-server/cloudera-scm-server.log to troubleshoot the problem.

Upgrade the Cluster Hosts

After updating Cloudera Manager, connect to Cloudera Manager and use the wizard to continue the upgrade process. In this part of the process, the Cloudera Manager agents and their databases are updated. The Host Monitor role is a new addition for Cloudera Manager 4, so upgrading includes adding this role and its supporting database. If you are adding new agents, such as the Host Monitor, you must have a database available to support these roles. For more information, see Installing and Configuring Databases.

  Important: All hosts in the cluster must have access to the Internet if you plan to use as the source for installation files. If you do not have Internet access, create a custom repository.
  1. Log in to the Cloudera Manager Admin Console. If you have just restarted the Cloudera Manager server, you may need to log in again.
  2. On the Welcome screen, select whether you want to:
    • Install Cloudera Standard,
    • Try the Cloudera Enterprise with a 60-day trial license, or
    • Install a license you have purchased for Cloudera Enterprise.
  3. After you upload the Cloudera Manager license, or if you have elected to use a Trial license, restart the Cloudera Manager server.
    $ sudo service cloudera-scm-server restart
    • As the Cloudera Manager server restarts, the UI indicates its progress, and presents the login page when the restart has completed.
  4. Click Continue to proceed to the Upgrade cluster hosts screen.
  5. On the Upgrade cluster hosts screen, click Start Upgrade to upgrade the existing managed hosts. Click Skip Host Upgrades to skip this step.
  6. Select the release of the Cloudera Manager Agent to install. Normally, this will be the Matched Release for this Cloudera Manager Server. However, if you used a custom repository for the Cloudera Manager server, select Custom Repository and provide the required information

    Click Continue to proceed.

  7. Provide credentials for authenticating with hosts.
    1. Select root or enter the user name for an account that has password-less sudo permissions.
    2. Select an authentication method.
      • If you choose to use password authentication, enter and confirm the password.
      • If you choose to use public-key authentication provide a passphrase and path to the required key files.
      • You can choose to specify an alternate SSH port. The default value is 22.
      • You can specify the maximum number of host installations to run at once. The default value is 10.
  8. Click Start Installation to install and start Cloudera Manager Agents. The status of installation on each host is displayed on the page that appears after you click Start Installation. You can also click the Details link for individual hosts to view detailed information about the installation and error messages if installation fails on any hosts.

    If you click the Abort Installation button while installation is in progress, it will halt any pending or in-progress installations and roll back any in-progress installations to a clean state. The Abort Installation button does not affect host installations that have already completed successfully or already failed.

    If installation fails on a host, you can click the Retry link next to the failed host to try installation on that host again. To retry installation on all failed hosts, click Retry Failed Hosts at the bottom of the screen.

  9. When the Continue button appears at the bottom of the screen, the installation process is complete. If the installation has completed successfully on some hosts but failed on others, you can click Continue if you want to skip installation on the failed hosts and continue to the next screen to start installing the Cloudera Management services on the successful hosts.
  10. On the next screen, click Continue to install the Cloudera Management services.
  11. The Host Inspector runs to validate your installation. This should show your currently installed components as CDH3, with CDH4 components shown as Not installed. Note that the Version will be shown as Unavailable for all components.
  12. Select the Cloudera Management Service roles you want to install. The wizard evaluates the hardware configurations of the cluster hosts to recommend the best machines for each role. The Host Monitor is a new role introduced in Cloudera Manager 4.1. Navigator is a new, independently-licensed feature introduced with Cloudera Manager 4.5.
      Important: For best performance, make sure the Host Monitor role is assigned to the host on which you installed the corresponding databases. For example, if you created the Host Monitor database on myhost1, then you should assign the Activity Monitor role to myhost1. The JDBC connector must be installed and configured on any machine to which any of these roles is assigned.

    Click Continue to proceed.

  13. On the Database Setup page, enter any required information for Host Monitor and Navigator databases.
      Important: The value you enter as the database hostname must match the value you entered for the hostname (if any) when you created the database (see Installing and Configuring Databases).
    1. Enter the fully-qualified domain name for the server that is hosting the database in Database Host Name.
    2. Select the proper database type from the choices provided in Database Type.
    3. Enter the name you specified when you created the database in Database Name.
    4. Enter the user name you specified when you created the database in Username.
    5. Enter the password you specified when you created the database in Password.

    Problems may occur if a database with a blank password is used.

  14. Click Test Connection to confirm that Cloudera Manager can communicate with the databases using the information you have supplied. This transaction takes two heartbeats to complete (about 30 seconds with the default heartbeat interval). If the test succeeds in all cases, click Continue; otherwise check and correct the information you have provided for the databases and then try the test again.
  15. Review the configuration changes to be applied during the upgrade and click Accept.
  16. On the next page, select the hosts where the Hive Metastore Server role should be installed. The Hive service is now managed by Cloudera Manager; you must select the host for the Hive MetaStore Server. You should assign the Hive Metastore server to a single host. Click Continue to proceed.
  17. Review the configuration values for your Hive roles, and click Accept to continue.
      Note: If Hue is using a Hive metastore of type Derby (the default), then the newly created Hive service will also use Derby. However, since Derby does not allow concurrent connection, Hue will continue to work but the new Hive Metastore Server will fail to start. The failure is harmless (because nothing uses this new Hive Metastore Server at this point) and intentional, to preserve the cluster functionality that existed before the upgrade. Hive's Bypass Metastore Server mode is enabled by default when upgrading to Cloudera Manager 4.5. This is to ensure the upgrade doesn't disrupt your existing setup. You should plan to disable the Bypass Hive Metastore Server mode, especially when using CDH 4.2 or later. Using the Hive Metastore Server is the recommended configuration. After changing this configuration, you must re-deploy your client configurations, restart Hive, and restart any Hue or Impala services configured to use Hive.
  18. You are now taken to the Hive service Instances page: The Hive metastore server will be stopped.
  19. Under the Services tab, click the All Services link to go to the service overview page. All the services except for Hive and the Cloudera Management Service should now be running.

Verify the Upgrade

You can use the host inspector to verify the upgrade completed.

To verify the upgrade has completed as expected

  1. Connect to the Cloudera Manager Admin Console.
  2. Click the Hosts tab.
  3. Click Host Inspector.
  4. Click Show Inspector Results. All results from the host inspector process are displayed including the currently installed versions. If this includes listings of current component versions, the installation completed as expected.

Add Hive Gateway Roles to Hosts

  1. Add Hive Gateway roles to any hosts where Hive clients should run.
  2. In the Cloudera Manager Admin console, pull down the Services tab and select the Hive service.
  3. Go to the Instances tab, and click the Add button. This opens the Add Role Instances page.
  4. Select the hosts on which you want a Hive Gateway role to run. This will ensure that the Hive client configurations are deployed on these hosts.

Restart the Cloudera Management Service

The Cloudera Management Services are not started automatically after an upgrade — you must restart them.

To start the Cloudera Management Service

  1. Click the Services tab and select All Services in the Cloudera Manager Admin Console.
  2. Choose Start on the Actions menu for the Cloudera Management Services. If you are running more than one cluster, you should do this for each one.

Adding the Cloudera Navigator Role

If you have upgraded to Cloudera Enterprise or are running the 60-day Trial and want to try Cloudera Navigator, you must add it as a role under the management service.

  1. From the Services page, select the Management Service.
  2. Go to the Instances tab, and click the Add button.
  3. In the table presented, scroll to the end and select the host where you want the Navigator Server role to be hosted, and click Continue.
  4. Because Cloudera Navigator is separately licensed, you are presented with a license statement. Click Accept to enable the trial license for this feature.
  5. Enter the credentials for the database to be used by the Navigator Server. Assuming you have not set up an external database, you can use the Embedded Database for this. Click Test Connection to verify connectivity to the Database, the click Continue.
  6. Review and accept any configuration changes (typically there are none). Click Accept. This returns you to the Instances page.
  7. The Navigator Server role is added but not started. To start the role:
    1. Click the checkbox next to the role.
    2. From the Actions for Selected menu, click Start, and confirm that you want to start the role.

Deploy Updated Client Configurations

During upgrades between major versions, resource locations may change. To ensure clients have current information about resources, update client configuration as described in Deploying Client Configuration Files.

Restart Your Cluster(s)

From the Actions menu for each cluster, click Restart.

(Optional) Upgrade CDH

Cloudera Manager 4.x can manage both CDH3 and CDH4, so upgrading existing installations is not required. However, to get the benefits of CDH4, you may want to upgrade to the latest version. If you are using CDH4.0 beta, you must upgrade to a newer version of CDH4.

See the following topics for more information on upgrading CDH: