Fog::profitbricks

Module for the 'fog' gem to support ProfitBricks Cloud API.

• Getting Started
  • Installation
  • Authentication
• Operations
  • Data Centers
    • List Data Centers
    • Retrieve a Data Center
    • Create a Data Centers
    • Update a Data Centers
    • Delete a Data Centers
  • Locations
    • List Locations
    • Get a Location
  • Servers
    • List Servers
    • Retrieve a Server
    • Create a Server
    • Update a Server
    • Delete a Server
    • List Attached Volumes
    • Attach a Volume
    • Retrieve an Attached Volume
    • Detach a Volume
    • List Attached CD-ROMs
    • Attach a CD-ROM
    • Retrieve an Attached CD-ROM
    • Detach a CD-ROM
    • Reboot a Server
    • Start a Server
    • Stop a Server
  • Volumes
    • List Volumes
    • Get a Volume
    • Create a Volume
    • Update a Volume
    • Delete a Volume
    • Create a Volume Snapshot
    • Restore a Volume Snapshot
  • Snapshots
    • List Snapshots
    • Get a Snapshot
    • Update a Snapshot
    • Delete a Snapshot
  • Load Balancers
    • List Load Balancers
    • Get a Load Balancer
    • Create a Load Balancer
    • Update a Load Balancer
    • List Load Balanced NICs
    • Get a Load Balanced NIC
    • Associate NIC to a Load Balancer
    • Remove a NIC Association
  • Firewall Rules
    • List Firewall Rules
    • Get a Firewall Rule
    • Create a Firewall Rule
    • Update a Firewall Rule
    • Delete a Firewall Rule
  • Images
    • List Images
    • Get an Image
    • Update an Image
    • Delete an Image
  • Network Interfaces (NICs)
    • List NICs
    • Get a NIC
    • Create a NIC
    • Update a NIC
    • Delete a NIC
  • IP Blocks
    • List IP Blocks
    • Get an IP Block
    • Create an IP Block
    • Delete an IP Block
  • Requests
    • List Requests
    • Get a Request
    • Get a Request Status
  • LANs
    • List LANs
    • Create a LAN
    • Get a LAN
    • Update a LAN
    • Delete a LAN
  • Contract Resources
    • List Contract Resources
  • User Management
    • List Groups
    • Retrieve a Group
    • Create a Group
    • Update a Group
    • Delete a Group
    • List Shares
    • Retrieve a Share
    • Add a Share
    • Update a Share
    • Delete a Share
    • List Users in a Group
    • Add User to Group
    • Remove User from a Group
    • List Users
    • Retrieve a User
    • Create a User
    • Update a User
    • Delete a User
    • List Resources
    • List All Resources of a Type
    • List a Specific Resource Type
  • Contributing

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

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

Add this line to your application's Gemfile:

gem 'fog-profitbricks'

And then execute:

$ bundle

Or install it yourself as:

$ gem install fog-profitbricks

Provide your credentials when creating a compute object:

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

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.

compute.datacenters.all

The following table describes the request arguments:

compute.datacenters.get('datacenter_id')

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.

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:

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 represent regions where you can provision your Virtual Data Centers.

compute.locations.all

Retrieves the attributes of a given location.

The following table describes the request arguments:

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

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

The following table describes the request arguments:

compute.servers.all('datacenter_id')

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')

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.

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

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

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

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')

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')

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')

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

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')

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')

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')

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

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

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

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')

Retrieves the attributes of a given volume.

The following table describes the request arguments:

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

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 is already set and cannot be changed. Similarly either the imagePassword or sshKeys parameters need to be supplied when creating a volume. We recommend setting a valid value for imagePassword even when using sshKeys so that it is possible to authenticate using the remote console feature of the DCD.

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

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

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

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')

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')

You can retrieve a list of all snapshots.

compute.snapshots.all

Retrieves the attributes of a specific snapshot.

The following table describes the request arguments:

compute.snapshots.get('snapshotId')

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

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

Retrieve a list of load balancers within the data center.

compute.load_balancers.all('datacenter_id')

Retrieves the attributes of a given load balancer.

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

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')

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

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

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

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')

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')

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')

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

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

Retrieves the attributes of a given firewall rule.

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

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')

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

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

Retrieve a list of images.

compute.images.all

Retrieves the attributes of a specific image.

The following table describes the request arguments:

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

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

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

Retrieve a list of LANs within the data center.

The following table describes the request arguments:

compute.nics.all('datacenter_id')

Retrieves the attributes of a given NIC.

