1&1 Python SDK
The 1&1 Python SDK is a Python library used for interacting with the 1&1 platform over the REST API.
This guide will show you how to programmatically use the 1&1 library to perform common management tasks also available through the 1&1 Control Panel.
Table of Contents
- Overview
- Getting Started
- Installation
- Authentication
-
Operations
- Resources and Using the Module
- Creating a Cloud Server
- Creating a Baremetal Server
- Creating a Server with SSH Key Access
- Creating a Firewall Policy
- Creating a Load Balancer
- Creating a Monitoring Policy
- Creating a Block Storage
- Creating an SSH Key
- Updating Server Cores, Memory, and Disk
- Listing Servers, Images, Shared Storages, etc.
- Example App
Overview
The Python Client Library wraps the latest version of the 1&1 REST API. All API operations are performed over SSL and authenticated using your 1&1 API Token. 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.
Getting Started
Before you begin you will need to have signed up for a 1&1 account. The credentials you create during sign-up will be used to authenticate against the API.
Installation
The Python Client Library is available on PyPi. You can install the latest stable version using pip:
$ pip install 1and1Done!
Authentication
Connecting to 1&1 is handled by first setting up your authentication.
from oneandone.client import OneAndOneService
client = OneAndOneService('API-TOKEN')You can also provide two other optional parameters:
api_url allows you to provide a custom URL for the API
client = OneAndOneService(api_token='<API-Token>', api_url="CUSTOM URL")
enable_logs when set to True it will print out http requests/response logs to the console for further debugging
client = OneAndOneService(api_token='<API-Token>', enable_logs=True)
You can now use client for any future requests.
Operations
Resources and Using the Module
Resources
Official 1&1 REST API Documentation: https://cloudpanel-api.1and1.com/documentation/v1/en/api/documentation.html
1&1 Python SDK Method Reference Sheet: reference.md
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 Cloud 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>',
server_type='cloud'
)
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 Baremetal 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>',
server_type='baremetal',
baremetal_model_id='<MODEL_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 Server with SSH Key Access
from oneandone.client import OneAndOneService
from oneandone.client import Server, Hdd
client = OneAndOneService('<API-TOKEN>')
# Assign your public key to a variable
pub_key = '<PUB-KEY>'
server1 = Server(name='Test Server',
description='Server Description',
vcore=1,
cores_per_processor=1,
ram=2,
appliance_id='<IMAGE ID>',
rsa_key=pub_key
)
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)Note: You may then SSH into your server by executing the following command in terminal
ssh –i <path_to_private_key_file> root@SERVER_IP
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=80,
action='allow',
source='0.0.0.0'
)
rule2 = FirewallPolicyRule(protocol='UDP',
port=443,
action='allow',
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
)Creating a Block Storage
from oneandone.client import OneAndOneService
from oneandone.client import BlockStorage
client = OneAndOneService('<API-TOKEN>')
block_storage = BlockStorage(name='My new block storage',
description='My block storage description',
size=20,
server_id='<SERVER-ID>',
datacenter_id='<DATACENTER-ID>')Creating an SSH Key
from oneandone.client import OneAndOneService
from oneandone.client import SshKey
client = OneAndOneService('<API-TOKEN>')
ssh_key = SshKey(name='Test SSH Key',
description='Test Description',
public_key='<PUBLIC-KEY>'
)
new_ssh_key = client.create_ssh_key(ssh_key)Then, you can pass the ssh key id when creating a server:
server1 = Server(name='Test Ssh Server',
description='Server Description',
vcore=1,
cores_per_processor=1,
ram=2,
appliance_id='<IMAGE ID>',
public_key=ssh_key.specs['ssh_key_id']
)
hdd1 = Hdd(size=40, is_main=True)
hdds = [hdd1]
new_server = client.create_server(server=server1, hdds=hdds)Updating Server Cores, Memory, and Disk
1&1 allows users to dynamically update cores, memory, and disk independently of each other. This means you will no longer have to upgrade your server to receive an increase in memory. You can now simply increase the instance's memory, which keeps your costs in-line with your resource needs.
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. Indicate 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()
block_storages = client.list_block_storages()
ssh_keys = client.list_ssh_keys()Example App
This simple app creates a load balancer, firewall policy, and server. It then adds the load balancer and firewall policy to the server's initial IP address. You can access a server's initial IP by using the first_ip attribute on the Server class object, as seen in the example below.
The source code for the Example App can be found here.
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='Example 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')
rules = [rule1]
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...'
print 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')
rules = [rule1]
new_firewall = client.create_firewall_policy(firewall_policy=fp1,
firewall_policy_rules=rules)
## Wait for Firewall Policy to go live
print 'Creating firewall policy...'
print fp1.wait_for()
# Create Server
server1 = Server(name='Example App Server',
fixed_instance_size_id='65929629F35BBFBA63022008F773F3EB',
appliance_id='6C902E5899CC6F7ED18595EBEB542EE1',
datacenter_id='5091F6D8CBFEF9C26ACE957C652D5D49')
new_server = client.create_server(server=server1)
## Wait for the Server to go live
print 'Creating new server...'
print server1.wait_for()
# Add Load Balancer to New Server
lb_response = client.add_load_balancer(server_id=new_server['id'],
ip_id=server1.first_ip['id'], load_balancer_id=new_load_balancer['id'])
## Wait for Load Balancer to be added
print 'Adding load balancer to Server...'
print server1.wait_for()
# Add Firewall Policy to New Server
fw_response = client.add_firewall_policy(server_id=new_server['id'],
ip_id=server1.first_ip['id'], firewall_id=new_firewall['id'])
## Wait for Firewall Policy to be added
print 'Adding firewall policy to Server...'
print server1.wait_for()
print 'Everything looks good!'
# Cleanup the rubbish
print 'Cleaning up the mess we just made...\n'
print 'Deleting server...'
client.delete_server(server_id=new_server['id'])
print 'Deleting load balancer...'
client.delete_load_balancer(load_balancer_id=new_load_balancer['id'])
print 'Deleting firewall...'
client.delete_firewall(firewall_id=new_firewall['id'])
print '\nAll done!'
