Upgrading Cloudera Director

This section contains notes and procedures for upgrading Cloudera Director.

Before Upgrading Cloudera Director

Follow these steps before upgrading Cloudera Director.

  1. Let running operations finish.

    For example, if Cloudera Director is setting up a Cloudera Manager or CDH cluster (indicated by a progress bar in the web UI), an upgrade will not complete successfully. An error in the log file instructs you to use the old version of Cloudera Director until all running operations are completed, and then perform the upgrade.

  2. Back up the Cloudera Director database that stores state information.

    By default, this is the embedded H2 database at /var/lib/cloudera-director-server/state.h2.db.

    If you are using a MySQL database to store the Cloudera Director state, use MySQL backup procedures to back up the Cloudera Director database. The following example shows how to do this using the mysqldump utility: 
    mysqldump --all-databases --single-transaction --user=root --password > backup.sql

    For more information on using mysqldump, see the MySQL documentation.

  3. If upgrading from Cloudera Director 1.1, change your default encryption key.

    After an upgrade from Cloudera Director 1.1 to a higher version, any new data that Cloudera Director persists in its database is encrypted with a default encryption key. For increased security, Cloudera recommends that you change your encryption key in the application.properties file after performing an upgrade from 1.1 to a higher version. The file is located at /etc/cloudera-director-server/application.properties.

    For more information about encryption and Cloudera Director data, see Cloudera Director Database Encryption.

Changes to the application.properties File

If you modified your existing application.properties file, the result of upgrading depends on which version of Linux you are using:
  • RHEL and CentOS - When new properties are introduced in Cloudera Director, they are added to application.properties.rpmnew. The original application.properties file functions as before and is not overwritten with the new Cloudera Director version properties. You do not need to copy the new properties from application.properties.rpmnew to the old application.properties file.
  • Ubuntu - The modified Cloudera Director application.properties file is backed up to a file named application.properties.dpkg-old. The original application.properties file is then overwritten by the new application.properties file containing new Cloudera Director properties. After upgrading, copy your changes from application.properties.dpkg-old to the new application.properties file.

Requirements for Cloudera Director 2.0 and Higher

The following are requirements for running Cloudera Director 2.0 and higher:
  • Cloudera Director 2.0 and higher support the following Linux operating systems:
    • RHEL and CentOS 6.5, 6.7, and 7.1
    • Ubuntu 14.04
  • Cloudera Director now requires Oracle JDK (Oracle Java SE Development Kit) version 7 or 8. Java 6 is not supported.
  • Cloudera Director 2.0 and higher can install any version of Cloudera Manager 5 with any CDH 5 parcels. Note that the Cloudera Manager minor version must the same as or higher than the CDH minor version. For instance, Cloudera Manager 5.7 can be used to launch and manage a CDH 5.5 cluster but not with a CDH 5.10. Cloudera Manager 4 and CDH 4 are not supported. Use of CDH packages is not supported.
If you are running a lower version of Cloudera Director on an operating system that is not supported for Cloudera Director 2.0, you cannot upgrade to Cloudera Director 2.0 or higher.

For complete requirements for Cloudera Director, see Requirements and Supported Versions.

Changes in Cloudera Director 2.0 and Higher

  • Cloudera Director 2.0 and higher requires Oracle JDK (Oracle Java SE Development Kit) version 7 or 8. Java 6 is not supported.
  • Cloudera Director 2.0 and higher can install any version of Cloudera Manager 5 with any CDH 5 parcels. Cloudera Manager 4 and CDH 4 are not supported. Use of CDH packages is not supported.

Handling Modified Plug-in Configuration Files

Cloudera Director includes plug-in configuration files that enable you to configure how the plug-ins work. The following plug-in files are located in directories in /var/lib/cloudera-director-plugins/:
  • aws-provider-version
  • azure-provider-version
  • byon-provider-example-version
  • google-provider-version
  • sandbox-provider-version

The location for plug-in configuration files has changed starting with Cloudera Director 2.0. In Cloudera Director 1.5.x and lower, they are located at /var/lib/cloudera-director-server/plugins. In Cloudera Director 2.0 and higher, they are located at /var/lib/cloudera-director-plugins/.

You do not normally need to modify the plug-in configuration files, but if you have modified any of them, your modifications will be overwritten during an upgrade. Before running the upgrade command, back up the modified files to another location. Then, after upgrading, redo your modifications in the new version of the file. These steps are included in the upgrade procedures below.

Upgrading Cloudera Director

The following sections describe steps for upgrading Cloudera Director on supported Linux operating systems.

