Skip to main content

CloudSigma's official python library.

Project description

CloudSigma's Python Library

Config file

In order for the CloudSigma library to interact with the API, you need to provide your credentials. These are set in the file ~/.cloudsigma.conf. Here's a sample version of the file that talks to the Zürich datacenter. If you instead want to use the Frankfurt datacenter, simply replace 'zrh' with 'fra' in the api_endpoint and ws_endpoint. Please note that this is not required in order to read back meta data on the server.

api_endpoint =
ws_endpoint = wss://
username =
password = secret

# Only needed for the integration/unit tests.

Since this file includes credentials, it is highly recommended that you set the permission of the file to 600 (chmod 600 ~/.cloudsigma.conf)


Mac OS X

sudo pip install cloudsigma

Ubuntu / Debian

sudo apt -y install python-pip
pip install cloudsigma


yum install -y python3-pip
pip install cloudsigma

Using pycloudsigma

Imports and definitions

import cloudsigma
from pprint import pprint

drive = cloudsigma.resource.Drive()
server = cloudsigma.resource.Server()

Create a drive

test_disk = {
    'name': 'test_drive',
    'size': 1073741824 * 1,
    'media': 'disk'
my_test_disk = drive.create(test_disk)

Print back the result:

{u'affinities': [],
 u'allow_multimount': False,
 u'jobs': [],
 u'licenses': [],
 u'media': u'disk',
 u'meta': {},
 u'mounted_on': [],
 u'name': u'test_drive',
 u'owner': {u'resource_uri': u'/api/2.0/user/b4b9XXX-ba52-4ad0-9837-a2672652XXX/',
            u'uuid': u'b4b9XXX-ba52-4ad0-9837-a2672652XXX'},
 u'resource_uri': u'/api/2.0/drives/5c33e407-23b9-XXX-b007-3a302eXXXX/',
 u'size': 1073741824,
 u'status': u'creating',
 u'storage_type': None,
 u'tags': [],
 u'uuid': u'5c33e407-23b9-XXX-b007-3a302eXXXX'}

Create a server without a drive

test_server = {
    'name': 'My Test Server',
    'cpu': 1000,
    'mem': 512 * 1024 ** 2,
    'vnc_password': 'test_server'
my_test_server = server.create(test_server)

Print back the result:

{u'context': True,
 u'cpu': 1000,
 u'cpus_instead_of_cores': False,
 u'drives': [],
 u'enable_numa': False,
 u'hv_relaxed': False,
 u'hv_tsc': False,
 u'mem': 536870912,
 u'meta': {},
 u'name': u'My Test Server',
 u'nics': [],
 u'owner': {u'resource_uri': u'/api/2.0/user/b4b9XXX-ba52-4ad0-9837-a2672652XXX/',
            u'uuid': u'b4b9XXX-ba52-4ad0-9837-a2672652XXX'},
 u'requirements': [],
 u'resource_uri': u'/api/2.0/servers/4d5bXXX-4da0-43cd-83aY-18b047014XXXX/',
 u'runtime': None,
 u'smp': 1,
 u'status': u'stopped',
 u'tags': [],
 u'uuid': u'4d5bXXX-4da0-43cd-83aY-18b047014XXXX',
 u'vnc_password': u'test_server'}

Attach a drive the drive and a NIC to the server

We could of course have attached this above, but in order to keep things simple, let's do this in two phases.

Attach the drive:

my_test_server['drives'] = [{
    'boot_order': 1,
    'dev_channel': '0:0',
    'device': 'virtio',
    'drive': my_test_disk['uuid']

Attach a public network interface:

my_test_server['nics']  = [{
    'ip_v4_conf': {
        'conf': 'dhcp',
        'ip': None
    'model': 'virtio',
    'vlan': None

Optional: Add a user-defined SSH key:

my_test_server['meta'] = {'ssh_public_key': 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDoHuFV7Skbu9G1iVokXBdB+zN4wEbqGKijlExUPmxuB6MXDBWCmXUEmMRLerTm3a8QMA+8Vyech0/TWQscYvs8xzM/HkRAqKwhhjPMRlfHgy+QKjRD8P989AYMnNcSYe8DayElFXoLYKwsDmoUcsnbf5H+f6agiBkWqz5odb8fvc2rka0X7+p3tDyKFJRt2OugPqLR9fhWddie65DBxAcycnScoqLW0+YAxakfWlKDUqwerIjuRN2VJ7T7iHywcXhvAU060CEtpWW7bE9T/PIoj/N753QDLYrmqtvqAQqU0Ss5rIqS8bYJXyM0zTKwIuncek+k+b9ButBf/Nx5ehjN vagrant@precise64'}

Push the settings:

server.update(my_test_server['uuid'], my_test_server)

Start the server


Stop the server


Reading Meta Data

CloudSigma supports the notion of exposing meta data to guests. Using the Python library, this can be done very easily. Please note that you do not need ~/.cloudsigma.conf in order to use this feature, as the data is read directly from /dev/ttyS1. More information on how to this works can be found here.

By default, various system information is exposed, but it is also possible to push user-defined data, such as an SSH-key to the guest.

Here's snippet that demonstrates how to read the meta meta data from a given server using the python library:

import cloudsigma
metadata = cloudsigma.metadata.GetServerMetadata().get()

from pprint import pprint
{u'cpu': 1000,
 u'cpus_instead_of_cores': False,
 u'drives': [{u'boot_order': 1,
              u'dev_channel': u'0:0',
              u'device': u'virtio',
              u'drive': {u'affinities': [],
                         u'allow_multimount': False,
                         u'licenses': [],
                         u'media': u'disk',
                         u'meta': {u'description': u'This is my test disk.'},
                         u'name': u'SomeName',
                         u'size': 21474836480,
                         u'tags': [],
                         u'uuid': u'19757XXX-8173-46ba-8822-YYYYc6bZZZZ'}}],
 u'enable_numa': False,
 u'hv_relaxed': False,
 u'hv_tsc': False,
 u'mem': 536870912,
 u'meta': {u'description': u'This is my test server.'},
 u'name': u'MyTestServer',
 u'nics': [{u'boot_order': None,
            u'ip_v4_conf': {u'conf': u'dhcp',
                            u'ip': {u'gateway': u'',
                                    u'meta': {},
                                    u'nameservers': [u'',
                                    u'netmask': 24,
                                    u'tags': [],
                                    u'uuid': u''}},
            u'ip_v6_conf': None,
            u'mac': u'22:bd:c4:XX:XX:XX',
            u'model': u'virtio',
            u'vlan': None}],
 u'requirements': [],
 u'smp': 1,
 u'tags': [],
 u'uuid': u'6cc0XXX-d024-4ecf-b0de-83dbc29ZZZ',
 u'vnc_password': u'NotMyPassword'}

If you get a permission error while running the above command, make sure you have access to read from /dev/ttyS1. For instance, on Ubuntu, the default owner is root and the group is set to dialout. Hence you need to either change the permission, or add your user to the group sudo usermod -a -G dialout $(whoami). Please note that you will need to logout and log in again for the permission change to take effect.

For more examples on how to read and write meta data, please visit our API documentation.

Sample: Install SSH key from meta data

In the example above, we pushed an SSH key as meta data to a server. That's great, but what if we want to put this to use? Don't worry, we got you covered.

The code snippet below assumes that you have installed your SSH key into the server's meta data with the key 'ssh_public_key'.

import cloudsigma
import os
import stat

metadata = cloudsigma.metadata.GetServerMetadata().get()
ssh_key = metadata['meta']['ssh_public_key']

# Define paths
home = os.path.expanduser("~")
ssh_path = os.path.join(home, '.ssh')
authorized_keys = os.path.join(ssh_path, 'authorized_keys')

def get_permission(path):
    return oct(os.stat(ssh_path)[stat.ST_MODE])[-4:]

if not os.path.isdir(ssh_path):
    print('Creating folder %s' % ssh_path)

if get_permission(ssh_path) != 0700:
    print('Setting permission for %s' % ssh_path)
    os.chmod(ssh_path, 0700)

# We'll have to assume that there might be other keys installed.
# We could do something fancy, like checking if the key is installed already,
# but in order to keep things simple, we'll simply append the key.
with open(authorized_keys, 'a') as auth_file:
    auth_file.write(ssh_key + '\n')

if get_permission(authorized_keys) != 0600:
    print('Setting permission for %s' % authorized_keys)
    os.chmod(authorized_keys, 0600)


Sample: Monitor websocket activity

Here's a sample application that listens to activity on the websocket. You can run this application to see activity from the web interface.

from cloudsigma.generic import GenericClient
from cloudsigma.resource import Websocket
from cloudsigma.errors import ClientError, PermissionError

ws = Websocket(timeout=None)
client = GenericClient()

print("Display Websocket activity.\nExit with ^C.")

while True:
        get_action =
        action_uri = get_action['resource_uri']
        print('Received Action: %s' % get_action)
        print('Result:\n%s' % client.get(action_uri))
    except ClientError as e:
        if e.args[0] == 404:
            print("Resource %s was deleted" % action_uri)
            print('Error retrieving: %s' % e)
    except PermissionError as e:
        print("No permissions for resource %s" % action_uri)


Sample: A CLI for taking snapshots

One handy functionality in our API is the ability to take snapshots of a drive. Since the drive can be running while you take the snapshot, combined with the fact that you only pay for the delta between the original disk and the snapshot, this becomes a very powerful backup tool.

Using the snippet below, you can easily create automated backups. All you need to do is to run the snapshot blow in an automated fashion, such as using the crontab.

import cloudsigma
import sys
from time import sleep

snapshot = cloudsigma.resource.Snapshot()
snapshot_done = False

if len(sys.argv) < 3:
    print('\nUsage: ./ drive-uuid snapshot-name\n')

snapshot_data = {
    'drive': sys.argv[1],
    'name': sys.argv[2],

create_snapshot = snapshot.create(snapshot_data)

while not snapshot_done:
    snapshot_status = snapshot.get(create_snapshot['uuid'])

    if snapshot_status['status'] == 'available':
        snapshot_done = True
        print('\nSnapshot successfully created\n')


There's also another script named that can used for automatically purging old snapshots.

Running the tests

There must be a VM available by the name that matches persistent_drive_name. This VM should be a server with SSH installed, where one can be log in as root with the password set in persistent_drive_ssh_password.

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

cloudsigma-1.0.tar.gz (24.5 kB view hashes)

Uploaded source

Built Distribution

cloudsigma-1.0-py3-none-any.whl (22.4 kB view hashes)

Uploaded py3

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