Usage

The syntax of the elasticluster command is:

elasticluster [-v] [-s PATH] [-c PATH] [subcommand] [subcommand args and opts]

The following options are general and are accepted by any subcommand:

-h, --help
Show an help message and exits.
-v, --verbose
Adding one or more -v will increase the verbosity accordingly.

-s PATH, --storage PATH

Path to the storage folder. This directory is used to store information about the cluster which are running. By default this is ``~/.elasticluster/storage`

WARNING: If you delete this directory elasticluster will not be able to access the cluster anymore!

-c PATH, --config PATH

Path to the configuration file. By default this is ~/.elasticluster/config

elasticluster provides multiple subcommands to start, stop, resize, inspect your clusters. The available subcommands are:

start
Create a cluster using one of the configured cluster tmplate.
stop
Stop a cluster and all associated VM instances.
list
List all clusters that are currently running.
list-nodes
Show information about the nodes in a specific started cluster.
list-templates
Show the available cluster configurations, as defined in the configuration file.
setup
Run ansible to configure the cluster.
resize
Resize a cluster by adding or removing nodes.
ssh
Connect to the frontend of the cluster using the ssh command.
sftp
Open an SFTP session to the cluster frontend host.

An help message explaining the available options and subcommand of elasticluster is available by running:

elasticluster -h

Options and arguments accepted by a specific subcommand <cmd> is available by running:

elasticluster <cmd> -h

The start command

This command will start a new cluster using a specific cluster configuration, defined in the configuration file. You can start as many clusters you want using the same cluster configuration, by providing different --name options.

Basic usage of the command is:

usage: elasticluster start [-h] [-v] [-n CLUSTER_NAME]
                           [--nodes N1:GROUP[,N2:GROUP2,...]] [--no-setup]
                           cluster

cluster is the name of a cluster section in the configuration file. For instance, to start the cluster defined by the section [cluster/slurm] you must run the command:

elasticluster start slurm

The following options are available:

-h, --help
Show an help message and exits.
-v, --verbose
Adding one or more -v will increase the verbosity accordingly.
-n CLUSTER_NAME, --name CLUSTER_NAME
Name of the cluster. By default this is the same as the cluster configuration name.

--nodes N1:GROUP[,N2:GROUP2,...]

This option allow you to override the values stored in the configuration file, by starting a different number of hosts fore each group.

Assuming you defined, for instance, a cluster with the following type of nodes in the configuration file:

hadoop-data_nodes=4
hadoop-task_nodes=4

and you want to run instead 10 data nodes and 10 task nodes, you can run elasticluster with option:

elasticluster ... --nodes 10:hadoop-data,10:hadoop-task
--no-setup
By default elasticluster will automatically run the setup command after all the virtual machines are up and running. This option prevent the setup step to be run and will leave the cluster unconfigured.

When you start a new cluster, elasticluster will:

  • create the requested/configured number of virtual machines.
  • wait until all the virtual machines are started.
  • wait until elasticluster is able to connect to all the virtual machines using ssh.
  • run ansible on all the virtual machines (unless --no-setup option is given).

This process can take several minutes, depending on the load of the cloud, the configuration of the cluster and your connection speed. Elasticluster usually print very few information on what’s happening, if you run it with -v it will display a more verbose output (including output of ansible command) to help you understanding what is actually happening.

After the setup process is done a summary of the created cluster is printed, similar to the following:

Cluster name:     slurm
Cluster template: slurm
Frontend node: frontend001
- compute nodes: 2
- frontend nodes: 1

To login on the frontend node, run the command:

    elasticluster ssh slurm

To upload or download files to the cluster, use the command:

    elasticluster sftp slurm

The first line tells you the name of the cluster, which is the one you are supposed to use with the stop, list-nodes, resize, ssh and sftp commands.

The second line specifies the cluster configuration section used to configure the cluster (in this case, for instance, the section [cluster/slurm] has been used)

The Frontend node line shows which node is used for the ssh and sftp commands, when connecting to the cluster.

Then a list of how many nodes of each type have been started

The remaining lines describe how to connect to the cluster either by opening an interactive shell to run commands on it, or an sftp session to upload and download files.

The stop command

The stop command will terminate all the instances running and delete all information related to the cluster saved on the local disk.

WARNING: elasticluster doesn’t do any kind of test to check if the cluster is used!

Basic usage of the command is:

usage: elasticluster stop [-h] [-v] [--force] [--yes] cluster

Like the start command, cluster is the name of a cluster section in the configuration file.

The following options are available:

-h, --help
Show an help message and exits.
-v, --verbose
Adding one or more -v will increase the verbosity accordingly.

--force

If some of the virtual machines fail to terminate (for instance because they have been terminated already not by elasticluster), this command will ignore these errors and will force termination of all the other instances.

--yes

Since stopping a cluster is a possibly desruptive action, elasticluster will always ask for confirmation before doing any modification, unless this option is given.

The list command

The list command print a list of all the cluster that have been started. For each cluster, it will print a few information including the cloud used and the number of nodes started for each node type:

$ elasticluster list

The following clusters have been started.
Please note that there's no guarantee that they are fully configured:

centossge
---------
  name:           centossge
  template:       centossge
  cloud:          hobbes
  - frontend nodes: 1
  - compute nodes: 2

slurm
-----
  name:           slurm
  template:       slurm
  cloud:          hobbes
  - frontend nodes: 1
  - compute nodes: 2

slurm13.04
----------
  name:           slurm13.04
  template:       slurm13.04
  cloud:          hobbes
  - frontend nodes: 1
  - compute nodes: 2

The list-nodes command

The list-nodes command print information on the nodes belonging to a specific cluster.

Basic usage of the command is:

usage: elasticluster list-nodes [-h] [-v] [-u] cluster

cluster is the name of a cluster that has been started previously.

The following options are available:

-h, --help
Show an help message and exits.
-v, --verbose
Adding one or more -v will increase the verbosity accordingly.

-u, --update

By default elasticluster list-nodes will not contact the EC2 provider to get up-to-date information, unless -u option is given.

Example:

$ elasticluster list-nodes centossge

Cluster name:     centossge
Cluster template: centossge
Frontend node: frontend001
- frontend nodes: 1
- compute nodes: 2

To login on the frontend node, run the command:

    elasticluster ssh centossge

To upload or download files to the cluster, use the command:

    elasticluster sftp centossge

frontend nodes:

  - frontend001
    public IP:   130.60.24.61
    private IP:  10.10.10.36
    instance id: i-0000299f
    instance flavor: m1.small

compute nodes:

  - compute001
    public IP:   130.60.24.44
    private IP:  10.10.10.17
    instance id: i-0000299d
    instance flavor: m1.small

  - compute002
    public IP:   130.60.24.48
    private IP:  10.10.10.29
    instance id: i-0000299e
    instance flavor: m1.small

The list-templates command

The list-templates command print a list of all the available templates defined in the configuration file with a few information for each one of them.

Basic usage of the command is:

usage: elasticluster list-templates [-h] [-v] [clusters [clusters ...]]

clusters is used to limit the clusters to be listed and uses a globbing-like pattern matching. For instance, to show all the cluster templates that contains the word slurm in their name you can run the following:

$ elasticluster list-templates *slurm*
11 cluster templates found.

name:     aws-slurm
cloud:     aws
compute nodes: 2
frontend nodes: 1

name:     slurm
cloud:     hobbes
compute nodes: 2
frontend nodes: 1

name:     slurm_xl
cloud:     hobbes
compute nodes: 2
frontend nodes: 1

name:     slurm13.04
cloud:     hobbes
compute nodes: 2
frontend nodes: 1

The setup command

The setup command will run ansible on the desired cluster once again. It is usually needed only when you customize and update your playbooks, in order to re-configure the cluster, since the start command already run ansible when all the machines are started.

Basic usage of the command is:

usage: elasticluster setup [-h] [-v] cluster

cluster is the name of a cluster that has been started previously.

The following options are available:

-h, --help
Show an help message and exits.
-v, --verbose
Adding one or more -v will increase the verbosity accordingly.

The resize command

The resize command allow you to add or remove nodes from a started cluster. Please, be warned that this feature is still experimental, and while adding nodes is usually safe, removing nodes can be desruptive and can leave the cluster in an unknwonw state.

Moreover, there is currently no way to decide which nodes can be removed from a cluster, therefore if you shrink a cluster you must ensure that any node of that type can be removed safely and no job is running on it.

When adding nodes, you have to specify the type of the node and the number of node you want to add. Then, elasticluster will basically re-run the start and setup steps:

  • create the requested/configured number of virtual machines.
  • wait until all the virtual machines are started.
  • wait until elasticluster is able to connect to all the virtual machines using ssh.
  • run ansible on all the virtual machines, including the virtual machines already configured (unless --no-setup option is given).

Growing a cluster (adding nodes to the cluster) should be supported by all the playbooks included in the elasticluster package.

Basic usage of the command is:

usage: elasticluster resize [-h] [-a N1:GROUP1[,N2:GROUP2]]
                            [-r N1:GROUP1[,N2:GROUP2]] [-v] [--no-setup]
                            [--yes]
                            cluster

cluster is the name of a cluster that has been started previously.

The following options are available:

-h, --help
Show an help message and exits.
-v, --verbose
Adding one or more -v will increase the verbosity accordingly.

-a N1:GROUP1[,N2:GROUP2], --add N1:GROUP1[,N2:GROUP2]

This option allow you to specify how many nodes for a specific group you want to add. You can specify multiple nodes separated by a comma.

Assuming you started, for instance, a cluster named hadoop using the default values stored in the configuration file:

hadoop-data_nodes=4
hadoop-task_nodes=4

and assuming you want to add 5 more data nodes and 10 more task nodes, you can run:

elasticluster resize -a 5:hadoop-data,10:hadoop-task

-r N1:GROUP1[,N2:GROUP2], --remove N1:GROUP1[,N2:GROUP2]

This option allow you to specify how many nodes you want to remove from a specific group. It follows the same syntax as the --add option.

WARNING: elasticluster pick the nodes to remove at random, so you have to be sure that any of the nodes can be removed. Moreover, not all the playbooks support shrkinging!

--no-setup

By default elasticluster will automatically run the setup command after starting and/or stopping the virtual machines. This option prevent the setup step to be run. WARNING: use this option wisely: depending on the cluster configuration it is impossible to know in advance what the status of the cluster will be after resizing it and NOT running the setup step.

--yes

Since resizing a cluster, especially shrinking, is a possibly desruptive action and is not supported by all the distributed playbooks, elasticluster will always ask for confirmation before doing any modification, unless this option is given.

The ssh command

After a cluster is started, the easiest way to login on it is by using the ssh command. This command will run the ssh command with the correct options to connect to the cluster using the configured values for user and ssh key to use.

If no ssh_to option is specified in the configuration file, the ssh command will connect to the first host belonging to the type which comes first in alphabetic order, otherwise it will connect to the first host of the group specified by the ssh_to option of the cluster section. However, running the command elasticluster list-nodes <cluster> will show which host will be used as frontend node.

The usage of the ssh command is as follow:

elasticluster ssh <clustername> [ -- ssh arguments]

All the options and arguments following the -- characters will be passed directly to the ssh command.

For instance, if you just want to run the hostname -f command on the frontend of the cluster you can run:

elasticluster ssh <clustername> -- hostname -f

Note that since the IP address of the virtual machines are likely to be reused by different virtual machines, in order to avoid annoying warning messages from ssh elasticluster will add the following options to the ssh command line:

-o UserKnownHostsFile=/dev/null
Use an empty virtual file to check the host key of the remote machine.
-o StrictHostKeyChecking=no
Disable check of the host key of the remove machine, without prompting to ask if the key can be accepted or not.

The sftp command

After a cluster is started, the easiest way to upload or download files to and from the cluster is by using the sftp command. This command will run the sftp command with the correct options to connect to the cluster using the configured values for user and ssh key to use.

If no ssh_to option is specified in the configuration file, the sftp command will connect to the first host belonging to the type which comes first in alphabetic order, otherwise it will connect to the first host of the group specified by the ssh_to option of the cluster section. However, running the command elasticluster list-nodes <cluster> will show which host will be used as frontend node.

The usage of the sftp command is as follow:

elasticluster sftp <clustername> [ -- sftp arguments]

All the options and arguments following the -- characters will be passed directly to the sftp command.

Note that since the IP address of the virtual machines are likely to be reused by different virtual machines, in order to avoid annoying warning messages from ssh elasticluster will add the following options to the sftp command line:

-o UserKnownHostsFile=/dev/null
Use an empty virtual file to check the host key of the remote machine.
-o StrictHostKeyChecking=no
Disable check of the host key of the remove machine, without prompting to ask if the key can be accepted or not.