Tutorials

Using the Ruby SDK to get Image UUIDs

Table of Contents

Overview

The ProfitBricks Ruby SDK can be used to access and modify various ProfitBricks resources. The purpose of this tutorial is to briefly demonstrate how to retrieve a list of available image UUIDs. The UUID of an image is NOT necessarily static. The public images for a particular OS may be updated or replaced. This process can result in a new UUID.

Requirements

You will need to have Ruby installed along with the ProfitBricks Ruby SDK. You will also need a valid ProfitBricks account as the credentials will be used by the Ruby SDK to authenticate against the Cloud API.

Getting Ruby installed will vary depending on what OS you are running on your server or local machine. You can determine if you have Ruby installed by running:

ruby -v

If it is installed, then the version should be returned:

ruby 2.3.1p112 (2016-04-26)[x86_64-linux-gnu]

If you get "not found" instead:

-bash: ruby: command not found

Then please refer to Installing Ruby to get Ruby installed.

The current release of Ruby, when this tutorial was written, is 2.3.3 and 2.4.0-rc1 has been announced. Once you have Ruby installed then installing the ProfitBricks Ruby SDK can be done using gem by running:

sudo gem install profitbricks-sdk-ruby

Now we can start putting together our program.

Basic Script

Ruby programs that are designed to be run from the shell need to know where the ruby binary is located. On *nix operating systems, you can generally determine this using the which command:

which ruby
/usr/bin/ruby

The path /usr/bin/ruby was returned, so we will start editing our Ruby program by opening a text editor and adding the first line:

!#/usr/bin/ruby

Since we are using the ProfitBricks Ruby SDK, we add another line:

require "profitbricks"

We will make use of YAML (Yet Another Markup Language) later to format output, so add:

require "yaml"

The ProfitBricks Ruby SDK needs to be given a few configuration parameters in order to successfully connect and interact with the Cloud API. To start building our Ruby program, we will supply that information.

ProfitBricks.configure do |config|
  config.username = 'username'
  config.password = 'password'
  config.url = 'https://api.profitbricks.com'
  config.path_prefix = '/cloudapi/v3/'
  config.timeout = 120
  config.interval = 1
end

You will need to substitute your own values for username and password. The other values provided should work fine. You may want or need to update the config.path_prefix at some point when a new version of the Cloud API is released.

Since the goal of our script is to retrieve a current list of image UUIDs, we will make use of Image.list. We want to collect this output so we can manipulate it. Add this line to the script:

imageInfo = Image.list

To display the contents of the imageInfo object, we can utilize puts and pass it our object name. Appending to_yaml makes the output human-readable.

puts imageInfo.to_yaml

We get quite a bit of output back as there are a large number of images available for our use. Take a look at the details available for one image and then we'll move into filtering this output a bit.

- !ruby/object:ProfitBricks::Image
  id: e490f866-b788-11e6-9724-525400f64d8d
  type: image
  href: https://api.profitbricks.com/cloudapi/v3/images/e490f866-b788-11e6-9724-525400f64d8d
  metadata:
    createdDate: '2016-12-01T05:42:05Z'
    createdBy: System
    etag: d361a0c9a74e7244abddb8ccab0f2ebf
    lastModifiedDate: '2016-12-01T05:42:05Z'
    lastModifiedBy: System
    state: AVAILABLE
  properties:
    name: Ubuntu-16.04-LTS-server-2016-12-01
    description: ''
    location: de/fra
    size: 2
    cpuHotPlug: true
    cpuHotUnplug: false
    ramHotPlug: true
    ramHotUnplug: false
    nicHotPlug: true
    nicHotUnplug: true
    discVirtioHotPlug: true
    discVirtioHotUnplug: true
    discScsiHotPlug: false
    discScsiHotUnplug: false
    licenceType: LINUX
    imageType: HDD
    public: true

You will likely find these specific properties to be useful:

|------------------------------------------------------------------------------|
| Property    | Value                                | Description             |
|------------------------------------------------------------------------------|
| id          | e490f866-b788-11e6-9724-525400f64d8d | The image UUID. This is |
|             |                                      | what we are trying to   |
|             |                                      | find so we can use it   |
|             |                                      | to provision servers or |
|             |                                      | perform other operations|
|-------------|--------------------------------------|-------------------------|
| name        | Ubuntu-16.04-LTS-server-2016-12-01   | The image name. This    |
|             |                                      | helps us determine what |
|             |                                      | OS the image provides.  |
|-------------|--------------------------------------|-------------------------|
| description |                                      | This may contain a      |
|             |                                      | description of the image|
|             |                                      | No value is set in this |
|             |                                      | particular example.     |
|-------------|--------------------------------------|-------------------------|
| location    | de/fra                               | Indicates where the     |
|             |                                      | image resides. The      |
|             |                                      | location of the image   |
|             |                                      | **must** match the      |
|             |                                      | location of the virtual |
|             |                                      | data center you wish to |
|             |                                      | use it in. Valid values |
|             |                                      | are: "de/fra", "de/fkb",|
|             |                                      | and "us/las".           |
|-------------|--------------------------------------|-------------------------|
| licenceType | LINUX                                | May help us determine   |
|             |                                      | the OS type. It could   |
|             |                                      | have a value of LINUX,  |
|             |                                      | WINDOWS, OTHER, or      |
|             |                                      | UNKNOWN.                |
|-------------|--------------------------------------|-------------------------|
| imageType   | HDD                                  | Should be HDD or CDROM. |
|-------------|--------------------------------------|-------------------------|
| public      | true                                 | This will be set to true|
|             |                                      | for public images       |
|             |                                      | provided by ProfitBricks|
|------------------------------------------------------------------------------|

Filtering

