Skip to content

API / CMK

OpenCloud provides a robust API for interfacing with the platform. The API underpins all operations within the graphical user interface, which can be particularly helpful when attempting to gain familiarity with how various tasks work in the API. Additionally, the community has developed many different helpful ways to use the API. This includes the following tools:

Consult the Cloudstack Programmers Guide for more information on interacting programmatically with CloudStack. The Cloudstack API Reference provide documentation of all API operations.

Getting started

To obtain access to the API, generate an Access and Secret Key for user account:

  1. Login in OpenCloud.
  2. Click on name in the top right corner of the GUI and select Profile.
  3. Click on the Generate New API/Secret Keys in the top right icon bar.
  4. This will generate an API Key and Secret Key that are visible towards the left bottom of profile. Click on the Copy Icon for both and store them in a secure location.

Endpoints

The following endpoints are currently available.

Coming Soon!

Cloudmonkey (CMK)

The Cloudstack community has developed a tool to provide a command line interface for APi interactions. For example, CMK uses tab completion, to help provide available options based on the typed content.

Install on Linux/MacOSX

It is recommended to download the latest CMK release from https://github.com/apache/cloudstack-cloudmonkey/releases. In most cases, the files can be places in /usr/local/bin/cmk, however, this may vary between linux distributions.

  1. Download the latest CMK release.

    sudo wget https://github.com/apache/cloudstack-cloudmonkey/releases/download/6.4.0/cmk.linux.x86-64 -O /usr/local/bin/cmk

  2. Set execute permissions on the downloaded binary.

    sudo chmod +x /usr/local/bin/cmk

Install on Windows

  1. To install CMK on windows, download the install file.

    https://github.com/apache/cloudstack-cloudmonkey/releases/download/6.4.0/cmk.windows.x86-64.exe

  2. Place the executable in the desired folder.

  3. Run the cmk.windows.x86-64.exe executable.

Profiles

Profiles are used to control access for user API logins. Profiles are helpful for ease of access to API credentials across various CloudStack environments.

  1. From the host where CMK was installed, launch CMK.

    cmk

    The output on initial launch appears like so:

    Loaded in-built API cache. Failed to read API cache, please run 'sync'.
Apache CloudStack 🐵 CloudMonkey 6.4.0 
Report issues: https://github.com/apache/cloudstack-cloudmonkey/issues

(localcloud) 🐱 >

  2. Set up a new profile in CMK. There can be multiple profiles or different instances. In the example below, the profile OpenCloud is created.

    set profile OpenCloud

  3. Configure the new profile with the desired information. 

    set username <User_Name_Here> #(1)!
set domain / # (2)
set apikey <API_Key_Here> # (3)
set url <API_URL_Here> # (4)
set secretkey <Secret_Key_Here> # (5)
    1. Change <User_Name_Here> to OpenCloud login ID.
    2. Change domain to your domain (I.E. AB123)
    3. Change <API_Key_Here> to API Key that was generated in previous steps.
    4. Change <API_URL_Here> to API URL from the table above.
    5. Change <Secret_Key_Here> to Secret Key generated in previous steps.

  4. Run the sync command to test the connection and sync the available APIs to CMK.

    sync

Query Example

The following command will output a list of users visible to the current profile.

list users

Below is the default output format (JSON). See Output Table for different format options.

(OpenCloud) 🐱 > list users
{
  "count": 1,
  "user": [
    {
      "account": "Customer",
      "accountid": "2d83a89f-e211-11ee-a104-005056010221",
      "accounttype": 1,
      "apikey": "",
      "created": "2024-03-14T10:43:10-0400",
      "domain": "AD123",
      "domainid": "00541816-e211-11ee-a104-005056010221",
      "firstname": "Customer",
      "id": "2da28c02-e211-11ee-a104-005056010221",
      "is2faenabled": true,
      "is2famandated": true,
      "iscallerchilddomain": false,
      "isdefault": true,
      "lastname": "Customer",
      "roleid": "146da9fe-e211-11ee-a104-005056010221",
      "rolename": "Cloud Domain Admin",
      "roletype": "Admin",
      "state": "enabled",
      "username": "Customer",
      "usersource": "native"
    },
    ...

Filters

Filters are supported. Filters provide the ability to only show certain columns of output.

list users domainid=<dominID> filter=account,domain,firstname,lastname,rolename,is2faenabled,is2famandated,

This generates something that looks like the following. This is in table format. See Output Table for different format options.

(OpenCloud) 🐱 > list users domainid=405575bb-e120-4544-a905-51f5610e38a3 filter=account,domain,firstname,lastname,rolename,is2faenabled,is2famandated,
count = 1
user:
+-------------+--------+-----------+----------+--------------------+--------------+---------------+
|   ACCOUNT   | DOMAIN | FIRSTNAME | LASTNAME |      ROLENAME      | IS2FAENABLED | IS2FAMANDATED |
+-------------+--------+-----------+----------+--------------------+--------------+---------------+
| Customer    | AD123  | Customer  | Customer | Cloud Domain Admin | true         | true          |
+-------------+--------+-----------+----------+--------------------+--------------+---------------+

Tab Completion

Commands in cloudmonkey can be tab completed. In the example below, the intent is to deploy an instance from a template. In order to do so, a template ID is required.

  1. Begin by typing out the deploy command and include the templateid key. Hit tab on the keyboard.

    deploy virtualmachine templateid=

    A list of available templates will fill the terminal, with their IDs listed next to them.

    (OpenCloud) 🐱 > deploy virtualmachine templateid=
07da3e52-9fc8-4cab-9df8-3923201dac82 (WIN2019-VM1)                    07da3e52-9fc8-4cab-9df8-3923201dac82 (Ubuntu-VM1)
0aa16f4d-c574-48f2-b46a-7b647a449ee3 (WIN2019-VM2)                    0aa16f4d-c574-48f2-b46a-7b647a449ee3 (Ubuntu-VM2)

  2. Begin typing the desired template ID into the cmk prompt and hit tab on the keyboard. Notice the template ID value is auto-completed.

    (OpenCloud) 🐱 > deploy virtualmachine templateid=07da3e52-9fc8-4cab-9df8-3923201dac82

Getting Help

Get help on any command by running the following:

list users -h

Example of results:

(OpenCloud) 🐱 > list users -h
listUsers: Lists user accounts
API Params               Type     Description
==========               ====     ===========
account                  string   list resources by account. Must be used w
                                ith the domainId parameter.
accounttype              integer  List users by account type. Valid types i
                                nclude admin, domain-admin, read-only-ad
                                min, or user.
domainid                 uuid     list only resources belonging to the doma
                                in specified
id                       uuid     List user by ID.
isrecursive              boolean  defaults to false, but if true, lists all
                                resources from the parent specified by
                                the domainId till leaves.
keyword                  string   List by keyword
listall                  boolean  If set to false, list only resources belo
                                nging to the command's caller; if set to
                                true - list resources that the caller i
                                s authorized to see. Default value is fa
                                lse. Resources dedicated to a project ar
                                e listed only if using the projectid par
                                ameter.
page                     integer
pagesize                 integer
showicon                 boolean  flag to display the resource icon for use
                                rs
state                    string   List users by state of the user account.
username                 string   List user by the username

Settings

Output Table

The default output is JSON, however, the output can changed to the following values as well: column, csv, json, table, text

For example, setting it output as a table

set output table
list users

(OpenCloud) 🐱 > set output table
(OpenCloud) 🐱 > list users
count = 1
user:
+---------+--------------------------------------+-------------+----------------------------------------------------------------------------------------+--------------------------+--------+--------------------------------------+-----------+--------------------------------------+--------------+---------------+---------------------+-----------+-----------+--------------------------------------+------------+----------+---------+-----------------+------------+
| ACCOUNT |              ACCOUNTID               | ACCOUNTTYPE |                                         APIKEY                                         |         CREATED          | DOMAIN |               DOMAINID               | FIRSTNAME |                  ID                  | IS2FAENABLED | IS2FAMANDATED | ISCALLERCHILDDOMAIN | ISDEFAULT | LASTNAME  |                ROLEID                |  ROLENAME  | ROLETYPE |  STATE  |    USERNAME     | USERSOURCE |
+---------+--------------------------------------+-------------+----------------------------------------------------------------------------------------+--------------------------+--------+--------------------------------------+-----------+--------------------------------------+--------------+---------------+---------------------+-----------+-----------+--------------------------------------+------------+----------+---------+-----------------+------------+
| Customer| 2d83a89f-e211-11ee-a104-005056010221 |           1 |                                                                                        | 2024-03-14T10:43:10-0400 | AB123  | 00541816-e211-11ee-a104-005056010221 | Customer  | 2da28c02-e211-11ee-a104-005056010221 | true         | true          | false               | true      | Customer  | 146da9fe-e211-11ee-a104-005056010221 | Cloud Admin| User     | enabled | Customer        | native     |
+---------+--------------------------------------+-------------+----------------------------------------------------------------------------------------+--------------------------+--------+--------------------------------------+-----------+--------------------------------------+--------------+---------------+---------------------+-----------+-----------+--------------------------------------+------------+----------+---------+-----------------+------------+

Debug Log

Out of the box, Cloudmoneky stores logs in ~/.cloudmonkey_log. This path can be changed by running the following command

set log_file <path>

Other Settings

Here is a full list of settings and the defaults that can be set with in CloudMonkey.

Key Purpose Default
profile Management server profile name local
url Management server API url (it should contain full url with protocol, port etc and paths) http://localhost:8080/client/api
timeout Timeout interval for polling async commands 3600
apikey User api key ""
secretkey User secret key ""
verifysslcert Enables/Disables SSL certification verification when making HTTP calls (per server profile) TRUE
username CloudStack user name admin
password CloudStack user password password
color Enable coloured output, set to false to disable TRUE
prompt cloudmonkey prompt >
display Line based, JSON, or tabular output, set to default or json or table default
log_file Log file ~/.cloudmonkey/log
history_file History file ~/.cloudmonkey/history
asyncblock Poll for async commands, making it false will cause cloudmonkey to return jobid TRUE
paramcompletion Tries to predict api for listing a parameter value for an api, experimental may fail TRUE

HTTP GET/POST API

API commands can be run from a web browser by using HTTP GET/POST. 

https://CloudStack_API_URL/client/api?command=listUsers

Results in this example XML output shown in a browser:

<listusersresponse cloud-stack-version="4.19.1.0">
<count>1</count>
<user>
<id>2da28c02-e211-11ee-a104-005056010221</id>
<username>Customer</username>
<firstname>Customer</firstname>
<lastname>Customer</lastname>
<created>2024-03-14T10:43:10-0400</created>
<state>enabled</state>
<account>Customer</account>
<accounttype>1</accounttype>
<usersource>native</usersource>
<roleid>146da9fe-e211-11ee-a104-005056010221</roleid>
<roletype>User</roletype>
<rolename>CloudDomainAdmin</rolename>
<domainid>00541816-e211-11ee-a104-005056010221</domainid>
<domain>AB123</domain>
<apikey></apikey>
<accountid>2d83a89f-e211-11ee-a104-005056010221</accountid>
<iscallerchilddomain>false</iscallerchilddomain>
<isdefault>true</isdefault>
<is2faenabled>true</is2faenabled>
<is2famandated>true</is2famandated>
</user>
</listusersresponse>