Resources

CloudServiceType

class cloudbridge.interfaces.resources.CloudServiceType[source]

Defines possible service types that are offered by providers.

Providers can implement the has_service method and clients can check for the availability of a service with:

if (provider.has_service(CloudServiceTypes.BUCKET))
    ...

CloudResource

class cloudbridge.interfaces.resources.CloudResource[source]

Base interface for any Resource supported by a provider.

This interface has a _provider property that can be used to access the provider associated with the resource, which is only intended for use by subclasses. Every CloudBridge resource also has an id, a name and a label property. The id property is a unique identifier for the resource. The name is a more user-friendly version of an id, suitable for display to an end-user. However, it cannot be used in place of id. See @name documentation. The label property is a user-assignable identifier for the resource.

abstract property id

Get the resource identifier.

The id property is used to uniquely identify the resource, and is an opaque value which should not be interpreted by CloudBridge clients, and is a value meaningful to the underlying cloud provider.

Return type

str

Returns

ID for this resource as returned by the cloud middleware.

abstract property name

Get the name id for the resource.

The name property is typically a user-friendly id value for the resource. The name is different from the id property in the following ways:

  1. The name property is often a more user-friendly value to display to the user than the id property.

  2. The name may sometimes be the same as the id, but should never be used in place of the id.

  3. The id is what will uniquely identify a resource, and will be used internally by CloudBridge for all get operations etc.

  4. All resources have a name.

  5. The name is read-only.

  6. However, the name may not necessarily be unique, which is the reason why it should not be used for uniquely identifying a resource.

Example: The AWS machine image name maps to a CloudBridge name. It is not editable and is a user friendly name such as ‘Ubuntu 18.04’ and corresponds to the ami-name. It is distinct from the ami-id, which maps to CloudBridge’s id property. The ami-name cannot be edited, and is set at creation time. It is not necessarily unique. In Azure, the machine image’s name corresponds to CloudBridge’s name property. In Azure, it also happens to be the same as the id property.

The name property and the label property share the same character restrictions. See label.

abstract to_json()[source]

Returns a JSON representation of the CloudResource object.

Configuration

class cloudbridge.interfaces.resources.Configuration[source]

Represents a CloudBridge configuration object

abstract property debug_mode

A flag indicating whether CloudBridge is in debug mode.

Setting this to True will cause the underlying provider’s debug output to be turned on. The flag can be toggled by sending in the cb_debug value via the config dictionary, or setting the CB_DEBUG environment variable.

Return type

bool

Returns

Whether debug mode is on.

abstract property default_result_limit

Get the default maximum number of results to return for a list method.

The default limit will be applied to most list() and find() methods whenever an explicit limit is not specified.

Return type

int

Returns

The maximum number of results to return

property default_wait_interval

Get the default wait interval for LifeCycleObjects.

The default wait interval is applied in wait_for() and wait_till_ready() methods if no explicit interval is specified.

Return type

int

Returns

How frequently to poll the object’s state.

property default_wait_timeout

Get the default wait timeout for LifeCycleObjects.

The default wait timeout is applied in wait_for() and wait_till_ready() methods if no explicit timeout is specified.

Return type

int

Returns

The maximum length of time (in seconds) to wait for the object to change to desired state.

ObjectLifeCycleMixin

class cloudbridge.interfaces.resources.ObjectLifeCycleMixin[source]

A mixin for an object with a defined life-cycle.

Object examples include an Instance, Volume, Image, or Snapshot. An object that supports ObjectLifeCycleMixin will always have a state, defining which point in its life cycle it is currently at.

It also defines a wait_till_ready operation, which indicates that the object is in a state in its life cycle where it is ready to be used by an end-user.

A refresh operation allows the object to synchronize its state with the service provider.

abstract refresh()[source]

Refresh this object’s state and synchronize it with the provider.

abstract property state

Get the current state of this object.

Return type

str

Returns

The current state as a string.

abstract wait_for(target_states, terminal_states=None, timeout=None, interval=None)[source]

Wait for for an object to reach a one of desired target states.

If the object does not reach the desired state within the specified timeout, a WaitStateException will be raised. The optional terminal_states property can be used to specify an additional set of states which, should the object reach one, the object thereafter will not transition into the desired target state. Should this happen, a WaitStateException will be raised.

Example:

instance.wait_for(
    [InstanceState.DELETED, InstanceState.UNKNOWN],
    terminal_states=[InstanceState.ERROR])
Parameters
  • target_states (list of states) – The list of target states to wait for.

  • terminal_states (list of states) – A list of terminal states after which the object will not transition into a target state. A WaitStateException will be raised if the object transition into a terminal state.

  • timeout (int) – The maximum length of time (in seconds) to wait for the object to changed to desired state. If no timeout is specified, the global default_wait_timeout defined in the provider config will apply.

  • interval (int) – How frequently to poll the object’s state (in seconds). If no interval is specified, the global default_wait_interval defined in the provider config will apply.