We can make use of find_all to filter our list of results. If we are planning to spin up a new server, it is likely that we want to find a public image with an imageType of "HDD" and a specific location. We probably have a preference on the OS we want to install. For this example, we will look for results with an imageType of "HDD", a location of "us/las", and find images with "centos" in the name. Here is the line to add to our program:

imageListFiltered = imageInfo.find_all { |image| image.properties['name'] =~ /centos-/i && image.properties['imageType'] == "HDD" && image.properties['location'] == "us/las" && image.properties['public'] == true}

That line is using find_all to iterate through imageInfo and examine various properties. Here is a quick summary:

  • image.properties['name'] =~ /centos/i This checks for a name that contains the string "centos". The search is case-insensitive as indicated by the trailing i.
  • image.properties['imageType'] == "HDD" This makes sure that the imageType is "HDD".
  • image.properties['location'] == "us/las" This only returns images that are available in the "Las Vegas, USA" location.
  • image.properties['public'] == true This makes sure that we only select a ProfitBricks public image.

We could add or remove search conditions to expand or narrow the results returned.

We want to see the results of our filter, so also add:

puts imageListFiltered.to_yaml

If we run the script now, we should see at least two results are returned:

- !ruby/object:ProfitBricks::Image
  id: 352533c5-0f41-11e6-ab6b-52540005ab80
  type: image
  href: https://api.profitbricks.com/cloudapi/v3/images/352533c5-0f41-11e6-ab6b-52540005ab80
  metadata:
    createdDate: '2016-05-01T02:05:41Z'
    createdBy: System
    etag: 1cb007cc6b1e1c2092283b13920310a9
    lastModifiedDate: '2016-05-01T02:05:41Z'
    lastModifiedBy: System
    state: AVAILABLE
  properties:
    name: CentOS-6-server-2016-05-01
    description: ''
    location: us/las
    size: 2
    cpuHotPlug: true
    cpuHotUnplug: false
    ramHotPlug: true
    ramHotUnplug: false
    nicHotPlug: true
    nicHotUnplug: true
    discVirtioHotPlug: true
    discVirtioHotUnplug: true
    discScsiHotPlug: false
    discScsiHotUnplug: false
    licenceType: LINUX
    imageType: HDD
    public: true

- !ruby/object:ProfitBricks::Image
  id: c12cf5af-b773-11e6-9724-525400f64d8d
  type: image
   href: https://api.profitbricks.com/cloudapi/v3/images/c12cf5af-b773-11e6-9724-525400f64d8d
  metadata:
    createdDate: '2016-12-01T03:10:47Z'
    createdBy: System
    etag: f69814db5410c4dabd90cfdf5830c4cc
    lastModifiedDate: '2016-12-01T03:10:47Z'
    lastModifiedBy: System
    state: AVAILABLE
  properties:
    name: CentOS-7-server-2016-12-01
    description: ''
    location: us/las
    size: 2
    cpuHotPlug: true
    cpuHotUnplug: false
    ramHotPlug: true
    ramHotUnplug: false
    nicHotPlug: true
    nicHotUnplug: true
    discVirtioHotPlug: true
    discVirtioHotUnplug: true
    discScsiHotPlug: false
    discScsiHotUnplug: false
    licenceType: LINUX
    imageType: HDD
    public: true

That is quite a bit of extra information about each image that we do not necessarily want to see. So lets replace our puts line with these:

imageListFiltered.each do |name|
  puts "#{name.id} - #{name.properties["name"]} - #{name.properties["location"]}"
end

If we run the script now, we'll see that our output has been reduced to two lines showing just three properties for each result.

352533c5-0f41-11e6-ab6b-52540005ab80 - CentOS-6-server-2016-05-01 - us/las
c12cf5af-b773-11e6-9724-525400f64d8d - CentOS-7-server-2016-12-01 - us/las

We didn't need to include the location since we had already filtered the results to a specific location, but this allows us double-check that our image resides in the desired location. Based on the results we simply need to decide if we want to provision using "CentOS 6" or "CentOS 7" and then we can use the associated image UUID to provision our server(s).

Here is our complete program with line numbers:

  1 #!/usr/bin/ruby
  2
  3 require "profitbricks"
  4 require "yaml"
  5
  6 ProfitBricks.configure do |config|
  7   config.username = "YOUR_USERNAME_HERE"
  8   config.password = "YOUR_PASSWORD_HERE"
  9   config.url = "https://api.profitbricks.com"
 10   config.path_prefix = "/cloudapi/v3/"
 11   config.timeout = 120
 12   config.interval = 1
 13 end
 14
 15 imageInfo = Image.list
 16
 17 imageListFiltered = imageInfo.find_all { |image| image.properties["name"] =~ /centos-/i && image.properties["imageType"] == "HDD" && image.properties["location"] == "us/las" && image.properties["public"] == true }
 18
 19 imageListFiltered.each do |name|
 20     puts "#{name.id} - #{name.properties["name"]} - #{name.properties["location"]}"
 21 end

You can take that sample code, remove the line numbers, provide your credentials, and save it as get_image_uuid.rb. Use chmod +x get_image_uuid.rb to make the program executable. Then it can be run by typing:

./get_image_uuid.rb

Summary

We've accomplished our goal of finding an image UUID using the ProfitBricks Ruby SDK. This program could be extended and enhanced in a number of ways. Perhaps we could solicit some input from the user interactively or via command-line arguments and then filter the results based on that input. We may want to add options to sort or group results.

Please remember to safeguard your account credentials. For the sake of simplicity, this script has them included. You may prefer to set them using environment variables. Keep track of where you are saving this script and pay attention to the file permissions so you know who has access to it.

I'm fairly new to Ruby and welcome feedback on this tutorial. Please comment below or open up a discussion in the community section of this site.