You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ambari.apache.org by om...@apache.org on 2011/10/27 01:12:25 UTC
svn commit: r1189528 - in /incubator/ambari/trunk: CHANGES.txt
src/site/apt/cli.apt
Author: omalley
Date: Wed Oct 26 23:12:25 2011
New Revision: 1189528
URL: http://svn.apache.org/viewvc?rev=1189528&view=rev
Log:
AMBARI-109. Minor fixes to the CLI documentation. (omalley)
Modified:
incubator/ambari/trunk/CHANGES.txt
incubator/ambari/trunk/src/site/apt/cli.apt
Modified: incubator/ambari/trunk/CHANGES.txt
URL: http://svn.apache.org/viewvc/incubator/ambari/trunk/CHANGES.txt?rev=1189528&r1=1189527&r2=1189528&view=diff
==============================================================================
--- incubator/ambari/trunk/CHANGES.txt (original)
+++ incubator/ambari/trunk/CHANGES.txt Wed Oct 26 23:12:25 2011
@@ -2,11 +2,15 @@ Ambari Change log
Release 0.1.0 - unreleased
+ AMBARI-109. Minor fixes to the CLI documentation. (omalley)
+
AMBARI-108. Change name blueprint to stack (vgogate)
AMBARI-106. Fixes some javadoc stuff (ddas)
- AMBARI-105. Remove post on clusters resource to create new cluster (instead use put operation on cluster resource along with update cluster) (vgogate)
+ AMBARI-105. Remove post on clusters resource to create new cluster
+ (instead use put operation on cluster resource along with update
+ cluster) (vgogate)
AMBARI-104. Polishes the CLI doc some (ddas)
@@ -16,7 +20,8 @@ Release 0.1.0 - unreleased
AMBARI-102. Reduce heartbeat message content, when installedRoleState
is empty. (Eric Yang)
- AMBARI-101. Remove clusterID and use cluster name as unique ID for the cluster(vgogate)
+ AMBARI-101. Remove clusterID and use cluster name as unique ID for
+ the cluster(vgogate)
AMBARI-100. Fixes the heartbeat to take into account install/uninstall
of components (ddas)
Modified: incubator/ambari/trunk/src/site/apt/cli.apt
URL: http://svn.apache.org/viewvc/incubator/ambari/trunk/src/site/apt/cli.apt?rev=1189528&r1=1189527&r2=1189528&view=diff
==============================================================================
--- incubator/ambari/trunk/src/site/apt/cli.apt (original)
+++ incubator/ambari/trunk/src/site/apt/cli.apt Wed Oct 26 23:12:25 2011
@@ -15,34 +15,38 @@
~~
Command Line Interface
- Ambari Client implements a convenient command line interface for administrators to
- manage the full life of Hadoop clusters. CLI is a thin client implemented using
- Ambari REST APIs. By design, there is a close mapping between CLI and REST APIs, where
- most of the logic is implemented in the REST API.
-
- []
+ Ambari Client implements a convenient command line interface for
+ administrators to manage the full life of Hadoop clusters. The CLI
+ is a thin client, which is implemented using Ambari REST APIs. By
+ design, there is a close mapping between CLI and REST APIs and the
+ logic is implemented on by server.
General syntax of the CLI command is as follows,
- * Ambari commands are divided into multiple command categories typically named after
- the resources them operate on e.g. cluster, node, blueprint etc.
-
- * Each command starts with command category followed by one of the commands in that category,
- followed by one or more options available for the command e.g.
+ * Ambari commands are divided into multiple command categories
+ typically named after the resources they operate on e.g. cluster,
+ node, stack etc.
+
+ * Each command starts with command category followed by one of the
+ commands in that category, followed by one or more options available
+ for the command e.g.
* ambari \[command_category\] \[command_name\] \[command_options\]
* Command options can follow in any order. Options are prefixed with "-".
- * Each option would have at most one value associated with it. Value is either a string e.g. -name "MyCluster"
- or a key=value pair e.g. -role rolename="hostname1, hostname[10-20]"
-
- * Certain command options can be repeated multiple times on the command line, they are marked accordingly
- using tag <<[REPEATABLE]>>.
+ * Each option would has at most one value associated with it. The value
+ is either a string, e.g. -name "MyCluster", or a key=value pair,
+ e.g. -role rolename="hostname1, hostname[10-20]"
+
+ * Certain command options can be repeated multiple times on the
+ command line, they are marked accordingly using the tag
+ <<[REPEATABLE]>>.
* All the required options are marked as <<[REQUIRED]>>
- * Generic commands do not have any category associated with them e.g. help, version
+ * Generic commands do not have any category associated with them
+ e.g. help, version
[]
@@ -50,15 +54,16 @@ Command Line Interface
* <<Cluster commands>>
- * cluster \{create | update | delete | list | rename | blueprint | nodes\}
+ * cluster \{create | update | list | get | delete | rename | stack |
+ nodes\}
- * <<Blueprint commands>>
+ * <<Stack commands>>
- * blueprint \{list | history | add | get\}
+ * stack \{create | update | list | get | delete | history \}
* <<Node commands>>
- * nodes \{node | list | get\}
+ * nodes \{list | get\}
* <<Generic commands>>
@@ -71,28 +76,33 @@ Cluster Commands
* <<cluster create>>
- * It submits the cluster creation request to Ambari. It may take some time to bring
- the cluster to the desired state and hence the state should be checked either through list command or user
- can optionally wait for cluster to reach the desired goal state.
+ * Submit the cluster creation request to Ambari. It may take some
+ time to bring the cluster to the desired state and hence the
+ cluster state should be checked either via the <<list>> command or
+ the <<-wait>> option should be used to wait for the cluster to
+ reach the goal state.
* <<Options:>>
* <<-name>> [ NAME ] <<[REQUIRED]>>
- * <<-blueprint>> [ BLUEPRINT NAME ] <<[REQUIRED]>>
+ * <<-stack>> [ STACK NAME ] <<[REQUIRED]>>
- * Name of the user defined blueprint defining cluster configuration
+ * Name of the user defined stack defining cluster configuration
- * <<-blueprint_revision>> [ BLUEPRINT REVISION ] <<[REQUIRED]>>
+ * <<-stack_revision>> [ STACK REVISION ]
- * Revision of the blueprint. If not specified latest one is used.
+ * Revision of the stack. If not specified latest one is used.
* <<-nodes>> [node_range_exp1, node_range_exp2] <<[REQUIRED]>>
- * Specify range of nodes associated with the cluster. One or more node range expressions can be specified
- separated by comma. If user has not explicitly specified role to nodes association using -role option then
- Ambari will assign the role(s) to nodes based on node attributes. If user wants to view the role to nodes
- association generated by Ambari, use -dry_run option
+ * Specify range of nodes associated with the cluster. One or
+ more node range expressions can be specified separated by
+ commas. If the user does not bind roles to specific nodes
+ using the <<-role>> option, Ambari will assign the roles to
+ nodes based on the nodes' attributes. If user wants to view
+ the role to nodes association generated by Ambari, use
+ <<-dry_run>> option
* <<-desc>> [ DESCRIPTION ]
@@ -104,13 +114,17 @@ Cluster Commands
* <<-services>> [component-1, component-2, component-3]
- * By default all the components will be activated upon cluster activation.
- If user specifies specific ones then only they will be activated upon cluster activation
-
- * <<-role>> rolename=[node_range_exp1, node_range_exp2, â¦] <<[REPEATABLE]>>
-
- * One or more -role options can be used to specify the association of nodes to various roles. Nodes not
- explicitly associated with any role will be associated with various roles based on node attributes.
+ * By default all the components will be activated upon cluster
+ activation. If user specifies specific ones then only they
+ will be activated upon cluster activation
+
+ * <<-role>> rolename=[node_range_exp1, node_range_exp2, â¦]
+ <<[REPEATABLE]>>
+
+ * One or more -role options can be used to specify the
+ association of nodes to various roles. Nodes not explicitly
+ associated with any role will be associated with various roles
+ based on node attributes.
* <<-dry_run>>
@@ -124,7 +138,8 @@ Cluster Commands
* <<cluster update>>
- * It updates the cluster definition. All the options except name are OPTIONAL
+ * It updates the cluster definition. All the options except name
+ are OPTIONAL
* <<Options:>>
@@ -132,11 +147,11 @@ Cluster Commands
* <<-desc>> [ DESCRIPTION ]
- * <<-blueprint>> [ BLUEPRINT NAME ]
+ * <<-stack>> [ STACK NAME ]
- * <<-blueprint_revision>> [ BLUEPRINT REVISION ] <<[REQUIRED]>>
+ * <<-stack_revision>> [ STACK REVISION ]
- * Revision of the blueprint. If not specified latest one is used.
+ * Revision of the stack. If not specified latest one is used.
* <<-goalstate>> [ACTIVE/INACTIVE/ATTIC]
@@ -146,18 +161,20 @@ Cluster Commands
* <<-nodes>> [node_range_exp1, node_range_exp2]
- * Specify range of nodes associated with cluster. Ambari controller will figure out the
- changes and accordingly allocate/deallocate the nodes.
+ * Specify range of nodes associated with cluster. Ambari
+ controller will figure out the changes and accordingly
+ allocate/deallocate the nodes.
* <<-role>> rolename=[node_exp1, node_exp2, â¦] <<[REPEATABLE]>>
- * Ambari controller will figure out the changes and accordingly allocate/deallocate the nodes
- associated with the role
+ * Change the nodes associated with each role. The nodes will be
+ re-deployed and re-configured appropriately.
* <<-dry-run>>
- * This will show the details of the changes being made to cluster definition without actually
- submitting them to Ambari controller
+ * This will show the details of the changes being made to
+ cluster definition without actually submitting them to Ambari
+ controller
* <<-wait>>
@@ -165,70 +182,70 @@ Cluster Commands
[]
- * <<cluster rename>>
+ * <<cluster list>>
- * Renames the cluster
+ * List clusters. In a non-verbose mode, list cluster will return
+ the list of cluster names.
* <<Options:>>
- * <<-name>> [NAME] <<[REQUIRED]>>
+ * <<-state>> [cluster_state]
- * <<-newname>> [NEW NAME] <<[REQUIRED]>>
+ * Optionally specify the cluster state to list the cluster(s)
+ in the specified state.
+
+ * <<-verbose>>
+
+ * This option will provide verbose cluster information, which includes
+ the name, creating user, state, and current number of nodes.
[]
- * <<cluster delete>>
+ * <<cluster get>>
- * Delete the cluster. It deactivates the cluster. Controller in the background would free all
- the associated nodes and then remove the cluster definition at the end.
+ * Get the detailed cluster information displayed.
* <<Options:>>
- * <<-name>> [NAME] <<[REQUIRED]>>
-
- * <<-wait>>
+ * <<-name>> [NAME] <<[REQUIRED]>>
- * Optionally wait for cluster to be deleted
+ * Name of the cluster
[]
- * <<cluster list>>
+ * <<cluster delete>>
- * List clusters. In a non-verbose mode, list cluster will return the basic metadata of the
- cluster and the current state of the cluster e.g. [ID, NAME, STATE, DATE CREATED, ACTIVE_SERVICES]
+ * Delete the cluster. It deactivates the cluster. Controller in
+ the background would free all the associated nodes and then remove
+ the cluster definition at the end.
* <<Options:>>
- * <<-state>> [cluster_state]
-
- * Optionally specify the cluster state to list the cluster(s) in the specified state.
+ * <<-name>> [NAME] <<[REQUIRED]>>
- * <<-verbose>>
+ * <<-wait>>
- * This option will provide verbose cluster information displayed as JSON document.
+ * Optionally wait for cluster to be deleted
[]
- * <<cluster get>>
+ * <<cluster rename>>
- * Get the cluster information displayed as a JSON document
+ * Renames the cluster
* <<Options:>>
- * <<-name>> [NAME] <<[REQUIRED]>>
-
- * Name of the cluster
-
- * <<-verbose>>
+ * <<-name>> [NAME] <<[REQUIRED]>>
- * This option will provide verbose cluster information displayed as JSON document.
+ * <<-newname>> [NEW NAME] <<[REQUIRED]>>
[]
- * <<cluster blueprint>>
+ * <<cluster stack>>
- * It displays the blueprint configuration associated with the cluster. Optionally -expand option
- would provide derived blueprint configuration as generated by overriding the parent blueprint.
+ * It displays the stack associated with the cluster. The
+ <<-expand>> option provides the derived stack configuration as
+ generated by recursively expanding the parent stack.
* <<Options:>>
@@ -238,11 +255,12 @@ Cluster Commands
* <<-file>> [Local File Path]
- * Optionally stores the configuration to local file path. If not specified it displays it on the console.
+ * Optionally stores the configuration to local file path. If
+ not specified it displays it on the console.
* <<-expand>>
- * Optionally specify this option to get expanded blueprint by inlining the parent blueprint
+ * Expand the stack by inline the parent stack into it.
[]
@@ -258,70 +276,79 @@ Cluster Commands
* <<-alive>> [true/false]
- * Optionally specify the node state alive as true or false. Alive nodes are ones
- regularly heart beating with Ambari controller. If this option is not specified then all nodes are returned.
+ * Only list the nodes that are alive (or dead). Alive nodes
+ are ones regularly heart beating with Ambari controller. If
+ this option is not specified then all nodes are returned.
* <<-role>> [ROLE_NAME]
- * Optional role name to list the nodes associated with specified role.
+ * Only list the nodes that are associated with the given role. If
+ it is not given, all nodes are listed.
[]
-Blueprint Commands
+Stack Commands
- * <<blueprint list>>
+ * <<stack create>>
- * List all the blueprints along with some metadata
+ * Add or update the stack. If stack exists, it will be
+ updated to create new revision else new stack is created.
+
* <<Options:>>
- * <<-name>> [BLUEPRINT_NAME]
+ * <<-name>> [NAME] <<[REQUIRED]>>
- * Optionally specify the blueprint name to list the specific one
+ * Name of the stack.
- * <<-tree>>
+ * <<-location>> [FILE_PATH/URL] <<[REQUIRED]>>
- * Optionally ask for the derivation hierarchy
+ * Specify local file path or the URL from where stack (in
+ XML format) is to be imported into Ambari
- []
+ []
- * <<blueprint history>>
+ * <<stack update>>
- * List all the revisions of a specified blueprint
+ * Update the stack. Only the properties set in file will be updated.
* <<Options:>>
* <<-name>> [NAME] <<[REQUIRED]>>
- * Name of the blueprint.
+ * Name of the stack.
- * <<-tree>>
+ * <<-location>> [FILE_PATH/URL] <<[REQUIRED]>>
- * Optionally ask for the derivation hierarchy
+ * Specify local file path or the URL from where stack (in
+ XML format) is to be imported into Ambari
[]
- * <<blueprint add>>
+ * <<stack list>>
- * Add or update the blueprint. If blueprint exists, it will be updated to create new revision else
- new bluprint is created.
-
+ * List all the stacks. In non-verbose mode, just lists the stacks' names.
* <<Options:>>
- * <<-name>> [NAME] <<[REQUIRED]>>
+ * <<-name>> [STACK_NAME]
- * Name of the blueprint.
+ * Optionally specify the stack name to list the specific one
- * <<-location>> [FILE_PATH/URL] <<[REQUIRED]>>
+ * <<-verbose>>
- * Specify local file path or the URL from where blueprint (in XML format) is to be imported into Ambari
+ * Lists the stack's name, current revision, parent stack, and the
+ date it was last modified.
- []
+ * <<-tree>>
+
+ * Optionally ask for the derivation hierarchy
+
+ []
- * <<blueprint get>>
+ * <<stack get>>
- * Get the blueprint document in JSON format
+ * Get the stack document in JSON format
* <<Options:>>
@@ -333,7 +360,36 @@ Blueprint Commands
* <<-file>> [Local File Path]
- * Optionally stores the configuration to local file path. If not specified it displays it on the console.
+ * Optionally stores the configuration to local file path. If
+ not specified it displays it on the console.
+
+ []
+
+ * <<stack delete>>
+
+ * Delete the stack.
+
+ * <<Options:>>
+
+ * <<-name>> [NAME] <<[REQUIRED]>>
+
+ * Name of the stack.
+
+ []
+
+ * <<stack history>>
+
+ * List all the revisions of a specified stack
+
+ * <<Options:>>
+
+ * <<-name>> [NAME] <<[REQUIRED]>>
+
+ * Name of the stack.
+
+ * <<-tree>>
+
+ * Optionally ask for the derivation hierarchy
[]
@@ -341,30 +397,34 @@ Node Commands
* <<node list>>
- * List all the nodes registered with Ambari for various clusters. Host name and associated cluster name is displayed.
+ * Lists the nodes being managed by Ambari. In non-verbose mode, just lists
+ the full host names.
* <<Options:>>
* <<-verbose>>
- * Optionally verbose option will display node state and attributes information. List will be displayed
- as a JSON document
+ * Optionally verbose option will display the nodes' name, cluster,
+ current state, and roles.
* <<-allocated>> [true/false]
- * Optional state of the nodes indicating if node is allocated to some cluster. If not specified, implies both allocated
- and free nodes
+ * Only include the nodes that allocated (or unallocated) to any
+ cluster. If not specified, both allocated and free nodes are
+ included.
* <<-alive>> [true/false]
- * Optional state of the nodes to be listed. If not specified, implies both alive and dead nodes
+ * Only include nodes that are alive (or dead). If not specified,
+ implies both alive and dead nodes.
[]
* <<node get>>
- * Node information is displayed as a JSON document including node attributes, node state, associated cluster,
- list of roles and servers associated with node with their current state etc.
+ * All of the information about the node is displayed including the
+ node name, machine attributes, node state, associated cluster,
+ list of roles and the current state of the servers.
* <<Options:>>