You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@helix.apache.org by zz...@apache.org on 2013/09/03 07:47:41 UTC
git commit: [HELIX-227] Create a wiki page for helix admin api,
rb=13933
Updated Branches:
refs/heads/master c57426501 -> 1d3c32ed2
[HELIX-227] Create a wiki page for helix admin api, rb=13933
Project: http://git-wip-us.apache.org/repos/asf/incubator-helix/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-helix/commit/1d3c32ed
Tree: http://git-wip-us.apache.org/repos/asf/incubator-helix/tree/1d3c32ed
Diff: http://git-wip-us.apache.org/repos/asf/incubator-helix/diff/1d3c32ed
Branch: refs/heads/master
Commit: 1d3c32ed264caf5cd3669ec6054a8518cce34a61
Parents: c574265
Author: zzhang <zz...@uci.edu>
Authored: Mon Sep 2 22:46:51 2013 -0700
Committer: zzhang <zz...@uci.edu>
Committed: Mon Sep 2 22:46:51 2013 -0700
----------------------------------------------------------------------
src/site/markdown/tutorial_admin.md | 500 +++++++++++++++++++++++--------
1 file changed, 368 insertions(+), 132 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-helix/blob/1d3c32ed/src/site/markdown/tutorial_admin.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/tutorial_admin.md b/src/site/markdown/tutorial_admin.md
index 57f34fc..72c1f13 100644
--- a/src/site/markdown/tutorial_admin.md
+++ b/src/site/markdown/tutorial_admin.md
@@ -19,149 +19,385 @@ under the License.
# Helix Tutorial: Admin Operations
-Helix provides interfaces for the operator to administer the cluster. For convenience, there is a command line interface as well as a REST interface.
+Helix provides a set of admin api for cluster management operations. They are supported via:
-### Helix Admin operations
+* _Java API_
+* _Commandline interface_
+* _REST interface via helix-admin-webapp_
-First, make sure you get to the command-line tool, or include it in your shell PATH.
+### Java API
+See interface [_org.apache.helix.HelixAdmin_](http://helix.incubator.apache.org/apidocs/reference/org/apache/helix/HelixAdmin.html)
-```
-cd helix/helix-core/target/helix-core-pkg/bin
-```
-
-Get help
-
-```
-./helix-admin.sh --help
-```
-
-All other commands have this form:
-
-```
-./helix-admin.sh --zkSvr <ZookeeperServerAddress (Required)> <command> <parameters>
-```
-
-Now, here are the admin commands:
-
-Add a new cluster
-
-```
- --addCluster <clusterName>
-```
-
-Add a new Instance to a cluster
-
-```
- --addNode <clusterName> <InstanceAddress (host:port)>
-```
-
-Add a State model to a cluster
-_WE NEED A SPEC FOR A VALID STATE MODEL_
+### Command-line interface
+The command-line tool comes with helix-core package:
-```
- --addStateModelDef <clusterName> <filename>>
-```
-
-Add a resource to a cluster
+Get the command-line tool:
-```
- --addResource <clusterName> <resourceName> <partitionNum> <stateModelRef> <mode (AUTO_REBALANCE|AUTO|CUSTOM)>
+```
+ - git clone https://git-wip-us.apache.org/repos/asf/incubator-helix.git
+ - cd incubator-helix
+ - ./build
+ - cd helix-core/target/helix-core-pkg/bin
+ - chmod +x *.sh
```
-Upload an IdealState (Partition to Node Mapping)
-_WE NEED A SPEC FOR A VALID IDEAL STATE_
+Get help:
```
- --addIdealState <clusterName> <resourceName> <filename>
-```
-
-Delete a cluster
-
-```
- --dropCluster <clusterName>
-```
-
-Delete a resource (drop an existing resource from a cluster)
-
+ - ./helix-admin.sh --help
```
- --dropResource <clusterName> <resourceName>
-```
-
-Drop an existing instance from a cluster
-
-```
- --dropNode <clusterName> <InstanceAddress (host:port)>
-```
-
-Enable/disable the entire cluster. This will pause the controller, which means no transitions will be trigger, but the existing nodes in the cluster continue to function, but without any management by the controller.
-
-```
- --enableCluster <clusterName> <true/false>
-```
-
-Enable/disable an instance. Useful to take a node out of the cluster for maintenance/upgrade.
-```
- --enableInstance <clusterName> <InstanceName> <true/false>
-```
-
-Enable/disable a partition
-
-```
- --enablePartition <clusterName> <instanceName> <resourceName> <partitionName> <true/false>
-```
-
-Query info of a cluster
-
-```
- --listClusterInfo <clusterName>
-```
-
-List existing clusters (remember, Helix can manage multiple clusters)
-
-```
- --listClusters
-```
-
-Query info of a single Instance in a cluster
-
-```
- --listInstanceInfo <clusterName> <InstanceName>
-```
-
-List instances in a cluster
-
-```
- --listInstances <clusterName>
-```
-
-Query info of a partition
-
-```
- --listPartitionInfo <clusterName> <resourceName> <partitionName>
-```
-
-Query info of a resource
-
-```
- --listResourceInfo <clusterName> <resourceName>
-```
-
-List resources hosted in a cluster
-
-```
- --listResources <clusterName>
-```
-
-Query info of a state model in a cluster
-
-```
- --listStateModel <clusterName> <stateModelName>
-```
-
-Query info of state models in a cluster
+All other commands have this form:
```
- --listStateModels <clusterName>
-```
+ ./helix-admin.sh --zkSvr <ZookeeperServerAddress> <command> <parameters>
+```
+
+Admin commands and brief description:
+
+| Command syntax | Description |
+| -------------- | ----------- |
+| _\-\-activateCluster \<clusterName controllerCluster true/false\>_ | Enable/disable a cluster in distributed controller mode |
+| _\-\-addCluster \<clusterName\>_ | Add a new cluster |
+| _\-\-addIdealState \<clusterName resourceName fileName.json\>_ | Add an ideal state to a cluster |
+| _\-\-addInstanceTag \<clusterName instanceName tag\>_ | Add a tag to an instance |
+| _\-\-addNode \<clusterName instanceId\>_ | Add an instance to a cluster |
+| _\-\-addResource \<clusterName resourceName partitionNumber stateModelName\>_ | Add a new resource to a cluster |
+| _\-\-addResourceProperty \<clusterName resourceName propertyName propertyValue\>_ | Add a resource property |
+| _\-\-addStateModelDef \<clusterName fileName.json\>_ | Add a State model definition to a cluster |
+| _\-\-dropCluster \<clusterName\>_ | Delete a cluster |
+| _\-\-dropNode \<clusterName instanceId\>_ | Remove a node from a cluster |
+| _\-\-dropResource \<clusterName resourceName\>_ | Remove an existing resource from a cluster |
+| _\-\-enableCluster \<clusterName true/false\>_ | Enable/disable a cluster |
+| _\-\-enableInstance \<clusterName instanceId true/false\>_ | Enable/disable an instance |
+| _\-\-enablePartition \<true/false clusterName nodeId resourceName partitionName\>_ | Enable/disable a partition |
+| _\-\-getConfig \<configScope configScopeArgs configKeys\>_ | Get user configs |
+| _\-\-getConstraints \<clusterName constraintType\>_ | Get constraints |
+| _\-\-help_ | print help information |
+| _\-\-instanceGroupTag \<instanceTag\>_ | Specify instance group tag, used with rebalance command |
+| _\-\-listClusterInfo \<clusterName\>_ | Show information of a cluster |
+| _\-\-listClusters_ | List all clusters |
+| _\-\-listInstanceInfo \<clusterName instanceId\>_ | Show information of an instance |
+| _\-\-listInstances \<clusterName\>_ | List all instances in a cluster |
+| _\-\-listPartitionInfo \<clusterName resourceName partitionName\>_ | Show information of a partition |
+| _\-\-listResourceInfo \<clusterName resourceName\>_ | Show information of a resource |
+| _\-\-listResources \<clusterName\>_ | List all resources in a cluster |
+| _\-\-listStateModel \<clusterName stateModelName\>_ | Show information of a state model |
+| _\-\-listStateModels \<clusterName\>_ | List all state models in a cluster |
+| _\-\-maxPartitionsPerNode \<maxPartitionsPerNode\>_ | Specify the max partitions per instance, used with addResourceGroup command |
+| _\-\-rebalance \<clusterName resourceName replicas\>_ | Rebalance a resource |
+| _\-\-removeConfig \<configScope configScopeArgs configKeys\>_ | Remove user configs |
+| _\-\-removeConstraint \<clusterName constraintType constraintId\>_ | Remove a constraint |
+| _\-\-removeInstanceTag \<clusterName instanceId tag\>_ | Remove a tag from an instance |
+| _\-\-removeResourceProperty \<clusterName resourceName propertyName\>_ | Remove a resource property |
+| _\-\-resetInstance \<clusterName instanceId\>_ | Reset all erroneous partitions on an instance |
+| _\-\-resetPartition \<clusterName instanceId resourceName partitionName\>_ | Reset an erroneous partition |
+| _\-\-resetResource \<clusterName resourceName\>_ | Reset all erroneous partitions of a resource |
+| _\-\-setConfig \<configScope configScopeArgs configKeyValueMap\>_ | Set user configs |
+| _\-\-setConstraint \<clusterName constraintType constraintId constraintKeyValueMap\>_ | Set a constraint |
+| _\-\-swapInstance \<clusterName oldInstance newInstance\>_ | Swap an old instance with a new instance |
+| _\-\-zkSvr \<ZookeeperServerAddress\>_ | Provide zookeeper address |
+
+### REST interface
+
+The REST interface comes wit helix-admin-webapp package:
+
+```
+ - git clone https://git-wip-us.apache.org/repos/asf/incubator-helix.git
+ - cd incubator-helix
+ - ./build
+ - cd helix-admin-webapp/target/helix-admin-webapp-pkg/bin
+ - chmod +x *.sh
+ - ./run-rest-admin.sh --zkSvr <zookeeperAddress> --port <port> // make sure zookeeper is running
+```
+
+#### URL and support methods
+
+* _/clusters_
+ * List all clusters
+
+ ```
+ curl http://localhost:8100/clusters
+ ```
+
+ * Add a cluster
+
+ ```
+ curl -d 'jsonParameters={"command":"addCluster","clusterName":"MyCluster"}' -H "Content-Type: application/json" http://localhost:8100/clusters
+ ```
+
+* _/clusters/{clusterName}_
+ * List cluster information
+
+ ```
+ curl http://localhost:8100/clusters/MyCluster
+ ```
+
+ * Enable/disable a cluster in distributed controller mode
+
+ ```
+ curl -d 'jsonParameters={"command":"activateCluster","grandCluster":"MyControllerCluster","enabled":"true"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster
+ ```
+
+ * Remove a cluster
+
+ ```
+ curl -X DELETE http://localhost:8100/clusters/MyCluster
+ ```
+
+* _/clusters/{clusterName}/resourceGroups_
+ * List all resources in a cluster
+
+ ```
+ curl http://localhost:8100/clusters/MyCluster/resourceGroups
+ ```
+
+ * Add a resource to cluster
+
+ ```
+ curl -d 'jsonParameters={"command":"addResource","resourceGroupName":"MyDB","partitions":"8","stateModelDefRef":"MasterSlave" }' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/resourceGroups
+ ```
+
+* _/clusters/{clusterName}/resourceGroups/{resourceName}_
+ * List resource information
+
+ ```
+ curl http://localhost:8100/clusters/MyCluster/resourceGroups/MyDB
+ ```
+
+ * Drop a resource
+
+ ```
+ curl -X DELETE http://localhost:8100/clusters/MyCluster/resourceGroups/MyDB
+ ```
+
+ * Reset all erroneous partitions of a resource
+
+ ```
+ curl -d 'jsonParameters={"command":"resetResource"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/resourceGroups/MyDB
+ ```
+
+* _/clusters/{clusterName}/resourceGroups/{resourceName}/idealState_
+ * Rebalance a resource
+
+ ```
+ curl -d 'jsonParameters={"command":"rebalance","replicas":"3"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/resourceGroups/MyDB/idealState
+ ```
+
+ * Add an ideal state
+
+ ```
+ echo jsonParameters={
+ "command":"addIdealState"
+ }&newIdealState={
+ "id" : "MyDB",
+ "simpleFields" : {
+ "IDEAL_STATE_MODE" : "AUTO",
+ "NUM_PARTITIONS" : "8",
+ "REBALANCE_MODE" : "SEMI_AUTO",
+ "REPLICAS" : "0",
+ "STATE_MODEL_DEF_REF" : "MasterSlave",
+ "STATE_MODEL_FACTORY_NAME" : "DEFAULT"
+ },
+ "listFields" : {
+ },
+ "mapFields" : {
+ "MyDB_0" : {
+ "localhost_1001" : "MASTER",
+ "localhost_1002" : "SLAVE"
+ }
+ }
+ }
+ > newIdealState.json
+ curl -d @'./newIdealState.json' -H 'Content-Type: application/json' http://localhost:8100/clusters/MyCluster/resourceGroups/MyDB/idealState
+ ```
+
+ * Add resource property
+
+ ```
+ curl -d 'jsonParameters={"command":"addResourceProperty","REBALANCE_TIMER_PERIOD":"500"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/resourceGroups/MyDB/idealState
+ ```
+
+* _/clusters/{clusterName}/resourceGroups/{resourceName}/externalView_
+ * Show resource external view
+
+ ```
+ curl http://localhost:8100/clusters/MyCluster/resourceGroups/MyDB/externalView
+ ```
+* _/clusters/{clusterName}/instances_
+ * List all instances
+
+ ```
+ curl http://localhost:8100/clusters/MyCluster/instances
+ ```
+
+ * Add an instance
+
+ ```
+ curl -d 'jsonParameters={"command":"addInstance","instanceNames":"localhost_1001"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/instances
+ ```
+
+ * Swap an instance
+
+ ```
+ curl -d 'jsonParameters={"command":"swapInstance","oldInstance":"localhost_1001", "newInstance":"localhost_1002"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/instances
+ ```
+* _/clusters/{clusterName}/instances/{instanceName}_
+ * Show instance information
+
+ ```
+ curl http://localhost:8100/clusters/MyCluster/instances/localhost_1001
+ ```
+
+ * Enable/disable an instance
+
+ ```
+ curl -d 'jsonParameters={"command":"enableInstance","enabled":"false"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/instances/localhost_1001
+ ```
+
+ * Drop an instance
+
+ ```
+ curl -X DELETE http://localhost:8100/clusters/MyCluster/instances/localhost_1001
+ ```
+
+ * Disable/enable partitions on an instance
+
+ ```
+ curl -d 'jsonParameters={"command":"enablePartition","resource": "MyDB","partition":"MyDB_0", "enabled" : "false"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/instances/localhost_1001
+ ```
+
+ * Reset an erroneous partition on an instance
+
+ ```
+ curl -d 'jsonParameters={"command":"resetPartition","resource": "MyDB","partition":"MyDB_0"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/instances/localhost_1001
+ ```
+
+ * Reset all erroneous partitions on an instance
+
+ ```
+ curl -d 'jsonParameters={"command":"resetInstance"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/instances/localhost_1001
+ ```
+
+* _/clusters/{clusterName}/configs_
+ * Get user cluster level config
+
+ ```
+ curl http://localhost:8100/clusters/MyCluster/configs/cluster
+ ```
+
+ * Set user cluster level config
+
+ ```
+ curl -d 'jsonParameters={"command":"setConfig","configs":"key1=value1,key2=value2"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/configs/cluster
+ ```
+
+ * Remove user cluster level config
+
+ ```
+ curl -d 'jsonParameters={"command":"removeConfig","configs":"key1,key2"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/configs/cluster
+ ```
+
+ * Get/set/remove user participant level config
+
+ ```
+ curl -d 'jsonParameters={"command":"setConfig","configs":"key1=value1,key2=value2"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/configs/participant/localhost_1001
+ ```
+
+ * Get/set/remove resource level config
+
+ ```
+ curl -d 'jsonParameters={"command":"setConfig","configs":"key1=value1,key2=value2"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/configs/resource/MyDB
+ ```
+
+* _/clusters/{clusterName}/controller_
+ * Show controller information
+
+ ```
+ curl http://localhost:8100/clusters/MyCluster/Controller
+ ```
+
+ * Enable/disable cluster
+
+ ```
+ curl -d 'jsonParameters={"command":"enableCluster","enabled":"false"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/Controller
+ ```
+
+* _/zkPath/{path}_
+ * Get information for zookeeper path
+
+ ```
+ curl http://localhost:8100/zkPath/MyCluster
+ ```
+
+* _/clusters/{clusterName}/StateModelDefs_
+ * Show all state model definitions
+
+ ```
+ curl http://localhost:8100/clusters/MyCluster/StateModelDefs
+ ```
+
+ * Add a state mdoel definition
+
+ ```
+ echo jsonParameters={
+ "command":"addStateModelDef"
+ }&newStateModelDef={
+ "id" : "OnlineOffline",
+ "simpleFields" : {
+ "INITIAL_STATE" : "OFFLINE"
+ },
+ "listFields" : {
+ "STATE_PRIORITY_LIST" : [ "ONLINE", "OFFLINE", "DROPPED" ],
+ "STATE_TRANSITION_PRIORITYLIST" : [ "OFFLINE-ONLINE", "ONLINE-OFFLINE", "OFFLINE-DROPPED" ]
+ },
+ "mapFields" : {
+ "DROPPED.meta" : {
+ "count" : "-1"
+ },
+ "OFFLINE.meta" : {
+ "count" : "-1"
+ },
+ "OFFLINE.next" : {
+ "DROPPED" : "DROPPED",
+ "ONLINE" : "ONLINE"
+ },
+ "ONLINE.meta" : {
+ "count" : "R"
+ },
+ "ONLINE.next" : {
+ "DROPPED" : "OFFLINE",
+ "OFFLINE" : "OFFLINE"
+ }
+ }
+ }
+ > newStateModelDef.json
+ curl -d @'./untitled.txt' -H 'Content-Type: application/json' http://localhost:8100/clusters/MyCluster/StateModelDefs
+ ```
+
+* _/clusters/{clusterName}/StateModelDefs/{stateModelDefName}_
+ * Show a state model definition
+
+ ```
+ curl http://localhost:8100/clusters/MyCluster/StateModelDefs/OnlineOffline
+ ```
+
+* _/clusters/{clusterName}/constraints/{constraintType}_
+ * Show all contraints
+
+ ```
+ curl http://localhost:8100/clusters/MyCluster/constraints/MESSAGE_CONSTRAINT
+ ```
+
+ * Set a contraint
+
+ ```
+ curl -d 'jsonParameters={"constraintAttributes":"RESOURCE=MyDB,CONSTRAINT_VALUE=1"}' -H "Content-Type: application/json" http://localhost:8100/clusters/MyCluster/constraints/MESSAGE_CONSTRAINT/MyConstraint
+ ```
+
+ * Remove a constraint
+
+ ```
+ curl -X DELETE http://localhost:8100/clusters/MyCluster/constraints/MESSAGE_CONSTRAINT/MyConstraint
+ ```