Working with the object oriented APIs

To make it easier for the end user, Libcloud components expose a fully object-oriented API.

This means that besides the driver object you also work with NodeImage, and NodeSize object in the compute API, Container and Object object in the Storage API, Zone and Record object in the DNS API and so on.

Methods which operate on those resources usually require you to pass in an instance of the resource you want to manipulate or work with and not just an id.

To obtain a reference to this resource, Libcloud providers corresponding get and / or list methods.

A couple of examples are shown below.

Example 1 - listing records for a zone with a known id

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

CREDENTIALS_ZERIGO = ('email', 'api key')
ZONE_ID = 'example.myzone.com'

Cls = get_driver(Provider.ZERIGO)
driver = Cls(*CREDENTIALS_ZERIGO)

zone = driver.get_zone(zone_id=ZONE_ID)
records = driver.list_records(zone=zone)

In this example, the driver.get_zone() method call results in an HTTP call.

Example 2 - creating an EC2 instance with a known NodeSize and NodeImage id

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

ACCESS_ID = 'your access id'
SECRET_KEY = 'your secret key'

IMAGE_ID = 'ami-c8052d8d'
SIZE_ID = 't1.micro'

cls = get_driver(Provider.EC2)
driver = cls(ACCESS_ID, SECRET_KEY, region="us-west-1")

# Here we select size and image
sizes = driver.list_sizes()
images = driver.list_images()

size = [s for s in sizes if s.id == SIZE_ID][0]
image = [i for i in images if i.id == IMAGE_ID][0]

node = driver.create_node(name='test-node', image=image, size=size)

In this example, both the driver.list_sizes() and driver.list_images() method calls result in HTTP calls.

As you can see above, most of those getter methods retrieve extra information about the resource from the provider API and result in an HTTP request.

There are some cases when you might not want this:

  • You don’t care if a resource doesn’t exist
  • You don’t care about the extra attributes
  • You want to avoid an extra HTTP request
  • You want to avoid holding a reference to the resource object

If that is true for you, you can directly instantiate a resource with a known id. You can see how to do this in the examples below.

Example 1 - listing records for a zone with a known id

from libcloud.dns.base import Zone
from libcloud.dns.providers import get_driver
from libcloud.dns.types import Provider

CREDENTIALS_ZERIGO = ('email', 'api key')
ZONE_ID = 'example.myzone.com'

Cls = get_driver(Provider.ZERIGO)
driver = Cls(*CREDENTIALS_ZERIGO)

zone = Zone(ZONE_ID, domain=None, type=None, ttl=None,
            driver=driver)
records = driver.list_records(zone=zone)

Example 2 - creating an EC2 instance with a known NodeSize and NodeImage id

from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
from libcloud.compute.base import NodeSize, NodeImage

ACCESS_ID = 'your access id'
SECRET_KEY = 'your secret key'

IMAGE_ID = 'ami-c8052d8d'
SIZE_ID = 't1.micro'

cls = get_driver(Provider.EC2)
driver = cls(ACCESS_ID, SECRET_KEY, region="us-west-1")

size = NodeSize(id=SIZE_ID, name=None, ram=None, disk=None, bandwidth=None,
                price=None, driver=driver)
image = NodeImage(id=IMAGE_ID, name=None, driver=driver)

node = driver.create_node(name='test-node', image=image, size=size)

Example 3 - creating an EC2 instance with an IAM profile

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

ACCESS_ID = 'your access id'
SECRET_KEY = 'your secret key'
IAM_PROFILE = 'your IAM profile arn or IAM profile name'

IMAGE_ID = 'ami-c8052d8d'
SIZE_ID = 't1.micro'
cls = get_driver(Provider.EC2)
driver = cls(ACCESS_ID, SECRET_KEY, region="us-west-1")

# Here we select size and image
sizes = driver.list_sizes()
images = driver.list_images()

size = [s for s in sizes if s.id == SIZE_ID][0]
image = [i for i in images if i.id == IMAGE_ID][0]

node = driver.create_node(name='test-node', image=image, size=size,
                          ex_iamprofile=IAM_PROFILE)