Groovy SDK

Version: 3.1.0

Abstract

This Groovy SDK provides a convenient way to use the ProfitBricks Cloud API from JVM based applications. This guide will show you how to programmatically perform infrastructure management operations with it.

Design Objective

There is essentially only one usage pattern: Create an entity, then invoke one of the CRUD methods on it:

create(): Effectively send a resource creation REST request (HTTP CREATE).
read(): Fetch an existing REST resource by its UUID (HTTP GET).
update(): Send an update to an existing REST resource (HTTP PUT).
delete(): Delete an existing resource (HTTP DELETE).
all: This property implements a list operation to fetch UUIDs of existing REST resources.

An entity must be sufficiently populated in order for the associated REST request to succeed. No extra validation will take place. If there is an error, you will see an exception with the cause.

For resources that exist within the context of another resource, that other resource must also be properly instantiated and injected.

For example: to successfully operate on a network interface, the entity (NIC) must also contain proper Server and LAN instances, while in turn the Server and LAN instances must contain a proper DataCenter instance (which needs just a valid id).

No extra modeling was made (e.g. no parent links and in total ignorance about the depth API parameter). The entities just enclose the transported JSON representations.

On a successfully-delivered POST, PUT or DELETE request, the Profitbricks API might send a Location header instead of the final resulting response to the requested action. This SDK will block on such a response, then continue polling for the final result. If a successful result does not come in time, an exception will be thrown.

This was made to allow for easy and agile API scripting, as the result matters most of the time, and such a behavior would be needed anyway.

For API resources which do not fit into the CRUD scheme, an extra command facade is provided. This provides functionality like attaching and detaching storage volumes to virtual servers or associating network interfaces with load balancers.

This implementation is based on Groovy 2, so it technically runs on any JVM version 7 or later.

Before you begin you will need to have signed up for a ProfitBricks account. The credentials you set up during the sign-up process must be used to authenticate against the Cloud API.

Getting Started

Installation

This SDK is available from the ProfitBricks GitHub Page as well as Maven Central

optional: build and deploy it to your local maven repository:

./gradlew clean build publishToMavenLocal -x test

add the dependency to your project:

example: gradle

dependencies {
    compile 'com.profitbricks:groovy-sdk:3.1.0'
}

example: maven

<dependency>
    <groupId>com.profitbricks</groupId>
    <artifactId>groovy-sdk</artifactId>
    <version>3.1.0</version>
</dependency>

Configuration

One way to configure the API client is to use system properties. The following table lists all those properties along with their default value (if any).

System Properties

name	default	notes
`com.profitbricks.sdk.verifySSL`	`true`	set to `false` to ignore SSL certificate verification issues, see also note below
`com.profitbricks.sdk.user`	-	the API user name for basic authentication. required
`com.profitbricks.sdk.password`	-	the API password for basic authentication. required
`com.profitbricks.sdk.wait.init.milliseconds`	100	if waiting for success, this is the initial time period between two checks.
`com.profitbricks.sdk.wait.timeout.seconds`	120	if waiting for success, this is the timeout.
`com.profitbricks.sdk.wait.max.milliseconds`	1500	if waiting for success, this is the maximum time period between two checks.
`com.profitbricks.sdk.wait.factor`	1.87	if waiting for success, this is the factor by which the current time period value is multiplied.

Individual configuration values can also be overridden with each individual request.

All CRUD (and list) methods as well as all commands can be invoked with an optional map as the last parameter. The keys in this map are expected to be named like the corresponding system property minus the prefix com.profitbricks.sdk..

Note: verifySSL can only be configured via system property before making the first API call and not be overridden.

// for example
datacenter.create(user: 'otheruser', password: 'otherpassword', 'wait.factor': Math.PI/2)
// or for read operations
assert userID : 'user id missing'
new User().read(userID, [password: 'mypassword'])

SDK Reference

This section provides details on all the available operations and the parameters they accept. Also included are brief code snippets illustrating its usage.

