Fog is an open-source, community Ruby library used for interacting with popular cloud infrastructure providers through a single, unified API.

This guide will show you how to programmatically use the ProfitBricks provider in Fog to perform common management tasks available in the ProfitBricks Data Center Designer.

Concepts

The Fog library wraps the Cloud API, a REST API that allows management of ProfitBricks compute, storage, and networking resources. 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.

The Fog library provides two methods of interacting with ProfitBricks. The first method utilizes an abstracted collection and model layer that is similar across all cloud providers within Fog.

A collection is a group of similar resources such as virtual datacenters, servers, or volumes and allows basic CRUD (create/read/update/delete) operations on collections and models. This guide will cover interactions with the ProfitBricks environment solely using collections and models.

While out of scope of this guide, the second Fog method provides direct request methods that specifically match provider API methods. In the case of the ProfitBricks provider, the request methods map to the ProfitBricks Cloud API methods and parameters. More details on requests can be found at the Fog website.

Getting Started

Before you begin, you will need to have signed up for a IONOS account. The credentials you create during sign-up will be used to authenticate against the API.

For more information on the ProfitBricks Cloud API, visit the API documentation page.

Installation

Add this line to your application's Gemfile:

gem 'fog-profitbricks'

And then execute:

$ bundle

Or install it yourself as:

$ gem install fog-profitbricks

Authentication

Provide your credentials when creating a compute object:

compute = Fog::Compute.new(:provider => 'ProfitBricks', :profitbricks_username => 'username', :profitbricks_password => 'password')

Operations

Data Centers

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 data centers as you want. Data centers have their own private network and are logically segmented from each other to create isolation.

List Data Centers

compute.datacenters.all

---

Retrieve a Data Center

The following table describes the request arguments:

compute.datacenters.get('datacenter_id')

---

Create a Data Center

The following table describes the request arguments:

The following table outlines the locations currently supported:

datacenter = compute.datacenters.create(:name => 'My data center', :location => 'us/las', :description => 'My data center description')

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

After retrieving a data center, either by getting it by id, or as a create response object, you can change it's properties and call the update method:

datacenter.name = 'My data center updated name'
datacenter.update

The following table describes the request arguments:

---

Delete a Data Center

This will remove all objects within the data center and remove the data center object itself.

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

datacenter.delete

---

Locations

Locations represent regions where you can provision your Virtual Data Centers.

List Locations

compute.locations.all

---

Get a Location

Retrieves the attributes of a given location.

The following table describes the request arguments:

compute.locations.get('us/las')

---

Servers

List Servers

You can retrieve a list of all servers within a data center.

The following table describes the request arguments:

compute.servers.all('datacenter_id')

---

Retrieve a Server

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

The following table describes the request arguments:

compute.servers.get('datacenter_id', 'server-id')

---

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.

The following table describes the request arguments:

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

The following table outlines the availability zones currently supported:

compute.servers.create(:datacenter_id => 'datacenter_id', :name => 'My server', :cores => 2, :ram => 2048, :availability_zone => 'AUTO', :licence_type => 'LINUX')

NOTE: When creating a volume, you must specify either the licence_type or an image.

---

Update a Server

Perform updates to attributes of a server.

The following table describes the request arguments:

After retrieving a server, either by getting it by id, or as a create response object, you can change it's properties and call the update method:

server = compute.servers.get('datacenter_id', 'server-id')
server.name = 'Updated server name'
server.ram = 1024
server.update

---

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:

After retrieving a server, either by getting it by id, or as a create response object, you can call the delete method directly on the object:

server = compute.servers.get('datacenter_id', 'server-id')
server.delete

---

List Attached Volumes

Retrieves a list of volumes attached to the server.

The following table describes the request arguments:

After retrieving a server, either by getting it by id, or as a create response object, you can call the get_volumes method directly on the object:

server = compute.servers.get('datacenter_id', 'server-id')
server.get_volumes

---

Attach a Volume

This will attach a pre-existing storage volume to the server.

The following table describes the request arguments:

After retrieving a server, either by getting it by id, or as a create response object, you can call the attach_volume method directly on the object:

server = compute.servers.get('datacenter_id', 'server-id')
server.attach_volume('storage-id')

---

Retrieve an Attached Volume

This will retrieve the properties of an attached volume.

The following table describes the request arguments:

After retrieving a server, either by getting it by id, or as a create response object, you can call the get_attached_volume method directly on the object:

server = compute.servers.get('datacenter_id', 'server-id')
server.get_attached_volume('volume-id')

---

Detach a Volume

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

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

The following table describes the request arguments:

