Use the 1&1 Python Cloud Server SDK

Table of Contents

Introduction

Learn how to use the 1&1 Python SDK, which wraps the latest version of the 1&1 Cloud Server API. All API operations are performed over SSL and authenticated using your 1&1 API Key. The API can be accessed within an instance running in 1&1 or directly over the Internet from any application that can send an HTTPS request and receive an HTTPS response.

Requirements

  • A platform (such as a server) which can send an HTTPS request and receive an HTTPS response.
  • The 1&1 Python SDK installed and configured.

Authentication

Connecting to 1&1 is handled by first setting up your authentication.

from oneandone.client import OneAndOneService

client = OneAndOneService('API-TOKEN')

You can now use client for any future requests.

Operations

Resources and Using the Module

Resources

Official 1&1 Cloud Server API Documentation

Using the Module

The following "How To's" are meant to give you a general overview of some of the things you can do with the 1&1 Python SDK. For a detailed list of all methods and functionality, please visit the reference.md file.

Creating a Server

from oneandone.client import OneAndOneService
from oneandone.client import Server, Hdd

client = OneAndOneService('<API-TOKEN>')

server1 = Server(name='Test Server',
                 description='Server Description',
                 vcore=1,
                 cores_per_processor=1, 
                 ram=2, 
                 appliance_id='<IMAGE ID>'
                 )

hdd1 = Hdd(size=120, is_main=True)
hdd2 = Hdd(size=60, is_main=False)

hdds = [hdd1, hdd2]

new_server = client.create_server(server=server1, hdds=hdds)

Creating a Firewall Policy

from oneandone.client import OneAndOneService
from oneandone.client import FirewallPolicy, FirewallPolicyRule

client = OneAndOneService('<API-TOKEN>')

fp1 = FirewallPolicy(name='Test Firewall Policy',
                 description='Test Description'
                 )

rule1 = FirewallPolicyRule(protocol='TCP',
                       port_from=80,
                       port_to=80,
                       source='0.0.0.0'
                       )

rule2 = FirewallPolicyRule(protocol='UDP',
                       port_from=443,
                       port_to=443,
                       source='0.0.0.0'
                       )

rules = [rule1, rule2]

new_firewall = client.create_firewall_policy(firewall_policy=fp1, firewall_policy_rules=rules)

Creating a Load Balancer

from oneandone.client import OneAndOneService
from oneandone.client import LoadBalancer, LoadBalancerRule

client = OneAndOneService('<API-TOKEN>')

lb1 = LoadBalancer(name='Test Load Balancer',
               description='Test Description',
               health_check_test='TCP',
               health_check_interval=40,
               persistence=True,
               persistence_time=1200,
               method='ROUND_ROBIN'
               )

rule1 = LoadBalancerRule(protocol='TCP',
                     port_balancer=80,
                     port_server=80,
                     source='0.0.0.0'
                     )
rule2 = LoadBalancerRule(protocol='TCP',
                     port_balancer=9999,
                     port_server=8888,
                     source='0.0.0.0'
                     )

rules = [rule1, rule2]

new_load_balancer = client.create_load_balancer(load_balancer=lb1, load_balancer_rules=rules)

Creating a Monitoring Policy

First, create the monitoring policy:

from oneandone.client import OneAndOneService
from oneandone.client import MonitoringPolicy, Threshold, Port, Process

client = OneAndOneService('<API-TOKEN>')

mp1 = MonitoringPolicy(name='Test MP',
                   description='Test Description',
                   email='test@example.com',
                   agent=True
                   )

cpu = Threshold(entity='cpu',
            warning_value=90,
            warning_alert=False,
            critical_value=95,
            critical_alert=False
            )

ram = Threshold(entity='ram',
            warning_value=90,
            warning_alert=False,
            critical_value=95,
            critical_alert=False
            )

disk = Threshold(entity='disk',
             warning_value=80,
             warning_alert=False,
             critical_value=90,
             critical_alert=False
             )

transfer = Threshold(entity='transfer',
                 warning_value=1000,
                 warning_alert=False,
                 critical_value=2000,
                 critical_alert=False
                 )

internal_ping = Threshold(entity='internal_ping',
                      warning_value=50,
                      warning_alert=False,
                      critical_value=100,
                      critical_alert=False
                      )

thresholds = [cpu, ram, disk, transfer, internal_ping]

port1 = Port(protocol='TCP',
         port=22,
         alert_if='RESPONDING',
         email_notification=False
         )

port2 = Port(protocol='TCP',
         port=44,
         alert_if='NOT_RESPONDING',
         email_notification=True
         )

ports = [port1, port2]

process1 = Process(process='TaskMgr',
               alert_if='NOT_RUNNING',
               email_notification=True
               )

process2 = Process(process='Logger',
               alert_if='NOT_RUNNING',
               email_notification=True
               )

processes = [process1, process2]

new_monitoring_policy = client.create_monitoring_policy(monitoring_policy=mp1,
                                                    thresholds=thresholds,
                                                    ports=ports,
                                                    processes=processes
                                                    )

Then, add a server or two:

from oneandone.client import OneAndOneService
from oneandone.client import AttachServer

client = OneAndOneService('<API-TOKEN>')

server1 = AttachServer(server_id='<SERVER1 ID>')
server2 = AttachServer(server_id='<SERVER2 ID>')