datacenters

Virtual data centers (VDCs) are the foundation of the ProfitBricks platform. VDCs act as logical containers for all other objects you will be creating, e.g., servers. You can provision as many VDCs as you want. VDCs have their own private network and are logically isolated from each other.

list datacenters

Lists the ids of all currently provisioned datacenters that are accessible for the current user.

List<String> datacenterIDs = new DataCenter().all
assert datacenterIDs : 'no datacenters found!'

retrieve a datacenter

Argument	Required
`DataCenter::id`	yes

assert datacenterId : 'datacenter id missing!'
DataCenter datacenter = new DataCenter(id: datacenterId).read()
assert datacenter : 'no such datacenter!'

create a datacenter

Argument	Required
`DataCenter::name`	yes
`DataCenter::location`	yes
`DataCenter::description`	no

Supported Locations

value	geographical location
`us/las`	US / Las Vegas
`us/ewr`	US / Newark
`de/fra`	Germany / Frankfurt
`de/fkb`	Germany / Karlsruhe

def dc = new DataCenter(
    name: "groovy name",
    location: 'us/ewr',
    description: 'groovy description'
).create()
assert dc.id : 'datacenter creation failed!'

update a datacenter

Argument	Required
`DataCenter::id`	yes
`DataCenter::name`	no
`DataCenter::description`	no

assert datacenter : 'datacenter missing!'
dc.name = "updated name from ${dc.name}"
dc.description = "groovy new datacenter! (old: ${dc.description})"
assert dc.update() : 'datacenter update failed!'

delete a datacenter

Removes all objects within the virtual data center AND removes the virtual data center object itself.

NOTE: This is a highly destructive operation which should be used with extreme caution.

Argument	Required
`DataCenter::id`	yes

assert datacenter : 'datacenter missing!'
assert dc.delete() : 'datacenter deletion failed!'

Locations

Locations are the physical ProfitBricks computing centers where you can provision your resources.

List locations

Retrieves the list of IDs of currently available locations.

List<String> locationIDs = new Location().all
assert locationIDs : 'no locations found!'

retrieve a location

Argument	Required
`Location::id`	yes

Location location = new Location(id: 'us/ewr').read()
assert location : 'no such location!'

Servers

A valid DataCenter instance is needed to manage servers.

List Servers

Retrieves the list of IDs of created servers for a given datacenter.

Argument	Required
`DataCenter::id`	yes

assert datacenter : 'datacenter missing!'
List<String> serverIDs = new Server(dataCenter: datacenter).all
assert serverIDs : 'no servers found!'

Retrieve a Server

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes

assert datacenter : 'datacenter missing!'
assert serverId : 'server id missing!'
Server server = new Server(id: serverId, dataCenter: datacenter).read()
assert server : 'no such server!'

Create a Server

Argument	Required	Description
`DataCenter::id`	yes
`Server::name`	yes
`Server::cores`	yes	number of cores
`Server::ram`	yes	amount of memory in MB, size must be specified in multiples of 256
`Server::availabilityZone`	no	fire zone (see table below)
`Server::cpuFamily`	no	CPU family: `AMD_OPTERON` or `INTEL_XEON` default: `AMD_OPTERON`

Supported Fire Zones

firezone	comment
`AUTO`	automatically selected zone, default
`ZONE_1`	firezone 1
`ZONE_2`	firezone 2

assert datacenter : 'datacenter missing!'
Server server = new Server(
    dataCenter: datacenter,
    name: "server name",
    cores: 1,
    ram: 1024,
    availabilityZone: "ZONE_1",
    cpuFamily: "INTEL_XEON"
).create()
assert server.id : 'server creation failed!'

Update a Server

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes
`Server::name`	no
`Server::cores`	no
`Server::ram`	no
`Server::availabilityZone`	no
`Server::cpuFamily`	no

assert server : 'server missing!'
server.name = "updated"
server.cores += 2
server.ram += 512
assert server.update() : 'server update failed!'

