The following sections will describe the commands which come bundled with the CLI tool that will allow you to interact with clusters on CycleCloud. To see a listing of all available commands you can run:

$ cyclecloud help

To get inline help for any command you can type cyclecloud <COMMAND> -h, for example:

$ cyclecloud import_cluster -h
Usage: cyclecloud import_cluster CLUSTER [options]

Imports a cluster from StarCluster.

Options:
  -h, --help            Show this help message and exit.

  -c TEMPLATE           The template name to use. If not specified, the
                        default is used.

  --sc                  If specified, the template is parsed as a StarCluster
                        file.

  --force               If specified, the cluster will be replaced if it
                        exists.

  -f FILE, --file=FILE  The file from which to import the template

initialize

The initialize command will ask about how to connect to your CycleCloud instance as well as your AWS account information so that a user can be created to spin up clusters.

config

The config command helps you switch easily between different CycleCloud configurations. You likely already have a CycleCloud configuration in place. To name the configuration that you currently have in place at ~/.cycle/config.ini:

$ cyclecloud config rename dev.cyclecloud.com

CycleCloud will create ~/.cycle/cyclecloud directory, move the current config to ~/.cycle/cyclecloud/dev.cyclecloud.com, and create a symlink ~/.cycle/config.ini that points to to ~/.cycle/cyclecloud/dev.cyclecloud.com

If you feel dev.cyclecloud.com is too long of a name, you can easily change the name of the configuration:

$ cyclecloud config rename dev

Assume that we have a new CycleCloud install for QA purposes, let’s create the configuration file for that:

$ cyclecloud config create qa.cyclecloud.com

cyclecloud config will remove the current symlink at ~/.cycle/config.ini, create ~/.cycle/cyclecloud/qa.cyclecloud.com, and create a symlink ~/.cycle/config.ini that points back to ~/.cycle/cyclecloud/qa.cyclecloud.com

To show the current configuration:

$ cyclecloud config show
 acme-prod : url = https://54.33.11.5:8443

To see all available configurations:

$ cyclecloud config list
 acme-prod : url = https://54.33.11.5:8443 [CURRENT]
 acme-qa : url = https://54.33.11.9:8443
 acme-dev : url = https://54.33.11.44:8443

To change the configuration in use:

$ cyclecloud config use NAME

While the examples above are all for *nix platforms, the cyclecloud config command also works on Windows.

import_template

This command allows you to import a cluster template from a cluster defintion file. Once imported these cluster templates can be used to create clusters using the the create_cluster command or from the UI.

For example:

$ cyclecloud import_template GridEngineCluster -f gridengine_template.txt
Importing template GridEngineCluster....
------------------------------
GridEngineCluster : *template*
------------------------------
Keypair: cyclecloud
Cluster nodes:
  master: off
Total nodes: 1

The above command imports a cluster template named GridEngineCluster from the template file gridengine_template.txt.

Note that if the file contains only one cluster, you can omit the cluster name on the command line.

create_cluster

This command allows you to create a cluster from a previously imported template. By passing a parameters file you can customize the cluster template to your needs, this is analagous to using the “Add Cluster” button from the UI.

For example:

$ cyclecloud create_cluster GridEngineCluster DemoCluster -p parameters.json
-----------------
DemoCluster : off
-----------------
Keypair: 000cyclecloud
Cluster nodes:
    master: off
Total nodes: 1

The above command create a cluster named DemoCluster from the previously imported template GridEngineCluster using the parameters specified in parameters.json

import_cluster

The import command allows you to import or update cluster configurations from a cluster definition file. Some basic templates are installed by the CLI tools during the initialize step (found in ~/.cycle/) that you can use or modify to suit your own needs.

For example:

$ cyclecloud import_cluster demo --file ~/.cycle/sge_templates.txt -c sge
Creating cluster demo....
----
demo
----
Keypair: cyclecloud
Cluster nodes:
    master: off
Total nodes: 1
Creating cluster demo....

The above command imports a cluster named demo using the cluster named sge in the built-in template file ~/.cycle/sge_templates.txt. If you already have a cluster with the same name as the one you are creating you will get an error to prevent accidental updates to existing clusters. If you are sure that you want to update the cluster’s configuration with the new template you can use the --force to make the action go through. Note that you cannot currently change the size of an existing cluster by re-importing a template.