servers = [server1, server2]

response = client.attach_monitoring_policy_server(monitoring_policy_id='<MONITORING POLICY ID>',
                                              servers=servers
                                              )

Adjusting the Amount of Server Cores, the RAM, and size of the SSDs

1&1 allows users to dynamically adjust the amount of cores, the size of the memory, and of the SSDs independently of each other.

The following code illustrates how you can update cores and memory:

from oneandone.client import OneAndOneService

client = OneAndOneService('<API-TOKEN>')

response = modify_server_hardware(server_id='<SERVER ID>',
                              vcore=2,
                              ram=6
                              )

This is how you would update a server disk's size:

response = client.modify_hdd(server_id='<SERVER_ID>',
                         hdd_id='<HDD ID>',
                         size=80
                         )

Listing Servers, Images, Shared Storages, etc.

Generating a list of resources is fairly straight forward. Each "list" method follows this general format: list_*() where the * is servers, images, load_balancers, etc. You may also pass optional query parameters to help filter your results. By default, these parameters are all set to None.

Available Parameters

  • page (integer): Allows to the use of pagination. Indicates which page to start on.
  • per_page (integer): Number of items per page.
  • sort (string): sort='name' retrieves a list of elements sorted alphabetically. sort='creation_date' retrieves a list of elements sorted by their creation date in descending order.
  • q (string): q is for query. Use this parameter to return only the items that match your search query.
  • fields (string): Returns only the parameters requested. (i.e. fields='id, name, description, hardware.ram')

Examples of Listing Resources

from oneandone.client import OneAndOneService

client = OneAndOneService('<API-TOKEN>')

servers = client.list_servers()

images = client.list_images()

shared_storages = client.list_shared_storages()

firewall_policies = client.list_firewall_policies()

load_balancers = client.list_load_balancers()

private_networks = client.list_private_networks()

monitoring_policies = client.list_monitoring_policies()

Example App

This simple app creates a load balancer, firewall policy, and server. It then creates a new IP for the server and attaches the load balancer and firewall policy to that IP.

Use the wait_for() method to chain together multiple actions that take a while to deploy. See the /docs/reference.md file for a more detailed description of the wait_for() method and other class helper methods.

The original source code for the Example App with some additional markup and cleanup can be found in /examples/example_app.py.

from oneandone.client import OneAndOneService
from oneandone.client import Server, Hdd, LoadBalancer, LoadBalancerRule
from oneandone.client import FirewallPolicy, FirewallPolicyRule

client = OneAndOneService('<API-TOKEN>')

# Create Load Balancer
lb1 = LoadBalancer(name='Example App LB',
               description='Test Description',
               health_check_test='TCP',
               health_check_interval=40,
               persistence=True,
               persistence_time=1200,
               method='ROUND_ROBIN'
              )

rule1 = LoadBalancerRule(protocol='TCP',
                     port_balancer=80,
                     port_server=80,
                     source='0.0.0.0'
                     )
rule2 = LoadBalancerRule(protocol='TCP',
                     port_balancer=9999,
                     port_server=8888,
                     source='0.0.0.0'
                     )

rules = [rule1, rule2]

new_load_balancer = client.create_load_balancer(load_balancer=lb1,
                                            load_balancer_rules=rules
                                            )

## Wait for Load Balancer to go live
print 'Creating load balancer...'
lb1.wait_for()

# Create Firewall Policy
fp1 = FirewallPolicy(name='Example App FP',
                 description='Test Description'
                 )

rule1 = FirewallPolicyRule(protocol='TCP',
                       port_from=80,
                       port_to=80,
                       source='0.0.0.0'
                       )

rule2 = FirewallPolicyRule(protocol='UDP',
                       port_from=443,
                       port_to=443,
                       source='0.0.0.0'
                       )

rules = [rule1, rule2]

new_firewall = client.create_firewall_policy(firewall_policy=fp1,
                                         firewall_policy_rules=rules
                                         )

## Wait for Firewall Policy to go live
print 'Creating firewall policy...'
fp1.wait_for()

# Create Server
server1 = Server(name='Example App Server',
             description='Server Description',
             vcore=1,
             cores_per_processor=1, 
             ram=2, 
             appliance_id='D9DBA7D7F7E9C8200A493CE9013C4605'
             )

hdd1 = Hdd(size=120, is_main=True)
hdd2 = Hdd(size=60, is_main=False)

hdds = [hdd1, hdd2]

new_server = client.create_server(server=server1, hdds=hdds)

## Wait for the Server to go live
print 'Creating new server...'
server1.wait_for()

# Add a new IP to the server
new_ip = client.add_new_ip(server_id=new_server['id'])

# Add Load Balancer to New Server IP
lb_response = client.add_load_balancer(server_id=new_server['id'],
                                   ip_id=new_ip['ips'][1]['id'],
                                   load_balancer_id=new_load_balancer['id']
                                   )

## Wait for Load Balancer to be added
print 'Adding load balancer to Server...'
server1.wait_for()

# Add Firewall Policy to New Server IP
fw_response = client.add_firewall_policy(server_id=new_server['id'],
                                     ip_id=new_ip['ips'][1]['id'],
                                     firewall_id=new_firewall['id']
                                     )

## Wait for Firewall Policy to be added
print 'Adding firewall policy to Server...'
server1.wait_for()

Comments