Go SDK

The ProfitBricks Client Library for Go provides you with access to the ProfitBricks REST API. It is designed for developers who are building applications in Go.

This guide will walk you through getting setup with the library and performing various actions against the API.

Concepts
Getting Started
Installation
How to: Create Data Center
How to: Delete Data Center
How to: Create Server
How to: List Available Images
How to: Create Storage Volume
How to: Update Cores and Memory
How to: Attach or Detach Storage Volume
How to: List Servers, Volumes, and Data Centers
Reference
Example
Support

Concepts

The Go SDK wraps the latest version of the ProfitBricks REST API. All API operations are performed over SSL and authenticated using your ProfitBricks portal credentials. The API can be accessed within an instance running in ProfitBricks 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 ProfitBricks account. The credentials you setup during sign-up will be used to authenticate against the API.

Install the Go language from: Go Installation

The GOPATH environment variable specifies the location of your Go workspace. It is likely the only environment variable you'll need to set when developing Go code. This is an example of pointing to a workspace configured underneath your home directory:

mkdir -p ~/go/bin
export GOPATH=~/go
export GOBIN=$GOPATH/bin
export PATH=$PATH:$GOBIN

Installation

The following go command will download profitbricks-sdk-go to your configured GOPATH:

go get "github.com/profitbricks/profitbricks-sdk-go"

The source code of the package will be located at:

$GOBIN\src\profitbricks-sdk-go

Create main package file example.go:

package main

import (
	"fmt"
)

func main() {
}

Import GO SDK:

import(
	"github.com/profitbricks/profitbricks-sdk-go"
)

Add your credentials for connecting to ProfitBricks:

profitbricks.SetAuth("username", "password")

Set depth:

profitbricks.SetDepth("5")

Depth controls the amount of data returned from the REST server ( range 1-5 ). The larger the number the more information is returned from the server. This is especially useful if you are looking for the information in the nested objects.

Caution: You will want to ensure you follow security best practices when using credentials within your code or stored in a file.

How To's

How To: Create Data Center

ProfitBricks introduces the concept of Data Centers. These are logically separated from one another and allow you to have a self-contained environment for all servers, volumes, networking, snapshots, and so forth. The goal is to give you the same experience as you would have if you were running your own physical data center.

The following code example shows you how to programmatically create a data center:

dcrequest := profitbricks.Datacenter{
		Properties: profitbricks.DatacenterProperties{
			Name:        "example.go3",
			Description: "description",
			Location:    "us/lasdev",
		},
	}

datacenter := profitbricks.CreateDatacenter(dcrequest)

How To: Create Data Center with Multiple Resources

To create a complex Data Center you would do this. As you can see, you can create quite a few of the objects you will need later all in one request.:

datacenter := model.Datacenter{
		Properties: model.DatacenterProperties{
			Name: "composite test",
			Location:location,
		},
		Entities:model.DatacenterEntities{
			Servers: &model.Servers{
				Items:[]model.Server{
					model.Server{
						Properties: model.ServerProperties{
							Name : "server1",
							Ram: 2048,
							Cores: 1,
						},
						Entities:model.ServerEntities{
							Volumes: &model.AttachedVolumes{
								Items:[]model.Volume{
									model.Volume{
										Properties: model.VolumeProperties{
											Type_:"HDD",
											Size:10,
											Name:"volume1",
											Image:"1f46a4a3-3f47-11e6-91c6-52540005ab80",
											Bus:"VIRTIO",
											ImagePassword:"test1234",
											SshKeys: []string{"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCoLVLHON4BSK3D8L4H79aFo..."},
										},
									},
								},
							},
							Nics: &model.Nics{
								Items: []model.Nic{
									model.Nic{
										Properties: model.NicProperties{
											Name : "nic",
											Lan : "1",
										},
									},
								},
							},
						},
					},
				},
			},
		},
	}
	
dc := CompositeCreateDatacenter(datacenter)

How To: Delete Data Center

You will want to exercise a bit of caution here. Removing a data center will destroy all objects contained within that data center -- servers, volumes, snapshots, and so on.

The code to remove a data center is as follows. This example assumes you want to remove previously data center:

profitbricks.DeleteDatacenter(response.Id)

How To: Create Server

The server create method has a list of required parameters followed by a hash of optional parameters. The optional parameters are specified within the "options" hash and the variable names match the REST API parameters.

The following example shows you how to create a new server in the data center created above:

req := profitbricks.Server{
 		Properties: profitbricks.ServerProperties{
 			Name:  "go01",
 			Ram:   1024,
 			Cores: 2,
 		},
}
server := CreateServer(datacenter.Id, req)

How To: List Available Images

A list of disk and ISO images are available from ProfitBricks for immediate use. These can be easily viewed and selected. The following shows you how to get a list of images. This list represents both CDROM images and HDD images.

images := profitbricks.ListImages()

This will return a collection object

How To: Create Storage Volume

ProfitBricks allows for the creation of multiple storage volumes that can be attached and detached as needed. It is useful to attach an image when creating a storage volume. The storage size is in gigabytes.

volumerequest := profitbricks.Volume{
		Properties: profitbricks.VolumeProperties{
			Size:        1,
			Name:        "Volume Test",
			LicenceType: "LINUX",
			Type:        "HDD",
		},
}

storage := CreateVolume(datacenter.Id, volumerequest)

How To: Update Cores and Memory

ProfitBricks allows users to dynamically update cores, memory, and disk independently of each other. This removes the restriction of needing to upgrade to the next size available size to receive an increase in memory. You can now simply increase the instances memory keeping your costs in-line with your resource needs.

Note: The memory parameter value must be a multiple of 256, e.g. 256, 512, 768, 1024, and so forth.

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

serverupdaterequest := profitbricks.ServerProperties{
	Cores: 1,
	Ram:   256,
}

resp := PatchServer(datacenter.Id, server.Id, serverupdaterequest)

How To: Attach or Detach Storage Volume

ProfitBricks allows for the creation of multiple storage volumes. You can detach and reattach these on the fly. This allows for various scenarios such as re-attaching a failed OS disk to another server for possible recovery or moving a volume to another location and spinning it up.

The following illustrates how you would attach and detach a volume and CDROM to/from a server:

profitbricks.AttachVolume(datacenter.Id, server.Id, volume.Id)
profitbricks.AttachCdrom(datacenter.Id, server.Id, images.Items[0].Id)

profitbricks.DetachVolume(datacenter.Id, server.Id, volume.Id)
profitbricks.DetachCdrom(datacenter.Id, server.Id, images.Items[0].Id)

How To: List Servers, Volumes, and Data Centers

Go SDK provides standard functions for retrieving a list of volumes, servers, and datacenters.

The following code illustrates how to pull these three list types:

volumes := profitbricks.ListVolumes(datacenter.Id)

servers := profitbricks.ListServers(datacenter.Id)

datacenters := profitbricks.ListDatacenters()

Reference

Data Centers

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

type Datacenter

Property Name	Type	Description
Id	String	Unique identifier of the object
Type_	String	Type of the object as returned from the Cloud API
Href	String	URL to the object’s representation
Headers	*http.Header	Response headers
Response	string	Raw JSON response
StatusCode	int	Http response status code
Metadata	*Metadata	See Metadata
Properties	DatacenterProperties	See DatacenterProperties
Entities	DatacenterEntities	See DatacenterEntities

type Metadata

Property Name	Type	Description
CreatedDate	time.Time	The date when the resource was created.
CreatedBy	string	The user who created the resource.
Etag	string	The etag for the request.
LastModifiedDate	time.Time	The last time the resource has been modified.
LastModifiedBy	string	The user who last modified the resource.
State	string	AVAILABLE There are no pending modification requests for this item; BUSY There is at least one modification request pending and all following requests will be queued; INACTIVE Resource has been de-provisioned.

type DatacenterProperties

