VMware Hands-on Labs - HOL-1811-07-SDC


Lab Overview - HOL-1811-07-SDC - Building a vSphere Client HTML Plugin Using the SDK

Lab Guidance


Recommended audience:  vSphere users and web app developers with an interest in developing customized UI functionality for the vSphere Client 

The Table of Contents can be accessed in the upper right-hand corner of the Lab Manual.

Lab Modules:

Module 2 can be taken independently from Module 1, however we recommend to start with the Introduction section of Module 1 which presents the vSphere Client SDK.

This lab manual can be downloaded from the Hands-on Labs Document site found here:

[http://docs.hol.pub/HOL-2017]

This lab may be available in other languages.  To set your language preference and have a localized manual deployed with your lab, you may utilize this document to help guide you through the process:

http://docs.hol.vmware.com/announcements/nee-default-language.pdf


 

Location of the Main Console

 

  1. The area in the RED box contains the Main Console.  The Lab Manual is on the tab to the Right of the Main Console.
  2. A particular lab may have additional consoles found on separate tabs in the upper left. You will be directed to open another specific console if needed.
  3. Your lab starts with 90 minutes on the timer.  The lab can not be saved.  All your work must be done during the lab session.  But you can click the EXTEND to increase your time.  If you are at a VMware event, you can extend your lab time twice, for up to 30 minutes.  Each click gives you an additional 15 minutes.  Outside of VMware events, you can extend your lab time up to 9 hours and 30 minutes. Each click gives you an additional hour.

 

 

Methods of Keyboard Data Entry

During this lab, you will be asked to enter commands and code into the Main Console. Besides directly typing in it you can also select text from the manual and drag it to the console.  However this doesn't work well for large text content. Instead we have provided a separate text file named Code and Commands to Copy.txt which contains the same text content and that you should keep open in Notepad or Notepad++.  For details see "Important note on copying text from the Manual" at end of Module 1's Introduction, following this Lab Guidance.

 

 

Activation Prompt or Watermark

 

When you first start your lab, you may notice a watermark on the desktop indicating that Windows is not activated.  

One of the major benefits of virtualization is that virtual machines can be moved and run on any platform.  The Hands-on Labs utilizes this benefit and we are able to run the labs out of multiple datacenters.  However, these datacenters may not have identical processors, which triggers a Microsoft activation check through the Internet.

Rest assured, VMware and the Hands-on Labs are in full compliance with Microsoft licensing requirements.  The lab that you are using is a self-contained pod and does not have full access to the Internet, which is required for Windows to verify the activation.  Without full access to the Internet, this automated process fails and you see this watermark.

This cosmetic issue has no effect on your lab.  

 

Module 1 - Build a vSphere Client Plugin the Easy Way (60 minutes)

Introduction


During this lab you will learn how to build and deploy a new vSphere Client plugin from scratch and take advantage of vSphere Client extensibility mechanisms. You will be using the vSphere Client SDK along with a leading-edge UI stack: Angular, Typescript, Clarity and Angular-CLI.

The content is fairly technical and it is recommended to have some web application development experience. But do not worry if you are not familiar with the UI stack or the vSphere Client SDK, the manual will guide you at every step!


 

vSphere Client SDK

vSphere Client SDK is a collection of libraries, tools, code samples and documentation that help you create vSphere Client HTML extensions to provide customized solutions in the vSphere UI.

 

 

 

Plugin Seed

 

Plugin seed is a tool that was added after the HTML Client SDK 6.5 release with three main goals in mind:

- Make it easier to start a vSphere Client plugin from scratch.

- Increase developer productivity with a fast development process and robust patterns.

- Use a modern UI stack.

This lab was built with plugin-seed 0.9.7 released on 5/7/2017.  After you complete the lab you can download the latest version on the HTML Client Fling page at https://labs.vmware.com/flings/vsphere-html5-web-client  (look for plugin-seed-<version>.zip in the drop down box)

 

 

Important note on copying text from the Manual

This lab contains a fair amount of commands to enter, and HTML / Javascript code to type. Unfortunately there is no fast way to copy/paste text from the manual to the lab console.   Single line commands can be copied using the drag & drop tool as shown in the picture below.  For bigger text sections we have provided a file named Code and Commands to Copy.txt that you should keep open in Notepad or Notepad++ so that you can  copy the same text referenced in the manual.

Drag & drop of single-line commands

Drag the seleted text to the Command Prompt window as shown below.
NOTE: the text is sent at a slow pace!  DO NOT click anywhere else in the console while this is happening.

Once the text is sent, click in the Command Prompt and hit Enter to execute the command.

 

All text input is in file: Code and Commands to Copy.txt

 

 

Getting Started with the Plugin Seed



 

Prepare to generate and run your first plugin

 

Open a command line window with Command Prompt in the bottom bar.

 

Click in the top left corner of the window (C:\), select Properties and increase the window Width to 100 or more in order to make command lines more readable throughout this lab.

IMPORTANT: you will be asked to open several command line windows for different purposes. It is important NOT to close them unless the manual explicitly ask you to do so.

 

 

Open Visual Studio Code

 

In this lab we will use Visual Studio Code as our development environment for editing HTML and Javascript code.

Double-click on the desktop icon on the left, or type Visual Studio in the Windows Start menu.

 

Open the File menu and verify that the Auto Save option is turned on.

Every code change will be applied directly to the running plugin. It is better not to have to remember to save your changes and to see the effect right away in the browser!

 

 

Install node modules

The plugin UI is a web application which depends on several Node modules both for its production build and its development setup. Since this lab doesn't have internet access we cannot use the npm or yarn commands to download those modules. Instead we will decompress an existing folder containing all the modules needed.

If you are curious about these dependencies see the file myplugin-ui/src/package.json for the full list.

 

In File Explorer right-click on node_modules.zip located in webClientPlugin and select Extract All...

Change the destination directory to C:\LabFiles\HOL-1811\webClientPlugin\generated\myplugin-ui and click Extract

 

WARNING: This operation takes time because of the large number of files being extracted.  A progress window should appear but it may be hidden behind other windows. You can skip to the next step or wait for the operation to complete. At the minimum you should check that the directory node_modules was created inside myplugin-ui

 

 

Start json-server to serve mock data

Separating the UI from backend services with the help of mock data is a common practice that speeds up the development process.  Our plugin uses json-server as a simple backend for prototyping and mocking. Other mocking solutions are available but json-server is very simple to set up and supports REST APIs.

 

Open a new Command Prompt and go to myplugin-ui

cd C:\LabFiles\HOL-1811\webClientPlugin\generated\myplugin-ui

 

Start the json-server with this command:

 npm run json-server 

The server responds with a list of its API resources and its home URL http://localhost:3000

NOTE: Command npm run json-server executes the script "json-server" defined at the top package.json.   Do NOT close this Command Prompt window for the rest of the lab because json-server needs to be running.

 

 

Start myplugin in Dev mode

As mentioned in the introduction the best way to start working on a new plugin is in Dev mode, i.e. the plugin UI is developped initially as a pure Angular application, outside the vSphere Client itself.

 

Switch back to the first command prompt you created (where the current directory should be simple-seed) and enter:

cd ..\generated\myplugin-ui
npm start

npm start builds a runtime version of the plugin app and launches a development server which makes the app available available at port 4201.

You should see the final output as shown above. This is standard for an Angular-CLI application, the build creates several .bundle.js files which contain the application components.

NOTE: if npm start gives you an error it's probably because the npm modules were not installed under myplugin-ui in the previous step. Go back and make sure you typed the correct destination when extracting node_modules.zip.  You must have a node_modules directory under generated\myplugin-ui.

 

 

Explore myplugin UI

 

Open Google Chrome from the desktop, or from the Start menu.

 

Chrome starts initially with a tab opened with vSphere Web Client, which won't be used here.

Replace that URL with http://localhost:4201/, or select the bookmark myplugin at the very end of the bookmarks bar.

This opens up myplugin's Home page.  The generated UI comes with various tools that we will explore next.

 

 

Backend APIs mocked with json-server

 

Open another Chrome tab and enter

 http://localhost:3000/hosts

This URL is a simple API which returns the list of mock hosts in json format as defined in db.json.  URL http://localhost:3000 is the default address for json-server.

To access a single host add the id at the end of the URL, like this:

 http://localhost:3000/hosts/1

 

 

Small improvement to the Host Monitor view

Now that we have done a quick tour of the generated plugin let's add more functionality to the host Monitor view. The current implementation only shows the number of VMs per host. We would like to make the Virtual Machines line expand with the list of VMs.

Switch back to Visual Studio Code

 

Deploy myPlugin to vSphere Client


In order to deploy a plugin with vSphere Client we need to build its UI and service bundles, to package them into a plugin package folder and to add this folder to your local vSphere Client setup for testing.  All this can be done with the script build-plugin-package

 

Open a new Command Prompt  


 

Build the plugin package

 

Enter the following in the command line window:

cd C:\LabFiles\HOL-1811\webClientPlugin\generated\myplugin-ui\ 

tools\build-plugin-package.bat 

This script takes about 30 seconds. It compiles both the UI and Java bundles of myplugin, generates a plugin package folder and copy it at the right location for the local Client.

You should see BUILD SUCCESSFUL once the script completes.

 

 

 

Start vSphere Client

A vSphere Client instance is included in the HTML Client SDK installed on this Windows machine, its runtime is called the Virgo server.  Once the script build-plugin-package.bat completes it gives this message as a reminder that a new plugin package requires a server restart.

 [echo] *** You must restart the Virgo server to use the new plugin package! ***

Start the Virgo server with the following command in the same terminal window:

%VSPHERE_SDK_HOME%\vsphere-ui\server\bin\startup.bat

Starting the server may take a couple of minutes depending on the performance of the lab environment. Luckily, during normal development, it doesn't need to be restarted very often because UI changes can be made live as we will see later.

Open a new tab in Chrome and enter https://localhost:9443/ui which is the entry point for the local vSphere Client.

 

 

myplugin in plugin mode

 

Click on Menu

Click on Shortcuts

You may need to either expand the browser size or minimize the Recent Tasks view at the bottom in order to see enough content.

 

 

 

Live data in Dev mode

Mock data is nice to start prototyping fast but at some point you also want to test with real data coming from backend services.  The “best of both worlds” would be to connect to real vSphere data while still in Dev mode.  Plugin-seed provides a simple mechanism to achieve that!

 

Go back to the tab where myplugin runs as standalone UI at URL http://localhost:4201/main

Click on the Live data switch in the header.

This has the effect to change the data request URL from the mock json-server endpoint to the java service endpoint, running in the Virgo server. We get an http error because the request going to Virgo is not authenticated.  Java services running in Virgo can only access vSphere data through an authenticated session obtained through the vSphere Client login.

To work around this error we are going to re-use a valid user session id, i.e. Client id, from vSphere Client running in the same browser!

Turn off Live data for now.

Go back to the vSphere Client tab.

The generated plugin has a built-in tool for setting the Client id, it is located in the Settings view in the Administration area.

 

 

 

Fast UI updates in plugin mode

We have seen in the previous chapter that code changes are reflected right away in dev mode, but it is also possible to quickly refresh the plugin UI code loaded in the vSphere Client.

This is done with the gulp watch script which compiles and pushes those changes to the vSphere Client.

 

 

Open a new command prompt and do the following:

cd C:\LabFiles\HOL-1811\webClientPlugin\generated\myplugin-ui
gulp watch

The gulp script compiles the UI code and uses Angular-CLI “watch mode” to react to code changes.  It takes a few seconds to initialize that mode, the terminal shows the UI build being updated once, with the javascript bundles in green.

After that initial step future code changes will trigger a fast incremental build.

Let's try it, switch to Chrome.

 

 

Updating HostService to display the VM names

The change made earlier to the Monitor view shows Virtual Machine IDs, not their names.  Let’s make another change to get the real VM names from the backend.

NOTE: As you make more code changes throughout this lab the Chrome tab myplugin will be refreshed automatically.  You may get a black screen showing Failed to Compile and a compilation error message.  This is normal if it takes several steps to complete a correct implementation.

 

Add a VM Monitor View


In this section we will add a brand new plugin view, under the VM > Monitor tab, to display some Virtual Machine CPU and Memory statistics. First we will add the view UI in Dev mode using Angular-CLI commands.

NOTE: this module takes 20-25 minutes to complete.  If you are short of time and cannot extend your Lab you can also skip ahead at any time to the last module "Plugin Lifecycle" which is independant.


 

Add the View Component

First we create a vm-monitor directory under myplugin-ui/src/app/views

 

 

Open a new command prompt and enter the following:

cd C:\LabFiles\HOL-1811\webClientPlugin\generated\myplugin-ui\src\app\views 
mkdir vm-monitor 
cd vm-monitor

 

 

 

Add a VM Service to retrieve data

We need a new Angular service to retrieve the stats for a Virtual Machine, similar to the HostService in host.service.ts used to retrieve Host data.

We will generate VmService.

 

You can re-use the command line window where you created VmMonitorComponent.

Go to the \src\app\services directory and run the generate command below:

cd C:\LabFiles\HOL-1811\webClientPlugin\generated\myplugin-ui\src\app\services
ng generate service vm --flat --module ../app.module.ts

In Visual Studio Code, see the files vm.service.ts and vm.service.spec.ts (unit tests) generated in /services.  Note that VmService was also added to app.module.ts list of service providers.

 

 

Add some mock VM data

Now that we updated the VM model let's add some mock data in db.json to match this model.

 

Open db.json

Look for "hosts: [ and add some space above it.

Select then copy this json data for three VMs  (drag it first to a Notepad window):

"vms": [
 {
   "id": "vm-10",
   "name": "mock-VM 1",
   "numCPU": 1,
   "maxCpuUsage": 2500,
   "overallCpuUsage": 2000,
   "overallCpuDemand": 1500,
   "maxMemoryUsage": 4096,
   "consumedOverheadMemory": 2000,
   "hostMemoryUsage": 3000
 },
 {
   "id": "vm-11",
   "name": "mock-VM 2",
   "numCPU": 2,
   "maxCpuUsage": 4000,
   "overallCpuUsage": 1500,
   "overallCpuDemand": 1000,
   "maxMemoryUsage": 2048,
   "consumedOverheadMemory": 1000,
   "hostMemoryUsage": 1500
 },
 {
   "id": "vm-12",
   "name": "mock-VM 3",
   "numCPU": 4,
   "maxCpuUsage": 3300,
   "overallCpuUsage": 1500,
   "overallCpuDemand": 0,
   "maxMemoryUsage": 2048,
   "consumedOverheadMemory": 20,
   "hostMemoryUsage": 26
 }
],

Let's check this new vms API in the browser:

 

Open a new Chrome tab at http://localhost:3000/vms

Verify that the VM data you just added is served through the json-server.

To get data for a specific VM add it id to the path, like http://localhost:3000/vms/vm-10, http://localhost:3000/vms/vm-11 , etc.

WARNING: If no data is returned in the browser it must be because of an invalid character in db.json. Check the command line window where you started the json-server, it will report errors with a line number.

 

 

Live VM Data

Let's look at the "live data" URL to retrieve the same VM properties.

 

The live data URL for VMs has the same format as for Hosts seen in the previous chapter, but uses a VM id and the list of VM properties. The picture above shows how you can copy the VM id embedded in the browser URL.  Below is the live data URL for that particular VM:

Open a new Chrome tab.

Select this entire URL then drag it to Chrome:

https://localhost:9443/ui/myplugin/rest/data/properties/urn:vmomi:VirtualMachine:vm-222:86cc9f35-d529-4404-ad5d-e08fe87e2c64?properties=name,config.hardware.numCPU,runtime.maxCpuUsage,summary.quickStats.overallCpuUsage,summary.quickStats.overallCpuDemand,summary.quickStats.hostMemoryUsage,summary.quickStats.consumedOverheadMemory 

 

 

The result of the http request is the json data returned by myplugin service, with the values for that VM.

Note that the property names are returned in their long format since it is what the request contained. We will need some code to convert them to their short format.

WARNING: If this URL doesn't return any data it may be because your current vSphere Client session has expired.  Go to https://localhost:9443/ui and login again.

 

With data request in mind we can now write a getVmProperties() function which will use the Angular Http service and return an Observable (i.e. a stream) containing the VM data.

Switch to Visual Studio Code

 

 

Modify VmService

 

Use Ctrl + P to find vm.service.ts under src\app\services

Replace the previously generated content with the following code:

import { Injectable } from '@angular/core';
import { Http } from "@angular/http";
import { VM } from "./vm.model";
import { GlobalsService } from "../shared/globals.service";
import { Observable } from "rxjs/Observable";
 
@Injectable()
export class VmService {
 
  constructor(private http: Http,
              private gs: GlobalsService) {
  }
}

The VmService constructor injects two existing services, this is the Angular way to make services available to classes.

- Http is the Angular service which allows to call backend APIs through standard http calls.

- GlobalsService is a built-in utility provided by plugin-seed to access global state information.

 

 

Prepare the VM Monitor view

Now that we have a VmService, let’s add the HTML content and wire up the Monitor view.  The first step is to add the Dev mode elements, header and sidenav, to integrate the view with the rest of the standalone app,as well as the app-alert component to report service errors.

 

 

In Visual Studio Code use Ctrl + P and find the file vm-monitor.component.html in myplugin-ui\src\app\views\vm-monitor

Replace the previously generated code with the following lines:

<!-- Optional alert component at the top of the view -->
<app-alert></app-alert>

<!-- Dev mode header -->
<app-header *ngIf="gs.showDevUI()" ></app-header>

<div class="main-container">
  <div class="content-container">
    <div class="content-area">
      <!-- Monitor view content -->
      <p>
        vm-monitor works!
      </p>
    </div>
    <!-- Dev mode sidenav to facilitate object navigation -->
    <sidenav *ngIf="gs.showSidenav()" style="order:-1"></sidenav>
  </div>
</div>

*ngIf="gs.showDevUI()  means that the app-header component is only displayed when showDevUI() returns true.  

Likewise *ngIf="gs.showSidenav() means that the sidenav component is only displayed when showSidenav() returns true.

Variable gs represents the GlobalsService provided in /shared/globals.service.ts, it gives access to global environment properties.

In order to use gs in the HTML template we must now inject it in the VmMonitorComponent constructor:

 

  1. Open vm-monitor.component.ts in the same directory.
  2. Add the constructor argument public  gs: GlobalsService
  3. Add the import statement for GlobalsService (or click on the light bulb that shows up when GlobalsService is still unknown)

 

 

Add visuals to the data

We want to display CPU and memory stats with simple meter bars as shown below. We will use a Clarity progress bar component to represent these meters.  This is how it will look like when you are done with the next few steps:

 

 

Open vm-monitor.component.html  in Visual Studio Code.

Paste the whole content <!-- Monitor view content --> provided above, in place of the title inside <div class="content-area">

See the app refresh automatically at http://localhost:4201/vm-monitor/vm-10, you should get the sample display as the screenshot above.

 

 

Replace hard-coded values

The next step is to replace the meters' hard-coded values with mock data, and then with service calls.

 

Before using VmService to get VM data let’s add a mockVm object in vm.model.ts:

Use Ctrl + P to open vm.model.ts at myplugin-ui\src\app\services

Select then copy this code at the end of the file:

export const mockVm: VM = {
   id: "vm-10",
   name: "mock-VM1",
   numCPU: 1,
   maxCpuUsage: 2500,
   overallCpuUsage: 2000,
   overallCpuDemand: 1500,
   maxMemoryUsage: 4096,
   consumedOverheadMemory: 2000,
   hostMemoryUsage: 3000
}

Now we will import the new mockVm in vm-monitor.component.ts and use it to initialize a vm object that represents the current VM data displayed in the view.

 

Use Ctrl + P to open vm-monitor.component.ts

  1. Declare the class variable:
    vm: VM;
  2. Initialize that variable in the constructor:
    this.vm = mockVm;
  3. Add the import statement to make the compiler happy:
    import { VM, mockVm} from "app/services/vm.model";

 

We also need a function to compute the percentage values used by the progress bar meters:

Select then copy or drag this code after the ngOnInit() function:

// Return CPU and Memory stats in whole integer percentages
percents(vm: VM) {
   return {
      cpuConsumed: Math.round(100 * vm.overallCpuUsage / vm.maxCpuUsage),
      cpuActive: Math.round(100 * vm.overallCpuDemand / vm.maxCpuUsage),
      memConsumed: Math.round(100 * vm.hostMemoryUsage / vm.maxMemoryUsage),
      memActive: Math.round(100 * vm.consumedOverheadMemory / vm.maxMemoryUsage)
   }
}

 

 

Use VmService for live data

Now we can wire up VmService and retrieve the real VM data based on the vm id

 

 

Navigating from Host to VM Monitor

Now that our VM monitor view is working it would be nice to let users navigate from a Host to its VMs. For this we will add a link over each VM name.

 

Open monitor.component.html

Add this <a> tag around the {{vm.name}} value

<clr-stack-content>
   <a (click)="goToVmMonitor(vm.id)" style="cursor: pointer">{{vm.name}}</a>
</clr-stack-content>

Note that we are changing the cursor to the pointer style to indicate that the name is clickable.

 

Function goToVmMonitor needs to be added to the HostMonitorComponent class:

Open monitor.component.ts

Select then copy or drag this code at the end of the class, before the last closing }

