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. .. figure:: /_static/images/provider_logos/cloudstack.png :align: center :width: 300 :target: http://cloudstack.apache.org `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 ``http://localhost:8080/client/api``) * ``path`` - The path to your CloudStack endpoint (e.g ``/client/api`` for ``http://localhost:8080/client/api``) * ``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: .. literalinclude:: /examples/compute/cloudstack/instantiate_driver_host_path.py :language: python A complete ``url`` can be used instead: .. literalinclude:: /examples/compute/cloudstack/instantiate_driver_url.py :language: python 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 .. literalinclude:: /examples/compute/cloudstack/instantiate_driver_insecure_port.py :language: python 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: .. literalinclude:: /examples/compute/cloudstack/turn_off_ssl_verification.py :language: python For more information on how SSL certificate validation works in Libcloud, see the :doc:`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 .. compound:: 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. literalinclude:: /examples/compute/cloudstack/start_interactive_shell_exoscale.py :language: python 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. .. literalinclude:: /examples/compute/cloudstack/ssh_keypairs_management_exoscale.py :language: python 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. .. literalinclude:: /examples/compute/cloudstack/security_groups_management.py :language: python 4. Create a node with a keypair and a list of security groups ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. literalinclude:: /examples/compute/cloudstack/create_cloudstack_node_keypair_secgroup.py :language: python 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. .. literalinclude:: /examples/compute/cloudstack/deploy_node_with_keypair_security_group.py :language: python 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: .. literalinclude:: /examples/compute/cloudstack/start_interactive_shell_ikoula.py :language: python 2. Create a node on a guest network and allocate an IP ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Starting a node requires a specific guest network. .. literalinclude:: /examples/compute/cloudstack/create_node_advanced_zone.py :language: python 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: .. literalinclude:: /examples/compute/cloudstack/port_forwarding_management.py :language: python API Docs -------- .. autoclass:: libcloud.compute.drivers.cloudstack.CloudStackNodeDriver :members: :inherited-members: .. _`CloudStack`: http://cloudstack.apache.org .. _`API`: http://cloudstack.apache.org/docs/api/ .. _`exoscale`: https://www.exoscale.ch/ .. _`ikoula`: http://www.ikoula.com/