Multiple cluster templates or multiple copies of the same cluster template may be imported simply by choosing separate names.

For example:

$ cyclecloud import_cluster demo_copy --file ~/.cycle/sge_templates.txt -c sge
Creating cluster demo_copy....
---------
demo_copy
---------
Keypair: cyclecloud
Cluster nodes:
    master: off
Total nodes: 1
Creating cluster demo....

export_parameters

The export_parameters allows you to export all the parameters for a given cluster. By default, the export_parameters command outputs a JSON document. It also supports outputting to XML and CSV.

For example:

$ cyclecloud export_parameters mycluster
{
 "InitialExecuteCoreCount" : 0,
 "MaxExecuteCoreCount" : 10,
 "ReturnProxy" : true,
 "Autoscale" : true,
 "CmMachineType" : "m3.large",
 "ExecuteMachineType" : "m3.large",
 "awsUseSpot" : false,
 "ClusterInit" : "cluster-init",
 "awsBidPrice" : null,
 "CloudProvider" : "AWS",
 "ChefRepoVersion" : null
}

copy_cluster

The copy_cluster command makes a duplicate of an existing cluster:

$ cyclecloud copy_cluster mycluster yourcluster

Making a copy of cluster mycluster as cluster yourcluster ....
-----------------
yourcluster : off
-----------------
Keypair: cyclecloud
Cluster nodes:
    master: off
Total nodes: 1

It supports the use of a parameter file to change the parameters in the new copy of a cluster. For example, if mycluster had the parameters in the above section and one wanted to change the ExecuteMachineType in the new copy:

$ cat largecluster_param.json
{
 "ExecuteMachineType" : "c3.8large",
}

$ cyclecloud copy_cluster mycluster mylargercluster -p largecluster_param.json
---------------------
mylargercluster : off
---------------------
Keypair: cyclecloud
Cluster nodes:
    master: off
Total nodes: 1

StarCluster support

The import command also supports importing from files in StarCluster format with the --sc argument. Note: the volume, permission, and plugin sections are not currently supported, and the resulting cluster is not configured in the same way. CycleCloud supports the following extensions to StarCluster:

subnet_id
If given, the nodes will be launched in the given VPC subnet.
security_groups
This is a comma-separated list of security group IDs to assign to the nodes.
master_bid_price/node_bid_price
If specified (in dollars), this creates spot instance requests for the master or execute nodes. Note: since spot instances can be terminated suddenly, they are not recommended for the master node.
master_elastic_ip
If specified, the master will use the given Elastic IP.

start_cluster

The start command analyzes the cluster to determine what instances to create and how they should be configured, and issues the appropriate AWS commands.

For example:

$ cyclecloud start_cluster demo
Starting cluster demo....
----
demo
----
Keypair: cyclecloud
Cluster nodes:
    master:  Launching instance
Total nodes: 1

Note that when a cluster is started, its nodes will be in a pending state but you will have access to the AWS instance ID. The other information about each of the nodes will become available as the requests are fulfilled. To get an updated status on the state of the cluster that was just started, see the show_cluster command.

show_cluster

If no cluster name is specified, this command will list all the clusters managed by CycleCloud along with their details.

For example:

$ cyclecloud show_cluster
----
demo
----
Keypair: cyclecloud
Cluster nodes:
    master:  running i-433c413f ec2-75-101-218-237.compute-1.amazonaws.com (10.96.214.97)
Total nodes: 1

---------
demo_copy
---------
Keypair: cyclecloud
Cluster nodes:
    master:  off
Total nodes: 1

The result of this show_cluster command shows that there are two clusters available. One named ‘demo’, which has been started and one named ‘demo_copy’, that is not currently running.

Optionally, the show_cluster command takes the name of a cluster and displays the details about all the nodes in that cluster. When a cluster is starting up, it is useful to run this command to check the cluster’s state to see when it becomes ready for use.

For example:

$ cyclecloud show_cluster demo
----
demo
----
Keypair: cyclecloud
Cluster nodes:
    master:  running i-433c413f ec2-75-101-218-237.compute-1.amazonaws.com (10.96.214.97)
Total nodes: 1

When the cluster is up and running you will be able to see detailed information about the cluster such as the availability zone the cluster is running in, the keypair it is using (if any), and each of the nodes in the cluster along with their state, instance ID, public hostname, and internal IP address.

add_node

The add command allows you to add more nodes to a cluster. You can specify a template to use for the new nodes by using the -t option and the number of nodes to add using the c option. If these options are not specified the template name defaults to execute` and a count of 1 will be used.

The add command also provides a --fixed command line option that instructs CycleCloud to permanently add the nodes to the cluster’s template. “Fixed” nodes become part of the cluster template, and will be restarted automatically after cluster termination and restart. If the nodes are not “Fixed” (default), then the nodes are automatically removed when the cluster is terminated.

To add 3 execute nodes to the demo cluster for example:

$ cyclecloud add_node demo -t execute -c 3 --fixed
Adding nodes to cluster demo....
----
demo
----
Keypair: cyclecloud
Cluster nodes:
    master:  running i-433c413f ec2-75-101-218-237.compute-1.amazonaws.com (10.96.214.97)
Cluster node arrays:
    execute: 3 instances, 3 cores, Allocation (AWS.RunInstances/default/us-east)
Total nodes: 4

To see the host information for individual nodes in node arrays, use the -l argument with the show_cluster command. For example:

$ cyclecloud show_cluster demo -l
----
demo
----
Keypair: cyclecloud
Cluster nodes:
    execute-1: running i-58bc7232 ec2-50-16-61-74.compute-1.amazonaws.com (10.232.47.229)
    execute-2: running i-56bc723c ec2-54-226-86-249.compute-1.amazonaws.com (10.171.18.169)
    execute-3: running i-54bc723e ec2-23-20-151-71.compute-1.amazonaws.com (10.233.21.43)
    master:  running i-433c413f ec2-75-101-218-237.compute-1.amazonaws.com (10.96.214.97)
Total nodes: 4

reboot_node

The reboot command forces a running node to reboot without terminating the instance.

To reboot an execute node in the demo cluster for example:

cyclecloud reboot_node demo execute-1
Rebooting node execute-1 in cluster demo...
----
demo
----
Keypair: cyclecloud
Cluster nodes:
    master:  running i-433c413f ec2-75-101-218-237.compute-1.amazonaws.com (10.96.214.97)
Cluster node arrays:
    execute: 3 instances, 3 cores, Started
Total nodes: 4

terminate_node

The terminate command can be used to shutdown nodes in a running cluster. If the running node was a “Fixed” node (or part of the cluster template), it will transition to the “Off” state. If the running node was auto-started or added without the “Fixed” attribute, it will be automatically removed upon termination.

For example to shutdown a node in the demo cluster:

cyclecloud terminate_node demo execute-1
Terminating node execute-1 in cluster demo....
----
demo
----
Keypair: cyclecloud
Cluster nodes:
    master:  running i-433c413f ec2-75-101-218-237.compute-1.amazonaws.com (10.96.214.97)
Cluster node arrays:
     execute:         1 instances, 1 cores, Termination (AWS.TerminateInstances)
     execute:         2 instances, 2 cores, Started
Total nodes: 4

And after a short delay:

$ cyclecloud show_cluster demo -l
----
demo
----
Keypair: cyclecloud
Cluster nodes:
    execute-1: off
    execute-2: running i-56bc723c ec2-54-226-86-249.compute-1.amazonaws.com (10.171.18.169)
    execute-3: running i-54bc723e ec2-23-20-151-71.compute-1.amazonaws.com (10.233.21.43)
    master:  running i-433c413f ec2-75-101-218-237.compute-1.amazonaws.com (10.96.214.97)
Total nodes: 4

The terminate_node command also supports advanced filtering options to perform bulk removal of nodes. The powerful --filter and --instance-filter options allow you to filter nodes and instances respectively using an arbitrary filter expression written in the classad expression format.

The --creds option also allows you to remove all the nodes started with a given credential name.

For example, to terminate all the nodes with the template ‘execute’ at once:

$ cyclecloud terminate_node sge --filter 'Template==="execute"'
The following nodes matched your filter in cluster demo:
 Name        ClusterName   InstanceId   MachineType                               PublicHostname   SecurityGroups
-------------------------------------------------------------------------------------------------------------------
 execute-2           demo   i-56bc723c      m1.small   ec2-54-211-138-249.compute-1.amazonaws.com          default
 execute-3           demo   i-54bc723e      m1.small    ec2-75-101-173-88.compute-1.amazonaws.com          default

Do you wish to terminate these instances? [y/N]

Typing ‘y’ will then terminate all the nodes listed.

start_node

The start command is used to re-start individual nodes that are part of a running cluster, but currently in the “Off” state. Nodes may be in the “off” state because the underlying instance failed or because the node was previously terminated using the terminate_node command.

For example, to restart “execute-1” terminated above:

$ cyclecloud start_node demo execute-1
Starting node execute-1 in cluster demo...
----
demo
----
Keypair: cyclecloud
Cluster nodes:
    master:  running i-433c413f ec2-75-101-218-237.compute-1.amazonaws.com (10.96.214.97)
Cluster node arrays:
    execute:         1 instances, 1 cores, Allocation (AWS.RunInstances/default/us-east)
    execute:         2 instances, 2 cores, Started
Total nodes: 4

remove_node

The remove command terminates (if running) and removes a node from a cluster. The remove command is used to modify an loaded cluster template by removing nodes without requiring a re-import.

Note that the difference between terminate_node and remove_node, is that remove_node permenantly removes the node from the cluster template rather than simply shutting the node down.

For example, to remove a node from the demo cluster:

$ cyclecloud remove_node demo execute-1
Removing node execute-1 in cluster demo....
----
demo
----
Keypair: cyclecloud
Cluster nodes:
    master:  running i-433c413f ec2-75-101-218-237.compute-1.amazonaws.com (10.96.214.97)
Cluster node arrays:
    execute:         1 instances, 1 cores, Termination (AWS.TerminateInstances)
    execute:         2 instances, 2 cores, Started
Total nodes: 4

And after a short delay:

$ cyclecloud show_cluster demo -l
----
demo
----
Keypair: cyclecloud
Cluster nodes:
    execute-2: running i-56bc723c ec2-54-226-86-249.compute-1.amazonaws.com (10.171.18.169)
    execute-3: running i-54bc723e ec2-23-20-151-71.compute-1.amazonaws.com (10.233.21.43)
    master:  running i-433c413f ec2-75-101-218-237.compute-1.amazonaws.com (10.96.214.97)
Total nodes: 3

The remove node command also supports advanced filtering options to perform bulk removal of nodes. The powerful --filter and --instance-filter options allow you to filter nodes and instances respectively, using an arbitrary filter expression written in the classad expression format.

The --creds option also allows you to remove all the nodes started with a given credential name.

For example, to remove all the nodes with the template ‘execute’ at once:

$ cyclecloud remove_node sge --filter 'Template==="execute"'
The following nodes matched your filter in cluster demo:
 Name        ClusterName   InstanceId   MachineType                               PublicHostname   SecurityGroups
-------------------------------------------------------------------------------------------------------------------
 execute-2           demo   i-56bc723c      m1.small   ec2-54-211-138-249.compute-1.amazonaws.com          default
 execute-3           demo   i-54bc723e      m1.small    ec2-75-101-173-88.compute-1.amazonaws.com          default

Do you wish to remove these instances? [y/N]

Typing ‘y’ will then remove all the nodes listed.

terminate_cluster

The terminate command terminates all nodes in the cluster and cancels all spot instance requests.

For example:

$ cyclecloud terminate_cluster demo
Terminating cluster demo....
----
demo
----
Keypair: cyclecloud
Cluster nodes:
    master:  Terminating instance i-433c413f
Cluster node arrays:
   execute: 2 instances, 2 cores, Termination (AWS.TerminateInstances)
Total nodes: 3

delete_cluster

The delete command will remove a non-running cluster from CycleCloud. If the cluster is already running, you will have to execute the terminate_cluster command before delete_cluster.

For example:

$ cyclecloud delete_cluster demo
Deleting cluster demo....

retry

In the event that an error occurs during any of the operations taking place to start a cluster such as invalid credentials, bad machine type, security group, etc., the retry command will re-execute the operations that failed. If you had, for instance, selected an invalid machine type, m1.smaller instead of m1.small, you would want to update your template file with the change, re-import the cluster using the --force option and then run the retry command to re-issue failed commands.

For example:

$ cyclecloud import_cluster demo -f ~/.cycle/sge_templates.txt --force

$ cyclecloud retry demo
Retrying failed operations for cluster demo....

connect

You can connect to machines running in CycleCloud with the connect command:

cyclecloud connect NODE_NAME

where NODE_NAME is either the name of the node or the instance ID to connect to. If the node name is ambiguous because you have two clusters using the same node name, you can specify the cluster with the -c CLUSTER argument.

Connecting to Windows machines is done via RDP (Remote Desktop Protocol). CycleCloud acquires the password for the instance and connects to it, by running a command line for your local OS:

  • Windows Uses the built-in mstsc client.

Note

Requires Windows Vista or later.

  • OS X Uses an rdp:// protocol handler, such as CoRD.
  • Others Not automatically supported, but you can add your own.

You can specify this command by setting rdp_command inside the cyclecloud section of your config.ini file:

[cyclecloud]
# Uses a fictional rdp_client program
rdp_command = rdp_client ${HOSTNAME} ${USERNAME} ${PASSWORD}

Connecting to Unix instances uses SSH. If the keypair for the node is known, it is added to the ssh command line. If not, it is assumed to be already added to a running ssh-agent.

Note that the keypair is required for Windows and Unix instances to decrypt the Administrator password. If the keypair was specified with KeyPairLocation on the node, it is used automatically. If not, the -k PATH_TO_KEYPAIR option lets you specify it. Furthermore, when connecting to a Windows instance, the path must be available to CycleCloud.

show_nodes

You can query the status of nodes/instances tracked by CycleCloud across multiple clusters using the show_nodes command:

cyclecloud show_nodes [NODE_NAME] [FILTER]

The optional NODE_NAME is either the name or instance id of a specific node to show. Instead of a node name, a FILTER may be provided to select a set of nodes to view.

show_nodes provides several built-in filters. You can select a node by name or instance ID using node_id. You can also filter nodes by cluster (--cluster), state (--states), and/or credentials used to start the node (--creds).

For complete control, the command also provides a powerful --filter and --instance-filter options, which allow you to filter nodes and instances respectively using an arbitrary filter expression written in the classad expression format.

Finally, the command also provides several output formating options:

  • You can request a specific list of node attributes using the --attrs option.
  • The --summary option requests a minimal set of data which is useful when viewing potentially large numbers of nodes.
  • The --long option can be used to request the complete set of node and instance data.
  • The --output option provides custom formatting of a selection of node and instance attributes. This can be used to format the data for parsing by a user application.

Finally, (when not using the --output mode), you can request output in csv, text, xml, JSON, or tabular format using the --format option.

Here’s an example of using a --filter expression to select nodes in the started state, and the --attrs option to limit the amount of data to a few relevant attributes:

$ cyclecloud show_nodes --filter='State === "Started"' --attrs=Name,MachineType
Name = "winnode-1"
Instance = [MachineType="m1.large"]
MachineType = "m1.large"

Name = "ad_server"
Instance = [MachineType="m1.large"]
MachineType = "m1.large"

Note

Both the node and it’s underlying instance contain a MachineType attribute, so it appears in both the node data and the contained instance data.

In the next example, we’re requesting the same attributes using the simpler --state option and requesting that the output be formatted as JSON:

$ cyclecloud show_nodes --state=Started --format=json --attrs=Name,MachineType
[ {
  "Name" : "winnode-1",
  "Instance" : {
    "MachineType" : "m1.large"
  },
  "MachineType" : "m1.large"
}, {
  "Name" : "ad_server",
  "Instance" : {
    "MachineType" : "m1.large"
  },
  "MachineType" : "m1.large"
} ]

Finally, here’s an example of using the --output formatter to get the data in an easily parsable “comma + tab” separated format:

$ cyclecloud show_nodes --filter='State === "Started"' --output="%(Name)s,t%(MachineType)s"
winnode-1,    m1.large
ad_server,    m1.large