// Navigate to the VM monitor view for the given VM id
goToVmMonitor(id: string): void {
   this.nav.showObjectView(id, "vm", "monitor");
}

The NavService in app/services/nav.service.ts already implements a generic showObjectView function which takes care of routing the application to the correct component.  You can now click on the VM name in the Host > Monitor view and navigate to the corresponding VM Monitor view.

  1. Select mock-Host 1 Monitor view
  2. Click Virtual Machines and see the list: vm-10, vm-11, vm-12
  3. When you mouse over each vm name it becomes a blue link and the cursor becomes a pointer.
  4. Click on vm-11 for instance.  This takes you to the monitor view of mock-VM 2 as shown below.
  5. See how the URL gets updated to http://localhost:4201/vm-monitor/vm-11
  6. The left navigator doesn't change because it doesn't support VM objects, but you can use the browser left and right arrows to go back and forth.

 

 

 

 

Adding Error Handling

NOTE: This section can be skipped if you are short of time and prefer to complete the rest of the lab.  In that case please continue to the next section: New VM Monitor in Plugin Mode.

 

When you navigate to a non existing vm the view remains blank and there is no visible error either.  We will improve this here with some error handling code.

 

 

  1. Select mock-Host 2 Monitor view
  2. Click Virtual Machines and see the VM list: vm-20, vm-21, vm-22
  3. Open the browser Developer Tools through the right-side menu and select the Network tab.
  4. Click on vm-20. The view gets blank because vm-20 doesn't match any mock VM id in db.json, so no data is returned.
  5. See the error 404 Not Found  in the Network tab for request http://localhost:3000/vms/vm-20

 

 

