website/0.9.0/src/site/markdown/tutorial

Helix Tutorial: Admin Operations

Helix provides a set of admin APIs for cluster management operations. They are supported via:

Java API
Command Line Interface
REST Interface via helix-admin-webapp

Java API

See interface org.apache.helix.HelixAdmin

Command Line Interface

The command line tool comes with helix-core package:

Get the command line tool:

git clone https://git-wip-us.apache.org/repos/asf/helix.git
cd helix
git checkout tags/helix-0.8.4
./build
cd helix-core/target/helix-core-pkg/bin
chmod +x *.sh

Get help:

./helix-admin.sh --help

All other commands have this form:

./helix-admin.sh --zkSvr <ZookeeperServerAddress> <command> <parameters>

Supported Commands

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/helix.git
cd helix
git checkout tags/helix-0.8.4
./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