There has been another exciting open-sourced release in the vSphere Automation SDK lineup. This time, it is the vSphere Automation SDK for Java!
That means it’s time for another blog post in our series on ‘Getting Started with the vSphere Automation SDKs’. The posts available in the series so far are as follows:
We’ll be taking a look at how to easily get started with this SDK on a Mac. Before diving in, there are a couple prerequisites we’ll need to download and install.
Prerequisites
The first thing we’ll want to do before getting started with this SDK is to clone the repository to the local system. We can do that with the following command:
|
|
git clone https://github.com/vmware/vsphere-automation-sdk-java.git |
Next, we’ll want to make sure we have the appropriate Java Development Kit (JDK) installed and available. The vSphere Automation SDK for Java has been developed to work with JDK 1.8. We can verify which version of Java is available by the following command:
In this situation, my system doesn’t have Java installed at all. I’ll need to head out to the JDK8 download page to download and install the appropriate version. Once complete, repeat the last command to ensure JDK 1.8 is installed. Verifying and/or updating the JAVA_HOME and PATH variables is the last step to the install process. We’ll start by finding the current value for the JAVA_HOME variable, then updating it, if necessary, to the Home directory of the newly installed JDK. We’ll then repeat that process for the PATH variable as well. This can be done with the following commands:
|
|
echo $JAVA_HOME export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk1.8.0_152.jdk/Contents/Home echo $PATH export PATH=$JAVA_HOME/bin:$PATH |
We will also need to ensure Maven, a build automation tool, is installed. We will use Maven to build out the SDK and the samples from source so we can start using it. My system doesn’t have Maven installed yet, so we’ll go to the download page and install it according to the instructions on Maven’s site. Alternatively, we can do it with the following commands:
|
|
curl -o apache-maven-3.5.2-bin.tar.gz -k http://apache.mirror.globo.tech/maven/maven-3/3.5.2/binaries/apache-maven-3.5.2-bin.tar.gz tar -xzf apache-maven-3.5.2-bin.tar.gz sudo mv apache-maven-3.5.2 /opt/ rm apache-maven-3.5.2-bin.tar.gz export PATH=/opt/apache-maven-3.5.2/bin:$PATH |
The last prerequisite, before starting to user the SDK, is instructing Maven to build out all the samples with Maven. We’ll first use the initialize command, within the cloned repository directory, to pre-stage any dependencies that are not available publicly. We’ll then follow that with install command. This can be done with the following commands:
|
|
mvn initialize mvn clean install |
We are now all setup to start using the vSphere Automation SDK for Java!
Running Samples
There are quite a few samples which are included with the SDK. Each sample can be run by using its fully qualified class name.
The first example we’ll take a look at is the ListVMs sample. In terminal, from the root of the SDK directory, we’ll call java, enabling assertions with the ‘ea’ parameter, using the ‘cp’ parameter to call the class path of ‘target/vsphere-samples-6.5.0.jar’, then the fully qualified class name. An example of this command is as follows:
|
|
java -ea -cp target/vsphere-samples-6.6.1.jar vmware.samples.vcenter.vm.list.ListVMs |
Based on the output, we see quite a few parameters that still need to be referenced in order to authenticate and run the sample. The required parameters are server, username, and password. However, there are also some considerations needed around the handling of the vCenter’s certificate. I’m using a lab environment that still has the vCenter’s self-signed certificate in use, so I’ll be using the ‘skip-server-verification’ parameter. Lastly, there are the optional paramaters, most of which are straight forward, but the config-file parameter is a convenient one. For now, we’ll keep it simple and call each parameter as part of the command. I’ll discuss using a configuration file later in this post.
Performing the ListVMs sample in my environment, with all of the required parameters, looks like the following:
|
|
java -ea -cp target/vsphere-samples-6.6.1.jar vmware.samples.vcenter.vm.list.ListVMs --server vcsa01.corp.local --username administrator@vsphere.local --password VMware1! --skip-server-verification |
There’s another sample which takes a VM through the lifecycle of power states. This sample can be discovered in the ‘../vmware/samples/vcenter/vm/power’ directory. The public class we’ll be using is ‘PowerLifeCyle’. If we run that without any parameters, we can see that we’ll need to add the ‘vmname’ parameter and call a specific VM by name. Running this sample can be done with the following command:
|
|
java -ea -cp target/vsphere-samples-6.6.1.jar vmware.samples.vcenter.vm.power.PowerLifeCycle --server vcsa01.corp.local --username administrator@vsphere.local --password VMware1! --skip-server-verification --vmname web01 |
The last example we’ll look at is the modifying the memory configured for a VM. This sample can be found in the ‘../vmware/samples/vcenter/vm/hardware/memory’ directory. The public class we’ll be using is ‘MemoryConfiguration’. If we run that without any parameters, we can see that we will again need to add the ‘vmname’ parameter and call a specific VM by name.
This sample will set the RAM to 8GB then enables hot-add. We can go execute this sample with the following command:
|
|
java -ea -cp target/vsphere-samples-6.6.1.jar vmware.samples.vcenter.vm.hardware.memory.MemoryConfiguration --server vcsa01.corp.local --username administrator@vsphere.local --password VMware1! --skip-server-verification --vmname svc01 |
One last thing before wrapping this up, let’s walk through using the configuration file. The configuration file can be any text-based file which contains lines that begin with the parameter names. In the following example, we create a new file and modify the file to include the following lines:
|
|
server=vcsa01.corp.local username=administrator@vsphere.local password=VMware1! |
We can now reference this config file in any of the examples to authenticate against a vCenter server. Reusing the ‘ListVMs’ sample, the command to run that again but instead using a configuration file will look like the following:
|
|
java -ea -cp target/vsphere-samples-6.6.1.jar vmware.samples.vcenter.vm.list.ListVMs --config-file config.file --skip-server-verification |
Summary
This post shows you how to easily get started with the vSphere Automation SDK for Java. It takes you through the setup of your local development 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 SDKs 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.