New VM Monitor view in Plugin Mode

The VM Monitor view added above in Dev mode will also work as is in Plugin mode, in vSphere Client, once we take care of one last important step: a new extension must be declared in plugin.xml in order for the vSphere Client platform to know about this new VM view.

plugin.xml contains all the extension definitions for a plugin, i.e. the metadata for views, menu items, shortcuts, etc. that make up the plugin, and which uses the vSphere Client SDK extension points.

 

Go back to mock-Host 1 and click on one of its vms to display a valid VM Monitor view

Toggle the View info switch in the header

This opens a light blue ribbon containing the extension id for that view: com.mycompany.myplugin.vm.monitorView

But the Show Details button has no effect because that extension definition still needs to be added to plugin.xml

 

Open src/webapp/plugin.xml and scroll to Host monitor tab view.

The new extension is almost identical to this Host monitor extension, you can copy/paste it and replace host with vm in two places.  You must also replace view=monitor by view=vm-monitor in the <url>.

Here is the xml code to insert if you prefer to copy this directly:

<!-- VM monitor tab view -->

<extension id="com.mycompany.myplugin.vm.monitorView">
   <extendedPoint>vsphere.core.vm.monitorViews</extendedPoint>
   <object>
      <name>#{app.name}</name>
      <componentClass className="com.vmware.vsphere.client.htmlbridge.HtmlView">
         <object>
            <root>
               <url>/vsphere-client/myplugin/index.html?view=vm-monitor</url>
            </root>
         </object>
      </componentClass>
   </object>
