Apache Ambari Upgrade
Also available as:

Chapter 4. Upgrading HDP

There are different HDP upgrade options based on your current HDP and the target HDP. This section describes the different upgrade options, their prerequisites, and the overall process. You are strongly encouraged to read completely through this entire document before starting the upgrade process, to that you understand the interdependencies and order of the steps. It is highly recommended you validate these steps in a test environment to adjust and account for any special configurations for your cluster.

The high-level process for performing an HDP upgrade is as follows:

Ambari will guide you through the steps required to upgrade HDP. Make sure Ambari and the cluster are healthy, operating normally and all service checks are passing. See Preparing to Upgrade Ambari and HDP for more information on performing the Ambari upgrade.


Be sure to review the available HDP upgrade scenarios below. It is strongly recommended that you first upgrade to Ambari 2.4 before upgrading HDP unless otherwise noted. After upgrading Ambari, be sure the cluster is operating normally and service checks are passing prior to attempting an HDP upgrade.

There are two methods for upgrading HDP with Ambari: Rolling Upgrade and Express Upgrade.

  • A Rolling Upgrade orchestrates the HDP upgrade in an order that is meant to preserve cluster operation and minimize service impact during upgrade. This process has more stringent prerequisites (particularly regarding cluster high availability configuration) and can take longer to complete than an Express Upgrade.

  • An Express Upgrade orchestrates the HDP upgrade in an order that will incur cluster downtime but with less stringent prerequisites.

The following table describes which upgrade option is available based on the current and target HDP version combinations. It is important to note that the HDP Stack version is based on the following format: major.minor.maintenance.patch-build#. A "minor" release is a release that increments the second-digit. A "maintenance" release is one that increments the third-digit. This terminology is used in the following table to describe the different upgrade paths. For example: if you want to upgrade from HDP 2.2 to HDP 2.3, that is a "Minor Upgrade". If you want to upgrade from HDP 2.2.x to HDP 2.2.y, that is a "Maintenance" Upgrade.

Table 4.1. HDP Upgrade Options

Upgrade Path

Current HDP*

Target HDP*

Rolling Upgrade

Express Upgrade


HDP 2.5.x.y

HDP 2.5.x.y


HDP 2.4.x.y

HDP 2.4.x.y


HDP 2.3.x.y

HDP 2.3.x.y


HDP 2.2.x.y

HDP 2.2.x.y

Minor **

HDP 2.4

HDP 2.5

Minor **

HDP 2.3

HDP 2.4 or 2.5

Minor ***

HDP 2.2

HDP 2.3 or 2.4


HDP 2.0 or 2.1

HDP 2.2, 2.3, or 2.4

Ambari 2.2.2 does not support managing an HDP 2.1 or 2.0 cluster. You must first upgrade to HDP 2.2 or higher using either Ambari 2.2.1, 2.2, 2.1 or 2.0 prior to upgrading to Ambari 2.2.2.

* The instructions in this document sometimes refer to an HDP “version” using the HDP #.#.x.y convention. For example, you will see the HDP 2.3.x.y convention to refer to any HDP 2.3 “maintenance” release. Therefore, to use a specific HDP 2.3 maintenance release, be sure to replace 2.3.x.y in the following instructions with the appropriate maintenance version, such as for the HDP 2.3 GA release, or for an HDP 2.3 maintenance release.

** A Minor upgrade can be performed from any current maintenance release to any target maintenance release in that minor release. For example, you can go from HDP 2.2.x.y to HDP 2.3.x.y as part of a Minor upgrade.

*** A direct upgrade from HDP 2.2 to HDP 2.5 is not available. You must first go from HDP 2.2 to HDP 2.4, then HDP 2.4 to HDP 2.5.


Because HDP 2.3.6 contains features and fixes that are not applicable to HDP 2.4.0 or HDP 2.4.2, do not upgrade from HDP 2.3.6 to HDP 2.4.0 or HDP 2.4.2.