Return type

True

Returns

Returns True if successful. A WaitStateException exception may be thrown by the underlying service if the object cannot get into a ready state (e.g. if the object is in an error state).

abstract wait_till_ready(timeout, interval)[source]

Wait till the current object reaches its ready state.

An object’s ready state is any state where the end-user can successfully interact with the object. Will throw a WaitStateException if the object is not ready within the specified timeout.

Parameters
  • timeout (int) – The maximum length of time (in seconds) to wait for the object to become ready.

  • interval (int) – How frequently to poll the object’s ready state (in seconds).

Return type

True

Returns

Returns True if successful. A WaitStateException exception may be thrown by the underlying service if the object cannot get into a ready state (e.g. if the object is in an error state).

PageableObjectMixin

class cloudbridge.interfaces.resources.PageableObjectMixin[source]

A marker interface for objects which support paged iteration.

The list of objects can be iterated over using the list(limit, marker) method.

abstract list(limit=None, marker=None)[source]

Returns a list of objects up to a maximum limit.

If a limit and marker are specified, the records will be fetched up to the limit starting from the marker onwards. The returned list is a list of class ResultList, which has extra properties like is_truncated, supports_total and total_records to provide extra information about record availability.

If limit is not specified, the limit will default to the underlying provider’s default limit. Therefore, you need to check the is_truncated property to determine whether more records are available.

The total number of results can be determined through the total_results property. Not all provides will support returning the total_results property, so the supports_total property can be used to determine whether a total is supported.

To iterate through all the records, it will be easier to iterate directly through the instances using __iter__ instead of calling the list method. The __iter__ method will automatically call the list method to fetch a batch of records at a time.

Example:

# get first page of results
instlist = provider.compute.instances.list(limit=50)
for instance in instlist:
    print("Instance Data: {0}", instance)
if instlist.supports_total:
    print("Total results: {0}".format(instlist.total_results))
else:
    print("Total records unknown,"
          "but has more data?: {0}".format(instlist.is_truncated))

# Page to next set of results
if (instlist.is_truncated)
    instlist = provider.compute.instances.list(limit=100,
                                               marker=instlist.marker)

# Alternative: iterate through every available record
for instance in provider.compute.instances:
    print(instance)

ResultList

class cloudbridge.interfaces.resources.ResultList(iterable=(), /)[source]

Provide extra properties to aid with paging through a many results.

This is a wrapper class around a standard Python list class.

Example:

# get first page of results
rl = provider.compute.instances.list(limit=50)
for result in rl:
    print("Instance Data: {0}", result)
if rl.supports_total:
    print("Total results: {0}".format(rl.total_results))
else:
    print("Total records unknown,"
          "but has more data?: {0}."format(rl.is_truncated))

# Page to next set of results
if (rl.is_truncated)
    rl = provider.compute.instances.list(limit=100,
                                         marker=rl.marker)
abstract property is_truncated

Indicate whether this result list has more results that can be paged.

abstract property marker

An opaque identifier used in paging through very long lists of objects.

This marker can be provided to the list method to get the next set of results.

abstract property supports_server_paging

Indicate whether this ResultList supports server side paging.

If server side paging is not supported, the result will use client side paging and the data property provides direct access to all available data.

abstract property supports_total

Indicate whether can obtain the total number of available results.

The supports_total property should be checked before accessing the total_results property. This is a provider-specific property.

abstract property total_results

Indicate the total number of results for a particular query.

The supports_total property should be used to check whether the provider supports returning the total number of results, before accessing this property, or the behavior is indeterminate.

InstanceState

class cloudbridge.interfaces.resources.InstanceState[source]

Standard states for an instance.

Variables
  • UNKNOWN – Instance state unknown.

  • PENDING – Instance is pending

  • CONFIGURING – Instance is being reconfigured in some way.

  • RUNNING – Instance is running.

  • REBOOTING – Instance is rebooting.

  • DELETED – Instance is deleted. No further operations possible.

  • STOPPED – Instance is stopped. Instance can be resumed.

  • ERROR – Instance is in an error state. No further operations possible.

Instance

class cloudbridge.interfaces.resources.Instance[source]
abstract add_floating_ip(floating_ip)[source]

Add a public IP address to this instance.

Parameters

floating_ip (:class:.FloatingIP or floating IP ID) – The FloatingIP object to associate with the instance. Note that is not the actual public IP address but the CloudBridge object encapsulating the IP or the respective provider ID that identifies the address.

abstract add_vm_firewall(firewall)[source]

Add a VM firewall to this instance

Parameters

firewall (:class:.VMFirewall) – The VMFirewall to associate with the instance.

