docs/compute/drivers/upcloud.rst

UpCloud Driver Documentation
===============================
`UpCloud`_ is a Finnish IaaS provider offering high performance servers
from data centers based in multiple countries.

.. figure:: /_static/images/provider_logos/upcloud.png
    :align: center
    :width: 300
    :target: https://upcloud.com/

UpCloud currently operates globally from eight (8) data centers:

* Amsterdam, Netherlands
* Chicago, USA
* Frankfurt, Germany
* Helsinki 1, Finland
* Helsinki 2, Finland
* London, UK
* San Jose, USA
* Singapore, Singapore

This driver uses the UpCloud API 1.3 endpoints.

Firewall rules
--------------

UpCloud manages network access through per-server firewall rules instead of
reusable security groups. The driver exposes those rules through extension
methods:

* ``ex_list_firewall_rules(node)``
* ``ex_get_firewall_rule(node, position)``
* ``ex_create_firewall_rule(node, rule)``
* ``ex_create_firewall_rules(node, rules)``
* ``ex_delete_firewall_rule(node, position)``

Instantiating a driver
----------------------

When you instantiate a driver you can authenticate with an API bearer token:

* ``token`` - Your UpCloud API bearer token

For example:

.. code-block:: python

    from libcloud.compute.types import Provider
    from libcloud.compute.providers import get_driver

    cls = get_driver(Provider.UPCLOUD)
    driver = cls(token="ucat_...")

You can also use basic authentication with an API enabled user:

* ``username`` - Your API access enabled users username
* ``password`` - Your API access enabled users password

For example:

.. code-block:: python

    from libcloud.compute.types import Provider
    from libcloud.compute.providers import get_driver

    cls = get_driver(Provider.UPCLOUD)
    driver = cls("username", "password")

Enabling API access
-------------------

To allow API access to your UpCloud account, you first need to enable the API
permissions by visiting `People`_ in your UpCloud Control
Panel. We recommend you to set up a sub-account specifically for the API usage
with its own username and password, as it allows you to assign specific permissions
for increased security.

Click **Add user** and fill in the required details, and check the
“**Allow API connections**” checkbox to enable API for the user. You can also
limit the API connections to a specific IP address or address range for additional
security. Once you are done entering the user information, hit the **Save** button
at the bottom of the page to create the new username.

.. _`UpCloud`: https://upcloud.com/
.. _`People`: https://hub.upcloud.com/people