Delete a Server

Removes a server from a data center. NOTE: This will not automatically remove the storage volume(s) attached to a server. A separate operation is required to delete a storage volume.

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes

assert server : 'server missing!'
assert server.delete() : 'server deletion failed!'

list attached volumes

Retrieves a list of ids of all volumes currently attached to a given server.

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes

assert server : 'server missing!'
List<String> volumeIDs = Commands.attached(server, Volume)
assert volumeIDs : 'no volumes found!'

attach a volume

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes
`Volume::id`	yes

assert server : 'server missing!'
assert volume : 'volume missing!'
assert Commands.attach(server, volume) : 'volume attachment failed!'

detach a volume

Depending on the volume hot_unplug settings, this may result in the server being rebooted.

This will NOT delete the volume from your virtual data center. You will need to make a separate request to delete a volume.

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes
`Volume::id`	yes

assert server : 'server missing!'
assert volume : 'volume missing!'
assert Commands.detach(server, volume) : 'volume detachment failed!'

list attached images

Retrieves a list of ids of all images (CDROMs) currently attached to a given server.

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes

assert server : 'server missing!'
List<String> imageIDs = Commands.attached(server, Image)
assert imageIDs : 'no attached images!'

attach an image

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes
`Image::id`	yes

assert server : 'server missing!'
assert image : 'image missing!'
assert Commands.attach(server, image) : 'image attachment failed!'

detach an image

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes
`Image::id`	yes

assert server : 'server missing!'
assert image : 'image missing!'
assert Commands.detach(server, image) : 'image detachment failed!'

reboot a server

Forces a hard reboot of the server. Do not use this method if you want to gracefully reboot the machine. This is the equivalent of powering off the machine and turning it back on.

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes

assert server : 'server missing!'
assert Commands.reboot(server) : 'server reboot failed!'

start a server

Starts a server. If the server's public IP address was deallocated then a new IP address will be assigned.

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes

assert server : 'server missing!'
assert Commands.start(s) : 'server start failed!'

stop a server

Stops a server. The machine will be forcefully powered off, billing will stop, and the public IP address, if one is allocated, will be deallocated.

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes

assert server : 'server missing!'
assert Commands.stop(s) : 'server stop failed!'

Images

list images

Retrieves a list of ids of all available images (CDROMs).

List<String> imageIDs = new Image().all
assert imageIDs : 'no images found!'

retrieve an image

Argument	Required
`Image::id`	yes

Image image = new Image(id: imageID).read()
assert image._public : 'image is not public!'

Volumes

list volumes

Retrieves a list of ids of volumes in a given datacenter. A valid DataCenter instance is needed for this.

Argument	Required
`DataCenter::id`	yes

assert dc : 'datacenter missing!'
List<String> volumeIDs = new Volume(dataCenter: dc).all
assert volumeIDs : 'no volumes found!'

retrieve a volume

Argument	Required
`DataCenter::id`	yes
`Volume::id`	yes

assert dc : 'datacenter missing!'
Volume volume = new Volume(dataCenter: dc, id: volumeId).read()
assert volume : 'no such volume!'

create a volume

Creates a volume within the virtual data center. This will not attach the volume to a server. Please see the Attach a Volume entry in the Server section for details on how to attach storage volumes.

Argument	Required	Description
`DataCenter::id`	yes	The ID of the VDC.
`Volume::name`	yes	The name of the volume.
`Volume::size`	yes	The size of the volume in GB.
`Volume::bus`	no	The bus type of the volume (VIRTIO or IDE). Default: VIRTIO.
`Volume::image`	no	The image or snapshot ID.
`Volume::imageAlias`	no	The alias of the image.
`Volume::type`	no	The volume type, HDD or SSD.
`Volume::licenceType`	no	The licence type of the volume. see table below
`Volume::imagePassword`	no	password for the root or administrative account, must consist of 8-50 alphanumeric characters
`Volume::sshKeys`	no	collection of SSH public keys
`Volume::availabilityZone`	no	availability zone the volume should reside in, see table below

