CloudStack Compute Driver Documentation — Apache Libcloud 3.8.0 documentation

CloudStack Compute Driver Documentation — Apache Libcloud 3.8.0 documentation
Docs
CloudStack Compute Driver Documentation
View page source
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 key
secret
- Your CloudStack secret key
host
- The host of your CloudStack endpoint
(e.g
localhost
for
path
- The path to your CloudStack endpoint
(e.g
/client/api
for
url
- The url to your CloudStack endpoint, mutually exclusive with
host
and
path
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
for
in
sizes
if
id
==
SIZE_ID
][
image
for
in
images
if
id
==
IMAGE_ID
][
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
MultiStepDeployment
cls
get_driver
Provider
EXOSCALE
driver
cls
"api key"
"api secret key"
image
driver
list_images
()[
size
driver
list_sizes
()[
# 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
],
size
sizes
],
networks
nets
]])
# 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
()[
node
driver
list_nodes
()[
# 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
node
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
alias of
libcloud.common.cloudstack.CloudStackConnection
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.
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.
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:
libcloud.compute.base.KeyPair
create_node
name
size
image
location=None
networks=None
project=None
diskoffering=None
ex_keyname=None
ex_userdata=None
ex_security_groups=None
ex_displayname=None
ex_ip_address=None
ex_start_vm=False
ex_rootdisksize=None
ex_affinity_groups=None
[source]
Create a new node
@inherits:
NodeDriver.create_node
Parameters:
networks
list
of
CloudStackNetwork
) – 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
of
str
) – 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
of
CloudStackAffinityGroup
) – List of affinity groups to assign to
the node
Return type:
CloudStackNode
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 of
StorageVolume
name
str
) – The name of the snapshot is disregarded
by CloudStack drivers
Return type:
VolumeSnapshot
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
deploy_node
deploy
ssh_username='root'
ssh_alternate_usernames=None
ssh_port=22
ssh_timeout=10
ssh_key=None
ssh_key_password=None
auth=None
timeout=300
max_tries=3
ssh_interface='public_ips'
at_exit_func=None
wait_period=5
**create_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
or
NodeAuthSSHKey
to the
auth
argument. If the
create_node
implementation supports that kind if credential (as
declared in
self.features['create_node']
) then it is passed on to
create_node
. Otherwise it is not passed on to
create_node
and
it is only used for authentication.
If the
auth
parameter is not supplied but the driver declares it
supports
generates_password
then the password returned by
create_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
>>>
key
NodeAuthSSHKey
'...'
# read from file
>>>
script
ScriptDeployment
"yum -y install emacs strace tcpdump"
>>>
msd
MultiStepDeployment
([
key
script
])
>>>
def
():
...
try
...
driver
deploy_node
deploy
msd
...
except
NotImplementedError
...
"not implemented for dummy driver"
>>>
()
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
or
NodeAuthPassword
) – Initial authentication information for the node
(optional)
ssh_key
str
or
list
of
str
) – A path (or paths) to an SSH private key with which
to attempt to authenticate. (optional)
ssh_key_password
str
) – Optional password used for encrypted keys.
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’.
at_exit_func
func
) –
Optional atexit handler function which will be
registered and called with created node if user
cancels the deploy process (e.g. CTRL+C), after
the node has been created, but before the deploy
process has finished.
This method gets passed in two keyword arguments:
driver -> node driver in question
node -> created Node object
Keep in mind that this function will only be
called in such scenario. In case the method
finishes (this includes throwing an exception),
at exit handler function won’t be called.
wait_period
int
) – How many seconds to wait between each iteration
while waiting for node to transition into
running state and have IP assigned. (default is 5)
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
volume
[source]
Return type:
bool
destroy_volume_snapshot
snapshot
[source]
Destroys a snapshot.
Parameters:
snapshot
VolumeSnapshot
) – The snapshot to delete
Return type:
bool
detach_volume
volume
[source]
Return 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:
CloudStackAddress
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
ex_authorize_security_group_ingress
securitygroupname
protocol
cidrlist
startport=None
endport=None
icmptype=None
icmpcode=None
**kwargs
[source]
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
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
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:
CloudStackAffinityGroup
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:
CloudStackEgressFirewallRule
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:
CloudStackFirewallRule
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
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
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:
CloudStackNetwork
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:
CloudStackNetworkACL
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:
CloudStackNetworkACLList
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:
CloudStackPortForwardingRule
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
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
ex_create_tags
resource_ids
resource_type
tags
[source]
Create tags for a resource (Node/StorageVolume/etc).
A list of resource types can be found at
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
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:
CloudStackVPC
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
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
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 used
Return type:
bool
ex_delete_firewall_rule
firewall_rule
[source]
Remove a Firewall Rule.
Parameters:
firewall_rule
CloudStackFirewallRule
) – Firewall rule which should be used
Return 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
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
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
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
ex_delete_tags
resource_ids
resource_type
tag_keys
[source]
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
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:
CloudStackNode
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:
CloudStackNode
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
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
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
Returns:
dict
Return type:
dict
ex_list_affinity_group_types
[source]
List Affinity Group Types
:rtype
list
of
CloudStackAffinityGroupTypes
ex_list_affinity_groups
[source]
List Affinity Groups
:rtype
list
of
CloudStackAffinityGroup
ex_list_disk_offerings
[source]
Fetch a list of all available disk offerings.
Return type:
list
of
CloudStackDiskOffering
ex_list_egress_firewall_rules
[source]
Lists all egress Firewall Rules
Return type:
list
of
CloudStackEgressFirewallRule
ex_list_firewall_rules
[source]
Lists all Firewall Rules
Return type:
list
of
CloudStackFirewallRule
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
of
CloudStackIPForwardingRule
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
of
dict
ex_list_network_acl
[source]
Lists all network ACL items
Return type:
list
of
CloudStackNetworkACL
ex_list_network_acllists
[source]
Lists all network ACLs
Return type:
list
of
CloudStackNetworkACLList
ex_list_network_offerings
[source]
List the available network offerings
:rtype
list
of
CloudStackNetworkOffering
ex_list_networks
project=None
[source]
List the available networks
Parameters:
project
CloudStackProject
) – Optional project the networks belongs to.
:rtype
list
of
CloudStackNetwork
ex_list_nics
node
[source]
List the available networks
Parameters:
vm
(:class:
CloudStackNode) – Node Object
:rtype
list
of
CloudStackNic
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
of
CloudStackPortForwardingRule
ex_list_projects
[source]
List the available projects
:rtype
list
of
CloudStackProject
ex_list_public_ips
[source]
Lists all Public IP Addresses.
Return type:
list
of
CloudStackAddress
ex_list_routers
vpc_id=None
[source]
List routers
:rtype
list
of
CloudStackRouter
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
ex_list_vpc_offerings
[source]
List the available vpc offerings
:rtype
list
of
CloudStackVPCOffering
ex_list_vpcs
project=None
[source]
List the available VPCs
Parameters:
project
CloudStackProject
) – Optional project under which VPCs are present.
:rtype
list
of
CloudStackVPC
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
of
CloudStackVpnConnection
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
of
CloudStackVpnCustomerGateway
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
of
CloudStackVpnGateway
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
ex_release_public_ip
address
[source]
Release a public IP.
Parameters:
address
CloudStackAddress
) – CloudStackAddress which should be used
Return 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:
CloudStackNetworkACLList
ex_restore
node
template=None
[source]
Restore virtual machine
Parameters:
node
CloudStackNode
) – Node to restore
template
NodeImage
) – Optional new template
:rtype
str
ex_revoke_security_group_ingress
rule_id
[source]
Revoke/delete an ingress security rule
Parameters:
id
str
) – The ID of the ingress security rule
Return 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
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
of
CloudStackAffinityGroup
) – List of CloudStackAffinityGroup to
associate
:rtype
CloudStackNode
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
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:
libcloud.compute.base.KeyPair
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
of
NodeImage
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
of
libcloud.compute.base.KeyPair
list_locations
[source]
:rtype
list
of
NodeLocation
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
of
CloudStackNode
list_sizes
location=None
[source]
:rtype
list
of
NodeSize
list_snapshots
[source]
Describe all snapshots.
Return type:
list
of
VolumeSnapshot
list_volume_snapshots
volume
List snapshots for a storage volume.
Return type:
list
of
VolumeSnapshot
list_volumes
node=None
[source]
List all volumes
Parameters:
node
CloudStackNode
) – Only return volumes for the provided node.
Return type:
list
of
StorageVolume
reboot_node
node
[source]
@inherits:
NodeDriver.reboot_node
:type node:
CloudStackNode
Return type:
bool
start_node
node
Start a node.
Parameters:
node
Node
) – The node to be started
Returns:
True if the start was successful, otherwise False
Return type:
bool
stop_node
node
Stop a node
Parameters:
node
Node
) – The node to be stopped.
Returns:
True if the stop was successful, otherwise False
Return type:
bool
wait_until_running
nodes
wait_period=5
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
of
Node
) – 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 the
list_nodes
method.
Returns:
[(Node,
ip_addresses)]
list of tuple of Node instance and
list of ip_address on success.
Return type:
list
of
tuple