CloudSigma Compute Driver Documentation

CloudSigma is a pure IaaS provided based in Zurich, Switzerland with data centers in Zurich, Switzerland, Las Vegas, United States and Washington DC, United States.

../../_images/cloudsigma.png

CloudSigma driver supports working with legacy API v1.0 and a new and actively supported API v2.0. API v1.0 has been deprecated and as such, you are strongly encouraged to migrate any existing code which uses API v1.0 to API v2.0.

Instantiating a driver

CloudSigma driver constructor takes different arguments with which you tell it which region to connect to, which api version to use and so on.

Available arguments:

  • region - Which region to connect to. Defaults to zrh. All the supported values: zrh, lvs, wdc
  • api_version - Which API version to use. Defaults to 2.0. All the supported values: 1.0 (deprecated), 2.0

For information on how to use those arguments, see the Examples section below.

Basics

Pre-installed library drives vs installation CD drives

CloudSigma has a concept of so called library drives. Library drives exist in two forms:

  1. Pre-installed library drives
  2. Installation CD drives

Pre-installed library drives already have an existing operating system installed on them. They can be cloned and directly used when creating a server.

In Libcloud, pre-installed library drives are exposed as libcloud.compute.base.NodeImage objects through a standard libcloud.compute.base.NodeDriver.list_images() method.

Installation CD drives are different and not something which is supported by a big chunk of other providers. Unlike pre-installed drives which represent an already installed operating system, those drives represent an operating system installation medium (CD / DVD).

Those installation CD drives don’t fit well into the NodeImage concept so they are represented using libcloud.compute.drivers.cloudsigma.CloudSigmaDrive objects through the libcloud.compute.drivers.cloudsigma.CloudSigma_2_0_NodeDriver.ex_list_library_drives() method.

For more information and examples on how to use the installation CD drives, see the Create a server using an installation CD example below.

Library drives vs user drives

As noted above, CloudSigma has a concept called library drives. You can use library drives either by cloning them (pre-installed library drives) or by directly mounting them to the server (installer CD drives).

Besides library drives, CloudSigma also has a concept of user drives. User drives are drives which belong to your account. Those drives have either been cloned from the library drives or created from scratch.

To view all the drives which belong to your account, you can use the libcloud.compute.drivers.cloudsigma.CloudSigma_2_0_NodeDriver.ex_list_user_drives() method.

Server creation work-flow

Server creation work-flow consists of multiple steps and depends on the type of the image you are using.

If you are using a pre-installed image:

  1. Provided image is cloned so it can be used
  2. Cloned drive is resized to match the size specified using NodeSize
  3. Server is created and the cloned drive is attached to it
  4. Server is started

If you are using an installation CD:

  1. Server is created and selected installation CD is attached to it
  2. Server is started

Examples

Connect to zrh region using new API v2.0

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

cls = get_driver(Provider.CLOUDSIGMA)

# "api_version" argument can be left out since it defaults to 2.0
driver = cls('username', 'password', region='zrh', api_version='2.0')

Connect to zrh region using deprecated API v1.0

As noted above, API 1.0 has been deprecated and you are strongly encouraged to migrate any code which uses API 1.0 to API 2.0. This example is only included here for completeness.

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

cls = get_driver(Provider.CLOUDSIGMA)
driver = cls('username', 'password', region='zrh', api_version='1.0')

Listing available sizes, images and drives

In Libcloud, a libcloud.compute.base.NodeSize represents a physical configuration of a server and a libcloud.compute.base.NodeImage represents an operating system.

To comply with a standard Libcloud API, libcloud.compute.base.NodeDriver.list_images() method only returns available pre-installed library images. Those images can be passed directly to libcloud.compute.drivers.cloudsigma.CloudSigma_2_0_NodeDriver.create_node() method and used to create a server.

If you want to list all the available images and drives, you should use libcloud.compute.drivers.cloudsigma.CloudSigma_2_0_NodeDriver.ex_list_library_drives() method.

The example below shows how to list all the available sizes, images and drives.

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

cls = get_driver(Provider.CLOUDSIGMA)
driver = cls('username', 'password', region='zrh', api_version='2.0')

sizes = driver.list_sizes()
print(sizes)

images = driver.list_images()
print(images)

drives = driver.ex_list_library_drives()
print(drives)

Create a server using a custom node size

Unlike most of the other cloud providers out there, CloudSigma is not limited to pre-defined instance sizes and allows you to specify your own custom size when creating a node.

This means you can totally customize server for your work-load and specify exactly how much CPU, memory and disk space you want.

To follow Libcloud standard API, CloudSigma driver also exposes some pre-defined instance sizes through the libcloud.compute.drivers.cloudsigma.CloudSigma_2_0_NodeDriver.list_sizes() method.