After retrieving a server, either by getting it by id, or as a create response object, you can call the detach_volume method directly on the object:

server = compute.servers.get('datacenter_id', 'server-id')
server.detach_volume('volume-id')

---

List Attached CD-ROMs

Retrieves a list of CD-ROMs attached to the server.

The following table describes the request arguments:

After retrieving a server, either by getting it by id, or as a create response object, you can call the get_cdroms method directly on the object:

server = compute.servers.get('datacenter_id', 'server-id')
server.get_cdroms

---

Attach a CD-ROM

You can attach a CD-ROM to an existing server.

The following table describes the request arguments:

After retrieving a server, either by getting it by id, or as a create response object, you can call the attach_cdrom method directly on the object:

server = compute.servers.get('datacenter_id', 'server-id')
server.attach_cdrom('cdrom-image-id')

---

Retrieve an Attached CD-ROM

You can retrieve a specific CD-ROM attached to the server.

The following table describes the request arguments:

After retrieving a server, either by getting it by id, or as a create response object, you can call the get_attached_cdrom method directly on the object:

server = compute.servers.get('datacenter_id', 'server-id')
server.get_attached_cdrom('cdrom-id')

---

Detach a CD-ROM

This will detach a CD-ROM from the server.

The following table describes the request arguments:

After retrieving a server, either by getting it by id, or as a create response object, you can call the detach_cdrom method directly on the object:

server = compute.servers.get('datacenter_id', 'server-id')
server.detach_cdrom('cdrom-id')

---

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.

The following table describes the request arguments:

After retrieving a server, either by getting it by id, or as a create response object, you can call the reboot method directly on the object:

server = compute.servers.get('datacenter_id', 'server-id')
server.reboot

---

Start a Server

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

The following table describes the request arguments:

After retrieving a server, either by getting it by id, or as a create response object, you can call the start method directly on the object:

server = compute.servers.get('datacenter_id', 'server-id')
server.start

---

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.

The following table describes the request arguments:

After retrieving a server, either by getting it by id, or as a create response object, you can call the stop method directly on the object:

server = compute.servers.get('datacenter_id', 'server-id')
server.stop

---

Volumes

List Volumes

Retrieve a list of volumes within the data center. If you want to retrieve a list of volumes attached to a server please see the Servers section for examples on how to do so.

The following table describes the request arguments:

compute.volumes.all('datacenter_id')

---

Get a Volume

Retrieves the attributes of a given volume.

The following table describes the request arguments:

compute.volumes.get('datacenter_id', 'volume-id')

---

Create a Volume

Creates a volume within the data center. This will NOT attach the volume to a server. Please see the Servers section for details on how to attach storage volumes.

The following table describes the request arguments:

*You will need to provide either the image or the licenceType parameters. licenceType is required, but if image is supplied, it will already have a licenceType set.

volume = compute.volumes.create(:datacenter_id => 'datacenter_id', :size => 5, :type => 'HDD', :licence_type => 'LINUX')

---

Update a Volume

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

You can increase the size of an existing storage volume. You cannot reduce the size of an existing storage volume. The volume size will be increased without reboot if the hot plug settings have been set to true. The additional capacity is not added to any partition therefore you will need to partition it afterwards. Once you have increased the volume size you cannot decrease the volume size.

Since an existing volume is being modified , none of the request parameters are specifically required as long as the changes being made satisfy the requirements for creating a volume.

After retrieving a volume, either by getting it by id, or as a create response object, you can change it's properties and call the update method:

volume = compute.volumes.get('datacenter_id', 'volume-id')
volume.name = 'My volume'
volume.update

---

Delete a Volume

Deletes the specified volume. This will result in the volume being removed from your data center. Use this with caution.

After retrieving a volume, either by getting it by id, or as a create response object, you can call the delete method directly on the object:

volume = compute.volumes.get('datacenter_id', 'volume-id')
volume.delete

---

Create a Volume Snapshot

Creates a snapshot of a volume within the data center. You can use a snapshot to create a new storage volume or to restore a storage volume.

The following table describes the request arguments:

After retrieving a volume, either by getting it by id, or as a create response object, you can call the create_snapshot method directly on the object:

volume = compute.volumes.get('datacenter_id', 'volume-id')
volume.create_snapshot('My snapshot', 'My snapshot description')

---

Restore a Volume Snapshot

This will restore a snapshot onto a volume. A snapshot is created as just another image that can be used to create new volumes or to restore an existing volume.

The following table describes the request arguments:

After retrieving a volume, either by getting it by id, or as a create response object, you can call the restore_snapshot method directly on the object:

volume = compute.volumes.get('datacenter_id', 'volume-id')
volume.restore_snapshot('snapshotId')

---

Snapshots

List Snapshots

You can retrieve a list of all snapshots.

compute.snapshots.all

---

Get a Snapshot

Retrieves the attributes of a specific snapshot.

The following table describes the request arguments:

compute.snapshots.get('snapshotId')

---

Update a Snapshot

Perform updates to attributes of a snapshot.

The following table describes the request arguments:

After retrieving a snapshot, either by getting it by id, or as a create response object, you can change it's properties and call the update method:

snapshot = compute.snapshots.get('snapshotId')
snapshot.name = 'Updated snapshot name'
snapshot.description = 'Updated snapshot description'
snapshot.nic_hot_plug = true
snapshot.nic_hot_unplug = true
snapshot.update

---

Delete a Snapshot

Deletes the specified snapshot.

The following table describes the request arguments:

After retrieving a snapshot, either by getting it by id, or as a create response object, you can call the delete method directly on the object:

snapshot = compute.snapshots.get('snapshotId')
snapshot.delete

---

Load Balancers

List Load Balancers

Retrieve a list of load balancers within the data center.

compute.load_balancers.all('datacenter_id')

---

Get a Load Balancer

Retrieves the attributes of a given load balancer.

compute.load_balancers.get('datacenter_id', 'load_balancer_id')

---

Create a Load Balancer

Creates a load balancer within the data center. Load balancers can be used for public or private IP traffic.

compute.load_balancers.create(:datacenter_id => 'datacenter_id', :name => 'My load balancer')

---

Update a Load Balancer

Perform updates to attributes of a load balancer.

After retrieving a load balancer, either by getting it by id, or as a create response object, you can change it's properties and call the update method:

load_balancer = compute.load_balancers.get('datacenter_id', 'load_balancer_id')
load_balancer.name = 'Updated load balancer name'
load_balancer.update

---

Delete a Load Balancer

Deletes the specified load balancer.

After retrieving a load balancer, either by getting it by id, or as a create response object, you can call the delete method directly on the object:

load_balancer = compute.load_balancers.get('datacenter_id', 'load_balancer_id')
load_balancer.delete

---

List Load Balanced NICs

This will retrieve a list of NICs associated with the load balancer.

After retrieving a load balancer, either by getting it by id, or as a create response object, you can call the get_nics method directly on the object:

load_balancer = compute.load_balancers.get('datacenter_id', 'load_balancer_id')
load_balancer.get_nics

---

Get a Load Balanced NIC

Retrieves the attributes of a given load balanced NIC.

After retrieving a load balancer, either by getting it by id, or as a create response object, you can call the get_nic method directly on the object:

load_balancer = compute.load_balancers.get('datacenter_id', 'load_balancer_id')
load_balancer.get_nic('nic_id')

---

Associate NIC to a Load Balancer

This will associate a NIC to a Load Balancer, enabling the NIC to participate in load-balancing.

After retrieving a load balancer, either by getting it by id, or as a create response object, you can call the associate_nic method directly on the object:

load_balancer = compute.load_balancers.get('datacenter_id', 'load_balancer_id')
load_balancer.associate_nic('nic_id')

---

Remove a NIC Association

Removes the association of a NIC with a load balancer.

After retrieving a load balancer, either by getting it by id, or as a create response object, you can call the remove_nic_association method directly on the object:

load_balancer = compute.load_balancers.get('datacenter_id', 'load_balancer_id')
load_balancer.remove_nic_association('nic_id')

---

Firewall Rules

List Firewall Rules

Retrieves a list of firewall rules associated with a particular NIC.

compute.firewall_rules.all('datacenter_id', 'server_id', 'nic_id')

---

Get a Firewall Rule

Retrieves the attributes of a given firewall rule.

fwr = compute.firewall_rules.get('datacenter_id', 'server_id', 'nic_id', 'firewall_rule_id')

---

Create a Firewall Rule

This will add a firewall rule to the NIC.

The following table describes the request arguments:

fwr = compute.firewall_rules.create(:datacenter_id => 'datacenter_id', :server_id => 'server-id', :nic_id => 'nic_id', :name => 'My firewall rule', :protocol => 'ANY')

---

Update a Firewall Rule

Perform updates to attributes of a firewall rule.

The following table describes the request arguments:

After retrieving a firewall rule, either by getting it by id, or as a create response object, you can change its properties and call the update method:

fwr = compute.firewall_rules.get('datacenter_id', 'server_id', 'nic_id', 'firewall_rule_id')
fwr.name = 'Updated firewall rule name'
fwr.update

