In addition to the web interface, CycleCloud can be controlled via the command line. CycleCloud’s command-line interface (CLI) tool can be used to create, configure and manage clusters controlled by CycleCloud. It is highly recommended that you install these tools to make cluster management and configuration easier.
The CycleCloud CLI is distributed as a standard installable Python package for v2.4+. It can be used on the same server that CycleCloud is installed on, or on remote clients. The command line tools are a separate download, with pre-built binaries for Linux and Windows.
To begin, copy the CycleCloud binary to a location in your $PATH (for example, /usr/local/bin on Linux).
Installing Command-Line Tools
The CycleCloud CLI is distributed as a Linux binary (cyclecloud-cli-6.5.6.linux64.tar.gz), a Windows binary (cyclecloud-cli-6.5.6.win64.zip) and as source (cyclecloud-cli-6.5.6.tar.gz). The binaries can be used once untarred. The source tarball can be installed just like any Python package.
Using pip is the recommended way of installing the package, as it allows for easy upgrading and removal of Python packages:
pip install cyclecloud-cli-6.5.6.tar.gz
Using easy_install is another easy way to install the CycleCloud CLI package along with all dependencies:
If you have multiple versions of python installed, you can select which version to install on by using version-specific pip or easy_install tools. For example, for python 2.6 you may have a pip installer with the name pip-2.6 or easy_install-2.6.
If you do not have pip or easy_install configured on your system, you can also use the standard setup.py install method:
tar -xzvf cyclecloud-cli-6.5.6.tar.gz cd cyclecloud-cli-6.5.6 python setup.py install
If you get a ‘permission denied’ error when installing, you may need to run the install command with sudo since packages will be written to your system level Python install:
$ sudo easy_install cyclecloud-cli-6.5.6.tar.gz
Test the Install
To make sure that your CLI has been installed correctly, you can run the cyclecloud command with no options. You should receive a help message like the following:
$ cyclecloud Usage: cyclecloud COMMAND [options] Options: -h, --help show this help message and exit ...
If you see this, you have successfully installed the CycleCloud CLI tool.
Before configuring the CycleCloud CLI, make sure that CycleCloud is running and accessible from the machine you are installing on. If you installed CycleCloud on the same machine you are installing the CLI tools on, you should be able to access http://localhost:8080 using your web browser. If you installed CycleServer on a different machine, make sure you can access it via your web browser.
Initialize the CLI
First, run the initialize command. This will ask you a few questions about how to connect to your CycleServer instance. If this is your first time configuring CycleCloud, you must provide some information about your Amazon Web Services (AWS) account. CycleCloud uses this information to start compute clusters and to store data to S3:
$ cyclecloud initialize Welcome to CycleCloud! CycleServer URL: [http://localhost:8080] http://10.0.1.31:8080 CycleServer username: [admin] admin CycleServer password: Generating CycleCloud key... CycleCloud configuration stored in /home/demo/.cycle/config.ini CycleCloud connection information is configured properly. Wrote cluster template file '~/.cycle/condor_templates.txt'. Wrote cluster template file '~/.cycle/sge_templates.txt'. Wrote cluster template file '~/.cycle/starcluster.txt'. Access Key: **YOUR_ACCESS_KEY** Secret Key: **YOUR_SECRET_KEY** Default Region (Enter for default): us-east-1 Bucket name to create (com.cyclecloud.<name>.locker): demo AWS account initialized and new credentials stored.
The first set of questions to answer are the URL pointing back to the CycleServer instance you have set up. If you are installing the CLI tools on the same machine, the default of localhost should be sufficient. Next, you have to specify the user name and password you created when setting up CycleServer for the first time.
Several example cluster templates will be written to the ~/.cycle directory for future reference.
You will have to provide some information so that CycleCloud can access your AWS account. If the AWS_ACCESS_KEY and AWS_SECRET_KEY environment variables are defined, the CLI tools will ask to use them. If not, you must provide them. You will also asked to provide a default region to use when starting clusters, the default is us-east-1 (Virginia). For a full list of available regions please see the official AWS documentation.
Finally, on first configuration you will be asked to give the name you wish to use for an S3 bucket. This bucket will be used to store run-time configuration for your compute clusters. The bucket will be named ‘com.cyclecloud.<name>.locker’ where <name> is the value you specify. CycleCloud will only access this bucket, so if you need to limit access for security reasons this bucket is the only one that needs read/write permission.
Your configuration information is saved in your home directory at ~/.cycle/config.ini. If you need to reconfigure your account, you can edit or remove this file and re-run the initialize command. Alternately, you can rerun cyclecloud initialize with the --force option.
Test Your Configuration
You can test your configuration by running the show_cluster command, which will return the details of all the clusters currently being managed by CycleCloud. If it is your first configuration, this list is likely to be empty. If you have configured the CLI tools correctly, the following command should not generate an error:
$ cyclecloud show_cluster
Congratulations! Your CycleCloud CLI tools are installed and functioning.