Property Name	Type	Description
Name	string	Name of the data center
Description	string	Description of the data center
Location	string	Location of the data center
Version	int32	The version of the data center

The following table outlines the locations currently supported:

ID	Country	City
us/las	United States	Las Vegas
de/fra	Germany	Frankfurt
de/fkb	Germany	Karlsruhe

type DatacenterEntities

Property Name	Type	Description
Servers	*Servers	See Servers
Volumes	*Volumes	See Volumes
Loadbalancers	*Loadbalancers	See LoadBalancers
Lans	*Lans	See Lans

type Datacenters

Property Name	Type	Description
Id	String	Unique identifier of the object
Type_	String	Type of the object as returned from the Cloud API
Href	String	URL to the object’s representation
Headers	*http.Header	Response headers
Response	string	Raw JSON response
StatusCode	int	Http response status code
Metadata	*Metadata	See Metadata
Items	[]Datacenter	Array of Datacenters

List Data Centers

func ListDatacenters() Datacenters

Retrieve a Data Center

func GetDatacenter(dcid string) Datacenter

Create a Data Center

func CreateDatacenter(dc Datacenter) Datacenter

Notes:

The value for name cannot contain the following characters: (@, /, , |, ‘’, ‘).
You cannot change a data center's location once it has been provisioned.

Update a Data Center

func PatchDatacenter(dcid string, obj DatacenterProperties) Datacenter

Delete a Data Center

func DeleteDatacenter(dcid string) Resp

Note: This is a highly destructive operation that will remove both the data center and all objects within the datacenter. This should be used with extreme caution.

Servers

Description here...

type Server

Name	Type	Description
Id	String	Unique identifier of the object
Type_	String	Type of the object as returned from the Cloud API
Href	String	URL to the object’s representation
Headers	*http.Header	Response headers
Response	string	Raw JSON response
StatusCode	int	Http response status code
Metadata	*Metadata	See Metadata
Properties	ServerProperties	See ServerProperties
Entities	*ServerEntities	See ServerEntities

The following table outlines the various licence types you can define:

Licence Type	Description
WINDOWS	You must specify this if you are using your own, custom Windows image due to Microsoft's licensing terms.
LINUX
UNKNOWN	If you are using an image uploaded to your account your OS Type will inherit as UNKNOWN.

The following table outlines the availability zones currently supported:

Availability Zone	Description
AUTO	Automatically selected zone
ZONE_1	Zone 1
ZONE_2	Zone 2
ZONE_3	Zone 3

type ServerProperties

Name	Type	Description
Name	string	The hostname of the server.
Cores	int	The total number of cores for the server.
Ram	int	The amount of memory for the server in MB, e.g. 2048.
AvailabilityZone	string	The availability zone in which the server should exist.
VmState	string	Status of the virtual Machine.
BootCdrom	*ResourceReference	Reference to a CD-ROM used for booting.
BootVolume	*ResourceReference	Reference to a Volume used for booting.
CpuFamily	string	Type of CPU assigned.

type ServerEntities

Name	Type	Description
Cdroms	*Cdroms	See Cdrom
Volumes	*Volumes	See Volumes
Nics	*Nics	See Nics

type Servers

Name	Type	Description
Id	String	Unique identifier of the object
Type_	String	Type of the object as returned from the Cloud API
Href	String	URL to the object’s representation
Headers	*http.Header	Response headers
Response	string	Raw JSON response
StatusCode	int	Http response status code
Metadata	*Metadata	See Metadata
Items	[]Server	Array of Servers

List Servers

func ListServers(dcid string) Server

Retrieve a Server

Returns information about a server such as its configuration, provisioning status, etc.

func GetServer(dcid, srvid string) Servers

Create a Server

Creates a server within an existing data center. You can configure additional properties such as specifying a boot volume and connecting the server to an existing LAN.

func CreateServer(dcid string, server Server) Server

Update a Server

Perform updates to attributes of a server.

func PatchServer(dcid string, srvid string, props ServerProperties) Server

Delete a Server

