Setting Up CloudMonkey

You need an API key and secret key for your Lightspeed Cloud account. These are generated from your account settings in the portal - see API access. CloudMonkey signs each request with the secret key, so your portal password is never stored or sent.

The examples on this page, and in the reference architectures, also use jq to extract values from CloudMonkey's JSON output. Install it from your operating system's package manager (dnf install jq, apt install jq or brew install jq) or from the jq download page.

Download the binary for your platform from the CloudMonkey releases page on GitHub. The project's Getting Started guide is the upstream reference for installation.

Linux and macOS#

Download the binary to a directory on your PATH and make it executable. This example installs version 6.6.0 on 64-bit Linux; substitute the file name for your platform, and the version number from the releases page.

sudo curl -L -o /usr/local/bin/cmk \
  https://github.com/apache/cloudstack-cloudmonkey/releases/download/6.6.0/cmk.linux.x86-64
sudo chmod +x /usr/local/bin/cmk

On macOS, downloading with curl as shown avoids the Gatekeeper prompt that appears when an unsigned binary is downloaded through a browser.

Windows#

Download cmk.windows.x86-64.exe, rename it to cmk.exe, and move it to a directory on your PATH - for example a C:\Tools directory that you have added to the user PATH through System Properties → Environment Variables. CloudMonkey runs from both PowerShell and Command Prompt.

The shell examples on this documentation site use Bash syntax for variables and loops. On Windows, run them from WSL with the Linux binary, or adapt the variable syntax for PowerShell.

Confirm the installation#

cmk version

The output reports the installed version, for example Apache CloudStack 🐵 CloudMonkey 6.6.0.

CloudMonkey stores connection details in named profiles. The default profile, localcloud, points at a CloudStack server on your own machine, so create a dedicated profile for Lightspeed Cloud. Each set command below writes to the active profile:

cmk set profile lightspeed
cmk set url https://cloud.lightspeedhosting.com.au/client/api
cmk set apikey <api key>
cmk set secretkey <secret key>
cmk set output json
cmk sync

• set profile creates the profile if it does not exist and makes it the active profile for later commands.
• set output json fixes the profile's output format as JSON. JSON is CloudMonkey's default, and the scripted examples on this site rely on it, so setting it explicitly protects those scripts if the default is later changed.
• sync downloads the list of API commands your account is permitted to call, and enables tab completion and command help. Run it again after each Lightspeed Cloud platform upgrade so that new commands and parameters become available.

Where the configuration is stored#

Profiles are saved in ~/.cmk/config on Linux and macOS, and in %USERPROFILE%\.cmk\config on Windows. The file holds your secret key in plain text, so restrict access to it:

chmod 600 ~/.cmk/config

The Terraform provider can read its credentials from this same file, so a single profile can serve both tools.

Working with more than one profile#

To run a single command against a specific profile without changing the active one, use the -p flag:

cmk -p lightspeed list zones

List the zones available to your account:

cmk list zones filter=name,id

A working connection returns the au-mel01 zone and its ID. The filter parameter limits the output to the named fields, which keeps listings readable.

An error reading unable to verify user credentials and/or request signature indicates that the API key or secret key is incorrect. Generate a new key pair from the portal and set both values again, as the two keys must belong to the same pair.

Interactive and one-shot modes#

Running cmk on its own opens an interactive shell with tab completion of commands and parameter names. Running cmk followed by a command executes that command and exits, which is the form used in scripts:

cmk list virtualmachines filter=name,state,ipaddress

Commands follow the CloudStack API, split into a verb and a noun: the listVirtualMachines API call becomes list virtualmachines, and deployVirtualMachine becomes deploy virtualmachine. Parameters are passed as name=value pairs.

Finding commands and parameters#

cmk deploy virtualmachine -h

Adding -h after any command lists its parameters and marks which are required. The full parameter reference for every command is in the CloudStack API documentation.

Output formats#

The -o flag overrides the default output format for one command. The supported formats are json, text, table, column and csv. table and column are the most readable at a terminal; json is the most reliable to parse in scripts.

cmk -o table list virtualmachines filter=name,state

Capturing IDs in scripts#

Most commands take resources by ID. Look the ID up by name and capture it with jq:

ZONE=$(cmk list zones name=au-mel01 filter=id | jq -r '.zone[0].id')
echo "$ZONE"

Asynchronous operations, such as deploying a VM, wait for the job to complete before CloudMonkey returns. The default wait limit is 1800 seconds; change it with cmk set timeout <seconds>.

Running in CI pipelines#

Where a configuration file is impractical, such as a CI runner, supply the connection details through environment variables. These take precedence over the configuration file:

export CMK_URL=https://cloud.lightspeedhosting.com.au/client/api
export CMK_API_KEY=<api key>
export CMK_SECRET_KEY=<secret key>
export CMK_OUTPUT=json

Store the key values in your CI system's secret store and inject them at run time.

Each reference architecture includes a complete CloudMonkey deployment, starting with RA-01. To manage infrastructure declaratively, see Setting Up Ansible and Setting Up Terraform.