On Friday, we deployed an update to Sample Exchange on VMware {code} that allows you to select any VMware product or SDK when contributing a sample. As a result, developers looking for samples for VMware products and services will have an easier time finding relevant content. Continue reading
The vSphere Automation SDK for Python has recently received some exciting updates. These updates add the ability to easily develop against and automate VMware Cloud on AWS! There are even samples to list organization information, manage SDDCs, and lots of networking functionality!
Let’s take a look at how to easily get started with this SDK on a MacOS system. Before diving in though, there are a couple prerequisites we’ll need to download and install.
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:
|
1 |
git clone https://github.com/vmware/vsphere-automation-sdk-python.git |
Next, we’ll need to install the package manager, Homebrew. Using Homebrew will allow us to easily download and update additional programs. It can be easily downloaded and installed with the following command:
|
1 |
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" |
Now, we’ll install Python in the recommended version of 3.6. It’s worth noting that MacOS comes with a version of Python already installed. However, it is generally an older version (normally, Python 2.7) and is used for some system related tasks. Due to that, it is best not to modify that version or the defaults.
Utilizing our package manager, we’ll install Python 3.6 with the following command:
|
1 |
brew install python3 |
It’s also recommended to isolate your development environments from each other so, we’ll setup a virtual environment and jump into it. We can do that with the following commands:
|
1 2 |
python3 -m venv VMWonAWSDemo source VMWonAWSDemo/bin/activate |
Then, we’ll install the SDK requirements. They’re listed within the root of the SDK folder in the file labeled: requirements.txt. After checking out which requirements are necessary, we’ll install those requirements by way of the following command while in the root of the SDK folder:
|
1 |
pip install --upgrade --force-reinstall -r requirements.txt --extra-index-url file:///Users/kyleruddy/GitHub/vsphere-automation-sdk-python/lib/ |
Lastly, we need to update the PYTHONPATH variable. This allows Python to be able to use the SDK helper methods. We can do this with the following command:
|
1 |
export PYTHONPATH=${PWD}:$PYTHONPATH |
One other item worth mentioning is an IDE. This will make editing, running and debugging the code a lot easier to deal with. I generally use Visual Studio Code, which is available here.
Let’s get started using some of the samples that have been included with this SDK.
The VMware Cloud on AWS APIs use an OAuth refresh token for authentication. These have to be created through the Cloud Console. Once logged into the Cloud Console, click the drop-down on the top right-hand corner that’s by your name. From there, click on the ‘OAuth Refresh Token’ button. If you don’t already have a refresh token available, there will be a blue link to create a new token. Afterwards, you’ll have a refresh token and be ready to authenticate into the VMware Cloud on AWS APIs.
The most important thing you can do when getting started is making your Organization (Org) ID easily accessible. This ID is referenced in almost every API method VMware Cloud on AWS has. If we browse through the SDK folder structure, we’ll see there’s an example we can use to retrieve information about the Orgs. There is a Python package named ‘organization_operations.py’ in the ‘samples/vmc/orgs’ directory.
Example:
|
1 2 |
export refreshtoken='0073c5b2-xxxx-xxxx-xxxx-606592f7f070' python3 ./samples/vmc/orgs/organization_operations.py -r $refreshtoken |
We can see in the results above this example performs a couple tasks. First, we receive a list of all the Orgs this refresh token is associated with. Second, we get some additional information about the first Org that was returned.
The next most important thing we can obtain is information about the SDDC/s this Org has. However, at the time of this blog release, that functionality wasn’t explicitly available. Let’s see how to do this in the REPL, or Python’s interactive interpreter:
|
1 2 3 4 5 6 7 8 |
import requests from vmware.vapi.vmc.client import create_vmc_client refreshtoken = '0073c5b2-xxxx-xxxx-xxxx-606592f7f070' orgid = 'eb8f2d0a-xxxx-xxxx-xxxx-a4d6282c5555' vmc_client = create_vmc_client(refreshtoken) sddcs = vmc_client.orgs.Sddcs.list(orgid) sddcs sddcs[0].name |
I think this ability is something that will be quite helpful as part of the example SDDC package. Adding it is as easy as adding the following to the ‘create_delete_sddc.py’ file:
|
1 2 3 4 5 6 7 8 9 10 |
def list_sddc(self): sddcs = self.vmc_client.orgs.Sddcs.list(self.org_id) if not sddcs: raise ValueError('The sample requires at least one SDDC associated' 'with the calling user') print("\n# Example: List SDDCs") table = [] for sddc in sddcs: table.append([sddc.id, sddc.name, sddc.resource_config.region]) print(tabulate(table, ['ID', 'Name', 'AWS Region'])) |
However, you won’t need to do that. This SDK is open-sourced and I was able to submit a pull request to get it added in already! As part of the PR, we updated the file name to be ‘sddc_crud.py’ and it is available in the ‘samples/vmc/sddc’ directory.
Last example, let’s run through some tasks for logical network administration. There’s a sample for this as well. The ‘logical_network_crud.py’ package will create a new logical network, list all of the logical networks, list only the newly created logical network, and then delete the newly created logical network. This file is available in the ‘samples/vmc/networks/’ directory.
Example:
|
1 2 3 |
export orgid='eb8f2d0a-xxxx-xxxx-xxxx-a4d6282c5555' export sddcid='584e8cc8-xxxx-xxxx-xxxx-733871f9f0a6' python3 ./samples/vmc/networks/logical_network_crud.py -r $refreshtoken -o $orgid -s $sddcid --network-name 'Python-SDK-LogicalNetwork' -c |
This post shows you how to easily get started with the vSphere Automation SDK for Python with VMware Cloud on AWS. 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.
If you’ve missed any of the prior posts, here are the others in this ‘Getting Started’ series with our open-sourced SDKs:
We are going to keep the ‘Getting Started’ series going on using the vSphere Automation SDKs. This time, we will be taking a look at the SDK for Perl.
If you’ve missed any of the prior posts, here are the others in the series:
Let’s take a look at how to easily get started with this SDK on a Windows 10 system. Before diving in though, there are a couple prerequisites we’ll need to download and install.
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:
|
1 |
git clone https://github.com/vmware/vsphere-automation-sdk-perl.git |
We also want to make sure Perl is available on the local system. The supported versions are Active Perl 5.14+ or Stawberry Perl 5.24.1.1+. For these examples, I’ll be using Active Perl which can be downloaded directly from their site: Active Perl
We will then need to make sure a couple Perl packages are installed and available. These can be installed with the following commands:
|
1 2 3 4 5 6 |
ppm install XML::LibXML ppm install UUID::Random ppm install Crypt::OpenSSL::RSA ppm install Exception::Class ppm install Crypt::X509 ppm install Data::Compare |
Next, this SDK also depends on some capabilities from the vSphere Perl SDK. We will need to login to the My VMware portal, download the executable, then install it from the following link: vSphere Perl SDK
We have one more step concerning the vSphere Perl SDK install. We also need to make sure the ‘python27.dll’ file is available in the vSphere Perl SDK’s folder as follows: ..\Perl\lib\VMware
The following code can be used to easily copy that file to the proper location:
|
1 |
cp 'C:\Program Files (x86)\VMware\VMware vSphere CLI\bin\python27.dll' 'C:\Program Files (x86)\VMware\VMware vSphere CLI\Perl\lib\VMware\' |
Last part of the prerequisites is to configure the environmental variable PERL5LIB to look for modules in the newly cloned SDK directory. The following directories need to be specified:
The following code was used to configure the PERL5LIB environmental variable for my lab:
|
1 |
set PERL5LIB=%PERL5LIB%;C:\Users\Kyle Ruddy\Documents\GitHub\vsphere-automation-sdk-perl\lib\runtime;C:\Users\Kyle Ruddy\Documents\GitHub\vsphere-automation-sdk-perl\lib\sdk;C:\Users\Kyle Ruddy\Documents\GitHub\vsphere-automation-sdk-perl\samples |
We are now all setup to start using the vSphere Automation SDK for Perl!
There are a handful of samples that are already included with this SDK. The samples are separated by the API namespaces into different directories and then presented as scripts. We’ll be looking at running some of the samples from the vCenter directory.
The first example we’ll run is the List VMs sample. This sample can be found in the ‘..\samples\Vcenter\Vm’ directory. There are a couple sample scripts here, which also include deleting a VM and performing some power actions.
If we run the ‘list_vms.pl’ sample as is, we will receive back the appropriate parameters to successfully complete the call. Those parameters would be username, password, and server name.
Performing the List VMs sample in my environment, with all of the required parameters, looks like the following:
|
1 |
perl list_vms.pl --username kruddy@corp.local --password VMware1! --server vcsa01.corp.local |
There’s another example in the VM folder which allows us to modify the power state for a given VM. However, this sample will take a given VM through all of the available power states. Again, running the sample without any parameters will give us the required parameters. We can see that we’ll need to also add parameters for the VM name and cleanup. The cleanup parameter is used to return the VM to the last state it was in.
Performing the List VMs sample in my environment, with all of the required parameters, looks like the following:
|
1 |
perl power_life_cycle.pl --username kruddy@corp.local --password VMware1! --server vcsa01.corp.local --vmname svc02 --cleanup false |
The last example we’ll take a look at is the creation of a new VM. We’ll take advantage of one of this new API’s features and create a new VM using defaults. This means the API fills in any parameters we do not specify with values based on what Guest OS has been specified. It’s also import to note that the Guest OS has been hardcoded in the sample to be ‘Windows_9_64’. This can be found on line 71 of the ‘default_vm.pl’ script. Additional Guest OS types can be found in the API documentation: Guest_OS Types
We’ll start by moving to the following directory: ..\samples\Vcenter\Vm\Create\DefaultVM Running the ‘default_vm.pl’ script will show us a number of parameters we’ll need to specify. These parameters include names for the following: VM, Datacenter, Cluster, VM folder, datastore. There’s also the authentication and cleanup parameters. In this case, giving the cleanup parameter a ‘True’ value will remove the newly created VM.
Performing the Create New Default VM sample in my environment, with all of the required parameters, looks like the following:
|
1 |
perl default_vm.pl --username kruddy@corp.local --password VMware1! --server vcsa01.corp.local --vmname demovm01 --datacenter DemoDC --clustername Demo --vmfolder Dev --datastore vsanDatastore --cleanup False |
This post shows you how to easily get started with the vSphere Automation SDK for Perl. 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.
We are going to keep the ‘Getting Started’ series going on using the vSphere Automation SDKs. This time, we will be taking a look at this SDK for .NET.
If you’ve missed any of the prior posts, here are the others in the series:
Let’s take a look at how to easily get started with this SDK on a Windows 10 system. Before diving in though, there are a couple prerequisites we’ll need to download and install.
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:
|
1 |
git clone https://github.com/vmware/vsphere-automation-sdk-.net.git |
The other things we’ll need is .NET Framework 4.5 and Visual Studio 2015 or newer. I’ll be using Visual Studio 2017. On Windows 10, .NET Framework 4.5 should already be available. If it’s not, you can download it directly from Microsoft at the following link: Microsoft .NET Framework 4.5. If you don’t already have Visual Studio, it can be downloaded through the following link: Visual Studio
The next thing we need to do is build out the samples in Visual Studio. We start this process by opening Visual Studio. Now we can click on “File”, “Open”, then click “Project/Solution”. From the new Explorer window, browse to the root directory of where the SDK repo was cloned, then select and open the ‘vSphere-Samples.sln’ file.
Note: This process may take some time and if there are any missing dependencies found in the Visual Studio install, it will prompt to install those items.
We will be ready to finish building out the samples once the vSphere-Samples solution has been presented in the Solution Explorer. We’ll then right click on “Solution ‘vSphere-Samples’ (17 projects)” and select “Build Solution”. After a few moments there should be a message on the bottom information bar indicating “Build succeeded”.
We are now all setup to start using the vSphere Automation SDK for .NET!
There are a handful of samples already included with this SDK. The samples are separated by the API namespace into different directories and presented as projects. We’ll be looking at running some of the samples from the vCenter directory.
The first example we’ll take a look at is the ‘ListVMs’ sample. We start in the Solution Explorer, expanding ‘vcenter’, ‘vm’, and finally the ‘list’ directory. We can now see a ‘ListVMs’ project. We will want to right click the project and click ‘Set as StartUp Project’.
Prior to running the sample, we need to populate the sample with some properties such as which vCenter Server to connect to and with what credentials. We can find what the available properties are by clicking on the ‘Debug’ menu and then selecting ‘Start Without Debugging’.
We should receive a command prompt window that gives us the available properties.
In order to pass those parameters, we’ll need to open up the properties of the project. Once open, select the ‘Debug’ tab and look for the ‘Start options’ section. The ‘Command line arguments’ text box is where we’ll be specifying the parameter values. The parameters for my environment end up looking like the following:
With the parameters now laid out, we’re ready to actually run the sample!
Example results after hitting the ‘Start’ button:
Alternatively, we can also run the built executable for the ListVMs sample. It is located in the following directory: ..\vmware\samples\vcenter\vm\list\ListVMs\bin\Debug
Example code:
|
1 |
.\vmware\samples\vcenter\vm\list\ListVMs\bin\Debug\ListVMs.exe --server vcsa01.corp.local --username kruddy@corp.local --password 'VMware1!' --skip-server-verification |
We can also make modifications to an existing VM’s configuration. One example would be to update a VM’s CPU configuration, so let’s take a look at the CpuConfiguration sample. This project is under ‘vm’ then ‘hardware’. This sample is already configured to increase the CPU count to 2 and to enable CPU Hot Add. These options can be modified in the source code (CpuConfiguration.cs) at line 71 and 81, respectively.
This time we’ll run the sample directly from the executable. The first time we run it, without adding any parameters, we can see that we need our standard authentication parameters but we also need to specify the VM name. Running this sample in my environment looks like the following:
|
1 |
.\vmware\samples\vcenter\vm\hardware\CpuConfiguration\bin\Debug\CpuConfiguration.exe --server vcsa01.corp.local --username kruddy@corp.local --password 'VMware1!' --vmname svc02 --skip-server-verification |
The last example we’ll take a look at is the creation of a new VM. We’ll take advantage of one of this new API’s features and create a new VM using defaults by using the CreateDefaultVM project. This means the API fills in any parameters we do not specify with values based on what Guest OS has been specified. It’s also import to note that the Guest OS has been hardcoded in the sample to be ‘Windows_9_64’ on line 38 of the source code (CreateDefaultVm.cs). Additional Guest OS types can be found in the API documentation: Guest_OS Types
The project for this sample is located under ‘vm’ then ‘create’. However, we will again be running this sample directly from the executable. Running the executable without any parameters shows that we will need some additional parameters specified. These parameters include names for the following items: datacenter, cluster, vmfolder, and datastore.
Performing the Create Default VM sample in my environment, with all of the required parameters, looks like the following:
|
1 |
.\vmware\samples\vcenter\vm\create\CreateDefaultVm\bin\Debug\CreateDefaultVm.exe --server vcsa01.corp.local --username kruddy@corp.local --password 'VMware1!' --datacenter DemoDC --cluster Demo --vmfolder Dev --datastore vsanDatastore --skip-server-verification |
This post shows you how to easily get started with the vSphere Automation SDK for .NET. 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.
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.
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:
|
1 |
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:
|
1 |
java -version |
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:
|
1 2 3 4 |
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:
|
1 2 3 4 5 |
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:
|
1 2 |
mvn initialize mvn clean install |
We are now all setup to start using the vSphere Automation SDK for Java!
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:
|
1 |
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:
|
1 |
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:
|
1 |
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:
|
1 |
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:
|
1 2 3 |
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:
|
1 |
java -ea -cp target/vsphere-samples-6.6.1.jar vmware.samples.vcenter.vm.list.ListVMs --config-file config.file --skip-server-verification |
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.
The vSphere Automation SDKs have recently received an exciting update! These open-sourced SDKs can now also interact with the VMware Cloud on AWS service. The first two SDK languages updated to include this feature set is Python and Java. The remaining SDK languages will follow soon.
The VMware Cloud on AWS service offers a couple different RESTful APIs to interact with. The updated SDKs will focus on the VMware Cloud on AWS (VMC) API, as well as provide the authentication method through the Cloud Services Platform (CSP) API. To find out more about the APIs available as part of the VMware Cloud on AWS service, see this blog post: An Overview of VMware Cloud on AWS APIs
On this initial release, both the Python and Java SDKs include a handful of sample frameworks. These include the following functions:
Let’s take a look at a couple of these in action.
One of the vSphere Automation SDK for Python samples has the functionality to perform two methods. The first will list all of the organizations the user’s refresh token is associated with. These orgs will be displayed by ID and display name. The second will list more detailed information for the first organization, such as ID, display name, name, create and updated dates, and SLA. This sample can be executed with the following command:
|
1 |
Python ./samples/vmc/orgs/organization_operations.py refresh-token-id |
This SDK also has a new way to interact with the API and that is through the interactive interpreter! This can be done by creating the service object using the ‘create_vmc_client’ function while passing our refresh token. At this point, we can start accessing the available collections. The collections can by discovered in two main ways. First, by referring to the documentation that’s located in the ‘vmc.zip’ file that’s located in the ‘doc’ folder. Second, by using tab-complete. Some example code to obtain similar output to our prior example while in the interactive shell:
|
1 2 3 4 5 6 |
from vmware.vapi.vmc.client import create_vmc_client client = create_vmc_client('refresh-token-id') client.Orgs.get('org-id') tmmOrg2 = client.Orgs.get('org-id') print(tmmOrg2.display_name) print(tmmOrg2.created) |
The vSphere Automation SDK for Java offers a similar sample to the first Python example from above. However, this particular sample operates a little differently. The output from this sample will be the complete details of each org the user is associated with. This sample can be executed with the following command:
|
1 |
java -ea -cp target/vsphere-samples-6.6.2.jar vmware.samples.vmc.orgs.OrganizationOperations -refreshtoken refresh-token-id |
The open-sourced vSphere Automation SDKs have recently received an update. This update allows these SDKs to work with the RESTful API service of VMware Cloud on AWS. There are also a number of samples available within each SDK to list information about organizations, add and/or remove SDDCs, and manage the host count within an SDDC. These samples are easy to have operational within a few minutes of updating your local repo and are quite simple to integrate into your existing code!
Stay tuned for a more detailed look at getting started with each of these SDKs with the VMware Cloud on AWS service in the future.
For more information about the VMware Cloud on AWS service, see the following blog post: VMware Cloud on AWS Technical Overview
For more information about the VMware Cloud on AWS APIs, see the following blog post: An Overview of VMware Cloud on AWS APIs
The VMware Workspace ONE product teams have been hard at work this year with the goal to make developing with VMware and Workspace ONE easier and better than ever. First we launched the brand new Workspace ONE Dev Center and then the completely revamped Workspace ONE Swift Software Development Kit (SDK).
You may already be familiar with the AirWatch Software Development Kit (SDK), a set of tools that let you easily add advanced security and management capabilities to enterprise mobile apps. The new Workspace ONE Swift SDK is the completely revamped version of the AirWatch SDK for the iOS platform. The Swift SDK takes the old SDK, written in Objective-C, and is updated with the Swift 3.1 (Swift 3.2 and 4.0 support is right around the corner) programming language from Apple (https://developer.apple.com/swift/) along with many other modern technologies.
By leveraging the latest and greatest Apple technology, the Swift SDK offers all of the benefits of the AirWatch SDK with a few more bells and whistles when it comes to user experience and performance.
You’ll love the Swift SDK, here is why:
Architecture for the Future
In addition to the tangible user experience and performance improvements, there are several major underlying architecture changes made in the new Swift SDK which set the groundwork for future improvements. Future improvements will include things such as bitcode support and adoption of modern package management technologies like Cocoa Pods.
So, want to try it out?
The Workspace ONE Swift SDK is available today. Contact your account representative or AirWatch customer support for more information.
What behavior has changed between Objective-C and. Swift?
The Swift SDK will introduce a new mechanism using the shared keychain for SDK apps to communicate with other SDK apps on the device. This approach provides benefits from both a security and a user experience perspective.
SDK applications built by the same developer account and are also in the same keychain group or “cluster” will now be able to share an app passcode & SSO session with each other without requiring a flip to the Agent or Container application every time authentication is required. However, applications on the same device built by different keychain groups will not be able to take advantage of this passcode sharing capability. There will still be some scenarios where a flip to the Agent, Container, or Workspace ONE app is required for obtaining the server URL and other setup information but this particular flip should only occur once per cluster of apps.
The diagram below illustrates this new “clustering” behavior. The dotted cluster represents a unique developer account and keychain group. Applications with the same color code represents SDK apps which will share information with each other.
How will Swift SDK and Objective-C SDK applications interact and behave when both are present on a device?
Upon upgrading one app to use the Swift SDK (see State 2 in diagram below), the Objective-C SDK applications will automatically switch to the clustering behavior for passcode and other app data sharing mentioned in the behavior changes section above. Thus, the Objective-C applications will no longer flip to the Agent for passcode authentication nor will it share a passcode with apps which are outside of its own keychain cluster.
Note: Anchor app refers to either Agent, Container, or Workspace ONE.
What is the plan for the Objective-C SDK?
The Objective-C version of the iOS SDK will be in maintenance mode and new features/capabilities will be exclusive to the new Swift SDK.
Join VMware {code}
Become a part of one of the fastest-growing developer communities devoted to cloud infrastructure and enterprise mobility.
Learn More
Check out the VMware EUC blog post on developing enterprise applications with the Workspace ONE SDK here.
We’re continuing the “Getting Started” series focusing on the vSphere Automation SDK for REST! In this part of the series, we’ll be switching gears and looking at the JavaScript (JS) examples which were included in the SDK download.
JS samples were included in the REST SDK to provide an easy example of how to call the vSphere REST API using a common and easy web based language.
To check out the first part in the series where we cover accessing the documentation and using Postman, see the following link: Getting Started with the vSphere Automation SDK for REST
If you haven’t already done any JS work in your current environment, there are a couple preparation steps that are required to get started. While there are many ways to get started with JS, my personal preference is outlined below.
Download NodeJS for your preferred OS and install it, ensuring the “NPM Package Manager” is also installed: https://nodejs.org/en/download/
The reasons I’m using NodeJS and the associated NPM is because NodeJS will allow us to execute JS directly from the command line. NPM (Node Package Manager) will be used to install any of the package dependencies we’ll be needing, as documented in the project.json file.
Lastly, download and install Visual Studio Code which will be used as the IDE (or Integrated Development Environment): https://code.visualstudio.com/Download
However, please note, an IDE is not required to run these samples.
We have our environment setup, the vSphere Automation SDK for REST is already downloaded (from Part 1), and we’re ready to move on. Let’s begin by examining the contents of the JS folder within the unzipped SDK directory: VMware-vSphere-Automation-SDK-REST-6.5.0\client\samples\javascript\vcenter
We’ll start by going through the README. There’s a couple important parts in there with regards to getting started, plus it’s always good to get a better understanding of what’s going on with some of these samples.
The beginning portion of the README illustrates a need to download and install some Node modules. These modules are dependencies of the samples and are sourced from the packages.json file in the vcenter directory. We can do this with the following commands at a prompt:
|
1 2 |
cd VMware-vSphere-Automation-SDK-REST-6.5.0\client\samples\javascript\vcenter npm install |
The bottom portion of the README provides a list of all the samples that have been included. Which are as follows:
The last of the first steps is to fill in some of the parameters included as part of the settings.js file. These parameters include some information like which REST endpoint we’re connecting to and which what credentials we’re using to authenticate with. If you recall the Environmental Variables we configured in Part One of this blog series, these parameters work very similarly to those. One item to keep in mind while filling in these parameters is related to the “Host” information, the endpoint will need to have to prepend “https://” to the value. See the example below for a bit more information:
There are several VM examples that are included with this SDK. The easiest and most straight forward of the examples is retrieving details of the VMs associated with the API endpoint by using the vm-details sample. It’s executed by running: npm run vm-details
Another sample is about how to create a VM using defaults. This sample requires the host1 and datastore parameters to be completed within the settings.js file.
If you remember from part 1 of this series, the default settings are made based upon the Guest OS type. This sample creates a VM based on it being a “RHEL_7_64” Guest OS type, which can be seen on line 86 of the create_vm_with_defaults.js script. Another parameter which is set as part of the script is which folder the VM is created in. Referencing line 72 of the same script, we can see it searching for the “Discovered Virtual Machine” folder.
The sample can then be run with the following command: npm run vm-create-defaults
We can see the VM was created with a hardware ID of vm-96. Let’s go back to our first sample and verify that the VM was indeed created.
If we want to perform some actions to that newly created VM, there are a couple samples we can use. However, before we do that, we will need to update the settings.js file to indicate the name of the VM we’re targeting.
The two samples we have access to which can modify the VM are power actions, so powering on or off the system. We can perform the power on action with the following command: npm run vm-power-on
We can see in the above example that the proper VM is found, as referenced by the hardware ID of vm-96. We can then see the status code of 200 meaning the request was successfully received.
Powering off the VM is just as easy as powering it on, and can performed with the following command: npm run vm-power-off
We’re going to switch gears a bit and take a look at some of the host based samples. Since this is an existing environment, I’ll be showing how to disconnect and reconnect a host. Before running the commands, we’ll need to update our settings.js file again to reference the host we’re working with. The host will be designated via the host1 parameter.
If you happen to be adding a host, the hostUsername and hostPassword parameters should be completed as well. They are not needed for the examples below.
In order to disconnect a host, we’ll run the following command: npm run host-disconnect
If we want to reconnect that host, we run the following command: npm run host-connect
When you start creating additional JS scripts, some of the work has already been done for you. Check out the resources directory, it will have multiple individual top level object based scripts that have some of the functions already created. If the function isn’t already created, the vSphere Automation API is really easy to work with so you can easily add your own to the SDK’s samples.
If you’ve missed any of the prior posts, here are the others in the series:
vSphere 6.5 introduced a big update to its newest API service, which is known as the vSphere Automation API. This API is a big step forward in the process of simplifying and modernizing our APIs. This service also allows us to introduce several new SDKs for the following programming languages: Java, Python, .NET, Perl, Ruby, and REST. This blog will take a look at the REST SDK and how to easily get started using it.
For more information about what was introduced with the vSphere Automation APIs, check out the associated What’s New blog post.
First things first, we need to gain access to the vSphere Automation SDK for REST from VMware’s GitHub repository: https://github.com/vmware/vsphere-automation-sdk-rest Make sure to read through the README, noting that we’ll be able to view and use these resources, as well as contribute back to the following items:
The easiest method is now to either download or clone the repository.
Downloading can be done as follows:
Cloning can be done as follows by CLI:
Cloning can also be done through the GitHub Desktop client as follows:
The documentation for this SDK has improved so much it deserves its own section. The documentation is just clean and straight forward. Looking at it from a high level, you can browse each API and see the sections of what the underlying operations cover. Each of the operations list the method, URL, and a brief description of what it’s used for. To receive some more in-depth information, click on the operation’s method. Here you’ll see all the information needed in order to perform the request including the request parameters, response codes, JSON and XML response representations, followed by a table of what those response types mean, and it also covers the error codes.
One of the most convenient ways to get started using this SDK is with the Postman application. If you’ve never heard of Postman, it is a simple and free REST API client. It can be installed on Windows, OSX, and Linux (although this is currently a beta install). While there is a Chrome app, we have found the best experience is with the full client application.
Postman can be downloaded at the following link: https://www.getpostman.com/apps
At this point we have the SDK downloaded and the recommended client installed, so let’s get Postman setup with everything needed to work with the SDK.
First, start by importing the collections which were downloaded as part of the SDK. This can be done by clicking the “Import” button. On the new screen, with “Import File” selected, click the orange “Choose Files” button, browse to the location where you unzipped the SDK and then navigate to: client\samples\postman. Select the two JSON files in the directory titled:
We’ll now notice two new collections which are named quite similarly to the files imported. The vSphere Automation REST Resources collection is a number of requests, grouped in folders by their object level, that can be performed against a vSphere environment. The vSphere Automation REST Samples is a couple groups of requests which can be combined to perform a normal task. Some of the examples include ESXi host connection and disconnection, VM creation, and VM power actions.
Last part of setup comes down to configuring some environmental variables. As you begin browsing through the requests, you’ll start noticing some double curly brackets that may look like this: {{vc}} This is what’s known as an environmental variable within Postman, and vc will be used to refer to the vCenter Server. There’s only a couple environmental variables which need to be set in order to begin: vc, user, password. Those are fairly self-explanatory, so let’s set them up in Postman.
To begin creating environmental variables, head towards the gear icon in the top right hand side and click on it. This is where environments are managed. Add a new environment by clicking on the orange “Add” button. Give the environment a name, then enter in those three items mentioned above and valid values for your environment. Click the orange “Add” button again to complete the creation, and click on the “X” to the right of “Manage Environments” to close the window.
As with all vSphere environments, the first step is to authenticate. Expand the vSphere Automation REST Resources collection, expand the Authentication folder, and select Login.
We can gather a bit of information about the request at this point. We’ll be doing a Post method to the vCenter’s URL of /rest/com/cmware/cis/session with a basic authentication type and sourcing the username and password from our environmental variables. Before making the request, make sure to select the environment that was just created by selecting it via dropdown box next to the gear icon on the top right hand side.
NOTE: If you have any issues, you may need to turn off SSL certificate verification in the Settings (File > Settings > General tab > SSL certificate verification, turn off, restart Postman)
We’re now authenticated to the vCenter’s API endpoint, so we can start exploring some other areas within the vSphere Automation REST Resources section. Let’s do some environmental discovery while we’re still exploring the SDK.
To get a list of the hosts available by this vCenter’s API endpoint, expand the Hosts folder and select List. Here we can see the request uses a Get method to the vCenter’s URL of /rest/vcenter/host. Clicking “Send” will give us a list of the hosts available as well as some basic information such as the host ID, name, connection state, and power state.
To get a list of the datastores available by this vCenter’s API endpoint, expand the Datastores folder and select List. This request is very similar to the last request, except it points to the vCenter’s URL of /rest/vcenter/datastore. Clicking “Send” will give us a list of the datastores available as well as their datastore ID, name, type, free space and capacity.
To get a list of the VMs available by this vCenter’s API endpoint, expand the VM folder and select List. At this point, hopefully you can figure out what the request is going to look like and a rough guess at what information is going to be pulled back.
We’ve got the basics down now, how about getting into some additional detail on a VM. In the VM folder, select the Details. In the URL, we’re just appending the VM’s ID to the end of the prior call. The example includes ‘vm-22’ which can be modified to a VM ID as identified in the prior request. Clicking on “Send” retrieves a ton of information back about the configuration settings for that VM including CPU information, NICs, boot configuration, and so forth.
Last example, creating a VM. We’ve just seen all of the configuration settings for a VM, however we don’t need to have all of those to create a VM with this SDK. The API endpoint has the capability of setting those options automatically per best practices and VMware’s guidance. These decisions are all based on the guest OS type.
We’ll start by selecting the “Create with defaults” option. Notice the familiar URL, however we’re performing a Post method on it this time. Switching over to the “Body” section, we can see some items have already been filled in for us like Guest OS type, datastore, folder, and resource pool. These are the basics in order to perform this request.
Once those options have been filled in with valid values for your environment, click the blue “Send” button to create the VM.
You should see a response that resembles a VM ID. Run the VM Details request again, only this time substituting the new VM’s ID in the request URL. Scrolling through the response’s body, take note of many of the areas which were populated automatically. Things like memory, disk size, SCSI controller, even the name were all populated automatically.
If you’ve done this through the API before, this is a tremendous improvement! If there are additional things you’d like to specify, that’s possible as well. If you want to populate the settings for all of those items, that too is possible. It is all about the user’s choice.
We just scratched the surface on what’s possible with this SDK and Postman. There’s many more areas to check out and explore. There’s also the samples collection to take a look at too. Be on the lookout for part two, where we take a look through the javascript portion of this SDK!
If you’ve missed any of the prior posts, here are the others in the series: