VMware Hands-on Labs - HOL-SDC-1422

HOL-SDC-1422 - VMware Development Tools and SDKs

Lab Overview

This introductory lab will get you up and running building cloud infrastructure solutions with VMware development tools and SDKs. These are developer focused modules and some familiarity with programming in Java or Python is expected. But don't worry, no coding is required. Complete sample code has been provided.

The lab is broken into Modules and the Modules can be taken in any order. Use the "Table of Contents" button in the menu bar for quick access to the module content. You have 90 minutes per seating to work in the lab. This will be enough time to complete one or more modules. Each module may be completed individually. In some Modules, the Lessons build off of each other, so once you pick a module, you will need to follow each Lesson in order:

Module 1 - Developer Center, Workbench IS and the vSphere Management SDK (30 Minutes) - You will build a Java application to manage resources on vCenter server and ESXi server. There is a Java sample already included that manages VMs in a vCenter cluster.

Module 2 - pyvmomi - The Python SDK for VMware vSphere API (30 Minutes) - You will build a Python application to manage resources on vCenter server and ESXi server. There is a Python sample already included that lists the VMs in a vCenter cluster.

Module 3 - Workbench IS Tools (15 Minutes) - This module is an introduction to tools included in Workbench IS including: RSE (Remote System Explorer) - A tool to inspect and manage resources on a remote ESXi or vCenter system and Log Browser - A tool to collect, analyze, and correlate log files from a remote system.

NOTE: If you are using a device with non-US keyboard layout, you might find it difficult to enter CLI commands, user names and passwords throughout the modules in this lab. Refer to the file README.txt on the desktop for additional information on resolving any keyboard input issues.

Introduction

This module will show you how to build a Java application to manage resources on vCenter server and ESXi server. There is a Java sample already included that manages VMs in a vCenter cluster. This module is expected to take approximately 30 minutes.

At the end there is an optional section that will cover installation of the Eclipse-based Workbench IS tooling and the SDK on your own system.

Using Workbench IS and the vSphere Management SDK

This lesson shows you how to use Workbench IS to run the sample and view the results. This also takes you through the code to understand how the SDK may be used to perform operations on the virtual infrastructure. For more detailed explanation refer to the SDK documentation at http://developercenter.vmware.com>> SDKs >> vSphere Management SDK.

First you will run the sample application from the command line via a batch script. Then you will debug the sample application using Workbench IS and the Eclipse debugger.

Run sample application

The sample can be run by double clicking PowerOnVM.bat on the desktop. Just hit "enter" four times to accept the defaults and connect to the vCenter instance in the lab, then follow the menu prompts to navigate the vCenter hierarchy. The image above shows an example run of the sample application.

Press "0" to return to previous menu or press a number to select an item from the menu.

Debug sample application

To debug the sample application, first launch Eclipse by double clicking the icon on the desktop.

Press the triangle next to the debug icon and select Debug Configurations ...

Debug

Select Java Application >> PowerOnVM.

The image above shows how the debug configuration is set up. The Main class is com.vmware.samples.poweronvm.Main

Click Debug to run the sample application in the Workbench IS debugger.

You can use the Eclipse debugger features to set breakpoints in the code, step through code, inspect variables, etc.

Sample application outline

Navigate back to the Java perspective and open the PowerOnVM project in the package explorer.

The image above shows the outline of the sample application. A more detailed explanation can be found in the code comments.

Connection.java: This class has methods for connecting and disconnecting from the vCenter Server.

HelloSDK.java: This is the main program entry point and it drives the console based UI for the sample.

Hosts.java: This class has methods for getting the ESXi host properties and Managed Object References (Morefs). Morefs are "handles" to remote objects in ESX or vCenter. When you manipulate the Moref, corresponding actions occur on the remote system.

SimpleUI.java: This class has helper methods used for rendering the menu based UI and capturing the users input. The user interface has intentionally been made simple and loosely coupled to allow easy reuse of this sample in a Web application or stand-alone Java application.

SSLCert.java: This class is used by the Connection class to handle the SSL Certificates for the vCenter connection.

VirtualMachine.java: This class has all the methods that interact with virtual machines such as getting VM properties, VM Power operations, getting VM name, getting VM Morefs etc

VMTask.java: This class has some helper methods used by the VirtualMachine class.

Creating a new vSphere management sample application

This lesson shows how to setup a vSphere Web Services Sample Application and configure it to run a sample.

