Skip to main content

A simple yet powerful CloudStack API client for Python and the command-line.

Project description

Build Status License Python versions

A simple, yet powerful CloudStack API client for python and the command-line.

  • Python 2.7+ and 3.3+ support.

  • Async support for Python 3.5+.

  • All present and future CloudStack API calls and parameters are supported.

  • Syntax highlight in the command-line client if Pygments is installed.

  • BSD license.

Installation

pip install cs

# with the colored output
pip install cs[highlight]

# with the async support (Python 3.5+)
pip install cs[async]

# with both
pip install cs[async,highlight]

Usage

In Python:

from cs import CloudStack

cs = CloudStack(endpoint='https://api.exoscale.ch/compute',
                key='cloudstack api key',
                secret='cloudstack api secret')

vms = cs.listVirtualMachines()

cs.createSecurityGroup(name='web', description='HTTP traffic')

From the command-line, this requires some configuration:

cat $HOME/.cloudstack.ini
[cloudstack]
endpoint = https://api.exoscale.ch/compute
key = cloudstack api key
secret = cloudstack api secret
# Optional ca authority certificate
verify = /path/to/certs/exoscale_ca.crt
# Optional client PEM certificate
cert = /path/to/client_exoscale.pem

Then:

$ cs listVirtualMachines
{
  "count": 1,
  "virtualmachine": [
    {
      "account": "...",
      ...
    }
  ]
}
$ cs authorizeSecurityGroupIngress \
    cidrlist="0.0.0.0/0" endport=443 startport=443 \
    securitygroupname="blah blah" protocol=tcp

The command-line client polls when async results are returned. To disable polling, use the --async flag.

To find the list CloudStack API calls go to http://cloudstack.apache.org/api.html

Configuration

Configuration is read from several locations, in the following order:

  • The CLOUDSTACK_ENDPOINT, CLOUDSTACK_KEY, CLOUDSTACK_SECRET and CLOUDSTACK_METHOD environment variables,

  • A CLOUDSTACK_CONFIG environment variable pointing to an .ini file,

  • A CLOUDSTACK_VERIFY (optional) environment variable pointing to a CA authority cert file,

  • A CLOUDSTACK_CERT (optional) environment variable pointing to a client PEM cert file,

  • A cloudstack.ini file in the current working directory,

  • A .cloudstack.ini file in the home directory.

To use that configuration scheme from your Python code:

from cs import CloudStack, read_config

cs = CloudStack(**read_config())

Note that read_config() can raise SystemExit if no configuration is found.

CLOUDSTACK_METHOD or the method entry in the configuration file can be used to change the HTTP verb used to make CloudStack requests. By default, requests are made with the GET method but CloudStack supports POST requests. POST can be useful to overcome some length limits in the CloudStack API.

CLOUDSTACK_TIMEOUT or the timeout entry in the configuration file can be used to change the HTTP timeout when making CloudStack requests (in seconds). The default value is 10.

CLOUDSTACK_RETRY or the retry entry in the configuration file (integer) can be used to retry list and queryAsync requests on failure. The default value is 0, meaning no retry.

Multiple credentials can be set in .cloudstack.ini. This allows selecting the credentials or endpoint to use with a command-line flag.

[cloudstack]
endpoint = https://some-host/api/compute
key = api key
secret = api secret

[exoscale]
endpoint = https://api.exoscale.ch/compute
key = api key
secret = api secret

Usage:

$ cs listVirtualMachines --region=exoscale

Optionally CLOUDSTACK_REGION can be used to overwrite the default region cloudstack.

Pagination

CloudStack paginates requests. cs is able to abstract away the pagination logic to allow fetching large result sets in one go. This is done with the fetch_list parameter:

$ cs listVirtualMachines fetch_list=true

Or in Python:

cs.listVirtualMachines(fetch_list=True)

Async client

cs provides the AIOCloudStack class for async/await calls in Python 3.5+.

from cs import AIOCloudStack, read_config

cs = AIOCloudStack(**read_config())
vms = await cs.listVirtualMachines()

By default, this client polls CloudStack’s async jobs to return actual results for commands that result in an async job being created. You can customize this behavior with job_timeout (default: None – wait indefinitely) and poll_interval (default: 2s).

cs = AIOCloudStack(**read_config(), job_timeout=300, poll_interval=5)

Async deployment of multiple vms

import asyncio
from cs import AIOCloudStack, read_config

cs = AIOCloudStack(**read_config())
tasks = [asyncio.ensure_future(cs.deployVirtualMachine(zoneid='',
                                                       serviceofferingid='',
                                                       templateid='')) for _ in range(5)]
results = []
done, pending = await asyncio.wait(tasks)
exceptions = 0
last_exception = None
for t in done:
    if t.exception():
        exceptions += 1
        last_exception = t.exception()
    elif t.result():
        results.append(t.result())
if exceptions:
    print(f"{exceptions} deployment(s) failed")
    raise last_exception

# Destroy all of them, but skip waiting on the job results
tasks = [cs.destroyVirtualMachine(id=vm['id'], fetch_result=False)
         for vm in results]
await asyncio.wait(tasks)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cs-2.3.tar.gz (9.8 kB view details)

Uploaded Source

Built Distribution

cs-2.3-py2.py3-none-any.whl (9.5 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file cs-2.3.tar.gz.

File metadata

  • Download URL: cs-2.3.tar.gz
  • Upload date:
  • Size: 9.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for cs-2.3.tar.gz
Algorithm Hash digest
SHA256 2408ef0f6e97cec8035658b9bd2a4ae229cfa6327fc907a4df76dd1033e87873
MD5 e8c9b1c55c9e50c877046f6a6bbbdb81
BLAKE2b-256 52418ce871e8d7b8aa774ede3c337852be3db4e745c84a8532609e03a0b96295

See more details on using hashes here.

File details

Details for the file cs-2.3-py2.py3-none-any.whl.

File metadata

  • Download URL: cs-2.3-py2.py3-none-any.whl
  • Upload date:
  • Size: 9.5 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No

File hashes

Hashes for cs-2.3-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 caa0327cf9749ec9fabf01ce4b601489906df9a2c8a82f17c0f963bb9c072a9f
MD5 ebd1049edbdf1928eefb312987a4f22e
BLAKE2b-256 d309e18f85e6da31f1a888c4b17c37374099a6685ac58c61e5db84ae23e213e8

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page