This example shows how to create a node using a custom size.

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
from libcloud.compute.drivers.cloudsigma import CloudSigmaNodeSize

cls = get_driver(Provider.CLOUDSIGMA)
driver = cls('username', 'password', region='zrh', api_version='2.0')

name = 'test node custom size'
image = driver.list_images()[0]

# Custom node size with 56 GB of ram, 5000 MHz CPU and 200 GB SSD drive
size = CloudSigmaNodeSize(id=1, name='my size', cpu=5000, ram=5600, disk=200,
                          bandwidth=None, price=0, driver=driver)
node = driver.create_node(name=name, size=size, image=image)
print(node)

Keep in mind that there are some limits in place:

  • CPU - 1 GHz to 80GHz
  • Memory - 1 GB to 128 GB
  • Disk - 1 GB to 8249 GB

You can find exact limits and free capacity for your account’s location using libcloud.compute.drivers.cloudsigma.CloudSigma_2_0_NodeDriver.ex_list_capabilities() method.

Create a server with a VLAN

By default, each server created with Libcloud has one network interface with a public IP assigned.

Besides networks with a public IP, CloudSigma also allows you to create and use VLANs.

This example shows how to do that. It first creates a VLAN by purchasing a subscription and then assigns the create VLAN to a node upon creation.

Created node will have two network interfaces assigned - one with a public IP and one with the provided VLAN.

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

cls = get_driver(Provider.CLOUDSIGMA)
driver = cls('username', 'password', region='zrh', api_version='2.0')

name = 'test node with vlan'
size = driver.list_sizes()[0]
image = driver.list_images()[0]

# 1. Create a VLAN. VLANs are created by purchasing a subscription.
subscription = driver.ex_create_subscription(amount=1, period='1 month',
                                             resource='vlan', auto_renew=True)
vlan_uuid = subscription.subscribed_object

# 2. Create a node with a VLAN
node = driver.create_node(name=name, size=size, image=image,
                          ex_vlan=vlan_uuid)
print(node)

Create a server using an installation CD

This example shows how to create a server using an installation CD instead of a pre-installed drive (all the other create server examples in this section assume you are using a pre-installed drive).

Creating a server using an installation CD means that you can’t directly use the server after it has been created. Instead, you need to connect to the server using VNC and walk-through the installation process.

The example below shows how to create a server using FreeBSD 8.2 installation CD.

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

cls = get_driver(Provider.CLOUDSIGMA)
driver = cls('username', 'password', region='zrh', api_version='2.0')

name = 'test node'
size = driver.list_sizes()[0]

drives = driver.ex_list_library_drives()
image = [drive for drive in drives if drive.name == 'FreeBSD 8.2' and
         drive.media == 'cdrom'][0]

# 1. Create a node
node = driver.create_node(name=name, size=size, image=image)
print(node)

# 2. Wait for node to come online
driver.wait_until_running(nodes=[node])

# 3. Enable and obtain VNC URL so we can connect to the VNC server and walk
# through the installation process
tunnel_url = driver.ex_open_vnc_tunnel(node=node)

print('VNC tunnel URL: %s' % (tunnel_url))
print('VNC password: %s' % (node.extra['vnc_password']))

Associate metadata with a server upon creation

CloudSigma allows you to associate arbitrary key / value pairs with each server. This examples shows how to do that upon server creation.

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

cls = get_driver(Provider.CLOUDSIGMA)
driver = cls('username', 'password', region='zrh', api_version='2.0')

name = 'test node sizeth metadata'
size = driver.list_sizes()[0]
image = driver.list_images()[0]

metadata = {'ssh_public_key': 'my public key', 'role': 'database server',
            'region': 'zrh'}

node = driver.create_node(name=name, size=size, image=image,
                          ex_metadata=metadata)
print(node)

Add a tag to the server

CloudSigma allows you to organize resources such as servers and drivers by tagging them. This example shows how to do that.

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

cls = get_driver(Provider.CLOUDSIGMA)
driver = cls('username', 'password', region='zrh', api_version='2.0')

node = driver.list_nodes()[0]

tag_names = [
    'zrh',
    'database-server',
    'monited'
]

tags = []

# 1. Create necessary tags
for tag_name in tag_names:
    tag = driver.ex_create_tag(name='database-servers')
    tags.append(tag)

# 2. Tag node with the created tags
for tag in tags:
    driver.ex_tag_resource(resource=node, tag=tag)

Open a VNC tunnel to the server

CloudSigma allows you to connect and manage your server using VNC. To connect to the server using VNC, you can use clients such as vinagre or vncviewer on Ubuntu and other Linux distributions.

