Profitbricks Groovy SDK

The official Groovy/Java SDK for the Profitbricks Cloud API v4.

License

License

Categories

Categories

Groovy Languages
GroupId

GroupId

com.profitbricks
ArtifactId

ArtifactId

groovy-sdk
Last Version

Last Version

3.1.0
Release Date

Release Date

Type

Type

jar
Description

Description

Profitbricks Groovy SDK
The official Groovy/Java SDK for the Profitbricks Cloud API v4.
Project URL

Project URL

https://github.com/profitbricks/profitbricks-sdk-groovy
Source Code Management

Source Code Management

https://github.com/profitbricks/profitbricks-sdk-groovy/tree/master

Download groovy-sdk

How to add to project

<!-- https://jarcasting.com/artifacts/com.profitbricks/groovy-sdk/ -->
<dependency>
    <groupId>com.profitbricks</groupId>
    <artifactId>groovy-sdk</artifactId>
    <version>3.1.0</version>
</dependency>
// https://jarcasting.com/artifacts/com.profitbricks/groovy-sdk/
implementation 'com.profitbricks:groovy-sdk:3.1.0'
// https://jarcasting.com/artifacts/com.profitbricks/groovy-sdk/
implementation ("com.profitbricks:groovy-sdk:3.1.0")
'com.profitbricks:groovy-sdk:jar:3.1.0'
<dependency org="com.profitbricks" name="groovy-sdk" rev="3.1.0">
  <artifact name="groovy-sdk" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.profitbricks', module='groovy-sdk', version='3.1.0')
)
libraryDependencies += "com.profitbricks" % "groovy-sdk" % "3.1.0"
[com.profitbricks/groovy-sdk "3.1.0"]

Dependencies

compile (3)

Group / Artifact Type Version
org.codehaus.groovy : groovy-all jar 2.4.15
org.codehaus.groovy.modules.http-builder : http-builder jar 0.7.2
org.apache.logging.log4j : log4j-core jar 2.11.0

runtime (1)

Group / Artifact Type Version
org.apache.logging.log4j : log4j-jcl jar 2.11.0

test (1)

Group / Artifact Type Version
org.spockframework : spock-core jar 1.1-groovy-2.4

Project Modules

There are no modules declared in this project.

Groovy SDK

Version: 3.1.0

Profitbricks Groovy/Java SDK

Table of Contents

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: "[email protected]",
    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
com.profitbricks

1&1 IONOS Cloud GmbH

ProfitBricks is now 1&1 IONOS Cloud GmbH

Versions

Version
3.1.0
3.0.0