This will remove a server from a data center. NOTE: This will not automatically remove the storage volume(s) attached to a server. A separate API call is required to perform that action.

The following table describes the request arguments:

Name	Type	Description	Required
dcid	string	The ID of the data center.	Yes
srvid	string	The ID of the server.	Yes

func DeleteServer(dcid, srvid string) Resp

Reboot a Server

This will force 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.

func RebootServer(dcid, srvid string) Resp

Start a Server

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

func StartServer(dcid, srvid string) Resp

Stop a Server

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

func StopServer(dcid, srvid string) Resp

Attach a CDROM

This will attach a CDROM to the server.

func AttachCdrom(dcid string, srvid string, cdid string) Image

Detach a CDROM

This will detach the CDROM from the server. Depending on the volume "hot_unplug" settings, this may result in the server being rebooted.

func DetachCdrom(dcid, srvid, cdid string) Resp

List attached CDROMs

This will list CDROMs that are attached to the server

func ListAttachedCdroms(dcid, srvid string) Images

Get attached CDROM

This will retrieve a CDROM that is attached to the server.

func GetAttachedCdrom(dcid, srvid, cdid string) Image

Volumes

Description here...

type Volume

Name	Type	Description
Id	String	Unique identifier of the object
Type_	String	Type of the object as returned from the Cloud API
Href	String	URL to the object’s representation
Headers	*http.Header	Response headers
Response	string	Raw JSON response
StatusCode	int	Http response status code
Metadata	*Metadata	See Metadata
Properties	VolumeProperties	See VolumeProperties

type VolumeProperties

Name	Type	Description
Name	string	The name of the volume.
Type	string	The volume type, HDD or SSD.
Size	int	The size of the volume in GB.
AvailabilityZone	string	The storage availability zone assigned to the volume.
Image	string	The image or snapshot ID.
ImagePassword	string	Always returns "null".
SshKeys	[]string	Always returns "null".
Bus	string	The bus type: VIRTIO or IDE. Returns "null" if not connected to a server.
LicenceType	string	Licence type.
CpuHotPlug	bool	This volume is capable of CPU hot plug
CpuHotUnplug	bool	This volume is capable of CPU hot unplug
RamHotPlug	bool	This volume is capable of memory hot plug
RamHotUnplug	bool	This volume is capable of memory hot unplug
NicHotPlug	bool	This volume is capable of nic hot plug
NicHotUnplug	bool	This volume is capable of nic hot unplug
DiscVirtioHotPlug	bool	This volume is capable of VirtIO drive hot plug
DiscVirtioHotUnplug	bool	This volume is capable of VirtIO drive hot unplug
DiscScsiHotPlug	bool	This volume is capable of SCSI drive hot plug
DiscScsiHotUnplug	bool	This volume is capable of SCSI drive hot unplug
DeviceNumber	int64	The LUN ID of the storage volume.

type Volumes

Name	Type	Description
Id	String	Unique identifier of the object
Type_	String	Type of the object as returned from the Cloud API
Href	String	URL to the object’s representation
Headers	*http.Header	Response headers
Response	string	Raw JSON response
StatusCode	int	Http response status code
Metadata	*Metadata	See Metadata
Items	[]Volume	Array of Volumes

List Volumes

func ListVolumes(dcid string) Volumes

Retrieve a Volume

func GetVolume(dcid string, volumeId string) Volume

Update a Volume

func PatchVolume(dcid string, volid string, request VolumeProperties) Volume

Create a Volume

func CreateVolume(dcid string, request Volume) Volume

Delete a Volume

This will delete a volume.

func DeleteVolume(dcid, volid string) Resp

NICs

type Nic

Name	Type	Description
Id	String	Unique identifier of the object
Type_	String	Type of the object as returned from the Cloud API
Href	String	URL to the object’s representation
Headers	*http.Header	Response headers
Response	string	Raw JSON response
StatusCode	int	Http response status code
Metadata	*Metadata	See Metadata
Properties	NicProperties	See NicProperties
Entities	*NicEntities	See NicEntities