RHEL and CentOS

  1. Stop the Cloudera Director server service by issuing the following command: 
    sudo service cloudera-director-server stop
  2. Cloudera Director 2.1.x and higher require Java 7 or 8. If you must upgrade your version of the Java SDK to meet this requirement, do so now.
  3. Update your Cloudera Director .repo file (the yum repository configuration file) to point to the version of Cloudera Director you are upgrading to by doing one of the following:
    • Open /etc/yum.repos.d/cloudera-director.repo. The baseurl value in this file now points to your current version of Cloudera Director, such as /1 or /2 (and may include a specific minor or maintenance release version, such as /1.1, /1.1.3, /2.2.0, or /2.2. Update the baseurl value to point to the new version, /2. In the absence of a minor version
    • Instead of editing your existing .repo file, you can download a new Cloudera Director .repo file, which will point to the latest version of Cloudera Director: 
      cd /etc/yum.repos.d/
sudo wget "http://archive.cloudera.com/director/redhat/7/x86_64/director/cloudera-director.repo"

      To upgrade to a version of Cloudera Director other than the latest version, you can edit the newly downloaded .repo file as described in the previous bullet point.

  4. If you have not modified the plug-in configuration files, skip to the next step. If you modified any configuration files in /var/lib/cloudera-director-plugins/plug-in_name-version (or, for Cloudera Director 1.5 or lower, in /var/lib/cloudera-director-server/plugins/plug-in_name-version), back them up to another location and remove them from this location before running the upgrade command.
  5. Issue the following commands: 
    sudo yum clean all
sudo yum update cloudera-director-server cloudera-director-client
  6. If you have not modified any configuration files, skip to the next step. If you modified any configuration files, restore your backed up files now to /var/lib/cloudera-director-plugins/plug-in_name-new_version, before restarting the Cloudera Director server.
  7. Restart the Cloudera Director server: 
    sudo service cloudera-director-server start

Ubuntu

  1. Stop the Cloudera Director server service by issuing the following command: 
    sudo service cloudera-director-server stop
  2. Cloudera Director 2.1.x and higher require Java 7 or 8. If you must upgrade your version of the Java SDK to meet this requirement, do so now.
  3. Update your Cloudera Director cloudera-director.list file (the repository configuration file) to point to the version of Cloudera Director you are upgrading to by doing one of the following:
    • Open /etc/apt/sources.list.d/cloudera-director.list. The baseurl value in this file now points to your current version of Cloudera Director, such as trusty-director1 or trusty-director2 (and may include a specific minor or maintenance release version, such as trusty-director1.1, trusty-director1.1.3, trusty-director2.2, or trusty-director2.2.0). Update the baseurl value to point to the newest version, trusty-director2, if this is not already the current value.
    • Instead of editing your existing cloudera-director.list file, you can download a new Cloudera Director cloudera-director.list file, which will point to the latest version of Cloudera Director: 
      cd /etc/apt/sources.list.d/
sudo curl "http://archive.cloudera.com/director/ubuntu/trusty/amd64/director/cloudera-director.list"

      To upgrade to a version of Cloudera Director other than the latest version, you can edit the newly downloaded cloudera-director.list file as described in the previous bullet point.

  4. If you have not modified the plug-in configuration files, skip to the next step. If you modified any configuration files in /var/lib/cloudera-director-plugins/plug-in_name-version (or, for Cloudera Director 1.5 or lower, in /var/lib/cloudera-director-server/plugins/plug-in_name-version), back them up to another location and remove them from this location before running the upgrade command.
  5. Issue the following commands: 
    sudo apt-get clean
sudo apt-get update 
sudo apt-get dist-upgrade 
sudo apt-get install cloudera-director-server cloudera-director-client
  6. If your original Cloudera Director application.properties file has not been modified, proceed to the next step. If your application.properties file was modified, the original properties file will be overwritten by the new properties file containing new Cloudera Director properties, as described above in Changes to the application.properties File. Copy your changes from application.properties.dpkg-old to the new application.properties file before restarting the server.
  7. If you have not modified any configuration files, skip to the next step. If you modified any configuration files, restore your backed up files now to /var/lib/cloudera-director-plugins/plug-in_name-new_version, before restarting the Cloudera Director server.
  8. Restart the Cloudera Director server: 
    sudo service cloudera-director-server start

Using IAM Policies with Cloudera Director 1.5 and Higher

In AWS, if you are using an IAM policy to control access to resources in the VPC, Cloudera Director 1.5 and higher requires permission for the method DescribeDBSecurityGroups. To give Cloudera Director permission for this method, add these values to your policy: 
{
  "Action": [ "rds:DescribeDBSecurityGroups" ],
  "Effect": "Allow",
  "Resource": ["*"]
}

This permission is required because Cloudera Director 1.5 and higher includes early validation of RDS credentials when creating or updating an environment, whether or not RDS database servers are used.

For a sample IAM policy that includes this permission, see Example IAM Policy. For more information on AWS IAM, see the IAM User Guide in the AWS documentation.