Licence Type	Comment
`WINDOWS2016`	for Microsoft Windows Server 2016
`WINDOWS`	for Microsoft Windows Server 2008 and 2012
`LINUX`	for Linux
`OTHER`	for any volumes that do not match one of the other licence types
`UNKNOWN`	default value when you've uploaded an image and haven't set the license type

Availability Zone	Comment
`AUTO`	Automatically Selected Zone
`ZONE_1`	Fire Zone 1
`ZONE_2`	Fire Zone 2
`ZONE_3`	Fire Zone 3

assert datacenter : 'datacenter missing!'
Volume v = new Volume(dataCenter: datacenter, name: "name", size: 1).create()
assert v.id : 'volume creation failed!'

update a volume

The size of an existing storage volume can only be increased.
If no according hot plug settings are configured, this operation may cause a server reboot.

Arguments	Required
`DataCenter::id`	yes
`Volume::id`	yes
`Volume::name`	no
`Volume::size`	no
`Volume::bus`	no
`Volume::image`	no
`Volume::type`	no
`Volume::licenceType`	no
`Volume::availabilityZone`	no

assert volume : 'volume missing!'
volume.name = "updated name from ${vname}"
volume.size = 2
assert v.update() : 'volume update failed!'

delete a volume

Argument	Required
`DataCenter::id`	yes
`Volume::id`	yes

assert volume : 'volume missing!'
assert volume.delete() : 'volume deletion failed!'

create a volume snapshot

Argument	Required
`DataCenter::id`	yes
`Volume::id`	yes
`Snapshot::name`	no
`Snapshot::description`	no

assert volume : 'volume missing!'
Snapshot snapshot = Commands.snapshot(v, 'snapshot_4711', 'a fancy snapshot')
assert snapshot : 'snapshot operation failed!'

restore a volume snapshot

Argument	Required
`DataCenter::id`	yes
`Volume::id`	yes
`Snapshot::id`	yes

assert volume : 'volume missing!'
assert snapshot : 'snapshot missing!'
assert Commands.restore(v, sn) : 'restoration from snapshot failed!'

Snapshots

list snapshots

Retrieves a list of ids of all available snapshots.

List<String> snapshotIDs = new Snapshot().all
assert snapshotIDs : 'no snapshots found!'

retrieve a snapshot

Argument	Required
`Snapshot::id`	yes

Snapshot snap = new Snapshot(id: snapshotId).read()
assert snap : 'no such snapshot!'

update a snapshot

Argument	Required	Description
`Snapshot::id`	yes
`Snapshot::name`	no
`Snapshot::description`	no
`Snapshot::licenceType`	no	licence type: `LINUX`, `WINDOWS`, `WINDOWS2016` or `OTHER`
`Snapshot::cpuHotPlug`	no	CPU hot plug capability
`Snapshot::cpuHotUnplug`	no	CPU hot unplug capability
`Snapshot::ramHotPlug`	no	memory hot plug capability
`Snapshot::ramHotUnplug`	no	memory hot unplug capability
`Snapshot::nicHotPlug`	no	NIC hot plug capability
`Snapshot::nicHotUnplug`	no	NIC hot unplug capability
`Snapshot::siscVirtioHotPlug`	no	VirtIO drive hot plug capability
`Snapshot::discVirtioHotUnplug`	no	VirtIO drive hot unplug capability
`Snapshot::discScsiHotPlug`	no	SCSI drive hot plug capability
`Snapshot::discScsiHotUnplug`	no	SCSI drive hot unplug capability

assert snapshot : 'snapshot missing!'
snapshot.name = "updated from ${snapshot.name}"
snapshot.ramHotPlug = true
assert snapshot.update() : 'snapshot update failed!'

delete a snapshot

Argument	Required
`Snapshot::id`	yes

assert snapshot : 'snapshot missing!'
assert snapshot.delete() : 'snapshot deletion failed!'

IP Blocks

list IP blocks

Retrieves a list of ids of previously reserved (created) IP blocks.

List<String> ipBlockIDs = new IPBlock().all
assert ipBlockIDs : 'no reserverd IP blocks!'

retrieve an IP block

Argument	Required
`IPBlock::id`	yes

assert ipBlockId : 'IP block id missing!'
IPBlock block = new IPBlock(id: ipBlockId).read()
assert block : 'no such IP block!'

create an IP block

Argument	Required	Description
`IPBlock::location`	yes	a valid location ID, see table above
`IPBlock::size`	yes	the number of IP addresses to reserve
`IPBlock::name`	no

IPBlock block = new IPBlock(location: 'us/ewr', size: 2).create()
assert block.id : 'IP block creation failed!'

delete an IP block

Argument	Required
`IPBlock::id`	yes

assert block : 'IP block missing!'
assert block.delete() : 'IP block deletion failed!'

LANs

list LANs

Retrieves a list of LAN ids within the virtual data center. This needs a valid DataCenter instance.

Argument	Required
`DataCenter::id`	yes

assert datacenter : 'datacenter missing!'
List<String> lanIDs = new LAN(dataCenter: datacenter).all
assert lanIDs : 'no LANs in this datacenter!'

create a LAN

Argument	Required	Description
`DataCenter::id`	yes
`LAN::_public`	yes	publicly reachable LAN?
`LAN::name`	no

assert datacenter : 'datacenter missing!'
LAN lan = new LAN(dataCenter: datacenter, name: 'primary LAN', _public: true).create()
assert lan.id : 'LAN creation failed!'

retrieve a LAN

Argument	Required
`DataCenter::id`	yes
`LAN::id`	yes

assert datacenter : 'datacenter missing!'
assert lanId : 'LAN id missing!'
LAN lan = new LAN(dataCenter: dc, id: lanId).read()
assert lan : 'no such LAN!'

update a LAN

Argument	Required	Description
`DataCenter::id`	yes
`LAN::id`	yes
`LAN::name`	no
`LAN::_public`	no
`LAN::ipFailover`	no	a collection of `IPFailover` instances

assert lan : 'LAN missing!'
lan.name = "name"
lan._public = false
lan.ipFailover = [
    new LAN.IPFailover(ip: '158.222.103.175', nicUuid: '43ec1562-042f-40ae-8162-44c97466ab52'),
    new LAN.IPFailover(ip: '158.222.103.175', nicUuid: '7240dbbc-de87-4fec-8e50-5a5ce77690e0')
]
assert lan.update() : 'LAN update failed!'

delete a LAN

Argument	Required
`DataCenter::id`	yes
`LAN::id`	yes

assert lan : 'LAN missing!'
assert lan.delete() : 'LAN deletion failed!'

Network Interfaces

list NICs

Retrieves a list of NIC ids for a given server. This needs a valid Server instance.

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes

assert server : 'server missing!'
List<String> nicIDs = new NIC(server: server).all
assert nicIDs : 'no NICs for this server!'

retrieve a NIC

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes
`NIC::id`	yes

assert server : 'server missing!'
assert nicID : 'NIC id missing!'
NIC nic = new NIC(server: s, id: nicID).read()
assert nic : 'no such NIC for this server!'

create a NIC

Argument	Required	Description
`DataCenter::id`	yes
`Server::id`	yes
`NIC::lan`	yes	id of the LAN the NIC will be attached on (if that LAN does not exist it will be created)
`NIC::name`	no
`NIC::ips`	no	all IPs assigned to the NIC
`NIC::dhcp`	no	DHCP enabled? default: true
`NIC::nat`	no	if address translation should be performed
`NIC::firewallActive`	no	if there are active firewall rules for this NIC

assert server : 'server missing!'
assert lan : 'LAN missing!'
NIC nic = new NIC(server: server, lan: lan, nat: true).create()
assert nic.id : 'NIC creation failed!'