</extension>

 

As soon as plugin.xml is updated with that new extension you can click again on Show Details to check that the <extension> xml code shows up correctly for the VM Monitor view.

 

Module 2 - Lifecycle of a vSphere Client Plugin (30 Minutes)

Plugin Lifecycle


In the previous module you have built and deployed a plugin in a Development environment, now we explore how a plugin is delivered to end-users in a Production environment, using the vCenter extension registration mechanism.

There are 3 steps:

  1. Prepare your plugin for production
  2. Register it as a vCenter extension
  3. Test the deployment in vSphere Client

Don't worry if you didn't finish the previous module, this one restarts from a brand new plugin which is already built.

IMPORTANT: If you are starting Module 2 in a different Lab session than Module 1 there are  installation steps required to get json-server running.  Before starting this module please follow the instructions for the first three chapters of Module 1:


 

Plugin Deployment Overview

 

When the user logs into the vSphere Client the plugin is requested from the vCenter, downloaded from the registered URL and deployed into vSphere Client application server.  Here are the detailed steps:

  1. The plugin package .zip file is hosted on the plugin provider's server.
  2. The vCenter administrator has registered the plugin using that hosted location URL
  3. During a user login the vSphere Client asks vCenter for the list of its registered plugins.
  4. If vSphere Client finds a plugin that hasn't been deployed yet (or is a new version) it downloads using the registered URL
  5. vSphere Client first performs compatibility checks
  6. Then the plugin bundles can be "hot deployed" on the vSphere Client runtime (Virgo server)
  7. The plugin UI becomes visible in the Client for all future users.

 

 

