CloudStack Compute Driver Documentation¶
CloudStack is an Apache Software Foundation open source software designed to deploy and manage large networks of virtual machines, as a highly available, highly scalable Infrastructure as a Service (IaaS) cloud computing platform. CloudStack is used by a number of service providers to offer public cloud services, and by many companies to provide an on-premises (private) cloud offering, or as part of a hybrid cloud solution.
CloudStack has its own non-standard API , libcloud provides a Python wrapper on top of this API with common methods with other IaaS solutions and Public cloud providers. Therefore, you can use use the CloudStack libcloud driver to communicate with your local CloudStack based private cloud as well as CloudStack based public clouds.
Instantiating a driver¶
When you instantiate a driver you need to pass the following arguments to the driver constructor:
key
- Your CloudStack API keysecret
- Your CloudStack secret keyhost
- The host of your CloudStack endpoint (e.glocalhost
forhttp://localhost:8080/client/api
)path
- The path to your CloudStack endpoint (e.g/client/api
forhttp://localhost:8080/client/api
)url
- The url to your CloudStack endpoint, mutually exclusive withhost
andpath
secure
- True or False. True by default
Typically this will lead to:
from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
apikey = 'your api key'
secretkey = 'your secret key'
host = 'example.com'
path = '/path/to/api'
Driver = get_driver(Provider.CLOUDSTACK)
conn = Driver(key=apikey, secret=secretkey, host=host, path=path)
A complete url
can be used instead:
from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
apikey = 'your api key'
secretkey = 'your secret key'
url = 'http://example.com/path/to/api'
Driver = get_driver(Provider.CLOUDSTACK)
conn = Driver(key=apikey, secret=secretkey, url=url)
In the testing scenario where you are running CloudStack locally, the connection may be insecure and you may run it on a specific port. In that case, the instantiation would look like this
from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
apikey = 'your api key'
secretkey = 'your secret key'
host = 'localhost'
path = '/path/to/api'
port = 8080
Driver = get_driver(Provider.CLOUDSTACK)
conn = Driver(key=apikey, secret=secretkey, host=host,
path=path, port=port, secure=False)
If you are making a connection to a secure cloud that does not use a trusted certificate, you will have to disable the SSL verification like so:
import libcloud.security as sec
sec.VERIFY_SSL_CERT = False
For more information on how SSL certificate validation works in Libcloud, see the SSL Certificate Validation page.
libcloud now features CloudStack based drivers for the exoscale and ikoula public clouds. Instantiating drivers to those clouds is shown in the example section below.
The base libcloud API allows you to:
- list nodes, images, instance types, locations
- list, create, attach, detach, delete volumes
Non-standard functionality and extension methods¶
The CloudStack driver exposes a lot of libcloud non-standard functionalities through extension methods and arguments.
These functionalities include:
- start and stop a node
- list disk offerings
- list networks
- list, allocate and release public IPs,
- list, create and delete port forwarding rules
- list, create and delete IP forwarding rules
- list, create, delete and authorize security groups
Some methods are only valid for CloudStack advanced zones, while others are suited for basic zones.
For information on how to use these functionalities please see the method docstrings below. You can also use an interactive shell for exploration as shown in the examples.
Basic Zone Examples¶
To start experimenting with libcloud, starting an ipython interactive shell can be very handy. Tab completion and shell history are available. Below is an example of starting such an interactive shell for the exoscale public cloud. Once started you can explore the libcloud API.
1. Start an interactive shell on Exoscale public cloud¶
import os
# pylint: disable=import-error
from IPython.terminal.embed import InteractiveShellEmbed
from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
apikey = os.getenv('EXOSCALE_API_KEY')
secretkey = os.getenv('EXOSCALE_SECRET_KEY')
Driver = get_driver(Provider.EXOSCALE)
conn = Driver(key=apikey, secret=secretkey)
shell = InteractiveShellEmbed(banner1='Hello from Libcloud Shell !!')
shell()
After experimenting through an interactive shell, you can write scripts that will directly execute libcloud commands. For instance starting a node with a specific ssh keypair and a couple of security groups can be done as shown in the following example:
2. SSH Keypairs management on Exoscale public cloud¶
The base libcloud API has been extended to handle management of ssh keypairs. This is very useful for CloudStack basic zones. SSH Keypairs, can be listed, created, deleted and imported. This new base API is only available in libcloud trunk.
import os
from pprint import pprint
from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
cls = get_driver(Provider.EXOSCALE)
driver = cls('api key', 'api secret key')
# Create a new key pair. Most providers will return generated private key in
# the response which can be accessed at key_pair.private_key
key_pair = driver.create_key_pair(name='test-key-pair-1')
pprint(key_pair)
# Import an existing public key from a file. If you have public key as a
# string, you can use import_key_pair_from_string method instead.
key_file_path = os.path.expanduser('~/.ssh/id_rsa_test.pub')
key_pair = driver.import_key_pair_from_file(name='test-key-pair-2',
key_file_path=key_file_path)
pprint(key_pair)
# Retrieve information about previously created key pair
key_pair = driver.get_key_pair(name='test-key-pair-1')
pprint(key_pair)
# Delete a key pair we have previously created
status = driver.delete_key_pair(key_pair=key_pair)
pprint(status)
3. Security Groups management on Exoscale public cloud¶
Currently there is no security group class defined, hence the result of ex_list_securitry_groups() is a list of dictionaries and not classes.
from pprint import pprint
from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
cls = get_driver(Provider.EXOSCALE)
driver = cls('api key', 'api secret key')
# List all security groups
sg = driver.ex_list_security_groups()
pprint(sg)
# Create a new security group.
security_group = driver.ex_create_security_group(name='test-security-group')
pprint(security_group)
# Authorize an ingress rule on a security group
# If `startport` is used alone, this will be the only port open
# If `endport` is also used then the entire range will be authorized
sg = driver.ex_authorize_security_group_ingress(
securitygroupname='test-security-group', protocol='tcp', startport='22',
cidrlist='0.0.0.0/0'
)
pprint(sg)
# Delete a security group we have previously created
status = driver.ex_delete_security_group(name='test-security-group')
pprint(status)
4. Create a node with a keypair and a list of security groups¶
from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
ACCESS_ID = 'your access id'
SECRET_KEY = 'your secret key'
HOST = 'hostname or ip address of your management server'
PATH = 'path to the api endpoint, e.g: /client/api'
SIZE_ID = 'id of the computer offering you want to use'
IMAGE_ID = 'id of the template you want to use'
# Name of the existing keypair you want to use
KEYPAIR_NAME = 'keypairname'
# The security groups you want this node to be added to
SECURITY_GROUP_NAMES = ['secgroup1', 'secgroup2']
cls = get_driver(Provider.CLOUDSTACK)
driver = cls(key=ACCESS_ID, secret=SECRET_KEY, secure=True,
host=HOST, path=PATH)
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-1', image=image, size=size,
ex_security_groups=SECURITY_GROUP_NAMES,
ex_keyname=KEYPAIR_NAME)
5. Deploying a node with a keypair¶
Executing deployment scripts when creating node is currently only supported in basic zones. The deploy_node method is used instead of the create_node, ssh key are passed as arguments as well as a list of scripts.
from pprint import pprint
from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
# Import the deployment specific modules
from libcloud.compute.deployment import ScriptDeployment
from libcloud.compute.deployment import MultiStepDeployment
cls = get_driver(Provider.EXOSCALE)
driver = cls('api key', 'api secret key')
image = driver.list_images()[0]
size = driver.list_sizes()[0]
# Define the scripts that you want to run during deployment
script = ScriptDeployment('/bin/date')
msd = MultiStepDeployment([script])
node = driver.deploy_node(name='test', image=image, size=size,
ssh_key='~/.ssh/id_rsa_test',
ex_keyname='test-keypair',
deploy=msd)
# The stdout of the deployment can be checked on the `script` object
pprint(script.stdout)
Advanced Zone examples¶
Advanced zones in CloudStack provide tenant isolation via VLANs or SDN technologies like GRE/STT meshes. In a typical advanced zones, users will deploy nodes on a private network and will use NAT to access their nodes. Therefore one needs to specify the network a node needs to be deployed on, and needs to setup port forwarding or IP forwarding rules.
1. Start an interactive shell on Ikoula public cloud¶
Instantiation of driver for an advanced zone is the same as with a basic zone, for example on the ikoula cloud:
import os
# pylint: disable=import-error
from IPython.terminal.embed import InteractiveShellEmbed
from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
apikey = os.getenv('IKOULA_API_KEY')
secretkey = os.getenv('IKOULA_SECRET_KEY')
Driver = get_driver(Provider.IKOULA)
conn = Driver(key=apikey, secret=secretkey)
shell = InteractiveShellEmbed(banner1='Hello from Libcloud Shell !!')
shell()
2. Create a node on a guest network and allocate an IP¶
Starting a node requires a specific guest network.
from pprint import pprint
from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
apikey = 'your api key'
secretkey = 'your secret key'
Driver = get_driver(Provider.IKOULA)
driver = Driver(key=apikey, secret=secretkey)
# This returns a list of CloudStackNetwork objects
nets = driver.ex_list_networks()
# List the images/templates available
# This returns a list of NodeImage objects
images = driver.list_images()
# List the instance types
# This returns a list of NodeSize objects
sizes = driver.list_sizes()
# Create the node
# This returns a Node object
node = driver.create_node(name='libcloud', image=images[0],
size=sizes[0], networks=[nets[0]])
# The node has a private IP in the guest network used
# No public IPs and no rules
pprint(node.extra)
pprint(node.private_ips)
3. List, create and delete a Port forwarding rule¶
To access the node via ssh you need you can create a port forwarding rule like so:
from pprint import pprint
from libcloud.compute.types import Provider
from libcloud.compute.providers import get_driver
cls = get_driver(Provider.EXOSCALE)
driver = cls('api key', 'api secret key')
# Allocate a public IP
# This returns a CloudStackAddress object
driver.ex_allocate_public_ip()
# You can now see this address when listing public IPs
ip = driver.ex_list_public_ips()[0]
node = driver.list_nodes()[0]
# Create a port forwarding rule for the node
# This returns a CloudStackPortForwardingRule object
rule = driver.ex_create_port_forwarding_rule(ip, 22, 22, 'TCP', node)
pprint(rule)
# The node now has a public IP and a rule associated to it
print node
print node.extra
API Docs¶
-
class
libcloud.compute.drivers.cloudstack.
CloudStackNodeDriver
(key, secret=None, secure=True, host=None, path=None, port=None, url=None, *args, **kwargs)[source]¶ Driver for the CloudStack API.
Variables: - host – The host where the API can be reached.
- path – The path where the API can be reached.
- async_poll_frequency – How often (in seconds) to poll for async job completion.
Inherits: NodeDriver.__init__
Parameters: - host (
str
) – The host where the API can be reached. (required) - path (
str
) – The path where the API can be reached. (required) - url (
str
) – Full URL to the API endpoint. Mutually exclusive with host and path argument.
-
attach_volume
(node, volume, device=None)[source]¶ @inherits:
NodeDriver.attach_volume
:type node:CloudStackNode
Return type: bool
-
connectionCls
¶
-
copy_image
(source_region, node_image, name, description=None)¶ Copies an image from a source region to the current region.
Parameters: - source_region (
str
) – Region to copy the node from. - node_image (
NodeImage
:) – NodeImage to copy. - name (
str
) – name for new image. - description – description for new image.
Return type: NodeImage
:Returns: NodeImage instance on success.
- source_region (
-
create_image
(node, name, description=None)¶ Creates an image from a node object.
Parameters: - node (
Node
) – Node to run the task on. - name (
description
) – name for new image. - description – description for new image.
Return type: NodeImage
:Returns: NodeImage instance on success.
- node (
-
create_key_pair
(name, **kwargs)[source]¶ Create a new key pair object.
Parameters: - name (
str
) – Key pair name. - name – Name of the keypair (required)
- projectid (
str
) – An optional project for the ssh key - domainid (
str
) – An optional domainId for the ssh key. If the account parameter is used, domainId must also be used. - account (
str
) – An optional account for the ssh key. Must be used with domainId.
Returns: Created key pair object.
Return type: - name (
-
create_node
(**kwargs)[source]¶ Create a new node
@inherits:
NodeDriver.create_node
Parameters: - networks (
list
ofCloudStackNetwork
) – Optional list of networks to launch the server into. - project (
CloudStackProject
) – Optional project to create the new node under. - diskoffering (
CloudStackDiskOffering
) – Optional disk offering to add to the new node. - ex_keyname (
str
) – Name of existing keypair - ex_userdata (
str
) – String containing user data - ex_security_groups (
list
ofstr
) – List of security groups to assign to the node - ex_displayname (
str
) – String containing instance display name - ex_ip_address (
str
) – String with ipaddress for the default nic - ex_start_vm (
bool
) – Boolean to specify to start VM after creation Default Cloudstack behaviour is to start a VM, if not specified. - ex_rootdisksize (
str
) – String with rootdisksize for the template - ex_affinity_groups (
list
ofCloudStackAffinityGroup
) – List of affinity groups to assign to the node
Return type: - networks (
-
create_volume
(size, name, location=None, snapshot=None, ex_volume_type=None)[source]¶ Creates a data volume Defaults to the first location
-
create_volume_snapshot
(volume, name=None)[source]¶ Create snapshot from volume
Parameters: - volume (
StorageVolume
) – Instance ofStorageVolume
- name (str) – The name of the snapshot is disregarded by CloudStack drivers
Return type: VolumeSnapshot
- volume (
-
delete_image
(node_image)¶ Deletes a node image from a provider.
Parameters: node_image ( NodeImage
) – Node image object.Returns: True
if delete_image was successful,False
otherwise.Return type: bool
-
delete_key_pair
(key_pair, **kwargs)[source]¶ Delete an existing key pair.
Parameters: - key_pair (
libcloud.compute.base.KeyPair
) – Key pair object. - projectid (
str
) – The project associated with keypair - domainid (
str
) – The domain ID associated with the keypair - account (
str
) – The account associated with the keypair. Must be used with the domainId parameter.
Returns: True of False based on success of Keypair deletion
Return type: bool
- key_pair (
-
deploy_node
(**kwargs)¶ Create a new node, and start deployment.
In order to be able to SSH into a created node access credentials are required.
A user can pass either a
NodeAuthPassword
orNodeAuthSSHKey
to theauth
argument. If thecreate_node
implementation supports that kind if credential (as declared inself.features['create_node']
) then it is passed on tocreate_node
. Otherwise it is not passed on tocreate_node
and it is only used for authentication.If the
auth
parameter is not supplied but the driver declares it supportsgenerates_password
then the password returned bycreate_node
will be used to SSH into the server.Finally, if the
ssh_key_file
is supplied that key will be used to SSH into the server.This function may raise a
DeploymentException
, if a create_node call was successful, but there is a later error (like SSH failing or timing out). This exception includes a Node object which you may want to destroy if incomplete deployments are not desirable.>>> from libcloud.compute.drivers.dummy import DummyNodeDriver >>> from libcloud.compute.deployment import ScriptDeployment >>> from libcloud.compute.deployment import MultiStepDeployment >>> from libcloud.compute.base import NodeAuthSSHKey >>> driver = DummyNodeDriver(0) >>> key = NodeAuthSSHKey('...') # read from file >>> script = ScriptDeployment("yum -y install emacs strace tcpdump") >>> msd = MultiStepDeployment([key, script]) >>> def d(): ... try: ... driver.deploy_node(deploy=msd) ... except NotImplementedError: ... print ("not implemented for dummy driver") >>> d() not implemented for dummy driver
Deploy node is typically not overridden in subclasses. The existing implementation should be able to handle most such.
Parameters: - deploy (
Deployment
) – Deployment to run once machine is online and available to SSH. - ssh_username (
str
) – Optional name of the account which is used when connecting to SSH server (default is root) - ssh_alternate_usernames (
list
) – Optional list of ssh usernames to try to connect with if using the default one fails - ssh_port (
int
) – Optional SSH server port (default is 22) - ssh_timeout (
float
) – Optional SSH connection timeout in seconds (default is 10) - auth (
NodeAuthSSHKey
orNodeAuthPassword
) – Initial authentication information for the node (optional) - ssh_key (
str
orlist
ofstr
) – A path (or paths) to an SSH private key with which to attempt to authenticate. (optional) - timeout (
int
) – How many seconds to wait before timing out. (default is 600) - max_tries (
int
) – How many times to retry if a deployment fails before giving up (default is 3) - ssh_interface (
str
) – The interface to wait for. Default is ‘public_ips’, other option is ‘private_ips’.
- deploy (
-
destroy_node
(node, ex_expunge=False)[source]¶ @inherits:
NodeDriver.reboot_node
:type node:CloudStackNode
Parameters: ex_expunge ( bool
) – If true is passed, the vm is expunged immediately. False by default.Return type: bool
-
destroy_volume_snapshot
(snapshot)[source]¶ Destroys a snapshot.
Parameters: snapshot ( VolumeSnapshot
) – The snapshot to deleteReturn type: bool
-
ex_allocate_public_ip
(vpc_id=None, network_id=None, location=None)[source]¶ Allocate a public IP.
Parameters: - vpc_id (
str
) – VPC the ip belongs to - network_id (''str'') – Network where this IP is connected to.
- location (
NodeLocation
) – Zone
Return type: - vpc_id (
-
ex_attach_nic_to_node
(node, network, ip_address=None)[source]¶ Add an extra Nic to a VM
Parameters: - network (:class:'CloudStackNetwork`) – NetworkOffering object
- node (:class:'CloudStackNode`) – Node Object
- ip_address (
str
) – Optional, specific IP for this Nic
Return type: bool
Creates a new Security Group Ingress rule
Parameters: - securitygroupname (
str
) – The name of the security group. Mutually exclusive with securitygroupid. - protocol (
str
) – Can be TCP, UDP or ICMP. Sometime other protocols can be used like AH, ESP or GRE. - cidrlist (
str
) – Source address CIDR for which this rule applies. - startport (
int
) – Start port of the range for this ingress rule. Applies to protocols TCP and UDP. - endport (
int
) – End port of the range for this ingress rule. It can be None to set only one port. Applies to protocols TCP and UDP. - icmptype (
int
) – Type of the ICMP packet (eg: 8 for Echo Request). -1 or None means “all types”. Applies to protocol ICMP. - icmpcode (
int
) – Code of the ICMP packet for the specified type. If the specified type doesn’t require a code set this value to 0. -1 or None means “all codes”. Applies to protocol ICMP. - account (
str
) – An optional account for the security group. Must be used with domainId. - domainid – An optional domainId for the security group. If the account parameter is used, domainId must also be used.
- projectid (
str
) – An optional project of the security group - securitygroupid (
str
) – The ID of the security group. Mutually exclusive with securitygroupname - usersecuritygrouplist (
dict
) – User to security group mapping
Return type: dict
- securitygroupname (
-
ex_change_node_size
(node, offering)[source]¶ Change offering/size of a virtual machine
Parameters: - node (
CloudStackNode
) – Node to change size - offering (
NodeSize
) – The new offering
:rtype
str
- node (
-
ex_create_affinity_group
(name, group_type)[source]¶ Creates a new Affinity Group
Parameters: - name (
str
) – Name of the affinity group - group_type (
CloudStackAffinityGroupType
) – Type of the affinity group from the available affinity/anti-affinity group types - description (
str
) – Optional description of the affinity group - domainid (
str
) – domain ID of the account owning the affinity group
Return type: - name (
-
ex_create_egress_firewall_rule
(network_id, cidr_list, protocol, icmp_code=None, icmp_type=None, start_port=None, end_port=None)[source]¶ Creates a Firewall Rule
Parameters: - network_id (
str
) – the id network network for the egress firewall services - cidr_list (
str
) – cidr list - protocol (
str
) – TCP/IP Protocol (TCP, UDP) - icmp_code (
int
) – Error code for this icmp message - icmp_type (
int
) – Type of the icmp message being sent - start_port (
int
) – start of port range - end_port (
int
) – end of port range
Return type: - network_id (
-
ex_create_firewall_rule
(address, cidr_list, protocol, icmp_code=None, icmp_type=None, start_port=None, end_port=None)[source]¶ Creates a Firewall Rule
Parameters: - address (
CloudStackAddress
) – External IP address - cidr_list (
str
) – cidr list - protocol (
str
) – TCP/IP Protocol (TCP, UDP) - icmp_code (
int
) – Error code for this icmp message - icmp_type (
int
) – Type of the icmp message being sent - start_port (
int
) – start of port range - end_port (
int
) – end of port range
Return type: - address (
-
ex_create_ip_forwarding_rule
(node, address, protocol, start_port, end_port=None)[source]¶ “Add a NAT/firewall forwarding rule.
Parameters: - node (
CloudStackNode
) – Node which should be used - address (
CloudStackAddress
) – CloudStackAddress which should be used - protocol (
str
) – Protocol which should be used (TCP or UDP) - start_port (
int
) – Start port which should be used - end_port (
int
) – End port which should be used
Return type: CloudStackForwardingRule
- node (
-
ex_create_keypair
(name, **kwargs)[source]¶ Creates a SSH KeyPair, returns fingerprint and private key
Parameters: - name (
str
) – Name of the keypair (required) - projectid (
str
) – An optional project for the ssh key - domainid (
str
) – An optional domainId for the ssh key. If the account parameter is used, domainId must also be used. - account (
str
) – An optional account for the ssh key. Must be used with domainId.
Returns: A keypair dictionary
Return type: dict
- name (
-
ex_create_network
(display_text, name, network_offering, location, gateway=None, netmask=None, network_domain=None, vpc_id=None, project_id=None)[source]¶ Creates a Network, only available in advanced zones.
Parameters: - display_text (
str
) – the display text of the network - name (
str
) – the name of the network - network_offering (:class:'CloudStackNetworkOffering`) – NetworkOffering object
- location (
NodeLocation
) – Zone object - gateway (
str
) – Optional, the Gateway of this network - netmask (
str
) – Optional, the netmask of this network - network_domain (
str
) – Optional, the DNS domain of the network - vpc_id (
str
) – Optional, the VPC id the network belongs to - project_id (
str
) – Optional, the project id the networks belongs to
Return type: - display_text (
-
ex_create_network_acl
(protocol, acl_id, cidr_list, start_port, end_port, action=None, traffic_type=None)[source]¶ Creates an ACL rule in the given network (the network has to belong to VPC)
Parameters: - protocol (
string
) – the protocol for the ACL rule. Valid values are TCP/UDP/ICMP/ALL or valid protocol number - acl_id (
str
) – Name of the network ACL List - cidr_list (
str
) – the cidr list to allow traffic from/to - start_port (
str
) – the starting port of ACL - end_port (
str
) – the ending port of ACL - action (
str
) – scl entry action, allow or deny - traffic_type (
str
) – the traffic type for the ACL,can be Ingress or Egress, defaulted to Ingress if not specified
Return type: - protocol (
-
ex_create_network_acllist
(name, vpc_id, description=None)[source]¶ Create an ACL List for a network within a VPC.
Parameters: - name (
string
) – Name of the network ACL List - vpc_id (
string
) – Id of the VPC associated with this network ACL List - description (
string
) – Description of the network ACL List
Return type: - name (
-
ex_create_port_forwarding_rule
(node, address, private_port, public_port, protocol, public_end_port=None, private_end_port=None, openfirewall=True, network_id=None)[source]¶ Creates a Port Forwarding Rule, used for Source NAT
Parameters: - address (
CloudStackAddress
) – IP address of the Source NAT - private_port (
int
) – Port of the virtual machine - protocol (
str
) – Protocol of the rule - public_port (
int
) – Public port on the Source NAT address - node (
CloudStackNode
) – The virtual machine - network_id (
string
) – The network of the vm the Port Forwarding rule will be created for. Required when public Ip address is not associated with any Guest network yet (VPC case)
Return type: - address (
-
ex_create_security_group
(name, **kwargs)[source]¶ Creates a new Security Group
Parameters: - name (
str
) – name of the security group (required) - account (
str
) – An optional account for the security group. Must be used with domainId. - domainid (
str
) – An optional domainId for the security group. If the account parameter is used, domainId must also be used. - description (
str
) – The description of the security group - projectid (
str
) – Deploy vm for the project
Return type: dict
- name (
-
ex_create_snapshot_template
(snapshot, name, ostypeid, displaytext=None)[source]¶ Create a template from a snapshot
Parameters: - snapshot – Instance of
VolumeSnapshot
- name (
str
) – the name of the template - name – the os type id
- name – the display name of the template
Return type: NodeImage
- snapshot – Instance of
Create tags for a resource (Node/StorageVolume/etc). A list of resource types can be found at http://goo.gl/6OKphH
Parameters: - resource_ids (
list
of resource IDs) – Resource IDs to be tagged. The resource IDs must all be associated with the resource_type. For example, for virtual machines (UserVm) you can only specify a list of virtual machine IDs. - resource_type (
str
) – Resource type (eg: UserVm) - tags (
dict
) – A dictionary or other mapping of strings to strings, associating tag names with tag values.
Return type: bool
- resource_ids (
-
ex_create_vpc
(cidr, display_text, name, vpc_offering, zone_id, network_domain=None)[source]¶ Creates a VPC, only available in advanced zones.
Parameters: - cidr – the cidr of the VPC. All VPC guest networks’ cidrs should be within this CIDR
- display_text (
str
) – the display text of the VPC - name (
str
) – the name of the VPC - vpc_offering (:class:'CloudStackVPCOffering`) – the ID of the VPC offering
- zone_id (
str
) – the ID of the availability zone - network_domain (
str
) – Optional, the DNS domain of the network
Return type:
-
ex_create_vpn_connection
(vpn_customer_gateway, vpn_gateway, for_display=None, passive=None)[source]¶ Creates a VPN Connection.
Parameters: - vpn_customer_gateway (
CloudStackVpnCustomerGateway
) – The VPN Customer Gateway (required). - vpn_gateway (
CloudStackVpnGateway
) – The VPN Gateway (required). - for_display (
str
) – Display the Connection to the end user or not. - passive (
bool
) – If True, sets the connection to be passive.
Return type: class: CloudStackVpnConnection - vpn_customer_gateway (
-
ex_create_vpn_customer_gateway
(cidr_list, esp_policy, gateway, ike_policy, ipsec_psk, account=None, domain_id=None, dpd=None, esp_lifetime=None, ike_lifetime=None, name=None)[source]¶ Creates a VPN Customer Gateway.
Parameters: - cidr_list (
str
) – Guest CIDR list of the Customer Gateway (required). - esp_policy (
str
) – ESP policy of the Customer Gateway (required). - gateway (
str
) – Public IP address of the Customer Gateway (required). - ike_policy (
str
) – IKE policy of the Customer Gateway (required). - ipsec_psk (
str
) – IPsec preshared-key of the Customer Gateway (required). - account (
str
) – The associated account with the Customer Gateway (must be used with the domain_id param). - domain_id (
str
) – The domain ID associated with the Customer Gateway. If used with the account parameter returns the gateway associated with the account for the specified domain. - dpd (
bool
) – If DPD is enabled for the VPN connection. - esp_lifetime (
int
) – Lifetime of phase 2 VPN connection to the Customer Gateway, in seconds. - ike_lifetime (
int
) – Lifetime of phase 1 VPN connection to the Customer Gateway, in seconds. - name (
str
) – Name of the Customer Gateway.
Return type: class: CloudStackVpnCustomerGateway - cidr_list (
-
ex_create_vpn_gateway
(vpc, for_display=None)[source]¶ Creates a VPN Gateway.
Parameters: - vpc – VPC to create the Gateway for (required).
- for_display (
bool
) – Display the VPC to the end user or not.
Return type: class: CloudStackVpnGateway
-
ex_delete_affinity_group
(affinity_group)[source]¶ Delete an Affinity Group
Parameters: affinity_group ( CloudStackAffinityGroup
) – Instance of affinity group:rtype
bool
-
ex_delete_egress_firewall_rule
(firewall_rule)[source]¶ Remove a Firewall rule.
Parameters: egress_firewall_rule ( CloudStackEgressFirewallRule
) – Firewall rule which should be usedReturn type: bool
-
ex_delete_firewall_rule
(firewall_rule)[source]¶ Remove a Firewall Rule.
Parameters: firewall_rule ( CloudStackFirewallRule
) – Firewall rule which should be usedReturn type: bool
-
ex_delete_ip_forwarding_rule
(node, rule)[source]¶ Remove a NAT/firewall forwarding rule.
Parameters: - node (
CloudStackNode
) – Node which should be used - rule (
CloudStackForwardingRule
) – Forwarding rule which should be used
Return type: bool
- node (
-
ex_delete_keypair
(keypair, **kwargs)[source]¶ Deletes an existing SSH KeyPair
Parameters: - keypair (
str
) – Name of the keypair (required) - projectid (
str
) – The project associated with keypair - domainid (
str
) – The domain ID associated with the keypair - account (
str
) – The account associated with the keypair. Must be used with the domainId parameter.
Returns: True of False based on success of Keypair deletion
Return type: bool
- keypair (
-
ex_delete_network
(network, force=None)[source]¶ Deletes a Network, only available in advanced zones.
Parameters: - network – The network
- force (
bool
) – Force deletion of the network?
Return type: bool
-
ex_delete_port_forwarding_rule
(node, rule)[source]¶ Remove a Port forwarding rule.
Parameters: - node (
CloudStackNode
) – Node used in the rule - rule (
CloudStackPortForwardingRule
) – Forwarding rule which should be used
Return type: bool
- node (
-
ex_delete_security_group
(name)[source]¶ Deletes a given Security Group
Parameters: - domainid (
str
) – The domain ID of account owning the security group - id (
str
) – The ID of the security group. Mutually exclusive with name parameter - name (
str
) – The ID of the security group. Mutually exclusive with id parameter - account (
str
) – The account of the security group. Must be specified with domain ID - projectid (
str
) – The project of the security group
Return type: bool
- domainid (
Delete tags from a resource.
Parameters: - resource_ids (
list
of resource IDs) – Resource IDs to be tagged. The resource IDs must all be associated with the resource_type. For example, for virtual machines (UserVm) you can only specify a list of virtual machine IDs. - resource_type (
str
) – Resource type (eg: UserVm) - tag_keys (
list
) – A list of keys to delete. CloudStack only requires the keys from the key/value pair.
Return type: bool
- resource_ids (
-
ex_delete_vpc
(vpc)[source]¶ Deletes a VPC, only available in advanced zones.
Parameters: vpc – The VPC Return type: bool
-
ex_delete_vpn_connection
(vpn_connection)[source]¶ Deletes a VPN Connection.
Parameters: vpn_connection ( CloudStackVpnConnection
) – The VPN Connection (required).Return type: bool
-
ex_delete_vpn_customer_gateway
(vpn_customer_gateway)[source]¶ Deletes a VPN Customer Gateway.
Parameters: vpn_customer_gateway ( CloudStackVpnCustomerGateway
) – The VPN Customer Gateway (required).Return type: bool
-
ex_delete_vpn_gateway
(vpn_gateway)[source]¶ Deletes a VPN Gateway.
Parameters: vpn_gateway ( CloudStackVpnGateway
) – The VPN Gateway (required).Return type: bool
-
ex_detach_nic_from_node
(nic, node)[source]¶ Remove Nic from a VM
Parameters: - nic (:class:'CloudStackNetwork`) – Nic object
- node (:class:'CloudStackNode`) – Node Object
Return type: bool
-
ex_get_node
(node_id, project=None)[source]¶ Return a Node object based on its ID.
Parameters: - node_id (
str
) – The id of the node - project (
CloudStackProject
) – Limit node returned to those configured under the defined project.
Return type: - node_id (
-
ex_get_volume
(volume_id, project=None)[source]¶ Return a StorageVolume object based on its ID.
Parameters: - volume_id (
str
) – The id of the volume - project (
CloudStackProject
) – Limit volume returned to those configured under the defined project.
Return type: - volume_id (
-
ex_import_keypair
(name, keyfile)[source]¶ Imports a new public key where the public key is passed via a filename
Parameters: - name (
str
) – The name of the public key to import. - keyfile (
str
) – The filename with path of the public key to import.
Return type: dict
- name (
-
ex_import_keypair_from_string
(name, key_material)[source]¶ Imports a new public key where the public key is passed in as a string
Parameters: - name (
str
) – The name of the public key to import. - key_material (
str
) – The contents of a public key file.
Return type: dict
- name (
-
ex_limits
()[source]¶ Extra call to get account’s resource limits, such as the amount of instances, volumes, snapshots and networks.
CloudStack uses integers as the resource type so we will convert them to a more human readable string using the resource map
A list of the resource type mappings can be found at http://goo.gl/17C6Gk
Returns: dict Return type: dict
-
ex_list_affinity_group_types
()[source]¶ List Affinity Group Types
:rtype
list
ofCloudStackAffinityGroupTypes
-
ex_list_affinity_groups
()[source]¶ List Affinity Groups
:rtype
list
ofCloudStackAffinityGroup
-
ex_list_disk_offerings
()[source]¶ Fetch a list of all available disk offerings.
Return type: list
ofCloudStackDiskOffering
-
ex_list_egress_firewall_rules
()[source]¶ Lists all egress Firewall Rules
Return type: list
ofCloudStackEgressFirewallRule
-
ex_list_firewall_rules
()[source]¶ Lists all Firewall Rules
Return type: list
ofCloudStackFirewallRule
-
ex_list_ip_forwarding_rules
(account=None, domain_id=None, id=None, ipaddress_id=None, is_recursive=None, keyword=None, list_all=None, page=None, page_size=None, project_id=None, virtualmachine_id=None)[source]¶ Lists all NAT/firewall forwarding rules
Parameters: - account (
str
) – List resources by account. Must be used with the domainId parameter - domain_id (
str
) – List only resources belonging to the domain specified - id (
str
) – Lists rule with the specified ID - ipaddress_id (
str
) – list the rule belonging to this public ip address - is_recursive (
bool
) – Defaults to false, but if true, lists all resources from the parent specified by the domainId till leaves. - keyword (
str
) – List by keyword - list_all (
bool
) – If set to false, list only resources belonging to the command’s caller; if set to true - list resources that the caller is authorized to see. Default value is false - page (
int
) – The page to list the keypairs from - page_size (
int
) – The number of results per page - project_id (
str
) – list objects by project - virtualmachine_id (
str
) – Lists all rules applied to the specified Vm
Return type: list
ofCloudStackIPForwardingRule
- account (
-
ex_list_keypairs
(**kwargs)[source]¶ List Registered SSH Key Pairs
Parameters: - projectid (
str
) – list objects by project - page (
int
) – The page to list the keypairs from - keyword (
str
) – List by keyword - listall (
bool
) – If set to false, list only resources belonging to the command’s caller; if set to true - list resources that the caller is authorized to see. Default value is false - pagesize (
int
) – The number of results per page - account (
str
) – List resources by account. Must be used with the domainId parameter - isrecursive (
bool
) – Defaults to false, but if true, lists all resources from the parent specified by the domainId till leaves. - fingerprint (
str
) – A public key fingerprint to look for - name (
str
) – A key pair name to look for - domainid (
str
) – List only resources belonging to the domain specified
Returns: A list of keypair dictionaries
Return type: list
ofdict
- projectid (
-
ex_list_network_acl
()[source]¶ Lists all network ACL items
Return type: list
ofCloudStackNetworkACL
-
ex_list_network_acllists
()[source]¶ Lists all network ACLs
Return type: list
ofCloudStackNetworkACLList
-
ex_list_network_offerings
()[source]¶ List the available network offerings
:rtype
list
ofCloudStackNetworkOffering
-
ex_list_networks
(project=None)[source]¶ List the available networks
Parameters: project ( CloudStackProject
) – Optional project the networks belongs to.:rtype
list
ofCloudStackNetwork
-
ex_list_nics
(node)[source]¶ List the available networks
Parameters: vm (:class:`CloudStackNode) – Node Object :rtype
list
ofCloudStackNic
-
ex_list_os_types
()[source]¶ List all registered os types (needed for snapshot creation)
Return type: list
-
ex_list_port_forwarding_rules
(account=None, domain_id=None, id=None, ipaddress_id=None, is_recursive=None, keyword=None, list_all=None, network_id=None, page=None, page_size=None, project_id=None)[source]¶ Lists all Port Forwarding Rules
Parameters: - account (
str
) – List resources by account. Must be used with the domainId parameter - domain_id (
str
) – List only resources belonging to the domain specified - for_display (
bool
) – List resources by display flag (only root admin is eligible to pass this parameter). - id (
str
) – Lists rule with the specified ID - ipaddress_id (
str
) – list the rule belonging to this public ip address - is_recursive (
bool
) – Defaults to false, but if true, lists all resources from the parent specified by the domainId till leaves. - keyword (
str
) – List by keyword - list_all (
bool
) – If set to false, list only resources belonging to the command’s caller; if set to true - list resources that the caller is authorized to see. Default value is false - network_id (
string
) – list port forwarding rules for certain network - page (
int
) – The page to list the keypairs from - page_size (
int
) – The number of results per page - project_id (
str
) – list objects by project
Return type: list
ofCloudStackPortForwardingRule
- account (
-
ex_list_projects
()[source]¶ List the available projects
:rtype
list
ofCloudStackProject
-
ex_list_public_ips
()[source]¶ Lists all Public IP Addresses.
Return type: list
ofCloudStackAddress
-
ex_list_routers
(vpc_id=None)[source]¶ List routers
:rtype
list
ofCloudStackRouter
-
ex_list_security_groups
(**kwargs)[source]¶ Lists Security Groups
Parameters: - domainid (
str
) – List only resources belonging to the domain specified - account (
str
) – List resources by account. Must be used with the domainId parameter. - listall (
bool
) – If set to false, list only resources belonging to the command’s caller; if set to true list resources that the caller is authorized to see. Default value is false - pagesize (
int
) – Number of entries per page - keyword (
str
) – List by keyword - tags (
dict
) – List resources by tags (key/value pairs) - id (
str
) – list the security group by the id provided - securitygroupname (
str
) – lists security groups by name - virtualmachineid (
str
) – lists security groups by virtual machine id - projectid (
str
) – list objects by project - isrecursive (
bool
) – (boolean) defaults to false, but if true, lists all resources from the parent specified by the domainId till leaves. - page (
int
) – (integer)
:rtype
list
- domainid (
-
ex_list_vpc_offerings
()[source]¶ List the available vpc offerings
:rtype
list
ofCloudStackVPCOffering
-
ex_list_vpcs
(project=None)[source]¶ List the available VPCs
Parameters: project ( CloudStackProject
) – Optional project under which VPCs are present.:rtype
list
ofCloudStackVPC
-
ex_list_vpn_connections
(account=None, domain_id=None, for_display=None, id=None, is_recursive=None, keyword=None, list_all=None, page=None, page_size=None, project_id=None, vpc_id=None)[source]¶ List VPN Connections.
Parameters: - account (
str
) – List resources by account (must be used with the domain_id parameter). - domain_id (
str
) – List only resources belonging to the domain specified. - for_display (
bool
) – List resources by display flag (only root admin is eligible to pass this parameter). - id (
str
) – ID of the VPN Connection. - is_recursive (
bool
) – Defaults to False, but if true, lists all resources from the parent specified by the domain_id till leaves. - keyword (
str
) – List by keyword. - list_all (
str
) – If set to False, list only resources belonging to the command’s caller; if set to True - list resources that the caller is authorized to see. Default value is False. - page (
int
) – Start from page. - page_size (
int
) – Items per page. - project_id (
str
) – List objects by project. - vpc_id (
str
) – List objects by VPC.
Return type: list
ofCloudStackVpnConnection
- account (
-
ex_list_vpn_customer_gateways
(account=None, domain_id=None, id=None, is_recursive=None, keyword=None, list_all=None, page=None, page_size=None, project_id=None)[source]¶ List VPN Customer Gateways.
Parameters: - account (
str
) – List resources by account (must be used with the domain_id parameter). - domain_id (
str
) – List only resources belonging to the domain specified. - id (
str
) – ID of the VPN Customer Gateway. - is_recursive (
bool
) – Defaults to False, but if true, lists all resources from the parent specified by the domain_id till leaves. - keyword (
str
) – List by keyword. - list_all (
str
) – If set to False, list only resources belonging to the command’s caller; if set to True - list resources that the caller is authorized to see. Default value is False. - page (
int
) – Start from page. - page_size (
int
) – Items per page. - project_id (
str
) – List objects by project.
Return type: list
ofCloudStackVpnCustomerGateway
- account (
-
ex_list_vpn_gateways
(account=None, domain_id=None, for_display=None, id=None, is_recursive=None, keyword=None, list_all=None, page=None, page_size=None, project_id=None, vpc_id=None)[source]¶ List VPN Gateways.
Parameters: - account (
str
) – List resources by account (must be used with the domain_id parameter). - domain_id (
str
) – List only resources belonging to the domain specified. - for_display (
bool
) – List resources by display flag (only root admin is eligible to pass this parameter). - id (
str
) – ID of the VPN Gateway. - is_recursive (
bool
) – Defaults to False, but if true, lists all resources from the parent specified by the domain ID till leaves. - keyword (
str
) – List by keyword. - list_all (
str
) – If set to False, list only resources belonging to the command’s caller; if set to True - list resources that the caller is authorized to see. Default value is False. - page (
int
) – Start from page. - page_size (
int
) – Items per page. - project_id (
str
) – List objects by project. - vpc_id (
str
) – List objects by VPC.
Return type: list
ofCloudStackVpnGateway
- account (
-
ex_register_iso
(name, url, location=None, **kwargs)[source]¶ Registers an existing ISO by URL.
Parameters: - name (
str
) – Name which should be used - url (
str
) – Url should be used - location (
NodeLocation
) – Location which should be used
Return type: str
- name (
-
ex_release_public_ip
(address)[source]¶ Release a public IP.
Parameters: address ( CloudStackAddress
) – CloudStackAddress which should be usedReturn type: bool
-
ex_replace_network_acllist
(acl_id, network_id)[source]¶ Create an ACL List for a network within a VPC.Replaces ACL associated with a Network or private gateway
Parameters: - acl_id (
string
) – the ID of the network ACL - network_id (
string
) – the ID of the network
Return type: - acl_id (
-
ex_restore
(node, template=None)[source]¶ Restore virtual machine
Parameters: - node (
CloudStackNode
) – Node to restore - template (
NodeImage
) – Optional new template
:rtype
str
- node (
-
ex_revoke_security_group_ingress
(rule_id)[source]¶ Revoke/delete an ingress security rule
Parameters: id ( str
) – The ID of the ingress security ruleReturn type: bool
-
ex_start
(node)[source]¶ Starts/Resumes a stopped virtual machine
Parameters: - id (
str
) – The ID of the virtual machine (required) - hostid (
str
) – destination Host ID to deploy the VM to parameter available for root admin only
:rtype
str
- id (
-
ex_stop
(node)[source]¶ Stops/Suspends a running virtual machine
Parameters: node ( CloudStackNode
) – Node to stop.Return type: str
-
ex_update_node_affinity_group
(node, affinity_group_list)[source]¶ Updates the affinity/anti-affinity group associations of a virtual machine. The VM has to be stopped and restarted for the new properties to take effect.
Parameters: - node (
CloudStackNode
) – Node to update. - affinity_group_list (
list
ofCloudStackAffinityGroup
) – List of CloudStackAffinityGroup to associate
:rtype
CloudStackNode
- node (
-
get_image
(image_id)¶ Returns a single node image from a provider.
Parameters: image_id ( str
) – Node to run the task on.:rtype
NodeImage
: :return: NodeImage instance on success.
-
get_key_pair
(name)[source]¶ Retrieve a single key pair.
Parameters: name ( str
) – Name of the key pair to retrieve.Return type: KeyPair
-
import_key_pair_from_file
(name, key_file_path)¶ Import a new public key from string.
Parameters: - name (
str
) – Key pair name. - key_file_path (
str
) – Path to the public key file.
Return type: KeyPair
object- name (
-
import_key_pair_from_string
(name, key_material)[source]¶ Import a new public key from string.
Parameters: - name (
str
) – Key pair name. - key_material (
str
) – Public key material.
Returns: Imported key pair object.
Return type: - name (
-
list_images
(location=None)[source]¶ List images on a provider.
Parameters: location ( NodeLocation
) – The location at which to list images.Returns: list of node image objects. Return type: list
ofNodeImage
-
list_key_pairs
(**kwargs)[source]¶ List registered key pairs.
Parameters: - projectid (
str
) – list objects by project - page (
int
) – The page to list the keypairs from - keyword (
str
) – List by keyword - listall (
bool
) – If set to false, list only resources belonging to the command’s caller; if set to true - list resources that the caller is authorized to see. Default value is false - pagesize (
int
) – The number of results per page - account (
str
) – List resources by account. Must be used with the domainId parameter - isrecursive (
bool
) – Defaults to false, but if true, lists all resources from the parent specified by the domainId till leaves. - fingerprint (
str
) – A public key fingerprint to look for - name (
str
) – A key pair name to look for - domainid (
str
) – List only resources belonging to the domain specified
Returns: A list of key par objects.
Return type: list
oflibcloud.compute.base.KeyPair
- projectid (
-
list_nodes
(project=None, location=None)[source]¶ @inherits:
NodeDriver.list_nodes
Parameters: - project (
CloudStackProject
) – Limit nodes returned to those configured under the defined project. - location (
NodeLocation
) – Limit nodes returned to those in the defined location.
Return type: list
ofCloudStackNode
- project (
-
list_volume_snapshots
(volume)¶ List snapshots for a storage volume.
Return type: list
ofVolumeSnapshot
-
list_volumes
(node=None)[source]¶ List all volumes
Parameters: node ( CloudStackNode
) – Only return volumes for the provided node.Return type: list
ofStorageVolume
-
reboot_node
(node)[source]¶ @inherits:
NodeDriver.reboot_node
:type node:CloudStackNode
Return type: bool
-
wait_until_running
(nodes, wait_period=3, timeout=600, ssh_interface='public_ips', force_ipv4=True, ex_list_nodes_kwargs=None)¶ Block until the provided nodes are considered running.
Node is considered running when it’s state is “running” and when it has at least one IP address assigned.
Parameters: - nodes (
list
ofNode
) – List of nodes to wait for. - wait_period (
int
) – How many seconds to wait between each loop iteration. (default is 3) - timeout (
int
) – How many seconds to wait before giving up. (default is 600) - ssh_interface (
str
) – Which attribute on the node to use to obtain an IP address. Valid options: public_ips, private_ips. Default is public_ips. - force_ipv4 (
bool
) – Ignore IPv6 addresses (default is True). - ex_list_nodes_kwargs (
dict
) – Optional driver-specific keyword arguments which are passed to thelist_nodes
method.
Returns: [(Node, ip_addresses)]
list of tuple of Node instance and list of ip_address on success.Return type: list
oftuple
- nodes (