update a NIC

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes
`NIC::id`	yes
`NIC::lan`	no
`NIC::name`	no
`NIC::ips`	no
`NIC::dhcp`	no
`NIC::nat`	no
`NIC::firewallActive`	no

assert nic : 'NIC missing!'
nic.name = "name"
nic.ips = ['192.168.0.2']
nic.dhcp = false
nic.nat = false
assert nic.update() : 'NIC update failed!'

delete a NIC

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes
`NIC::id`	yes

assert nic : 'NIC missing!'
assert nic.delete() : 'NIC deletion failed!'

Firewall Rules

list firewall rules

Retrieves a list of firewall rules associated with a particular NIC. Needs a valid NIC instance.

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes
`NIC::id`	yes

assert nic : 'NIC missing!'
List<String> fwRuleIDs = new FirewallRule(nic: nic).all
assert fwRuleIDs : 'no firewall rules for the given NIC!'

Retrieve a firewall rule

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes
`NIC::id`	yes
`FirewallRule::id`	yes

assert nic : 'NIC missing!'
assert ruleID : 'firewall rule id missing!'
FirewallRule rule = new FirewallRule(nic: nic, id: ruleID).read()
assert rule : 'no such firewall rule for this NIC!'

Create a firewall rule

Argument	Required	Description
`DataCenter::id`	yes
`Server::id`	yes
`NIC::id`	yes
`FirewallRule::protocol`	yes	one of `TCP`, `UDP`, `ICMP` or `ANY`
`FirewallRule::name`	no
`FirewallRule::sourceMac`	no	only allow connections from this MAC
`FirewallRule::sourceIp`	no	only allow connections from this IPv4 address
`FirewallRule::targetIp`	no	only allow connections to this IPv4 address
`FirewallRule::portRangeStart`	no	only allow connections for ports in the given range, this defines the range start
`FirewallRule::portRangeEnd`	no	only allow connections for ports in the given range, this defines the range end
`FirewallRule::icmpType`	no	only allow packets with the given ICMP type
`FirewallRule::icmpCode`	no	only allow packets with the given ICMP code

assert nic : 'NIC missing!'
FirewallRule rule = new FirewallRule(nic: nic, protocol: 'UDP').create()
assert rule.id : 'firewall rule creation failed!'

Update a Firewall Rule

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes
`NIC::id`	yes
`FirewallRule::id`	yes
`FirewallRule::protocol`	no
`FirewallRule::name`	no
`FirewallRule::sourceMac`	no
`FirewallRule::sourceIp`	no
`FirewallRule::targetIp`	no
`FirewallRule::portRangeStart`	no
`FirewallRule::portRangeEnd`	no
`FirewallRule::icmpType`	no
`FirewallRule::icmpCode`	no

assert rule : 'firewall rule missing!'
rule.name = "name"
rule.sourceMac = 'aa:bb:cc:dd:ee:ff'
rule.sourceIp = '23.23.23.23'
rule.targetIp = n.ips.first()
rule.portRangeStart = '1234'
rule.portRangeEnd = '4711'
assert rule.update() : 'firewall rule update failed!'

Delete a Firewall Rule

Argument	Required
`DataCenter::id`	yes
`Server::id`	yes
`NIC::id`	yes
`FirewallRule::id`	yes

assert rule : 'firewall rule missing!'
assert rule.delete() : 'firewall rule deletion failed!'

Load Balancers

list load balancers

Retrieves a list of load balancer ids within the data center. This needs a valid DataCenter instance.

Argument	Required
`DataCenter::id`	yes

assert datacenter : 'datacenter missing!'
List<String> loadbalancerIDs = new LoadBalancer(dataCenter: datacenter).all
assert loadbalancerIDs : 'no load balancers for this datacenter!'

retrieve a load balancer

Argument	Required
`DataCenter::id`	yes
`LoadBalancer::id`	yes

