Repository: ambari Updated Branches: refs/heads/trunk 16a97aace -> d906f7d1e
AMBARI-9926. RU: create documentation for new API (ncole) Project: http://git-wip-us.apache.org/repos/asf/ambari/repo Commit: http://git-wip-us.apache.org/repos/asf/ambari/commit/d906f7d1 Tree: http://git-wip-us.apache.org/repos/asf/ambari/tree/d906f7d1 Diff: http://git-wip-us.apache.org/repos/asf/ambari/diff/d906f7d1 Branch: refs/heads/trunk Commit: d906f7d1e17db4551f8afba9b156f744c697cbb2 Parents: 16a97aa Author: Nate Cole <[email protected]> Authored: Wed Mar 4 11:51:43 2015 -0500 Committer: Nate Cole <[email protected]> Committed: Wed Mar 4 13:52:56 2015 -0500 ---------------------------------------------------------------------- ambari-server/docs/api/v1/index.md | 3 + ambari-server/docs/api/v1/upgrades.md | 131 +++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/ambari/blob/d906f7d1/ambari-server/docs/api/v1/index.md ---------------------------------------------------------------------- diff --git a/ambari-server/docs/api/v1/index.md b/ambari-server/docs/api/v1/index.md index 026efbe..96abf64 100644 --- a/ambari-server/docs/api/v1/index.md +++ b/ambari-server/docs/api/v1/index.md @@ -350,6 +350,9 @@ Rolling upgrades check resources store information about successful/unsuccessful [Rolling Upgrade Check Resources](rolling-upgrade-check-resources.md) +#### upgrades +[Upgrade Resources](upgrades.md) + Partial Response ---- http://git-wip-us.apache.org/repos/asf/ambari/blob/d906f7d1/ambari-server/docs/api/v1/upgrades.md ---------------------------------------------------------------------- diff --git a/ambari-server/docs/api/v1/upgrades.md b/ambari-server/docs/api/v1/upgrades.md new file mode 100644 index 0000000..d8e78b5 --- /dev/null +++ b/ambari-server/docs/api/v1/upgrades.md @@ -0,0 +1,131 @@ +<!--- +Licensed to the Apache Software Foundation (ASF) under one or more +contributor license agreements. See the NOTICE file distributed with +this work for additional information regarding copyright ownership. +The ASF licenses this file to You under the Apache License, Version 2.0 +(the "License"); you may not use this file except in compliance with +the License. You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> + +# Upgrade Resources +Upgrade resources are used to manage and query the state of any rolling +upgrade that is in progress. + +### Concept +An upgrade consists of 4 distinct object types. + +#### Upgrade +An upgrade is the top-level object that maps to a Request. + +#### UpgradeGroup +An upgrade group is a collection of UpgradeItem instances that are related. For example, "Core Masters" can be a group that contains the master services for HDFS, HBase and YARN. There are many groups associated with an Upgrade. Groups do not match an existing Requst/Stage/Task object. + +#### UpgradeItem +An upgrade item matches the framework Stage instance. UpgradeItems must be processed sequentially. There are several items associated to a group. + +#### Task +A task is the same Task created for normal Request/Stage. It represents a singular command that is run on an agent. Tasks may run in parallel so long as they are for different hosts. For example, restarting a Datanode may happen on two different hosts simultaneously. Many tasks may be associated to a single UpgradeItem. + +A sample hierarchy is as follows: + + Upgrade + |-UpgradeGroup - "Core Masters" + | |-UpgradeItem - "Prepare Namenode" + | | |-Task - message task + | |-UpgradeItem - "Restart Namenode" + | |-Task - restart task + | |-Task - execution task + |-UpgradeGroup + + + +### API Summary + +##### Create Upgrade +Initiates the upgrade process. Uses the repository version specfied and creates the groups, items and tasks. You must have the correct version from [Repository Versions](repository-version-resources.md) +###### Request: + + POST http://<server>:8080/api/v1/clusters/<cluster>/upgrades + { + "Upgrade": { + "repository_version": "2.2.2.0-1234" + } + } + +###### Response + { + "resources" : [ + { + "href" : "http://<server>:8080/api/v1/clusters/<cluster>/upgrades/27", + "Upgrade" : { + "request_id" : 27 + } + } + ] + } + +##### Get Upgrade +Numerous properties and information can be retrieved from the upgrade id. Sample output: + + { + "Upgrade" : { + "cluster_name" : "<cluster>", + "request_id": 27 + }, + "upgrade_groups" : [ + { + "UpgradeGroup" : { + "group_id": 29, + "progress_percent" : 0.0, + "title" : "ZooKeeper" + }, + "upgrade_items" : [ + { + "UpgradeItem" : { + "stage_id": 1, + "context" : "Preparing ZooKeeper Client on 2 hosts", + "status" : "HOLDING" + } + }, + { + "UpgradeItem" : { + "stage_id": 2, + "context" : "Restarting ZooKeeper Client on host3", + "status" : "PENDING" + } + },... + ] + } + ] + } + +##### Manual Items Processing +In the example above, note the UpgradeItem step that is in a HOLDING status. This means that in the course of an upgrade, a Manual Task was generated. Manual Tasks are used to show a message to the end user, and must be continued by issuing the status to the UpgradeItem: + +###### Request + PUT http://<server>:8080/api/v1/clusters/<cluster>/upgrades/27/upgrade_groups/29/upgrade_items/1 + { + "UpgradeItem": { + "status": "COMPLETED" + } + } +###### Response +The response for the above call does not return a body. It returns the status code 200 on completion. After the call is made, the next UpgradeItem status becomes QUEUED and eventually IN_PROGRESS when it scheduled for agent execution. + + +###### Other HOLDING Statuses +In addition to HOLDING, there are two other statuses that may pause execution + +* HOLDING_FAILED is used to indicate that the task has failed. The UpgradeItem can either be retried with PENDING, or skipped with FAILED. Most tasks for an Upgrade are retry-able and skippable. However, in the event that the UpgradeItem is not marked as skippable, marking as FAILED will abort the entire request. +* HOLDING_TIMEDOUT is similar to HOLDING_FAILED, except it can be transition to PENDING (retry) or TIMEDOUT. + +Either can transition to ABORTED to abort the entire request. +
