There has been another exciting open-sourced release in the vSphere Automation SDK lineup. This time, it is the vSphere Automation SDK for Ruby!

That means it’s time for another blog post in our series on ‘Getting Started with the vSphere Automation SDKs’. The posts already available in the series so far are as follows:

• vSphere Automation SDK for REST
• vSphere Automation SDK for REST Part 2
• vSphere Automation SDK for Python
• vSphere Automation SDK for Ruby
• vSphere Automation SDK for .NET

We’ll be taking a look at how to easily get started with this SDK on Mac OS. Before diving in, there are a couple prerequisites we’ll need to download and install.

Note: If you’re using this SDK on any other OS, check out the ‘Quick Start Guide‘ section of the GitHub repository for guidance.

Prerequisites

The first thing we’ll want to do before getting started with this SDK is to clone the repo to the local system. We can do that with the following command:
git clone https://github.com/vmware/vsphere-automation-sdk-ruby.git

We will then need Ruby to be at version 2.3.1 or better. On this particular system, which is currently running Mac OS Sierra (10.12), we see that it’s currently running Ruby 2.0.0.

In order to obtain the newer version of Ruby, we will need to install the package manager, Homebrew. If you don’t have it already, it can be easily downloaded and installed with the following command:
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Next, we will install the latest version of Ruby available. We will do this, through Homebrew, with the following command:
brew install ruby

This SDK also has a couple dependencies which will also need to be installed. These dependencies are called out in the Gem specification file which is located in the root of our cloned repo directory. The Gem spec file is named: vsphere-automation-sdk-ruby.gemspec

In order to easily install all of these dependencies, we will use Bundler. Bundler is used to manage the required gems and which versions of those gems are required. We can install bundler with the following command:
gem install bundler

Lastly, we will need to build and then install our Gem. To perform the build, switch to the directory where the vsphere-automation-sdk-ruby.gemspec file is located and run the following command:
gem build vsphere-automation-sdk-ruby.gemspec

Once complete, we will have the Gem that we’ll need to then install. We can take the Gem filename and run the following command:
gem install vsphere-automation-sdk-2.5.0.gem

We are now all setup to start using the vSphere Automation SDK for Ruby!

One quick item to note, the SDK’s documentation is available locally as part of the cloned repository.
The API docs are available in the following location: /docs/apidocs/vsphereautomation-bindings
The Samples docs are available in the following location: /docs/apidocs/vsphereautomation-samples

Running Samples

There are a couple samples which are included with the SDK, they are:

• Connection: Sample framework to successfully connect to the vSphere Automation API endpoint and retrieve the SAML token
• Tagging: Create vSphere Tag Category and associated tags
• List_VMs: Create a list of available VMs containing the VM Name, Power State, Number of CPUs, and Memory Size in Megabytes

These are made available through the launcher.rb file in the following directory within the repo: /client/samples/bin/launcher.rb

As additional samples are created and/or contributed from the community (such as the ‘list_vms’ sample was), this will be the place to look for them.

To call each of these samples, we’ll need to call the following file: /client/samples/bin/run_sample

If we run that command alone, it will show an example populated command and the available samples matched to their configuration files within the repo.

Each of these samples also offer a help functionality using either the ‘–help’ or ‘-h’ parameter which will display additional parameters for the given sample.

Taking a look at the connection sample, we can run the following command to understand what the sample is looking for in terms of parameters: bin/run_sample connection –help

Now, we can create the full command in order to obtain a SAML token and login to the vSphere Automation API endpoint. The example we’ll use is as follows:
bin/run_sample connection -l vcsa01.corp.local -u 'administrator@vsphere.local' -p 'VMware1!' –k

Moving to the tagging sample, we have the ability to create tag categories and their associated tags. Running an example will look like the following:
bin/run_sample tagging -l vcsa01.corp.local -u 'administrator@vsphere.local' -p 'VMware1!' -k --category-name 'SDKTagCategory' --tag-name 'SDKTag'

Lastly, we’ll use the ‘list_vms’ sample to create a list of the VMs available in our environment. We can do this with the following command:
bin/run_sample list_vms -l vcsa01.corp.local -u 'administrator@vsphere.local' -p 'VMware1!' –k

Summary

This post shows you how to easily get started with the vSphere Automation SDK for Ruby. It takes you through the setup of an entire environment, as well as running some of the individual samples. You can then take whichever is most relevant to you and apply to your environment or, pull parts of this code out and use it to automate or integrate as needed.

With our SDK now being open sourced, we are intent on making sure these samples are of a high quality. If you notice areas of improvement, or come up with some new samples, please feel free to raise issues or pull requests on our GitHub repository.