Apache Ambari Upgrade
Also available as:

Chapter 5. Upgrading HDP

There are different HDP upgrade options based on your current HDP version and the target HDP version. 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.


Be sure to review the available HDP upgrade scenarios below. It is strongly recommended that you first upgrade to Ambari 2.5.0 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.

  • [Note]Note

    Rolling upgrade of Phoenix is not supported from HDP versions lesser than 2.5 to HDP 2.5.x, 2.6 and higher. If you have Phoenix use cases running in your environment and looking at upgrading from HDP versions less than 2.5 to HDP versions greater than 2.5 and above then that is possible only with a planned downtime.

  • 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: an upgrade from HDP 2.4 to HDP 2.5, is a "Minor Upgrade". An upgrade from HDP 2.4.x to HDP 2.4.y, is a "Maintenance" Upgrade.

Table 5.1. HDP Upgrade Options

Upgrade Path

Current HDP*

Target HDP*

Rolling Upgrade

Express Upgrade

Minor **

HDP 2.5

HDP 2.6

Minor **

HDP 2.4

HDP 2.5 or 2.6

Minor **

HDP 2.3

HDP 2.4, 2.5 or 2.6


HDP 2.2

HDP 2.3, 24,or 2.5

Ambari 2.5.0 does not support managing an HDP 2.2 or earlier cluster. You must first upgrade to HDP 2.3 or higher using Ambari 2.4.2, 2.2.1, 2.2, 2.1 or 2.0 before upgrading to Ambari 2.5.0.


HDP 2.6.x.y

HDP 2.6.x.y


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

* 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.3.x.y to HDP 2.4.x.y as part of a Minor upgrade.


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.

More Information

Preparing to Upgrade Ambari and HDP

Rolling Upgrade Prerequisites