Preparing the plugin for release to production

 

In the first module, under Deploy the Plugin to vSphere Client, you were asked to build the plugin package and deploy it with the local vSphere Client. This was done with the script .\tools\build-plugin-package.bat.  You can see the output of that script in the File Explorer under HOL-1811\webClientPlugin\html-client-sdk\vsphere-ui\plugin-packages\myplugin.

The folder myplugin contains the following:

- plugin-package.xml: the xml manifest containing the plugin ID, version, general information and compatibility constraints.

- plugins/: the set of bundles containing the plugin code and 3rd party libraries.  In this case we have one UI bundle, myplugin-ui.war, one Java service bundle, myplugin-service.jar, and the library gson-2.3.1.jar.

 

 

Registering your plugin as a vCenter extension

The SDK includes a tool to register plugins with vCenter. It is available in html-client-sdk\tools\vCenter plugin registration

 

Open a new Command Prompt and enter this command:

cd C:\LabFiles\HOL-1811\webClientPlugin\html-client-sdk\tools\vCenter plugin registration 

The directory vCenter plugin registration contains a default version of the registration tool in prebuilt and a customizable version in project.

 

 

Copy the following command and execute it, it should end with message "successfully registered" as shown above:

prebuilt\extension-registration.bat -action registerPlugin -k com.mycompany.myplugin -v 1.0.0 -url https://vcsa-01a.corp.local/sdk -u administrator@corp.local -p VMware1! -pu http://localhost:3000/myplugin.zip

NOTE: since it is a long command it may easier to drag it into a Notepad window first, and then copy it in the Command Prompt window.

NOTE: The INFO message about not using https is there to remind you that the plugin download location should always use https in a production environment.  We only used http here for convenience in our dev environment.

 

 

Deploy the registered plugin from vCenter

At this point of the lab, we have a local vSphere Client which no longer contains our test plugin and we're ready to check the "production" deployment lifecyle.  Now that the plugin is registered with vCenter all that is left to do is for one user to login into vSphere Client.

 

Open a browser tab at https://localhost:9443/ui

Use the standard HOL credentials or select Use Windows session authentication and hit Login.

 

 

 

Client Plug-Ins View

 

  1. Click Administration in the left navigator or the Home menu.
  2. Select Client Plug-Ins in the Administration menu
  3. The newly installed myplugin is visible at the top of the list of Client plugins.

NOTE: It is normal to have an empty Vendor field here although if contains "Add vendor" in plugin-package.xml. The values in plugin-package.xml are only used when a plugin is installed manually during development, i.e. not registered as a vCenter extension.  When the plugin is registered with vCenter, the fields Vendor, Version and Description must be included in the registration script.

 

Plugin Upgrade



 

Upgrade Cycle Example

In this section we will go through an upgrade cycle by just changing the plugin version.

