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 </other/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/