assert datacenter : 'datacenter missing!'
assert loadbalancerId : 'load balancer id missing!'
LoadBalancer lb = new LoadBalancer(dataCenter: datacenter, id: loadbalancerId).read()
assert lb : 'no such load balancer!'

create a load balancer

Argument	Required	Description
`DataCenter::id`	yes
`LoadBalancer::name`	yes
`LoadBalancer::ip`	no	IPv4 address of the load balancer. All attached NICs will inherit this address
`LoadBalancer::dhcp`	no	if DHCP shall be used

assert datacenter : 'datacenter missing!'
LoadBalancer lb = new LoadBalancer(dataCenter: datacenter, name: "frontend").create()
assert lb.id : 'load balancer creation failed!'

update a load balancer

Argument	Required
`DataCenter::id`	yes
`LoadBalancer::id`	yes
`LoadBalancer::name`	no
`LoadBalancer::ip`	no
`LoadBalancer::dhcp`	no

assert loadbalancer : 'load balancer missing!'
loadbalancer.name = "name"
loadbalancer.dhcp = false
loadbalancer.ip = '192.168.0.11'
assert loadbalancer.update() : 'load balancer update failed!'

delete a load balancer

Argument	Required
`DataCenter::id`	yes
`LoadBalancer::id`	yes

assert loadbalancer : 'load balancer missing!'
assert loadbalancer.delete() : 'load balancer deletion failed!'

list load balanced NICs

Retrieves a list of ids of NICs associated with the load balancer. Needs valid DataCenter and LoadBalancer instances.

Argument	Required
`DataCenter::id`	yes
`LoadBalancer::id`	yes

assert loadbalancer : 'load balancer missing!'
List<String> nicIDs = Commands.associatedNICs(loadbalancer)
assert nicIDs : 'no NICs associated with this load balancer!'

associate a NIC with a load balancer

Argument	Required
`DataCenter::id`	yes
`LoadBalancer::id`	yes
`NIC::id`	yes

assert loadbalancer : 'load balancer missing!'
assert nic : 'NIC missing!'
assert Commands.associate(loadbalancer, nic) : 'nic to load balancer association failed!'

remove a NIC association

Argument	Required
`DataCenter::id`	yes
`LoadBalancer::id`	yes
`NIC::id`	yes

assert loadbalancer : 'load balancer missing!'
assert nic : 'NIC missing!'
assert Commands.dissociate(loadbalancer, nic) : 'nic from load balancer dissociation failed!'

Users

list users

Retrieves a list of ids of all users for the current contract.

List<String> userIDs = new User().all
assert userIDs : 'no users found!'

retrieve a user

Argument	Required
`User::id`	yes

assert userId : 'user id missing!'
User user = new User(id: userId).read()
assert user : 'no such user!'

create a User

Argument	Required	Description
`User::firstname`	yes	user first name
`User::lastname`	yes	user last name
`User::email`	yes	user email address
`User::password`	yes	user basic auth password
`User::administrator`	no	assigns administrative rights
`User::forceSecAuth`	no	if two-factor auth should be forced

User user = new User(
    firstname: "John",
    lastname: "Doe",
    email: "groovy.user@dev.org",
    password: "HJhbjhjhbhhhgjhhhg6567fsdf234",
    administrator: true,
    forceSecAuth: true
).create()
assert user.id : 'user creation failed!'

update a user

Argument	Required
`User::id`	yes
`User::firstname`	no
`User::lastname`	no
`User::email`	no
`User::administrator`	no
`User::forceSecAuth`	no

assert user : 'user missing!'
user.administrator = false
assert user.update() : 'user update failed!'

delete a user

Argument	Required
`User::id`	yes

assert user : 'user missing!'
assert user.delete() : 'user deletion failed!'

User Groups

list user groups

List<String> groupIDs = new UserGroup().all
assert groupIDs : 'no user groups exist!'

retrieve a user group

Request Arguments

Argument	Required
`UserGroup::id`	yes

assert groupId : 'user group id missing!'
UserGroup group = new UserGroup(id: groupId).read()
assert group : 'no such user group!'