The following table describes the request arguments:

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

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)

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

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

Retrieve a list of IP Blocks.

compute.ip_blocks.all

Retrieves the attributes of a specific IP Block.

The following table describes the request arguments:

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

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')

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')

Retrieve a list of requests.

compute.requests.all

Retrieves the attributes of a specific request.

The following table describes the request arguments:

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

Retrieves the status of a request.

The following table describes the request arguments:

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

Retrieve a list of LANs within the data center.

The following table describes the request arguments:

compute.lans.all('datacenter_id')

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)

Retrieves the attributes of a given LAN.

The following table describes the request arguments:

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

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

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

Checking the amount of available resources under a contract can help you to avoid provisioning errors resulting from the attempt to provision more resources than are available.

Returns information about the resource limits for a particular contract and the current resource usage.

compute.contract_resources.all

The amount of data included in the response payload will vary slightly depending on the credentials supplied when making the request. If the credentials supplied belong to the "Contract Owner", then all the available information is returned.

Retrieve a full list of all groups.

compute.groups.all

Retrieves detailed information about a specific group.

The following table describes the request arguments:

compute.groups.get('group-id')

Create a new group and set group privileges.

The following table describes the request arguments:

compute.groups.create(:name => 'fogTestGroup', :create_datacenter => true)

Perform updates to attributes of a group.

The following table describes the request arguments:

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

group = compute.groups.get('group-id')
group.name = 'fogTestGroupUpdated'
group.reserve_ip = true
group.update

Delete a single group.

Resources that are assigned to the group are NOT deleted, but are no longer accessible to the group members unless the member is a Contract Owner, Admin, or Resource Owner.

The following table describes the request arguments:

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

group = compute.groups.get('group-id')
group.delete

Retrieves a full list of all the resources that are shared through this group and lists the permissions granted to the group members for each shared resource.

The following table describes the request arguments:

compute.shares.all(group-id )

Retrieves the details of a specific shared resource available to the specified group.

The following table describes the request arguments:

compute.shares.get(group-id, resource-id)

Adds a specific resource share to a group and optionally allows the setting of permissions for that resource. As an example, you might use this to grant permissions to use an image or snapshot to a specific group.

The following table describes the request arguments:

compute.shares.create(:group_id => group-id, :resource_id => resource-id, :share_privilege => true)

Update the permissions that a group has for a specific resource share.

The following table describes the request arguments:

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

share = compute.shares.get(group-id, resource-id)
share.edit_privilege = true
share.update

Remove a resource share from a specified group.

The following table describes the request arguments:

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

share = compute.shares.get(group-id, resource-id)
share.delete

Retrieves a full list of all the users that are members of a particular group.

The following table describes the request arguments:

compute.users.list_group_users(group-id)

Add an existing user to a group.

The following table describes the request arguments:

compute.users.add_group_user(group-id, user-id)

Remove a user from a group.

The following table describes the request arguments:

compute.users.remove_group_user(group-id, user-id)

Retrieve a list of all the users that have been created under a contract.

compute.users.all

Retrieve details about a specific user including what groups and resources the user is associated with.

The following table describes the request arguments:

compute.users.get(user-id)

Creates a new user under a particular contract.

The following table describes the request arguments:

compute.users.create(:firstname => 'Fog', :lastname => 'Testuser', :email => 'email@address.com', :password => 'P4$$w0rd', :administrator => false, :force_sec_auth => false)

Update details about a specific user including their privileges.

Note: The password attribute is immutable. It is not allowed in update requests. It is recommended that a new user log into the DCD and change their password.

The following table describes the request arguments:

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

user = compute.users.get(user-id)
user.force_sec_auth = true
user.update

Blacklists the user, disabling them. The user is not completely purged, therefore if a need to create a user with the same name in the future is anticipated, we suggest renaming the user before it is deleted.

The following table describes the request arguments:

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

user = compute.users.get(user-id)
user.delete

Retrieve a list of all resources and optionally their group associations.

Please Note: This API call can take a significant amount of time to return when there are a large number of provisioned resources. You may wish to consult the next section on how to list resources of a particular type.

compute.resources.all

Retrieve a list of all resources and optionally their group associations.

Please Note: This API call can take a significant amount of time to return when there are a large number of provisioned resources. You may wish to consult the next section on how to list resources of a particular type.

The following table describes the request arguments:

The values available for resource-type are listed in this table:

compute.resources.get_by_type('datacenter')

The following table describes the request arguments:

The values available for resource-type are listed in this table:

compute.resources.get_resource_by_type('datacenter', resource-id)

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