One of the most gargantuan tasks of any cluster administrator is upgrading the bits since it is a tedious, risky, and inherently complex process that can take days. Ambari comes to the rescue with two features: Rolling Upgrade (RU), and Express Upgrade (EU), aimed upgrading the HDP cluster with a couple of clicks. For starters, Rolling Upgrade was first released in Ambari 2.0.0 (March 2015) and the latest incarnation (as of October 2015) in Ambari 2.1.2 provides added robustness and a couple of goodies. Express Upgrade is set to be released in Ambari 2.2.0 (ETA is Dec 16, 2015). So how does it work? What are the gotcha's? What do I need to know? Overview: Both upgrade mechanisms update the bits and configurations of your cluster. The main difference is that RU upgrades one node at a time, and maintains the cluster and all Hadoop jobs running, while EU stops all services, changes the version and configs, then starts all services in parallel. Therefore, RU is the prime candidate for environments that cannot take downtime, whereas EU is faster since it takes downtime. If your cluster is large, on the order of 500+ nodes and you must finish upgrade in a weekend, then EU is the clear choice. Pre-Reqs: Bits: In both cases, the user must first register a new repo, and install the bits side-by-side. For example, /usr/hdp/2.2.4.2-2 (current version) /usr/hdp/2.3.0.0-2557 (version that will upgrade to) The good news is that this can be done ahead of time. Ambari will only install the bits for the services needed on that host, this ensures that we save on disk-space since the full HDP stack can take up to 2.5 GB. Pre-Checks: It is wise for users to make sure that they pass the Pre-Checks before attempting to start the upgrade. The pre-checks include: All hosts have the repo version installed All components are installed All hosts are heartbeating All hosts in maintenance state do not have any master components No services are in maintenance mode All Services are up Hive is configured for dynamic discovery For RU, client retry enabled for HDFS, Hive, and Oozie For RU, YARN has work-preserving restart enabled For RU, MapReduce2 History server has state preserving mode enabled For RU, MapReduce jobs reference hadoop libraries from the distributed cache For RU, Tez jobs reference hadoop libraries from the distributed cache For RU, Hive has at least 2 MetaStores For RU, NameNode High Availability is required, and must use a dfs nameservice If the user adds any services or hosts after already installing the bits for a repo, then they must redistribute the bits since Ambari will mark that repo as "out_of_sync". Orchestration: Rolling Upgrade orchestrates the services one at a time, and restarts one component at a time. When a component is restarted, it is stopped on the old version, then started on the newer version. For HDP, this is done by calling hdp-select set $comp $version to set the symlink of the binary, and if on HDP 2.3 or higher, then also calling conf-select set-conf-dir $package $stack_version $conf_version to change the symlink for the configuration. The binary symlinks are controlled by /usr/hdp/current/$comp-name/ -> /usr/hdp/$version/$comp The confs are controlled by two symlinks, /etc/$comp/conf -> /usr/hdp/$version/$comp/conf -> /etc/$comp/$version/0 RU restarts the services from the bottom-up, i.e., ZK Ranger Core Masters: HDFS, MR2, YARN, HBASE Core Slaves: DataNode, RegionServer, NodeManager on each host Auxiliary & Clients: Hive, Spark, Oozie, Falcon, Clients, Kafka, Knox, Storm, Slider, Flume, Accumulo Before starting, Ambari will prompt the user to take backups of the database, and will automatically snapshot the HDFS namespace. Throughout the process, Ambari will orchestrate Service Checks after critical points. At the end, Ambari will finalize the rolling upgrade, and save the state in its database. Express Upgrade has a slightly different orchestration; it stops all services on the current stack from the top-down, then it changes to the new stack and applies configs, then it starts services from the bottom-up. When both stopping and starting services, it will do so in parallel. Furthermore, because EU takes downtime, it does not require NameNode High Availability. Merging Configurations: When upgrading across major versions, e.g. HDP 2.2->2.3, Ambari will have to merge configs. E.g., HDP 2.2 default configs = base HDP 2.3 default configs = desired Ambari has rules for how to add, rename, transform, and delete configs from the base stack to the desired stack. Any properties that the user modified in the base stack will be persisted, even if the new stack has a different value. Error Handling: All operations are retry-able in the case of an error and we've made a considerable effort to ensure all ops are idempotent. Moreover, non-critical steps (such as Service Checks and the higher-level services) can always be skipped, since they can always be fixed right before finalizing. In Ambari 2.1.2, Ambari introduced two values that allow the Upgrade Packs to automatically skip Service Check or Component Failures. See AMBARI-13032. In Ambari 2.1.3, these error-handling options can be controlled at run-time, and it makes it easier to ignore errors until the end. See AMBARI-13018. Further, Ambari 2.1.3 also allows suppressing manual tasks so they run silently. See AMBARI-13457. Gotcha's, Tips, and Tricks: 1. Checkout this presentation: RU Tips, Tricks, Hacks 2. Always move to the latest version of Ambari. 3. Backup the Ambari database before starting UpgradeIf you run into any problems attempting to "Save the Cluster State", this is likely because some hosts/components are still on the older version. To find out these components, run SELECT h.host_name, hcs.service_name, hcs.component_name, hcs.version FROM hostcomponentstate hcs JOIN hosts h ON hcs.host_id = h.host_id ORDER BY hcs.version, hcs.service_name, hcs.component_name, h.host_name; To fix the components, on each host, run this for the applicable components, hdp-select versions hdp-select set $comp_name $desired_version and restart the components (note: you may have to do this manually, or by enabling the /#/experimental flag) 4. If you run into any problems during Upgrade, try RU Magician! It's a python script that checks the database and can perform some updates for you, RU Magician 5. For advanced users, you can still modify properties by navigating to http://$server:8080/#/experimental and enabling "opsDuringRollingUpgrade" 6. If planning to upgrade Knox to HDP 2.3.2 or higher, must first upgrade Ambari to 2.1.2 7. If patching tez.lib.uris, then must reset the path to the original value before starting the Upgrade; otherwise, Ambari will persist the value of the patched jar, which will not work in the new version. 8. If performing a manual stack upgrade, don't forget to call this to save the new version as "current" ambari-server set-current --cluster-name=$CLUSTERNAME --version-display-name=$VERSION_NAME In Ambari 2.2, you can now force the finalization, thereby skipping any errors. al stack upgrade, don't In Ambari 2.1.3, you can force the finalization by running the command above with "--force". See AMBARI-13591 Example of APIs: Run the pre-checks: curl -u $admin:$password -X POST -H 'X-Requested-By:admin' <a href="http://$server:8080/api/v1/clusters/$name/rolling...">http://$server:8080/api/v1/clusters/$name/rolling...</a> Start the upgrade: curl -u $admin:$password -X POST -H 'X-Requested-By:admin' <a href="http://$server:8080/api/v1/clusters/$name/upgrade...">http://$server:8080/api/v1/clusters/$name/upgrade...</a> -d '{"Upgrade":{"repository_version":"2.3.0.0-2557", "type":"ROLLING"}}' Check the status: curl -u $admin:$password -X GET -H 'X-Requested-By:admin' <a href="http://$server:8080/api/v1/clusters/c1/upgrades">http://$server:8080/api/v1/clusters/c1/upgrades</a> Debugging & Logging: If the the upgrade fails to Finalize, find out which hosts and components are still not on the newer version. -- Check the repo version state SELECT rv.version, cv.state FROM repo_version rv JOIN cluster_version cv ON rv.repo_version_id = cv.repo_version_id ORDER BY rv.version ASC; -- Check the hosts SELECT rv.version, h.host_name, hv.state FROM repo_version rv JOIN host_version hv ON rv.repo_version_id = hv.repo_version_id JOIN hosts h ON hv.host_id = h.host_id ORDER BY rv.version ASC, h.host_name; -- Find the components on the wrong version, -- call "hdp-select set <comp> <version>", check the config symlinks, and restart them manually SELECT hcs.service_name, hcs.component_name, h.host_name, hcs.version FROM hostcomponentstate hcs JOIN hosts h ON hcs.host_id = h.host_id ORDER BY hcs.version ASC, hcs.service_name, hcs.component_name, h.host_name; Postgres: SELECT u.upgrade_id, u.direction, substr(g.group_title, 0, 40), substr(i.item_text, 0, 80), substr(hrc.status, 0, 40), hrc.task_id, h.host_name, hrc.output_log, hrc.error_log FROM upgrade_group g JOIN upgrade u ON g.upgrade_id = u.upgrade_id JOIN upgrade_item i ON i.upgrade_group_id = g.upgrade_group_id JOIN host_role_command hrc ON hrc.stage_id = i.stage_id AND hrc.request_id = u.request_id JOIN hosts h ON hrc.host_id = h.host_id ORDER BY u.upgrade_id, g.upgrade_group_id, i.stage_id; MySQL: SELECT u.upgrade_id, u.direction, LEFT(g.group_title, 40), LEFT(i.item_text, 80), LEFT(hrc.status, 40), hrc.task_id, h.host_name, hrc.output_log, hrc.error_logFROM upgrade_group AS g JOIN upgrade AS u ON g.upgrade_id = u.upgrade_idJOIN upgrade_item AS i ON i.upgrade_group_id = g.upgrade_group_idJOIN host_role_command AS hrc ON hrc.stage_id = i.stage_id AND hrc.request_id = u.request_idJOIN hosts AS h ON hrc.host_id = h.host_id ORDER BY u.upgrade_id, g.upgrade_group_id, i.stage_id; If you have any questions, feel free to email user@ambari.apache.org ... View more