Skip to main content

UpCloud API Client

Project description

# UpCloud-python-api
Python client for [UpCloud's API](https://www.upcloud.com/documentation/api/).

NOTE: This Python client is still work-in-progress and is not considered production ready.

## Installation

```
pip install --pre upcloud-api-python

# with older pip:
pip install upcloud-api-python
```

Alternatively, clone the project and run
```
python setup.py install
```

**Supported versions** (offline tests pass with tox):

* python 3.2
* python 3.3
* python 3.4
* python 3.5
* pypi3 2.4.0

## Features
* OOP based management of Servers, Storages and IP-addresses with full CRUD.
* since 0.2: manage both IPv4 and IPv6 addresses
* since 0.1.1: can use custom storage templates in addition to public templates
* Clear way to define your infrastructure, emphasis on clear and easy syntax
* Access all the data of the objects ( e.g. ssh credentials )
* Scale horizontally by creating / destroying servers
* Scale vertically by changing the RAM, CPU, storage specs of any server
* Manage firewall (on/off and individual rules)
* since 0.2: full management of firewall rules

**TODO:**
* Cloning of storages
* Full management of special storage types:
* CDROMs, custom OS templates
* (custom templates can already be cloned to a disk via UUID)
* Full management of backups (instant and scheduled)

**Changelog:**
* See the [Releases page](https://github.com/UpCloudLtd/upcloud-python-api/releases)

**Documentation:**
* Available [here](http://upcloudltd.github.io/upcloud-python-api/)



## Examples

Note that operations are not instant, for example a server is not fully shut down when the API responds.
You must take this into account in your automations.

### Defining and creating Servers

```python
import upcloud
from upcloud import Server, Storage, ZONE

manager = upcloud.CloudManager("api_user", "password")
manager.authenticate() # test credentials

cluster = {
"web1": Server( core_number = 1, # CPU cores
memory_amount = 512, # RAM in MB
hostname = "web1.example.com",
zone = ZONE.London, # ZONE.Helsinki and ZONE.Chicago available also
storage_devices = [
# OS: Ubuntu 14.04 from template
# default tier: maxIOPS, the 100k IOPS storage backend
Storage(os = "Ubuntu 14.04", size=10),
# secondary storage, hdd for reduced cost
Storage(size=100, tier="hdd")
]),

"web2": Server( core_number = 1,
memory_amount = 512,
hostname = "web2.example.com",
zone = ZONE.London,
storage_devices = [
Storage(os = "Ubuntu 14.04", size=10),
Storage(size=100, tier="hdd"),
]),

"db": Server( core_number = 2,
memory_amount = 2048,
hostname = "db.example.com",
zone = ZONE.London,
storage_devices = [
Storage(os = "Ubuntu 14.04", size=10),
Storage(size=100),
]),

"lb": Server( core_number = 2,
memory_amount = 1024,
hostname = "balancer.example.com",
zone = ZONE.London,
storage_devices = [
Storage(os = "Ubuntu 14.04", size=10)
])
}

for server in cluster:
manager.create_server( cluster[server] ) # automatically populates the Server objects with data from API

```

### Stop / Start / Destroy Servers
```python

for server in cluster:
server.shutdown()
# OR:
server.start()
# OR:
server.destroy()
for storage in server.storage_devices:
storage.destroy()

```

### Upgrade a Server
```python

server = cluster["web1"]
server.shutdown()
server.core_number = 4
server.memory_amount = 4096
server.save()
server.start()

```

### GET resources:
```python

servers = manager.get_servers()
server1 = manager.get_server(UUID) # e.g servers[0].uuid
storages = manager.get_storages()
storage1 = manager.get_storage(UUID) # e.g sever1.storage_devices[0].uuid
ip_addrs = manager.get_IPs()
ip_addr = manager.get_IP(address) # e.g server1.ip_addresses[0].address

```

## Tests

Set up environment and install dependencies:

```
# run at project root, python3 and virtualenv must be installed
virtualenv ENV
source ENV/bin/activate
pip install -r requirements.txt
```

Install the package in editable mode, as mentioned in
[https://pytest.org/latest/goodpractises.html](https://pytest.org/latest/goodpractises.html)

```python
# run at project root
pip install -e .
```

Tests located in `project_root/tests/` directory. Run with:

```python
py.test tests/
```

To test against python3.2=< and pypy3-2.4.0, run:

```python
tox
```

The project also supplies a small test suite to test against the live API at `test/live_test.py`. This suite is NOT run with `py.test` as it will permanently remove all resources related to an account. It should only be run with a throwaway dev-only account when preparing for a new release. It is not shipped with PyPI releases. See source code on how to run the live tests.

## Bugs, Issues, Problems, Ideas

Feel free to open a new issue : )

## Documentation

Documentation available [here](http://upcloudltd.github.io/upcloud-python-api/)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

upcloud-api-python-0.2.0.tar.gz (26.8 kB view details)

Uploaded Source

File details

Details for the file upcloud-api-python-0.2.0.tar.gz.

File metadata

File hashes

Hashes for upcloud-api-python-0.2.0.tar.gz
Algorithm Hash digest
SHA256 222b1c157f8e7cfe47008b0dab677cbbed85d2fd5fb15db84c540bc33c11218a
MD5 703f9e4e5e1ebe8a5e3c739833297d87
BLAKE2b-256 f1d8fa735a356963f51b1f418a6f86c94965da36d6f9cd1789c6073b0d0f5668

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page