create a user group

Argument	Required	Description
`UserGroup::name`	yes
`UserGroup::createDataCenter`	no	permission to create data centers
`UserGroup::createSnapshot`	no	permission to create snapshots
`UserGroup::reserveIp`	no	permission to create IP blocks
`UserGroup::accessActivityLog`	no	permission to access the activity log

UserGroup group = new UserGroup(
    name: 'Admin Group',
    createDataCenter: true,
    createSnapshot: true,
    reserveIp: true,
    accessActivityLog: false
).create()
assert group.id : 'user group creation failed!'

update a user group

Argument	Required
`UserGroup::id`	yes
`UserGroup::name`	no
`UserGroup::createDataCenter`	no
`UserGroup::createSnapshot`	no
`UserGroup::reserveIp`	no
`UserGroup::accessActivityLog`	no

assert userGroup : 'user group missing!'
userGroup.createDatacenter = false
assert userGroup.update() : 'user group update failed!'

delete a user group

Argument	Required
`UserGroup::id`	yes

assert userGroup : 'user group missing!'
assert group.delete() : 'user group deletion failed!'

list group users

Retrieves a list of ids of all users that are members of a group.

Argument	Required
`UserGroup::id`	yes

assert userGroup : 'user group missing!'
List<String> userIDs = Commands.userIDs(group)
assert userIDs : 'no users in this group!'

add a user to a group

Argument	Required
`UserGroup::id`	yes
`User::id`	yes

assert userGroup : 'user group missing!'
assert user : 'user missing!'
assert Commands.assign(userGroup, user) : 'assigning user to user group failed!'

remove a user from a group

Argument	Required
`UserGroup::id`	yes
`User::id`	yes

assert userGroup : 'user group missing!'
assert user : 'user missing!'
assert Commands.unassign(group, user) : 'assigning user to user group failed!'

Contract Resources

Retrieve the current resource allocation statistics for this contract.

ContractStats stats = new ContractStats().read()
assert stats : 'retrieval of contract stats failed!'

A Concise Example

import com.profitbricks.sdk.model.*
import static com.profitbricks.sdk.Commands.*

// create a datacenter
DataCenter dc = new DataCenter(name: "Example DC", location: 'de/fkb', description: 'desc').create()

// create a LAN
LAN lan = new LAN(dataCenter: dc, name: "public lan", _public: true).create()

// create a server
Server server = new Server(dataCenter: dc, name: "Example server", cores: 1, ram: 1024).create()

// add a NIC to server
NIC nic = new NIC(server: server, lan: lan, name: "example nic").create()
assert nic.ips

// find a linux image to attach to server
Image image = new Image().all.collect{image.read(it) as Image}.findAll {
    it._public &&
    it.location == dc.location &&
    it.licenceType =~ /(?i)linux/ &&
    it.imageType =~ /(?i)hdd/
}.first()

// create a volume from that image
Volume volume = new Volume(dataCenter: dc, name: "OS volume", image: image.id, imagePassword: 'test1234').create()

// attach volume to server
attach server, volume

// delete datacenter
dc.delete()

TODO

Having proper life cycle control over your entities is helpful in the long run. The current approach to query for /request resources should be replaced by a future/promise based mechanism.
To circumvent hitting the rate limit there should be a way to indicate slowing down depending on the value of the X-RateLimit-Remaining and X-RateLimit-Burst response headers.

Support

You can engage with us in the ProfitBricks DevOps Central community, there we'll gladly answer any questions you might have about this SDK or the Profitbricks Cloud API.

Please report any issues or bugs your encounter using the GitHub Issue Tracker.

Testing

You can find a full test suite in src/test/groovy. Run all tests by issuing

./gradlew test \
-Dcom.profitbricks.sdk.user=YOUR_USERNAME \
-Dcom.profitbricks.sdk.password=YOUR_PASSWORD

Files

Readme.md

Latest commit

History