Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time
January 17, 2022 09:22
October 31, 2018 08:33
October 4, 2021 12:54
October 15, 2020 16:05
January 17, 2022 09:31
October 19, 2022 08:26
October 4, 2021 11:48
October 3, 2022 13:48
October 16, 2018 15:28
October 4, 2021 12:54
March 29, 2022 09:55
October 15, 2018 16:28
January 17, 2022 09:31

alternate text

Elastic Cloud Computing Cluster (EC3) is a tool to create elastic virtual clusters on top of Infrastructure as a Service (IaaS) providers, either public (such as Amazon Web Services, Google Cloud or Microsoft Azure) or on-premises (such as OpenNebula and OpenStack). We offer recipes to deploy TORQUE (optionally with MAUI), SLURM, SGE, HTCondor, Mesos, Nomad and Kubernetes clusters that can be self-managed with CLUES: it starts with a single-node cluster and working nodes will be dynamically deployed and provisioned to fit increasing load (number of jobs at the LRMS). Working nodes will be undeployed when they are idle. This introduces a cost-efficient approach for Cluster-based computing.



The program ec3 requires Python 2.6+, PLY, PyYAML, Requests, jsonschema and an IM server, which is used to launch the virtual machines.

PyYAML is usually available in distribution repositories (python-yaml in Debian; PyYAML in Red Hat; and PyYAML in pip).

PLY is usually available in distribution repositories (python-ply and ply in pip).

Requests is usually available in distribution repositories (python-requests and requests in pip).

jsonschema is usually available in distribution repositories (python-jsonschema and jsonschema in pip).

By default ec3 uses our public IM server in Optionally you can deploy a local IM server following the instructions of the IM manual.

Also sshpass command is required to provide the user with ssh access to the cluster.


As Python 2 is no longer supported, we recommend to install ec3 with Python 3.

First you need to install pip tool. To install them in Debian and Ubuntu based distributions, do:

sudo apt update
sudo apt install -y python3-pip

In Red Hat based distributions (RHEL, CentOS, Amazon Linux, Oracle Linux, Fedora, etc.), do:

sudo yum install -y epel-release
sudo yum install -y which python3-pip

Then you only have to call the install command of the pip tool with the ec3-cli package:

sudo pip3 install ec3-cli

You can also download the last ec3 version from this git repository:

git clone

Then you can install it calling the pip tool with the current ec3 directory:

sudo pip3 install ./ec3

Basic example with Amazon EC2

First create a file auth.txt with a single line like this:

id = provider ; type = EC2 ; username = <<Access Key ID>> ; password = <<Secret Access Key>>

Replace <<Access Key ID>> and <<Secret Access Key>> with the corresponding values for the AWS account where the cluster will be deployed. It is safer to use the credentials of an IAM user created within your AWS account.

This file is the authorization file (see Authorization file), and can have more than one set of credentials.

The next command deploys a TORQUE cluster based on an Ubuntu image:

$ ec3 launch mycluster torque ubuntu-ec2 -a auth.txt -y
WARNING: you are not using a secure connection and this can compromise the secrecy of the passwords and private keys available in the authorization file.
Creating infrastructure
Infrastructure successfully created with ID: 60
   ▄▟▙▄¨        Front-end state: running, IP:

If you deployed a local IM server, use the next command instead:

$ ec3 launch mycluster torque ubuntu-ec2 -a auth.txt -u http://localhost:8899

This can take several minutes.

Bear in mind that you have to specify a resource manager (like torque in our example) in addition to the images that you want to deploy (e.g. ubuntu-ec2). For more information about this check the templates documentation.

You can show basic information about the deployed clusters by executing:

$ ec3 list
    name       state          IP        nodes
  mycluster  configured    0

Once the cluster has been deployed, open a ssh session to the front-end (you may need to install the sshpass library):

$ ec3 ssh mycluster
Welcome to Ubuntu 14.04.1 LTS (GNU/Linux 3.13.0-24-generic x86_64)

You may use the cluster as usual, depending on the LRMS. For Torque, you can decide to submit a couple of jobs using qsub, to test elasticity in the cluster:

$ for i in 1 2; do echo "/bin/sleep 50" | qsub; done

Notice that CLUES will intercept the jobs submited to the LRMS to deploy additional working nodes if needed. This might result in a customizable (180 seconds by default) blocking delay when submitting jobs when no additional working nodes are available. This guarantees that jobs will enter execution as soon as the working nodes are deployed and integrated in the cluster.

Working nodes will be provisioned and relinquished automatically to increase and decrease the cluster size according to the elasticity policies provided by CLUES.

Enjoy your virtual elastic cluster!

EC3 in Docker Hub

EC3 has an official Docker container image available in Docker Hub and GitHub Container Regitry that can be used instead of installing the CLI. You can download it by typing:

$ sudo docker pull grycap/ec3
$ sudo docker pull

You can exploit all the potential of EC3 as if you download the CLI and run it on your computer:

$ sudo docker run grycap/ec3 list
$ sudo docker run grycap/ec3 templates

To launch a cluster, you can use the recipes that you have locally by mounting the folder as a volume. Also it is recommendable to mantain the data of active clusters locally, by mounting a volume as follows:

$ sudo docker run -v /home/user/:/tmp/ -v /home/user/ec3/templates/:/etc/ec3/templates -v /home/user/.ec3/clusters:/root/.ec3/clusters grycap/ec3 launch mycluster torque ubuntu16 -a /tmp/auth.dat

Notice that you need to change the local paths to the paths where you store the auth file, the templates folder and the .ec3/clusters folder. So, once the front-end is deployed and configured you can connect to it by using:

$ sudo docker run -ti -v /home/user/.ec3/clusters:/root/.ec3/clusters grycap/ec3 ssh mycluster

Later on, when you need to destroy the cluster, you can type:

$ sudo docker run -ti -v /home/user/.ec3/clusters:/root/.ec3/clusters grycap/ec3 destroy mycluster

Additional information