Create new Eclipse project

Start the Eclipse IDE by double clicking on the desktop icon.

From the "File" Menu select "New" then "Other" as shown in the image above.

Select a wizard

Scroll down to the "VMware" folder and select the "Development Kit Projects" wizard and click Next.

Create a new Debug (or Run) configuration

In the Package Explorer select the newly created samples project (e.g. vspheresamples).

Press the triangle next to the debug icon.

Select Debug Configurations ...

Create a Java launch configuration

Select Java Application

Press the New button to create a new launch configuration

Set the Name (e.g. vspheresamples)

Set the Main class to com.vmware.common.Main

Set the Program arguments and debug

To run a sample specify the sample class name in the arguments section of the launch configuration. You will run the SimpleClient sample. This sample will connect to a vCenter server and print out an inventory of datacenters, hosts, and virtual machines.

Select the Arguments tab

Set the Program arguments to com.vmware.general.SimpleClient

Press Apply to save the configuration

Press Debug to run the sample

Sample output

The image above shows an example run of the SimpleClient code sample

Next steps

You now know how to build a Java application to manage resources on vCenter server or ESXi server.

For further study, try some of the following:

Set a breakpoint in the PowerOnVM application and debug. Step through the code and inspect the returned data structures.

Extend the PowerOnVM sample. Inspect and copy code fragments from the sample created in "Creating a new vSphere management sample application" and add them to PowerOnVM. For example "clone" the VM (see class VMclone.java).

Make it yours (optional)

Module 2 - pyvmomi - The Python SDK for VMware vSphere API (30 min)

Introduction

This module will show you how to build a Python script or application to manage resources on vCenter server and ESXi server. There is a Python sample already included that lists the VMs in a vCenter cluster. This module is expected to take approximately 30 minutes.

At the end there is an optional section that will cover installation of the pyvmomi SDK on your own system.

Using PyDev and the pyvmomi SDK

This lesson shows you how to use Workbench IS and the PyDev plugin to run the sample and view the results. This also takes you through the code to understand how the SDK may be used to perform operations on the virtual infrastructure in a vSphere or vCenter environment.

First you will run the sample application from the command line via a Python script. Then you will debug the sample application using Workbench IS with the PyDev plugin and the Eclipse debugger.

Run sample application

The sample can be run by double clicking GetAllVMs.bat on the desktop. The image above shows an example run of the sample application.

Edit sample application

Start Workbench IS by double clicking on the Eclipse icon on the desktop

Navigate to the PyDev perspective.

Open the GetAllVMs project in the PyDev Package Explorer.

Open getallvms.py.

The image above shows the sample application. A more detailed explanation can be found in the code comments.

Debug sample application

In this lesson you will learn how to debug a pyvmomi Python application.

Set a breakpoint

In getallvms.py scroll down into the main function.

At the line vm_folder = datacenter.vmFolder right click in the left margin to get the context menu as shown in the image above.

Select Add Breakpoint

Verify breakpoint

You will know that the breakpoint is set when you see the green debug icon to the left of the line of code.

Select Debug Configurations

Press the triangle next to the debug icon and select Debug Configurations ...

Click Debug to run the sample application in the Workbench IS debugger.

Inspect the results

The image above shows the Eclipse graphical debugger. Try inspecting the datacenter variable or stepping through the code.

Inspecting the vCenter inventory from the Python interpreter.

One of the benefits of the Python programming language is its interpretive nature and powerful interactive shell. In this lesson you will learn how to use these tools to inspect the vCenter hierarchy of objects (Datacenter, Host, VM, etc.).

While you can always get to the Python interpreter by typing python in a terminal window, using a special purpose Python shell has advantages such as command completion.

If you prefer using command line and no IDE, then try IDLE, the shell that comes with your Python installation. You may run it by double clicking the icon on the desktop.

The examples below will use the console shell that comes with PyDev.

You may cut and paste helpful text from the README.txt file on the desktop.

Understanding the vCenter Inventory Hierarchy

VMware vCenter allows you to manage physical and virtual infrastructure in a datacenter. The pyvmomi SDK provides Python bindings that allow you to programmatically manage the inventory of that same infrastructure.

The inventory is managed as a collection of virtual datacenters. Each datacenter contains compute, data storage, and networking resources. Virtual machines and virtual applications can be created in these datacenters that consume these resources. Folders can be used to hierarchically group objects of the same type. The nested structure allows you to organize the objects in the datacenter into an easily manageable structure. Possible reasons include aligning with various functions and/or organizational structure.