abstract create_image(label)[source]

Create a new image based on this instance.

Return type

:class:.Image

Returns

an Image object

abstract delete()[source]

Permanently delete this instance.

abstract property image_id

Get the image ID for this instance.

Return type

str

Returns

Image ID (i.e., AMI) this instance is using.

abstract property key_pair_id

Get the id of the key pair associated with this instance.

Return type

str

Returns

Id of the ssh key pair associated with this instance.

abstract property label

Get the resource label.

The label property is a user-defined, editable identifier for a resource. It will often correspond to a user editable resource label in the underlying cloud provider, or be simulated through tags/labels.

The label property adheres to the following restrictions:

  • Must be at least 3 characters in length.

  • Cannot be longer than 63 characters.

  • May only contain ASCII characters comprising of lowercase letters, numeric characters, and dashes.

  • Must begin with an alphanumeric character and end with one (i.e. cannot begin or end with a dash)

Some resources may not support labels, in which case, a NotImplementedError will be thrown.

Return type

str

Returns

Label for this resource as returned by the cloud middleware.

Raise

NotImplementedError if this resource does not support labels.

abstract property private_ips

Get all the private IP addresses for this instance.

Return type

list

Returns

A list of private IP addresses associated with this instance.

abstract property public_ips

Get all the public IP addresses for this instance.

Return type

list

Returns

A list of public IP addresses associated with this instance.

abstract reboot()[source]

Reboot this instance (using the cloud middleware API).

Return type

bool

Returns

True if the reboot was successful; False otherwise.

abstract remove_floating_ip(floating_ip)[source]

Remove a public IP address from this instance.

Parameters

floating_ip (:class:.FloatingIP or floating IP ID) – The FloatingIP object to remove from the instance. Note that is not the actual public IP address but the CloudBridge object encapsulating the IP or the respective provider ID that identifies the address.

abstract remove_vm_firewall(firewall)[source]

Remove a VM firewall from this instance

Parameters

firewall (VMFirewall) – The VMFirewall to associate with the instance.

abstract start()[source]

Start this instance (using the cloud middleware API)

Return type

bool

Returns

True if the starting was successful; False otherwise.

abstract stop()[source]

Stop this instance (using the cloud middleware API)

Return type

bool

Returns

True if the stopping was successful; False otherwise.

abstract property subnet_id

Get the subnet ID where this instance is placed.

Return type

str

Returns

Subnet ID to which this instance is connected.

abstract property vm_firewall_ids

Get the IDs of the VM firewalls associated with this instance.

Return type

list or :class:str

Returns

A list of the VMFirewall IDs associated with this instance.

abstract property vm_firewalls

Get the firewalls (security groups) associated with this instance.

Return type

list or VMFirewall objects

Returns

A list of VMFirewall objects associated with this instance.

abstract property vm_type

Retrieve full VM type information for this instance.

Return type

VMType

Returns

VM type for this instance

abstract property vm_type_id

Get the VM type id for this instance.

This will typically be a string value like ‘m1.large’. On OpenStack, this may be a number or UUID. To get the full :class:.VMType object, you can use the instance.vm_type property instead.

Return type

str

Returns

VM type id for this instance (e.g., m1.large)

abstract property zone_id

Get the placement zone ID where this instance is running.

Return type

str

Returns

Region/zone/placement where this instance is running.

MachineImageState

class cloudbridge.interfaces.resources.MachineImageState[source]

Standard states for a machine image

Variables
  • UNKNOWN – Image state unknown.

  • PENDING – Image is pending

  • AVAILABLE – Image is available

  • ERROR – Image is in an error state. Not recoverable.

LaunchConfig

class cloudbridge.interfaces.resources.LaunchConfig[source]

Represents an advanced launch configuration object.

This object can contain information such as BlockDeviceMappings configurations and other advanced options, which may be useful when launching an instance.

Example:

lc = provider.compute.instances.create_launch_config()
lc.add_block_device(...)

inst = provider.compute.instances.create(
    'MyVM', image, vm_type, subnet, launch_config=lc)
abstract add_ephemeral_device()[source]

Add a new ephemeral block device mapping to the boot configuration.

This can be used to add existing ephemeral devices to the instance (the total number of ephemeral devices available for a particular VMType can be determined by querying the VMType service). Note that on some providers, such as AWS, ephemeral devices must be added in as a device mapping at instance creation time and cannot be added afterwards.

Note that the device name, such as /dev/sda1, cannot be selected at present, since this tends to be provider and VM type specific. However, the order of device addition coupled with device type will generally determine naming order, with devices added first getting lower letters than instances added later.

Example:

lc = provider.compute.instances.create_launch_config()

