Overview

The VMware vSphere Automation SDKs provide support for your client application infrastructure with services to perform management operations in your vSphere environment. The vSphere Automation SDK for Ruby also contains samples to demonstrate how to use the new APIs.

The version 6.5 SDK enables programmatic access to the following services:

Service discovery using Lookup Service
Authentication (Single Sign-On)
Session management
Tagging
Content Library
Virtual Machines
vCenter Server Appliance management

Note: Single Sign-On authentication is available through the VMware vCenter Single Sign-On API. Service discovery is available through the Lookup Service API.

Distribution Kit

When you extract the contents of the vSphere Automation SDK for Ruby distribution kit, you see the following directory structure:

client/ docs/ open_source_license.txt README.txt SDK-EULA.txt

You can download the vSphere Automation SDK for Ruby distribution kit from the VMware Developer Center.

Important Security Note

Before you begin using Ruby, check the to make sure you have the latest version of OpenSSL. This is a general note to make you aware of this vulnerability.

To verify which version of the OpenSSL library you link to Ruby, use the following:

ruby -v -ropenssl -rfiddle -e 'puts Fiddle::Function.new(Fiddle.dlopen(nil)["SSLeay_version"], [Fiddle::TYPE_INT], Fiddle::TYPE_VOIDP).call(0)'

To verify the version of OpenSSL currently installed with Ruby, use the following:

ruby -ropenssl -e 'puts OpenSSL::OPENSSL_VERSION'

For more information, see Ruby SSL Vulnerability.

What's New

This release of vSphere 6.5 included the following new features:

vCloud Suite SDK for Ruby is now renamed to vSphere Automation SDK for Ruby.
Creating a content library backed by a file storage URI is not supported. When you create a content library and specify a Windows Shared Folder as a storage backing, note that the file URI format is not supported and you should use smb://unc-server/path instead of file://unc-server/path.
Creating a subscribed content library with a file subscription URL is not supported. When you create a subscribed library you can use an HTTP or HTTPS subscription URL. The new URI schemes supported for this release are NFS, SMB, and DS. For more information about the supported URI formats, see the API Reference documentation.
Virtual Machine Management APIs that enable developers to manage the lifecycle and configure the hardware of a virtual machine.
The Tagging API is more powerful, including improved search methods and bulk tagging capability.
vCenter Server Appliance Management APIs that enable developers to create client applications to configure, monitor, and manage the vCenter Server Appliance.

Known Issues

The following issues were discovered during testing.

Internal Server Error if Tagging Description Field is Empty
The Tag Category Description field is optional in the vSphere Web Services API, but it is mandatory in the vSphere Automation SDK. Therefore, if the description field is empty, the vSphere Automation SDK can return an internal server error that states, "the ‘description’ field of the Category model is empty".
Workaround:
When creating tags, do not leave the description field empty. If you do not have any description, you may add a whitespace character (i.e. space).
Unauthenticated exception following long-running operation
After an API client completes a long-running operation, such as an upload to the content library, the next operation might fail with an "Unauthenticated exception" message. This happens if the long running operation did not complete within the lifetime of the authentication session.

Workarounds:
- Keep the session alive by issuing short operations on another thread until the long running operation completes.
- Increase the session length using the VMware vSphere Web Client. Select Administration > System Configuration > Services > vAPI Endpoint > Manage > General, and increase the value for the Maximum session idle time.
Validation of server certificates.
The samples in the vSphere Automation SDK for Ruby do not perform server certificate validation, as written. This is suitable for development environments, but is not recommended for production environments.

The Ruby samples use the Net::HTTP library and other HTTP client libraries that can be configured to do certificate validation.
- For the Lookup Service and the vCenter Single Sign-On Service, the samples use the Savon gem and its HTTP client connection. For information about configuring SSL for the Savon gem, see the explanation of SSL configuration properties at http://savonrb.com/version2/globals.html. To configure the Lookup Service connection, modify the sample file client/samples/lib/sample/framework/lookup_service_helper.rb. To configure the vCenter Single Sign-On Service connection, modify the sample file client/samples/lib/sso.rb.
- For other connections, the Ruby runtime uses the Net::HTTP library. To enable certificate validation for these connections, modify the file ruby-toolkit/runtime/lib/vapi/protocol/client/rpc/http_provider.rb to set the http.verify_mode and the properties for the key and certificate as well.