The image above shows the hierarchy of objects in the vCenter inventory.

For many pyvmomi applications, the flow of applications is similar. You connect to a vCenter server, get a service instance, and starting with the root folder, navigate the hierarchy. You can then perform various operations on these managed objects.

Launching the PyDev console

Navigate to the PyDev perspective and make sure a console is visible. If no console is visible, you can launch one with menu Window >> Show View >> Console.

In the console view, press the triangle next to the Open Console icon and select PyDev Console.

Configure the console

Select Python console and press OK.

The Python interpreter shell will start. Double click the console tab to expand or restore the console view. Press the stop icon to exit the console.

Initial setup and useful commands

In the console type

from pyVim import connect

Nothing is returned but this loads parts of the pyvmomi library into the interpreter.

Useful commands

Use the up and down arrows to navigate the command history. Use <tab> or <control>-<space> for command completion.

will print the directory of the object, showing properties and methods.

Navigate to a VM

Type the following commands to get to a VM. Remember to use <tab> or <control>-<space> for command completion.

Get the inventory:

inv = si.RetrieveContent()

Get the (first) datacenter:

dc1 = inv.rootFolder.childEntity[0]

Make sure we really have a datacenter:

type(dc1)

returns:

<class 'pyVmomi.VmomiSupport.vim.Datacenter'>

The type command is useful in the interpreter, but when writing scripts, there is a another way to check types at runtime. First import the vim module:

from pyVmomi import vim

This imports the vim and vmodl symbol tables and allows you to use shorter class names.

isinstance(dc1, vim.Datacenter) == True

can now be used to ensure that we really have a datacenter object.

Now get a list of VMs:

vmList = dc1.vmFolder.childEntity

Get the first VM

vm = vmList[0]

Verify the type.

type(vm)

But wait, this is a folder not a VM. Remember the vmfolder may be just a collection of VMs, but it really is a hierarchy of VMs grouped using subfolders. The same is true for other folders (datacenter, datastore, network, etc.) Try again seting vm = vmList[1]. Use the up arrow to go up the command history and edit the 0 into a 1 to save typing.

This time type(vm) returns:

<class 'pyVmomi.VmomiSupport.vim.VirtualMachine'>

Get the vm name:

vm.name

returns

'w12-core1'

vm.summary

will return a wealth of information about this VM, including runtime, configuration, and guest properties.

Power on VM

Now you will power on the VM.

First check the power state of the VM:

vm.runtime.powerState

returns

'poweredOff'

Power on the VM with the following command:

t = vm.PowerOn()

Code completion can be used to quickly get you to relevant properties and functions.

Type t = vm.p and wait for the pop up completion menu. If the menu doesn't appear, use <control>-<space>. Use the arrow key to select PowerOn().

The image above shows how code completion works.

Press <enter> twice to execute the power on command.

A task is launched on the remote server.

t.info

returns status of the task.

Specifically:

t.info.state

will return

'success'

when the PowerOn task has successfully completed on the server.

Verify the state of the VM:

vm.runtime.powerState

returns

'poweredOn'

Use vCenter to check VM power state

You can verify the VM is really powered on in vCenter.

Launch the firefox browser and go to the vSphere Web Client page.

Log in as user root password VMware1!.

Navigate the hierarchy and get the summary for VM w12-core.

The summary shows that the VM is up and running.

Putting it all together

The project powercyclevm contains a Python script to select a VM by name, power it off and power it back on. It optionally answers any VM questions on power on.

Edit powercyclevm

Edit the file virtual_machine_power_cycle_and_question.py

This script uses Tasks and you can see it check the state of the tasks to ensure previous steps have completed.

Try debugging this application and stepping through the code. Use the powercyclevm debug configuration to launch the script.

Next Steps

You now know how to build a Python application to manage resources on vCenter server or ESXi server.

Module 3 - Workbench IS Tools (15 min)

Introduction

RSE - Remote System Explorer - This tool allows you to inspect and manage resources on a remote ESXi or vCenter system including files, the datacenter inventory, virtual machines and ssh sessions.

Log Browser - This tool allows you to collect, analyze, and correlate log files from a remote system.

This module is expected to take approximately 15 minutes.

Using the Remote System Explorer (RSE)

