- Abstract
- Quick Start Guide
- API Documentation
- Submitting samples
- Resource Maintenance
- Repository Administrator Resources
- VMware Resources
This document describes the vSphere Automation Ruby SDK samples that use the vSphere Automation Ruby client library. You will need Ruby version 2.3.1 or greater to run the samples.
All samples support vCenter 6.5. Tagging samples also support vCenter 6.0.
This document will walk you through getting up and running with the Ruby SDK samples. Prior to running the samples you will need to set up a vCenter test environment. The following steps will take you through this process.
Before you can run the SDK samples we'll need to walk you through the following steps:
- Installing the required Ruby packages
- Installing SDK provided packages
- Setting up a vSphere test environment
Note: The SDK requires Ruby v2.3.1+ (preferably the latest stable release) to run the setup/samples, please make sure you have the appropriate version installed before continuing.
If you are on macOS, OSX, or Linux, please note that the system installed version of Ruby may not be sufficient for development and we recommended you install Ruby yourself before installing the required packages.
If you are on Windows, you will need the necessary build tools to build native extensions. The easiest way to install everything needed is to use the Ruby Installer. You will need to install the Development Kit (DevKit) as well.
The Gem specification file (vsphere-automation-sdk-ruby.gemspec) lists the
required dependencies. To install them, you will need
Bundler. You can install Bundler by running
gem install bundler and then the required packages by running
bundle install. For more details on how to install Ruby packages using
Bundler, please refer to the Bundler documentation.
Install the SDK by running
gem build vsphere-automation-sdk-ruby.gemspec
gem install vsphere-automation-sdk-2.5.0.gemUninstall the SDK by running
gem uninstall vsphere-automation-sdk
NOTE: We strongly recommend running the samples against a freshly installed non-production vSphere setup as the scripts may make changes to the test environment and in some cases can destroy items when needed.
The samples require a vSphere test environment with the following configuration:
- 1 vCenter Server
- 2 ESX hosts
- 1 NFS Datastore with at least 3GB of free capacity
Please have the details of these available, but do not have any configuration pre-created on vCenter server or ESXi Hosts (i.e. there should be no existing datacenters, clusters or attached hosts on the vCenter server).
To run a sample:
cd client/samples
bin/run_sample --helpTo run a sample, you will use bin/run_sample followed by a sample name (e.g.
connection) and the necessary options. To see the available options for a
sample, run bin/run_sample [sample_name] --help.
The API documentation is in the
docs/apidocs/client/vsphereautomation-bindings folder. Open the index.html
files in your browser to view the documentation.
The following information must be in the README.md (or in the sample comments in case a README.md already exists in same folder).
- Author Name
- This can include full name, email address or other identifiable piece of information that would allow interested parties to contact author with questions.
- Date
- The date that the sample was originally written
- Minimal/High Level Description
- What does the sample do? What is the purpose of the sample?
- Any KNOWN limitations or dependencies
Include the following information when possible. Inclusion of information provides valuable information to consumers of the resource.
- Which vSphere version was the sample developed/tested against?
- Whic SDK version was the sample developed/tested against?
- Whic Ruby version was the sample developed/tested against?
- Follow the GitHub process
- Please use one branch per sample or change-set
- Please use one commit and pull request per sample
- Please post the sample output along with the pull request
- If you include a license with your sample, use the project license
Please conform to the Ruby Style Guide.
Check your code by running RuboCop
using Bundler (bundle exec rubocop [filename]).
The submitter will maintain ownership of all submitted samples.
File any bugs or other issues within GitHub by way of the repository's Issue Tracker.
Any community member can resolve issues within the repository, however only the board member can approve the update. Once approved, assuming the resolution involves a pull request, only a board member will be able to merge and close the request.
It is highly recommended to add all submitted samples to the VMware Sample Exchange.
The Sample Exchange can access your GitHub resources by way of a linking process. The community can then search for those resources. There are VMware social media accounts which will advertise resources posted to the site. There are no additional accounts needed as the VMware Sample Exchange uses MyVMware credentials.
Board members are volunteers from the SDK community and VMware staff members, board members are not held responsible for any issues which may occur from running of samples from this repository.
Members:
- J.R. Garcia (VMware)
- Steve Trefethen (VMware)
All items added to the repository, including items from the Board members, require two (2) votes from the board members for approval. The approving members ideally will have downloaded and tested the item. A board member will merge the pull request once two board members have given approval.