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

Supported Operating Systems for Cloudera Director

Cloudera Director 2.0.0 and higher support the following Linux operating systems:
  • RHEL and CentOS 6.5, 6.7, and 7.1
  • Ubuntu 14.04
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 version Cloudera Director 2.0.

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-server/plugins/:
  • aws-provider-version
  • byon-provider-example-version
  • google-provider-version
  • sandbox-provider-version
You do not normally need to modify these files, but if you have modified any of them, back up the modified files to another location before running the upgrade command. Then, restore your backed-up copies after the upgrade. Both of these steps are included in the upgrade procedures below.

Changes in Cloudera Director 2.0

  • Cloudera Director now requires Oracle JDK (Oracle Java SE Development Kit) version 7 or 8. Java 6 is not supported.
  • Cloudera Director 2.0 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.
  • Improved validation of create and update endpoints allows Cloudera Director to fail faster in many cases.
  • General API changes:
    • Listing the external database servers for a nonexistent environment now returns 404 Not Found.
    • The response codes for the v4 endpoints has been changed from 500 Internal Server Error to 204 No Content under the following conditions:
      • Attempting to GET a Deployment when the deployment is in a failed state.
      • Attempting to GET an ExternalDatabaseServer when the external database server is in a failed state.
      • Attempting to GET the Cluster when the cluster is in a failed state.

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.0.x requires 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/ (and may include a specific minor or maintenance release version, such as /1.1/ or /1.1.3/). Update the baseurl value to point to the new version, /2/.
    • 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 the plug-in configuration files in /var/lib/cloudera-director-server/plugins/plug-in_name-version/etc, back them up to another 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 the plug-in configuration files, skip to the next step. If you modified the plug-in configuration files in /var/lib/cloudera-director-server/plugins/plug-in_name-version/etc, restore your backed up files now to the new location, /var/lib/cloudera-director-plugins/plug-in_name-new_version/etc, 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.0.x requires 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 (and may include a specific minor or maintenance release version, such as trusty-director1.1 or trusty-director1.1.3). Update the baseurl value to point to the new version, trusty-director2.
    • 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 the plug-in configuration files in /var/lib/cloudera-director-server/plugins/plug-in_name-version/etc, back them up to another 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 the plug-in configuration files, skip to the next step. If you modified the plug-in configuration files in /var/lib/cloudera-director-server/plugins/plug-in_name-version/etc, restore your backed up files now to the new location, /var/lib/cloudera-director-plugins/plug-in_name-new_version/etc, 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.