---

Delete a Firewall Rule

Removes the specific firewall rule.

After retrieving a firewall rule, either by getting it by id, or as a create response object, you can call the delete method directly on the object:

fwr = compute.firewall_rules.get('datacenter_id', 'server_id', 'nic_id', 'firewall_rule_id')
fwr.delete

---

Images

List Images

Retrieve a list of images.

compute.images.all

---

Get an Image

Retrieves the attributes of a specific image.

The following table describes the request arguments:

compute.images.get('image-id')

---

Update an Image

Perform updates to attributes of an image.

The following table describes the request arguments:

After retrieving an image, either by getting it by id, or as a create response object, you can change it's properties and call the update method:

image = compute.snapshots.get('snapshotId')
image.name = 'Updated snapshot name'
image.description = 'Updated snapshot description'
image.ram_hot_plug = true
image.ram_hot_unplug = true
image.update

---

Delete an Image

Deletes the specified image.

The following table describes the request arguments:

After retrieving an image, either by getting it by id, or as a create response object, you can call the delete method directly on the object:

image = compute.images.get('image-id')
image.delete

---

Network Interfaces (NICs)

List NICs

Retrieve a list of LANs within the data center.

The following table describes the request arguments:

compute.nics.all('datacenter_id')

---

Get a NIC

Retrieves the attributes of a given NIC.

The following table describes the request arguments:

compute.nics.get('datacenter_id', 'server-id', 'nic-id')

---

Create a NIC

Adds a NIC to the target server.

The following table describes the request arguments:

compute.nics.create(:datacenter_id => 'datacenter_id', :server_id => 'server_id', :name = 'Internal NIC', :dhcp => true, :lan => 1)

---

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.

The following table describes the request arguments:

After retrieving a NIC, either by getting it by id, or as a create response object, you can call the update method directly on the object:

nic = compute.nics.get('datacenter_id', 'server-id', 'nic-id')
nic.name = 'Internal NIC updated'
nic.ips = ['10.0.0.7']
nic.update

---

Delete a NIC

Deletes the specified NIC.

The following table describes the request arguments:

After retrieving a NIC, either by getting it by id, or as a create response object, you can call the delete method directly on the object:

nic = compute.nics.get('datacenter_id', 'server-id', 'nic-id')
nic.delete

---

IP Blocks

List IP Blocks

Retrieve a list of IP Blocks.

compute.ip_blocks.all

---

Get an IP Block

Retrieves the attributes of a specific IP Block.

The following table describes the request arguments:

compute.ip_blocks.get('ipblock-id')

---

Create an IP Block

Creates an IP block.

The following table describes the request arguments:

compute.ip_blocks.create(:location => 'de/fkb', :size => 1, :name => 'Fog test IP block')

---

Delete an IP Block

Deletes the specified IP Block.

The following table describes the request arguments:

After retrieving an IP block, either by getting it by id, or as a create response object, you can call the delete method directly on the object:

ipb = compute.ip_blocks.get('ipblock-id')
ipb.delete

compute.ip_blocks.get('ipblock-id')

---

Requests

List Requests

Retrieve a list of requests.

compute.requests.all

---

Get a Request

Retrieves the attributes of a specific request.

The following table describes the request arguments:

compute.requests.get('request-id')

---

Get a Request Status

Retrieves the status of a request.

The following table describes the request arguments:

compute.requests.get_status('request-id')

---

LANs

List LANs

Retrieve a list of LANs within the data center.

The following table describes the request arguments:

compute.lans.all('datacenter_id')

---

Create a LAN

Creates a LAN within a data center.

The following table describes the request arguments:

compute.lans.create(:datacenter_id => 'datacenter_id', :name => 'My lan', :public => false)

---

Get a LAN

Retrieves the attributes of a given LAN.

The following table describes the request arguments:

compute.lans.get('datacenter_id', 'lan-id')

---

Update a LAN

Perform updates to attributes of a LAN.

The following table describes the request arguments:

After retrieving a LAN, either by getting it by id, or as a create response object, you can change it's properties and call the update method:

lan = compute.lans.get('datacenter_id', 'lan-id')
lan.name = 'Updated LAN name'
lan.update

---

Delete a LAN

Deletes the specified LAN.

The following table describes the request arguments:

After retrieving a LAN, either by getting it by id, or as a create response object, you can call the delete method directly on the object:

lan = compute.lans.get('datacenter_id', 'lan-id')
lan.delete

---

Contributing

1. Fork it ( https://github.com/fog/fog-profitbricks/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request