# 1. Add all available ephemeral devices
vm_type = provider.compute.vm_types.find(name='m1.tiny')[0]
for i in range(vm_type.num_ephemeral_disks):
    lc.add_ephemeral_device()
abstract add_volume_device(source=None, is_root=None, size=None, delete_on_terminate=None)[source]

Add a new volume based block device mapping to the boot configuration.

The volume can be based on a snapshot, image, existing volume or be a blank new volume, and is specified by the source parameter.

The property is_root can be set to True to override any existing root device mappings. Otherwise, the default behavior is to add new block devices to the instance.

Note that the device name, such as /dev/sda1, cannot be selected at present since this tends to be provider and VM type specific. However, the order of device addition coupled with device type will generally determine naming order, with devices added first getting lower letters than instances added later (except when is_root is set).

Example:

lc = provider.compute.instances.create_launch_config()

# 1. Create and attach an empty volume of size 100GB
lc.add_volume_device(size=100, delete_on_terminate=True)

# 2. Create and attach a volume based on a snapshot
snap = provider.storage.snapshots.get('<my_snapshot_id>')
lc.add_volume_device(source=snap)

# 3. Create+attach a volume based on an image and set it as root
img = provider.compute.images.get('<my_image_id>')
lc.add_volume_device(source=img, size=100, is_root=True)
Parameters
  • source (Volume, Snapshot, Image or None.) – The source block_device to add. If Volume, the volume will be attached directly to the instance. If Snapshot, a volume will be created based on the Snapshot and attached to the instance. If Image, a volume based on the Image will be attached to the instance. If None, the source is assumed to be a blank volume.

  • is_root (bool) – Determines which device will serve as the root device. If more than one device is defined as root, an InvalidConfigurationException will be thrown.

  • size (int) – The size of the volume to create. An implementation may ignore this parameter for certain sources like ‘Volume’.

  • delete_on_terminate (bool) – Determines whether to delete or keep the volume on instance termination.

MachineImage

class cloudbridge.interfaces.resources.MachineImage[source]
abstract delete()[source]

Delete this image.

Return type

bool

Returns

True if the operation succeeded.

abstract property description

Get the image description.

Return type

str

Returns

Description for this image as returned by the cloud middleware.

abstract property min_disk

Return the minimum size of the disk that’s required to boot this image.

Value returned is in gigabytes.

Return type

int

Returns

The minimum disk size needed by this image.

NetworkState

class cloudbridge.interfaces.resources.NetworkState[source]

Standard states for a network.

Variables
  • UNKNOWN – Network state unknown.

  • PENDING – Network is being created.

  • AVAILABLE – Network is available.

  • DOWN – Network is not operational.

  • ERROR – Network is in error state.

Network

class cloudbridge.interfaces.resources.Network[source]

Represents a software-defined network, like the Virtual Private Cloud.

abstract property cidr_block

A CIDR block for this network.

Note

OpenStack does not define a CIDR block for networks.

Return type

str

Returns

A CIDR block string.

abstract delete()[source]

Delete this network.

Return type

bool

Returns

True if successful.

abstract property external

A flag to indicate if this network is capable of Internet-connectivity.

Return type

bool

Returns

True if the network can be connected to the Internet.

abstract property gateways

Provides access to the internet gateways attached to this network.

Return type

GatewaySubService

Returns

A GatewaySubService object

abstract property label

Get the resource label.

The label property is a user-defined, editable identifier for a resource. It will often correspond to a user editable resource label in the underlying cloud provider, or be simulated through tags/labels.

The label property adheres to the following restrictions:

  • Must be at least 3 characters in length.

  • Cannot be longer than 63 characters.

  • May only contain ASCII characters comprising of lowercase letters, numeric characters, and dashes.

  • Must begin with an alphanumeric character and end with one (i.e. cannot begin or end with a dash)

Some resources may not support labels, in which case, a NotImplementedError will be thrown.

Return type

str

Returns

Label for this resource as returned by the cloud middleware.

Raise

NotImplementedError if this resource does not support labels.

abstract property state

The state of the network.

Return type

str

Returns

One of unknown, pending, available, down or error.

abstract property subnets

The associated subnets.

Return type

list of Subnet

Returns

List of subnets associated with this network.

SubnetState

class cloudbridge.interfaces.resources.SubnetState[source]

Standard states for a subnet.

Variables
  • UNKNOWN – Subnet state unknown.

  • PENDING – Subnet is being created.

  • AVAILABLE – Subnet is available.

  • DOWN – Subnet is not operational.

  • ERROR – Subnet is in error state.

Subnet

class cloudbridge.interfaces.resources.Subnet[source]

Represents a subnet, as part of a Network.

abstract property cidr_block

A CIDR block for this subnet.

Return type

str

Returns

A CIDR block string.

abstract delete()[source]

Delete this subnet.

Return type

bool

Returns

True if successful.

abstract property label

Get the resource label.

The label property is a user-defined, editable identifier for a resource. It will often correspond to a user editable resource label in the underlying cloud provider, or be simulated through tags/labels.

The label property adheres to the following restrictions:

  • Must be at least 3 characters in length.

  • Cannot be longer than 63 characters.

  • May only contain ASCII characters comprising of lowercase letters, numeric characters, and dashes.

  • Must begin with an alphanumeric character and end with one (i.e. cannot begin or end with a dash)

Some resources may not support labels, in which case, a NotImplementedError will be thrown.

Return type

str

Returns

Label for this resource as returned by the cloud middleware.

Raise

NotImplementedError if this resource does not support labels.

abstract property network

The parent network object associated with this this subnet.

Return type

Network

Returns

Network object

abstract property network_id

ID of the network associated with this this subnet.

Return type

str

Returns

Network ID.

abstract property zone

Placement zone of the subnet.

If the provider does not support subnet placement, return None.

Return type

PlacementZone object

Returns

Placement zone of the subnet, or None if not defined.

FloatingIP

class cloudbridge.interfaces.resources.FloatingIP[source]

Represents a floating (i.e., static) IP address.

abstract delete()[source]

Delete this address.

Return type

bool

Returns

True if successful.

abstract property in_use

Whether the address is in use or not.

Return type

bool

Returns

True if the address is attached to an instance.

abstract property private_ip

Private IP address this address is attached to.

Return type

str

Returns

IP address or None.

abstract property public_ip

Public IP address.

Return type

str

Returns

IP address.

RouterState

class cloudbridge.interfaces.resources.RouterState[source]

Standard states for a router.

Variables
  • UNKNOWN – Router state unknown.

  • ATTACHED – Router is attached to a network and should be operational.

  • DETACHED – Router is detached from a network.

Router

class cloudbridge.interfaces.resources.Router[source]

Represents a private network router.

This logical router is meant to roughly mimic the properties of a physical router. Therefore, attaching a subnet can be thought of as plugging in a network cable to enable routing to/from that subnet. Attaching a gateway can be thought of as plugging in an upstream link.

abstract attach_gateway(gateway)[source]

Attach a gateway to this router.

Parameters

gateway (Gateway) – The Gateway to attach to this router.

Return type

bool

Returns

True if successful.

abstract attach_subnet(subnet)[source]

Attach this router to a subnet.

Parameters

subnet (Subnet or str) – The subnet to which to attach this router.

Return type

bool

Returns

True if successful.

abstract delete()[source]

Delete this router.

Return type

bool

Returns

True if successful.

abstract detach_gateway(gateway)[source]

Detach this router from a gateway.

Return type

bool

Returns

True if successful.

abstract detach_subnet(subnet)[source]

Detach this subnet from a network.

Parameters

subnet (Subnet or str) – The subnet to detach from this router.

Return type

bool

Returns

True if successful.

abstract property label

Get the resource label.

The label property is a user-defined, editable identifier for a resource. It will often correspond to a user editable resource label in the underlying cloud provider, or be simulated through tags/labels.

The label property adheres to the following restrictions:

  • Must be at least 3 characters in length.

  • Cannot be longer than 63 characters.

  • May only contain ASCII characters comprising of lowercase letters, numeric characters, and dashes.

  • Must begin with an alphanumeric character and end with one (i.e. cannot begin or end with a dash)

Some resources may not support labels, in which case, a NotImplementedError will be thrown.

Return type

str

Returns

Label for this resource as returned by the cloud middleware.

Raise

NotImplementedError if this resource does not support labels.

abstract property network_id

ID of the network to which the router is attached.

Return type

str

Returns

ID for the attached network or None.

abstract property state

Router state: attached or detached to a network.

Return type

str

Returns

attached or detached.

abstract property subnets

List of subnets attached to this router.

Return type

list of Subnet objects

Returns

A list of subnets associated with this router.

Gateway

class cloudbridge.interfaces.resources.Gateway[source]

Represents a gateway resource.

abstract delete()[source]

Delete this gateway. On some providers, if the gateway is public/a singleton, this operation will do nothing.

abstract property floating_ips

Provides access to floating IPs connected to this internet gateway.

Return type

FloatingIPSubService

Returns

A FloatingIPSubService object

abstract property network_id

ID of the network to which the gateway is attached.

Return type

str

Returns

ID for the attached network or None.

InternetGateway

class cloudbridge.interfaces.resources.InternetGateway[source]

Represents an Internet gateway resource.

VolumeState

class cloudbridge.interfaces.resources.VolumeState[source]

Standard states for a volume

Variables
  • UNKNOWN – Volume state unknown.

  • CREATING – Volume is being created.

  • CONFIGURING – Volume is being configured in some way.

  • AVAILABLE – Volume is available and can be attached to an instance.

  • IN_USE – Volume is attached and in-use.

  • DELETED – Volume has been deleted. No further operations possible.

  • ERROR – Volume is in an error state. No further operations possible.

Volume

class cloudbridge.interfaces.resources.Volume[source]

Represents a block storage device (aka volume).

abstract attach(instance, device)[source]

Attach this volume to an instance.

Parameters
  • instance (str or Instance object) – The ID of an instance or an Instance object to which this volume will be attached.

  • device (str) – The device on the instance through which the volume will be exposed (e.g. /dev/sdh).

Return type

bool

Returns

True if successful.

abstract property attachments

Get attachment information for this volume.

Return type

AttachmentInfo

Returns

Returns an AttachmentInfo object.

abstract create_snapshot(label, description=None)[source]

Create a snapshot of this Volume.

Parameters
  • label (str) – The label for this snapshot.

  • description (str) – A description of the snapshot. Limited to 256 characters.

Return type

Snapshot

Returns

The created Snapshot object.

abstract property create_time

Get the creation data and time for this volume.

Return type

DateTime

Returns

Creation time for this volume as returned by the cloud middleware.

abstract delete()[source]

Delete this volume.

Return type

bool

Returns

True if successful.

abstract property description

Get the volume description.

Some cloud providers may not support this property, and will return the volume label instead.

Return type

str

Returns

Description for this volume as returned by the cloud middleware.

abstract detach(force=False)[source]

Detach this volume from an instance.

Parameters

force (bool) – Forces detachment if the previous detachment attempt did not occur cleanly. This option is supported on select clouds only. This option can lead to data loss or a corrupted file system. Use this option only as a last resort to detach a volume from a failed instance. The instance will not have an opportunity to flush file system caches nor file system meta data. If you use this option, you must perform file system check and repair procedures.

Return type

bool

Returns

True if successful.

abstract property label

Get the resource label.

The label property is a user-defined, editable identifier for a resource. It will often correspond to a user editable resource label in the underlying cloud provider, or be simulated through tags/labels.

The label property adheres to the following restrictions:

  • Must be at least 3 characters in length.

  • Cannot be longer than 63 characters.

  • May only contain ASCII characters comprising of lowercase letters, numeric characters, and dashes.

  • Must begin with an alphanumeric character and end with one (i.e. cannot begin or end with a dash)

Some resources may not support labels, in which case, a NotImplementedError will be thrown.

Return type

str

Returns

Label for this resource as returned by the cloud middleware.

Raise

NotImplementedError if this resource does not support labels.

abstract property size

Get the volume size (in GB).

Return type

int

Returns

Size for this volume as returned by the cloud middleware.

abstract property source

If available, get the source that this volume is based on.

This can be a Snapshot, an Image, or None if no source.

Return type

Snapshot, Image, or None

Returns

Snapshot or Image source for this volume as returned by the cloud middleware.

abstract property zone_id

Get the placement zone id that this volume belongs to.

Return type

str

Returns

PlacementZone for this volume as returned by the cloud middleware.

SnapshotState

class cloudbridge.interfaces.resources.SnapshotState[source]

Standard states for a snapshot

Variables
  • UNKNOWN – Snapshot state unknown.

  • PENDING – Snapshot is pending.

  • CONFIGURING – Snapshot is being configured in some way.

  • AVAILABLE – Snapshot has been completed and is ready for use.

  • ERROR – Snapshot is in an error state. No further operations possible.

Snapshot

class cloudbridge.interfaces.resources.Snapshot[source]

Represents a snapshot of a block storage device.

abstract property create_time

Get the creation data and time for this snapshot.

Return type

DateTime

Returns

Creation time for this snapshot as returned by the cloud middleware.

abstract create_volume(size=None, volume_type=None, iops=None)[source]

Create a new Volume from this Snapshot.

Parameters
  • size (int) – The size of the new volume, in GiB (optional). Defaults to the size of the snapshot.

  • volume_type (str) – The type of the volume (optional). Availability and valid values depend on the provider.

  • iops (int) – The provisioned IOPs you want to associate with this volume (optional). Availability depends on the provider.

Return type

Volume

Returns

An instance of the created Volume.

abstract delete()[source]

Delete this snapshot.

Return type

bool

Returns

True if successful.

abstract property description

Get the snapshot description.

Some cloud providers may not support this property, and will return the snapshot label instead.

Return type

str

Returns

Description for this snapshot as returned by the cloud middleware.

abstract property label

Get the resource label.

The label property is a user-defined, editable identifier for a resource. It will often correspond to a user editable resource label in the underlying cloud provider, or be simulated through tags/labels.

The label property adheres to the following restrictions:

  • Must be at least 3 characters in length.

  • Cannot be longer than 63 characters.

  • May only contain ASCII characters comprising of lowercase letters, numeric characters, and dashes.

  • Must begin with an alphanumeric character and end with one (i.e. cannot begin or end with a dash)

Some resources may not support labels, in which case, a NotImplementedError will be thrown.

Return type

str

Returns

Label for this resource as returned by the cloud middleware.

Raise

NotImplementedError if this resource does not support labels.

abstract property size

Get the snapshot size (in GB).

Return type

int

Returns

Size for this snapshot as returned by the cloud middleware.

abstract property volume_id

Get the id of the volume that this snapshot is based on.

This method may return None if the source volume no longer exists.

Return type

int

Returns

Id of the volume that this snapshot is based on

KeyPair

class cloudbridge.interfaces.resources.KeyPair[source]

Represents an ssh key pair.

abstract delete()[source]

Delete this key pair.

Return type

bool

Returns

True if successful.

abstract property material

Unencrypted private key.

Return type

str

Returns

Unencrypted private key or None if not available.

Region

class cloudbridge.interfaces.resources.Region[source]

Represents a cloud region.

A cloud region is typically a separate geographic area and will contain at least one placement zone.

abstract property zones

Access information about placement zones within this region.

Return type

Iterable

Returns

Iterable of available placement zones in this region.

PlacementZone

class cloudbridge.interfaces.resources.PlacementZone[source]

Represents a placement zone.

A placement zone is contained within a Region.

abstract property region_name

A region this placement zone is associated with.

Return type

str

Returns

The id of the region the zone is associated with.

VMType

class cloudbridge.interfaces.resources.VMType[source]

A VM type object.

abstract property extra_data

A dictionary of extra data about this instance. May contain nested dictionaries, but all key value pairs are strings or integers.

Return type

dict

Returns

Extra attributes for this VM type.

abstract property family

The family/group that this VM type belongs to.

For example, General Purpose Instances or High-Memory Instances. If the provider does not support such a grouping, it may return None.

Return type

str

Returns

Name of the instance family or None.

abstract property num_ephemeral_disks

The total number of ephemeral disks on this VM type.

Return type

int

Returns

Number of ephemeral disks available.

abstract property ram

The amount of RAM (in GB) supported by this VM type.

Return type

float

Returns

Total RAM (in GB).

abstract property size_ephemeral_disks

The size of this VM types’s total ephemeral storage (in GB).

Return type

int

Returns

Size of ephemeral disks (in GB).

abstract property size_root_disk

The size of this VM types’s root disk (in GB).

Return type

int

Returns

Size of root disk (in GB).

abstract property size_total_disk

The total disk space available on this VM type (root_disk + ephemeral).

Return type

int

Returns

Size of total disk space (in GB).

abstract property vcpus

The number of VCPUs supported by this VM type.

Return type

int

Returns

Number of VCPUs.

VMFirewall

class cloudbridge.interfaces.resources.VMFirewall[source]

Represents a firewall resource applied to virtual machines.

This is in contrast to a firewall for a network, for example.

abstract property description

Return the description of this VM firewall.

Return type

str

Returns

A description of this VM firewall.

abstract property label

Get the resource label.

The label property is a user-defined, editable identifier for a resource. It will often correspond to a user editable resource label in the underlying cloud provider, or be simulated through tags/labels.

The label property adheres to the following restrictions:

  • Must be at least 3 characters in length.

  • Cannot be longer than 63 characters.

  • May only contain ASCII characters comprising of lowercase letters, numeric characters, and dashes.

  • Must begin with an alphanumeric character and end with one (i.e. cannot begin or end with a dash)

Some resources may not support labels, in which case, a NotImplementedError will be thrown.

Return type

str

Returns

Label for this resource as returned by the cloud middleware.

Raise

NotImplementedError if this resource does not support labels.

abstract property network_id

Network ID with which this VM firewall is associated.

Return type

str

Returns

Provider-supplied network ID or None is not available.

abstract property rules

Get access to the rules belonging to this VM firewall.

This object can be used for further operations on rules, such as get, list, create, etc.

Return type

An object of VMFirewallRuleSubService

Returns

A VMFirewallRuleSubService for further operations

VMFirewallRule

class cloudbridge.interfaces.resources.VMFirewallRule[source]

Represents a VM firewall rule.

abstract property cidr

CIDR block this VM firewall is providing access to.

Return type

str

Returns

CIDR block.

abstract delete()[source]

Delete this rule.

abstract property direction

Direction of traffic to which this rule applies.

Either TrafficDirection.INBOUND or TrafficDirection.OUTBOUND.

Return type

str

Returns

Direction of traffic to which this rule applies.

abstract property from_port

Lowest port number opened as part of this rule.

Return type

int

Returns

Lowest port number or 0 if not set.