type NicProperties

Name	Type	Description
Name	string	The name of the NIC.
Mac	string	The MAC address of the NIC.
Ips	[]string	IPs assigned to the NIC represented as a collection of strings
Dhcp	bool	Boolean value that indicates if the NIC is using DHCP or not.
Lan	int	The LAN ID the NIC sits on.
FirewallActive	bool	A true value indicates the firewall is enabled. A false value indicates the firewall is disabled.
Nat	bool	Boolean value indicating if the private IP address has outbound access to the public internet.

type NicEntities

Name	Type	Description
Firewallrules	talk*Firewallrules	See Firewallrules

type Nics

Name	Type	Description
Id	String	Unique identifier of the object
Type_	String	Type of the object as returned from the Cloud API
Href	String	URL to the object’s representation
Headers	*http.Header	Response headers
Response	string	Raw JSON response
StatusCode	int	Http response status code
Metadata	*Metadata	See Metadata
Items	[]Nic	Array of Nics

List NICs

Retrieve a list of LANs within the data center.

func ListNics(dcid, srvid string)Nics

Get a NIC

Retrieves the attributes of a given NIC.

func GetNic(dcid, srvid, nicid string) Nic

Create a NIC

Adds a NIC to the target server.

func CreateNic(dcid string, srvid string, request Nic) Nic

Update a NIC

You can update -- in full or partially -- various attributes on the NIC; however, some restrictions are in place:

The primary address of a NIC connected to a load balancer can only be changed by changing the IP of the load balancer. You can also add additional reserved, public IPs to the NIC.

The user can specify and assign private IPs manually. Valid IP addresses for private networks are 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16.

func PatchNic(dcid string, srvid string, nicid string, obj NicProperties) Nic

Delete a NIC

This will delete a volume

func DeleteNic(dcid, srvid, nicid string) Resp

Example

package main

import (
	"fmt"
	"time"

	"github.com/profitbricks/profitbricks-sdk-go"
)

func main() {

	//Sets username and password
	profitbricks.SetAuth("username", "password")
	//Sets depth.
	profitbricks.SetDepth("5")

	dcrequest := profitbricks.Datacenter{
		Properties: profitbricks.DatacenterProperties{
			Name:        "example.go3",
			Description: "description",
			Location:    "us/lasdev",
		},
	}

	datacenter := profitbricks.CreateDatacenter(dcrequest)

	serverrequest := profitbricks.Server{
		Properties: profitbricks.ServerProperties{
			Name:  "go01",
			Ram:   1024,
			Cores: 2,
		},
	}
	server := profitbricks.CreateServer(datacenter.Id, serverrequest)

	volumerequest := profitbricks.Volume{
		Properties: profitbricks.VolumeProperties{
			Size:        1,
			Name:        "Volume Test",
			LicenceType: "LINUX",
			Type:        "HDD",
		},
	}

	storage := profitbricks.CreateVolume(datacenter.Id, volumerequest)

	serverupdaterequest := profitbricks.ServerProperties{
		Name:  "go01renamed",
		Cores: 1,
		Ram:   256,
	}

	profitbricks.PatchServer(datacenter.Id, server.Id, serverupdaterequest)
	//It takes a moment for a volume to be provisioned so we wait.
	time.Sleep(60 * time.Second)

	profitbricks.AttachVolume(datacenter.Id, server.Id, storage.Id)

	volumes := profitbricks.ListVolumes(datacenter.Id)
	fmt.Println(volumes.Items)
	servers := profitbricks.ListServers(datacenter.Id)
	fmt.Println(servers.Items)
	datacenters := profitbricks.ListDatacenters()
	fmt.Println(datacenters.Items)

	profitbricks.DeleteServer(datacenter.Id, server.Id)
	profitbricks.DeleteDatacenter(datacenter.Id)
}

Support

You are welcome to contact us with questions or comments at ProfitBricks DevOps Central. Please report any issues via GitHub's issue tracker.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation