Skip to content
Cloudbricks.dev logo

Apache CloudStack - API, CloudMonkey & Kubernetes

Part 7 of the Apache CloudStack series: the REST API, CloudMonkey CLI, automation patterns, and the CloudStack Kubernetes Service.

Kishore 6 min read

Everything the CloudStack UI does is an API call. That is the single most useful fact about automating CloudStack: there is no hidden admin path. If you can click it, you can script it, and the API reference documents the same objects the UI renders.

This part covers how the API authenticates, how to drive it with CloudMonkey, how to handle asynchronous jobs, and how to run Kubernetes on CloudStack with CKS.

How the API works

CloudStack exposes a single HTTP endpoint:

https://<management-server>/client/api

Every operation is a command with a name (deployVirtualMachine, listZones, createNetwork) and parameters. The API returns JSON or XML; JSON is the default for most clients.

There are two authentication styles:

StyleUse caseHow it works
Session loginInteractive UI / scriptsPOST login with username, password, domain; returns a JSESSIONID cookie
API keysAutomationEach request is signed with an API key and secret

API keys are the right choice for scripts and integrations because they do not expire with a session and can be revoked independently.

Generating API keys

In the UI: Accounts → your account → View Users → Generate Keys. With the API:

cmk register userkeys id=<user-id>

The response contains apikey and secretkey. Store the secret in a secrets manager; it is shown once and is equivalent to a password.

Signing a request

CloudStack uses a simplified AWS-style signature:

  1. Sort the request parameters by name.
  2. URL-encode and join them into a canonical query string.
  3. Compute an HMAC-SHA1 of that string using the secret key.
  4. Base64-encode the digest and send it as the signature parameter.

The exact algorithm is documented in the CloudStack API guide. Most people never implement it by hand — CloudMonkey and the SDKs do it for you — but knowing the shape helps when a signature error appears.

CloudMonkey

CloudMonkey (the cmk command) is the official CLI. It wraps the API, handles signing, formats output, and offers interactive help.

Install it with pipx or pip:

python3 -m pip install --user cloudmonkey
cmk

On first run it prompts for the management server, API key, and secret. The configuration lives in ~/.cloudmonkey/config. A minimal config looks like:

[core]
profile = local
asyncblock = true
paramcompletion = true

[local]
url = https://cloud.example.com/client/api
apikey = <your-api-key>
secretkey = <your-secret-key>
expires = 600
verifyssl = true

asyncblock = true makes cmk wait for asynchronous jobs and print the final result, which is what you usually want interactively. For scripts, set it to false and poll the job yourself.

Using it

cmk list zones
cmk list virtualmachines zoneid=<zone-id>
cmk list serviceofferings
cmk deploy virtualmachine serviceofferingid=<id> templateid=<id> zoneid=<id> networkids=<id> name=web-01

CloudMonkey is also a discovery tool:

cmk sync
cmk list apis | grep -i volume
cmk help command=createVolume

cmk sync refreshes the local cache of API commands and parameters from the server, so help matches your version.

Asynchronous jobs

Most write operations return a job ID rather than the finished object:

{
  "deployvirtualmachineresponse": {
    "id": "a1b2c3d4-...",
    "jobid": "f6e5d4c3-..."
  }
}

Poll the job:

cmk query asyncjobresult jobid=<job-id>

The result has jobstatus: 0 in progress, 1 succeeded, 2 failed. On failure, jobresult.errorcode and jobresult.errortext explain why. Always check the job result; a successful HTTP response only means the request was accepted.

A small shell helper:

wait_job() {
  local job="$1"
  while :; do
    local status
    status=$(cmk -o json query asyncjobresult jobid="$job" | jq -r '.queryasyncjobresultresponse.jobstatus')
    [ "$status" = "1" ] && return 0
    [ "$status" = "2" ] && {
      cmk -o json query asyncjobresult jobid="$job" | jq -r '.queryasyncjobresultresponse.jobresult.errortext'
      return 1
    }
    sleep 3
  done
}

Automation patterns

A few patterns that keep scripts maintainable:

  • Resolve IDs by name, not by copying them. Look up zone, template, offering, and network IDs at runtime with list commands and jq. IDs differ between installations.
  • Treat every write as a job. Deploy, start, stop, migrate, snapshot, and destroy are asynchronous. Poll the job before the next step.
  • Use idempotent checks. Before creating a network or VM, list for an existing object with the same name and reuse it. This makes reruns safe.
  • Keep credentials out of the script. Read the API key and secret from environment variables or a config file with restricted permissions.
  • Pin the API version. The apiVersion parameter (or the Accept header) lets you stay on a known contract while the server upgrades.

The official Terraform provider for CloudStack is a better fit than shell scripts once the number of objects grows. It handles dependency ordering, state, and drift detection. CloudMonkey remains useful for one-off operations and debugging.

CloudStack Kubernetes Service (CKS)

CKS provisions Kubernetes clusters on CloudStack. CloudStack creates the control-plane and worker VMs, installs the cluster, and manages the lifecycle. It is a good fit when you already run CloudStack and want Kubernetes without a separate infrastructure provider.

Requirements:

  • An advanced-zone network with a source NAT and a public IP.
  • A Kubernetes-compatible template (CloudStack publishes one, or you build your own).
  • A service offering with enough CPU and RAM for the control plane and workers.
  • A CKS-enabled CloudStack version and the CKS plugin configured.

Create a cluster with the API:

cmk create kubernetescluster \
  name=lab-k8s \
  zoneid=<zone-id> \
  kubernetestemplateid=<template-id> \
  serviceofferingid=<offering-id> \
  networkid=<network-id> \
  controlnodes=1 \
  workernodes=2

Add a node pool:

cmk create kubernetescluster \
  name=lab-k8s-pool \
  kubernetesclusterid=<cluster-id> \
  serviceofferingid=<offering-id> \
  nodecount=2

Check the cluster and retrieve the kubeconfig:

cmk list kubernetesclusters
cmk get kubernetesconfig kubernetesclusterid=<cluster-id>

CKS clusters are ordinary CloudStack resources: they consume IPs, offerings, and storage, and they are billed and limited like any other instance. The control plane is managed by CloudStack; you do not SSH into it for day-to-day work.

CKS vs a self-managed cluster

CKSSelf-managed on CloudStack
Control planeManaged by CloudStackYou run it
UpgradesCloudStack-drivenYour responsibility
FlexibilityCloudStack’s supported versionsAny distribution
Operational loadLowerHigher

For a lab, CKS is the fastest route to a working cluster. For production, evaluate whether CloudStack’s supported Kubernetes versions and upgrade cadence match your needs.

Security notes

  • Give automation its own account, with limits and only the roles it needs.
  • Rotate API keys like passwords, and revoke keys for departed users.
  • Put the management server behind TLS with a trusted certificate; do not disable verification in production.
  • Restrict the API endpoint by network policy so only automation hosts and administrators can reach it.

Troubleshooting

  • 401 / signature error. Check the secret key, the clock skew, and that every parameter is included in the signature.
  • 414 or a truncated response. The signed query string is too long; use POST or reduce the parameter set.
  • Job stays at status 0. The management server may be waiting on an agent. Check the host agent and the management server logs.
  • list returns nothing. Confirm the account and domain context; an admin sees more than a user, and a user only sees its own account.
  • CKS cluster fails to provision. Check the template, the network’s source NAT, and that the CKS plugin is enabled.