CI PyPi Python versions Downloads / Week License

CS - Python CloudStack API client

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

  • Async support.

  • 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
pip install cs[async]

# with both
pip install cs[async,highlight]

Usage

In Python:

from cs import CloudStack

cs = CloudStack(endpoint='https://cloudstack.example.com/client/api',
                key='cloudstack api key',
                secret='cloudstack api secret')

vms = cs.listVirtualMachines()

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

The key and secret are optional. Leave them out to send unauthenticated requests, for example against the CloudStack integration port, which rejects requests carrying an API key or signature:

cs = CloudStack(endpoint='http://localhost:8096/client/api')

From the command-line, this requires some configuration:

cat $HOME/.cloudstack.ini
[cloudstack]
endpoint = https://cloudstack.example.com/client/api
key = cloudstack api key
secret = cloudstack api secret
# Optional ca authority certificate
verify = /path/to/certs/ca.crt
# Optional client PEM certificate
cert = /path/to/client.pem
# If you need to pass the certificate and key as separate files
cert_key = /path/to/client_key.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, (CLOUDSTACK_KEY and CLOUDSTACK_SECRET are optional: leave them unset for unauthenticated requests, e.g. against the integration port)

  • 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_CERT_KEY (optional) environment variable pointing to a client PEM certificate key 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.

CLOUDSTACK_JOB_TIMEOUT or the job_timeout` entry in the configuration file (float) can be used to set how long an async call is retried assuming fetch_result is set to true). The default value is None, it waits forever.

CLOUDSTACK_POLL_INTERVAL or the poll_interval entry in the configuration file (number of seconds, float) can be used to set how frequently polling an async job result is done. The default value is 2.

CLOUDSTACK_EXPIRATION or the expiration entry in the configuration file (integer) can be used to set how long a signature is valid. By default, it picks 10 minutes but may be deactivated using any negative value, e.g. -1.

CLOUDSTACK_DANGEROUS_NO_TLS_VERIFY or the dangerous_no_tls_verify entry in the configuration file (boolean) can be used to deactivate the TLS verification made when using the HTTPS protocol.

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/v1
key = api key
secret = api secret

[region-example]
endpoint = https://cloudstack.example.com/client/api
key = api key
secret = api secret

Usage:

$ cs listVirtualMachines --region=region-example

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

For the power users that don’t want to put any secrets on disk, CLOUDSTACK_OVERRIDES let you pick which key will be set from the environment even if present in the ini file.

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)

Tracing HTTP requests

Once in a while, it could be useful to understand, see what HTTP calls are made under the hood. The trace flag (or CLOUDSTACK_TRACE) does just that:

$ cs --trace listVirtualMachines

$ cs -t listZones

Async client

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

import asyncio
from cs import AIOCloudStack, read_config

cs = AIOCloudStack(**read_config())

async def main():
   vms = await cs.listVirtualMachines(fetch_list=True)
   print(vms)

asyncio.run(main())

Async deployment of multiple VMs

import asyncio
from cs import AIOCloudStack, read_config

cs = AIOCloudStack(**read_config())

machine = {"zoneid": ..., "serviceofferingid": ..., "templateid": ...}

async def main():
   tasks = asyncio.gather(*(cs.deployVirtualMachine(name=f"vm-{i}",
                                                    **machine,
                                                    fetch_result=True)
                            for i in range(5)))

   results = await tasks

   # Destroy all of them, but skip waiting on the job results
   await asyncio.gather(*(cs.destroyVirtualMachine(id=result['virtualmachine']['id'])
                          for result in results))

asyncio.run(main())

Development

This project uses uv for dependency management and ruff for linting and formatting.

# Create the virtualenv and install all dependencies
uv sync --all-extras

# Run the test suite (with a coverage report)
uv run pytest

# Run a subset of the tests, without the coverage threshold
uv run pytest --no-cov tests/test_client.py -k signature

# Run the test suite against another Python version
uv run --python 3.10 pytest

# Lint and format
uvx ruff check .
uvx ruff format .

Release Procedure

Bump the version in cs/version.py, then create a GitHub release: the Upload Python Package workflow builds and publishes to PyPI. To build and publish manually:

rm -rf dist
uv build
uv publish

Links

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for resmo from gravatar.com resmo Avatar for Rohit.Yadav from gravatar.com Rohit.Yadav

Credits

Author: Bruno Renié

License expression

BSD-3-Clause
View SPDX License List

Requires

Python >=3.10

Provides Extra

async highlight

Tags

api cli client cloud cloudstack

Classifiers

Report project as malware

Download files

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

Source Distribution

cs-5.1.0.tar.gz (22.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

cs-5.1.0-py3-none-any.whl (14.3 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: cs-5.1.0.tar.gz
  • Upload date:
  • Size: 22.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for cs-5.1.0.tar.gz
Algorithm Hash digest
SHA256 dcfa2ab6103dcbd3a53f9f5d40731b4addd6a5a30f0d905ee80479a1e73df852
MD5 07ecacbe87bb65c70f88b2088ac8c3a6
BLAKE2b-256 4c2bc59c437310abcce9b6c647d1a157d38bd49a334c9cf0fd68b90acdbf735e

See more details on using hashes here.

File details

Details for the file cs-5.1.0-py3-none-any.whl.

File metadata

  • Download URL: cs-5.1.0-py3-none-any.whl
  • Upload date:
  • Size: 14.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for cs-5.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 a35876c45618e1373d7797d09b56b652e2bef096e585894c98aa84797cd85614
MD5 deba309baabb9c56cfdbf04e35023157
BLAKE2b-256 9b5a13860577b9c58dc0479c01787322ffe678aba14bd60b298daa57883c7ea6

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

5.1.0 This release

2 files

5.0.0

2 files

4.0.1

2 files

4.0.0

2 files

Pre-release

4.0.0a1

2 files

3.4.1

2 files

3.4.0

2 files

3.3.1

2 files

3.3.0

2 files

3.2.0

2 files

3.1.0

2 files

3.0.0

2 files

2.7.1

2 files

2.7

2 files

2.6.1

2 files

2.6

2 files

2.5.9

2 files

2.5.8

2 files

2.5.7

2 files

2.5.6

2 files

2.5.5

2 files

2.5.4

2 files

2.5.3

2 files

2.5.2

2 files

2.5.1

2 files

2.5

2 files

2.4.1

2 files

2.4

2 files

2.3.1

2 files

2.3

2 files

2.2

2 files

2.1.6

2 files

2.1.5

2 files

2.1.4

2 files

2.1.3

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.0

2 files

1.1.1

2 files

1.1.0

2 files

1.0.0

2 files

0.9.1

2 files

0.9.0

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.1

2 files

0.7

2 files

0.6.10

2 files

0.6.9

2 files

0.6.8

2 files

0.6.7

2 files

0.6.6

2 files

0.6.5

2 files

0.6.4

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.8

2 files

0.5.7

2 files

0.5.6

2 files

0.5.5

2 files

0.5.4

2 files

0.5.3

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page