This example shows how to open a VNC connection to your server and retrieve a connection URL.

After you have retrieved the URL, you will also need a password which you specified (or it was auto-generated if you haven’t specified it) when creating a server.

If you can’t remember the password, you can use libcloud.compute.drivers.CloudSigma_2_0_NodeDriver.list_nodes() method and access node.extra['vnc_password'] attribute.

After you are done using VNC, it’s recommended to close a tunnel using libcloud.compute.drivers.cloudsigma.CloudSigma_2_0_NodeDriver.ex_close_vnc_tunnel() method.

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

cls = get_driver(Provider.CLOUDSIGMA)
driver = cls('username', 'password', region='zrh', api_version='2.0')

node = driver.list_nodes()[0]

vnc_url = driver.ex_open_vnc_tunnel(node=node)
vnc_password = node.extra['vnc_password']

values = {'url': vnc_url, 'password': vnc_password}
print('URL: %(url)s, Password: %(password)s' % values)

# When you are done
driver.ex_close_vnc_tunnel(node=node)

Attach firewall policy to the server

CloudSigma allows you to restrict access to your servers by using firewall policies. This example shows how to attach an existing policy to all your servers tagged with database-server.

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

cls = get_driver(Provider.CLOUDSIGMA)
driver = cls('username', 'password', region='zrh', api_version='2.0')

tags = driver.ex_list_tags()
tag = [tag for tag in tags if tag.name == 'database-server'][0]

nodes = driver.list_nodes(ex_tag=tag)
policy = driver.ex_list_firewall_policies()[0]

for node in nodes:
    driver.ex_attach_firewall_policy(policy=policy, node=node)

Starting a server in a different availability group using avoid functionality

CloudSigma allows you to specify a list of server UUIDs which to avoid when starting a server.

This helps make your infrastructure more highly available and is useful when you want to create a server in a different availability zone than the existing server.

The example below shows how to create a new server in a different availability zone from all the existing servers.

Keep in mind that as noted in the CloudSigma documentation, this functionality uses the best effort mode. This means that the request might succeed even if the avoid can not be satisfied and the requested resource ends in the same availability group as an avoid resource.

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

cls = get_driver(Provider.CLOUDSIGMA)
driver = cls('username', 'password', region='zrh', api_version='2.0')

name = 'test node avoid mode'
size = driver.list_sizes()[0]
image = driver.list_images()[0]

existing_nodes = driver.list_nodes()
existing_node_uuids = [node.id for node in existing_nodes]


node = driver.create_node(name=name, size=size, image=image,
                          ex_avoid=existing_node_uuids)
print(node)

To check which servers and drives share the same physical compute / storage host, you can use the libcloud.compute.drivers.cloudsigma.CloudSigma_2_0_NodeDriver.ex_list_servers_availability_groups() and libcloud.compute.drivers.cloudsigma.CloudSigma_2_0_NodeDriver.ex_list_drives_availability_groups() method as displayed below.

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

cls = get_driver(Provider.CLOUDSIGMA)
driver = cls('username', 'password', region='zrh', api_version='2.0')

servers_groups = driver.ex_list_servers_availability_groups()
drives_groups = driver.ex_list_drives_availability_groups()

print(servers_groups)
print(drives_groups)

Both of those methods return a list. Servers and drives which share the same physical host will be stored under the same index in the returned list.

Purchasing a subscription

A lot of resources such as SSDs, VLANs, IPs and others are created by purchasing a subscription.

When you purchase a subscription you need to supply the following arguments:

  • amount - Subscription amount. Unit depends on the purchased resource. For example, if you are purchasing a vlan resource, amount represents a number of VLAN networks you want to purchase.
  • period - For how long to purchase the subscription. Example values: 1 month, 30 days, etc.
  • resource - Resource to purchase the subscription for. Valid values: cpu, mem, tx, ip, vlan
  • auto_renew - True to auto renew the subscription when it expires.

The example below shows how to purchase a single VLAN for a duration of 30 days which will be automatically renewed when it expires.

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

cls = get_driver(Provider.CLOUDSIGMA)
driver = cls('username', 'password', region='zrh', api_version='2.0')

subscription = driver.ex_create_subscription(amount=1, period='30 days',
                                             resource='vlan', auto_renew=True)
print(subscription)

Retrieving the account balance

This example shows how to retrieve the account balance. The method returns a dictionary with two keys - balance and currency.

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver

cls = get_driver(Provider.CLOUDSIGMA)
driver = cls('username', 'password', region='zrh', api_version='2.0')

balance = driver.ex_get_balance()

values = {'balance': balance['balance'], 'currency': balance['currency']}
print('Account balance: %(balance)s %(currency)s' % values)

Other Resources

API Docs