In this lesson you will use the Remote System Explorer to connect to an ESX host or vCenter server, explore the inventory of resources, power on a virtual machine, and launch an SSH terminal window on an ESX host.

Think of the Remote System Explorer as a mini vSphere Client (albeit with limited functionality) embedded in the Eclipse IDE. This can be useful if you need to connect to an ESX host directly or prefer an experience, integrated with your development environment, for inspecting and manipulating the vCenter infrastructure. RSE is cross platform and runs on Windows, Linux, and Mac OSX.

Switch to the Remote System Explorer perspective

Launch Eclipse by double clicking the icon on the desktop.

Switch to the Remote System Explorer (RSE) perspective by clicking the icon on the upper right.

Connect to a vCenter server

Right click in the Remote System panel and select New >> Connection …

Select the connection type

Select Virtual Center for Linux and click Next

New Connection wizard

In the New Connection wizard set the Host name to vcsa-01a.corp.local, the User name to root, and the Password to VMware1! and click Finish.

Explore vCenter resources

You will now see a new connection. Expand the hierarchy. You can see the inventory of resources such as datacenters, clusters, and hosts, as well as a list of VMs.

Click on a VM and, in the Properties panel, you will see a summary of properties for the VM such as memory, cpus, etc.

Power on a Virtual Machine

In the Remote System panel, find a VM in the vCenter inventory and right click to get a context menu. Then select Power On.

If the VM is already powered on, you will see options to power off, suspend or reset the VM.

Connect to an ESX host

Open the Remote System Explorer perspective.

Right click in the Remote System panel and select New >> Connection …

Select the connection type

Select ESX and click Next

New Connection wizard

In the New Connection wizard set the Host name to esx-01a.corp.local, the User name to root, and the Password to VMware1!

Click Finish

Explore ESX resources

You will now see a new connection. Expand the hierarchy. You can see resources such as datastores and network devices, as well as a list of VMs.

Click on a VM and, in the Properties panel, you will see a summary of properties for the VM such as memory, cpus, etc.

Open an SSH terminal on an ESX host

In the Remote Systems panel, right click on Ssh Terminals to get a context menu and select Launch Terminal.

If this is the first time you are connecting to this host, you may see a message about unknown SSH hosts. Click Yes to allow the connection to proceed.

SSH terminal

A Terminals panel appears with a remote connection to the ESX host. You may now perform administrative tasks such as running ESXCLI commands.

Using the Log Browser

Log Browser allows you to collect, analyze, and correlate log files from a remote ESX or vCenter system. In normal development, you may never need Log Browser. However, if something goes wrong, this can be a powerful diagnostic tool.

In this lesson you will use Log Browser to connect to an ESX host, collect system log files, and analyze one of them to find errors and specific events such as the power on of a virtual machine.

Open the resource perspective

Click the Open Perspective button and select Resource.

Create a new Log Analysis

In the menu select File >> New >> Log Analysis.

New Log Analysis wizard

Set the Source host by selecting esx-01.corp.local from the pull down menu. This connection should already exist from the lesson Using the Remote System Explorer >> Connect to an ESX host. If it does not exist you may create it by clicking the Add … button.

Set the Log format by selecting [Standard Log Collection] from the pull down menu.

Set the Project container with any project name such as esxlogs (the project will be created if it doesn’t exist).

Click Next.

Summary

Click Finish to create the new log analysis.

Open the Log Browser views

Double click on esx-01a.corp.local_hostd.logx to open the Log Viewer with that log file.

Double click on the log entry "Current working directory ..." to open the Log Entry Details view with that log entry.

Analyzing a log file

You can use filtering to find patterns or events in log files.

Type error in the Filter input field and click the Filter button (the button label will change to Unfilter). You will now see all log entries with the string error.

You can use this same technique to find warnings as well. You can also use the filter with any set of keywords to find specific events.

Find PowerOn events

Type PowerOn in the Filter input field and also check the Case sensitive checkbox.

Click the Filter button (the button label will change to Unfilter).

You will now see all of the PowerOn events. If you double click on the log entry you can find detailed information down to the path to the virtual machine VMX files.

You can use this technique to help diagnose various development tasks. If you were writing vSphere programs or scripts to add a datastore, you could filter the logs using the datastore keyword to find all log messages related to datastores on this ESX host.

Conclusion

Thank you for participating in the VMware Hands-on Labs. Be sure to visit http://hol.vmware.com/ to continue your lab experience online.