We don't need to change the plugin content itself to demonstrate the upgrade mechanism. The only thing that matters for vSphere Client to replace an existing plugin is to find a registered plugin with the same id and a higher version number.

 

Bring back the terminal window where you ran the extension-registration script earlier and enter the following command:

prebuilt\extension-registration.bat -action updatePlugin -k com.mycompany.myplugin -v 1.0.1 -url https://vcsa-01a.corp.local/sdk -u administrator@corp.local -p VMware1! -pu http://localhost:3000/myplugin.zip -c MyCompany

The only differences with the previous command are -action updatePlugin,  -v 1.0.1, and -c MyCompany. We're updating the existing plugin registration, changing its version to a higher number and adding a vendor name "MyCompany".

 

In order to see the new plugin version you must login again in the vSphere Client.  The login process will trigger the download of the newer plugin version.

NOTE: the vSphere Client version included in this lab requires that your quit and relaunch the Chrome browser before you attempt to login again because of cookies problems.

 

The terminal window for the Virgo server process shows the undeployment of myplugin version 1.0.0 and the deployment of version 1.0.1.

You can also verify that the local cache contains the new version at C:\ProgramData\VMware\vCenterServer\cfg\vsphere-client\vc-packages\vsphere-client-serenity\com.mycompany.myplugin-1.0.1

NOTE: The UI and service bundles still show version '1.0.0' in the terminal window because we haven't updated their version.

Congratulations, you have reached the end of this Hands-on Lab!

 

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.

Lab SKU: HOL-1811-07-SDC

Version: 20180109-194516