abstract property protocol

IP protocol used. Either tcp | udp | icmp.

Return type

str

Returns

Active protocol.

abstract property src_dest_fw

VM firewall given access permissions by this rule.

Return type

:class:.VMFirewall

Returns

The VM firewall granted access.

abstract property src_dest_fw_id

VM firewall id given access permissions by this rule.

Return type

str

Returns

The VM firewall granted access.

abstract property to_port

Highest port number opened as part of this rule.

Return type

int

Returns

Highest port number or 0 if not set.

TrafficDirection

class cloudbridge.interfaces.resources.TrafficDirection(value)[source]

Direction of data flow in a firewall.

BucketObject

class cloudbridge.interfaces.resources.BucketObject[source]

Represents an object stored within a bucket.

abstract delete()[source]

Delete this object.

Return type

bool

Returns

True if successful.

abstract generate_url(expires_in, writable=False)[source]

Generate a signed URL to this object.

A signed URL associated with an object gives time-limited read access to that specific object. Anyone in possession of the URL has the access granted by the URL.

Parameters
  • expires_in (int) – Time to live of the generated URL in seconds.

  • writable (bool) – Write permission for this signed URL. Users with the URL will be able to upload to this object, but they will NOT be able to read from it.

Return type

str

Returns

A URL to access the object.

abstract iter_content()[source]

Returns this object’s content as an iterable.

Return type

Iterable

Returns

An iterable of the file contents

abstract property last_modified

Get the date and time this object was last modified.

Return type

str

Returns

Date and time formatted string %Y-%m-%dT%H:%M:%S.%f

abstract property name

Retrieve the name of the current object.

The bucket object name adheres to a naming requirement that is more relaxed than the naming requirement enforced across CloudBridge. More details are available here: http://docs.aws.amazon.com/AmazonS3/latest/ dev/UsingMetadata.html#object-key-guidelines

Return type

str

Returns

Name for this object as returned by the cloud middleware.

abstract refresh()[source]

Refresh this object’s state and synchronize it with the underlying service provider.

abstract save_content(target_stream)[source]

Save this object and write its contents to the target_stream.

abstract property size

Get this object’s size.

Return type

int

Returns

Size of this object in bytes.

abstract upload(source_stream)[source]

Set the contents of the object to the data read from the source stream.

Return type

bool

Returns

True if successful.

abstract upload_from_file(path)[source]

Store the contents of the file pointed by the “path” variable.

Parameters

path (str) – Absolute path to the file to be uploaded to S3.

Bucket

class cloudbridge.interfaces.resources.Bucket[source]

Represents a namespace for objects (eg, object store bucket or container).

abstract delete(delete_contents=False)[source]

Delete this bucket.

Parameters

delete_contents (bool) – If True, all objects within the bucket will be deleted.

Return type

bool

Returns

True if successful.

abstract property name

Retrieve the name of the current bucket.

Return type

str

Returns

Name for this instance as returned by the cloud middleware.

abstract property objects

Get a container for the objects belonging to this Bucket.

This object can be used to iterate through bucket objects, as well as perform further operations on buckets, such as get, list, create, etc.

# Show all objects in bucket
print(list(bucket.objects))

# Find an object by name
print(bucket.objects.find(name='my_obj.txt'))

# Get first page of bucket list
print(bucket.objects.list())

# Create a new object within this bucket
obj = bucket.objects.create('my_obj.txt')
Return type

BucketContainer

Returns

A BucketContainer for further operations.

DnsZone

class cloudbridge.interfaces.resources.DnsZone[source]

Represents a dns host zone.

A host zone represents a top level domain (e.g. cloudve.org) in which multiple dns records (e.g. A, CNAME. MX etc.) are contained.

property admin_email

Email address of this zone’s administrator. Some cloud providers do not support this field, and therefore, it may be stored in an extra field such as description or not supported at all. (This field is mandatory in OpenStack)

Returns

Administrator’s email as a string

abstract delete()[source]

Delete this zone.

abstract property records

List of DNS records in this zone.

Return type

list of DnsRecord objects

Returns

A list of DnsRecords associated with this zone.

DnsRecord

class cloudbridge.interfaces.resources.DnsRecord[source]

Represents a dns record.

A dns record belongs to a host zone and can contain records of varous types such as A, CNAME. MX etc.

abstract property data

Dns Record data

Return type

str

Returns

A string containing this DNS record’s data.

abstract property ttl

ttl for this record

Return type

int

Returns

The ttl (in seconds) for this record.

abstract property type

Dns Record type which could be A, CNAME, MX, AAAA, PTR

Return type

DnsRecordType

Returns

An enum representing the DNS record type.

abstract property zone_id

The containing zone for this dns record

Return type

str

Returns

The ID of the zone for this dns record