Try the Remote Plug-in Sample Starter

Build and run the remote plug-in sample starter for a quick introduction to the process of deploying and viewing a remote plug-in for the vSphere Client.

The plug-in sample starter demonstrates a very simple plug-in that serves only static HTML content. This is the easiest way to be introduced to the remote plug-in environment, including only a few components that extend the vSphere Client user interface with a full-screen view available for plug-in content.

What To Do First

Check the dependencies on your development machine:

• Java Development Kit 8
• Maven 3

Install the vSphere Client SDK:

1. Download the SDK from https://code.vmware.com/sdk/client
2. In a shell window, unzip the SDK file:

   PowerShell:

   PS C:\> Get-Item vsphere-client-sdk-*zip |
    Foreach-Object { Expand-Archive -Path $_ -DestinationPath C:\ }

   MacOS:

   Downloads % unzip vsphere-client-sdk-*zip -d ~

Generate a Plug-in Server Certificate

1. Generate an SSL certificate and a JKS key store for the remote plug-in server using Java's keytool certificate management utility.

   PowerShell example:

   PS C:\> keytool -genkeypair -alias plugin-server -keyalg RSA -keysize 4096 `
   -storetype JKS -keystore keystore.jks -storepass "remote.plugin" -keypass "remote.plugin" `
   -dname "CN=mydevbox"

   MacOS example:

   Downloads % keytool -genkeypair -alias plugin-server -keyalg RSA -keysize 4096 \
   -storetype JKS -keystore keystore.jks -storepass "remote.plugin" -keypass "remote.plugin" \
   -dname "CN=mydevbox"

   Note:

   Do not change the values of arguments to the keytool utility, except the value mydevbox in the -dname "CN=mydevbox" argument. The value mydevbox must be replaced by the IP address or the DNS name of the machine on which the remote plug-in server will run. The value is significant because vCenter Server will check whether the Common Name (CN) field value of the remote plug-in server certificate matches the host through which remote plug-in resources are served.

2. Replace the default keystore in the Remote Plug-in Sample Starter code with the newly generated one:

   PowerShell example:

   PS C:\> Move-Item -Path "keystore.jks" -Destination `
    "html-client-sdk\samples\remote-plugin-sample-starter\src\main\resources\keystore.jks" `
    -Force

   MacOS example:

   Downloads % mv -f keystore.jks \
    ~/html-client-sdk/samples/remote-plugin-sample-starter/src/main/resources/keystore.jks

Build the Remote Plug-in Sample Starter

1. Navigate to the sample starter directory:

   PowerShell example:

   PS C:\> cd html-client-sdk/samples/remote-plugin-sample-starter

   MacOS example:

   Downloads % cd ~/html-client-sdk/samples/remote-plugin-sample-starter

2. Issue the Maven build command:

   PowerShell example:

   PS C:\html-client-sdk\samples\remote-plugin-sample-starter> mvn clean install

   MacOS example:

   remote-plugin-sample-starter % mvn clean install

Start the Remote Plug-in Sample Starter

1. Navigate to the target directory:

   PowerShell example:

   PS C:\html-client-sdk\samples\remote-plugin-sample-starter> cd target

   MacOS example:

   remote-plugin-sample-starter % cd target

2. Issue the Java command to run the plug-in server:

   PowerShell example:

   PS C:\html-client-sdk\samples\remote-plugin-sample-starter\target> `
   java -jar (Get-ChildItem remote-plugin*.jar -Name | Select-Object -first 1)

   MacOS example:

   target % java -jar remote-plugin-sample-starter-*.jar

3. Use a browser to verify that the remote plug-in server can supply its manifest. Enter the following URL:

   https://localhost:8443/sample-ui/plugin.json

   Leave the browser window open for the next step.

Save the Certificate or Fingerprint of the Plug-in Server

1. Find the security certificate and/or fingerprint of the plug-in server.

   In Chrome browser for example, click the padlock icon next to the URL at the top of the browser window. Then click Connection is secure > Certificate is valid. You can copy the SHA-256 Fingerprint or Thumbprint (depending on the browser) from there. For the certificate, click Details > Export.

2. Paste the SHA-256 fingerprint into a file, or save the certificate as a PEM file with .cer suffix.

   vCenter Server expects the fingerprint (thumbprint) to contain colon-separated character pairs. As of vSphere 8.0 U3, the registration script changes unseparated or space-separated character pairs into the expected format.

   For PEM, select base64-encoded ASCII, single certificate. In the plug-in server certificate, check that the server host name is specified according to subjectAltName extension (RFC 2818, Section 3.1 Server Identity).

Register the Remote Plug-in Sample Starter

1. Navigate to the directory containing the registration script:

   PowerShell example:

   PS C:\html-client-sdk\samples\remote-plugin-sample-starter\target> `
   cd 'C:\html-client-sdk\tools\vCenter plugin registration\prebuilt'

   MacOS example:

   target % cd ~/html-client-sdk/tools/vCenter\ plugin\ registration/prebuilt

2. Run the registration script for the plug-in. Use the name of your vCenter Server instance in the URL and use valid credentials to authenticate. Enter the password for [email protected] when prompted.

   PowerShell example:

   PS C:\html-client-sdk\tools\vCenter plugin registration\prebuilt> `
    .\extension-registration.bat `
    -action registerPlugin -remote `
    -url https://myvcenter.example.com/sdk `
    -username [email protected] `
    -key com.vmware.sample.remote.starter -version 1.0.0 `
    -pluginUrl https://mydevbox:8443/sample-ui/plugin.json `
    -serverThumbprint 19:FD:2B:0E:62:5E:0E:10:FF:24:34:7A:81:F1:D5:33:`
   19:A7:22:A0:DA:33:27:07:90:0F:8E:8D:72:F1:BD:F1 `
    -serverCertificateFile C:\plugin-server.cer `
    -c 'Example, Inc.' -n 'Remote Plug-in' -s 'This is a sample plug-in'

   MacOS example:

   prebuilt % ./extension-registration.sh \
    -action registerPlugin -remote \
    -url https://myvcenter.example.com/sdk \
    -username [email protected] \
    -key com.vmware.sample.remote.starter -version 1.0.0 \
    -pluginUrl https://mydevbox:8443/sample-ui/plugin.json \
    -serverThumbprint 19:FD:2B:0E:62:5E:0E:10:FF:24:34:7A:81:F1:D5:33:\
   19:A7:22:A0:DA:33:27:07:90:0F:8E:8D:72:F1:BD:F1 \
    -serverCertificateFile /tmp/plugin-server.cer \
    -c 'Example, Inc.' -n 'Remote Plug-in' -s 'This is a sample plug-in' -insecure

When registering the plug-in, it's highly recommended to provide the SSL certificate of the plug-in server in addition to the thumbprint of the SSL certificate of the plug-in server. Performing a full SSL certificate check during SSL handshake is more secure than performing an SSL certificate thumbprint check. Furthermore, in future vSphere releases, support for SSL certificate thumbprints will be dropped and full SSL certificates will be required.

View the Plug-in User Interface

1. Connect a web browser to the vCenter Server instance and log in to the vSphere Client. Example URL:

   https://myvcenter.example.com/ui/

2. Navigate to the Home screen (for example, use ctrl-alt-home) or the Shortcut screen.
3. In the object navigator pane on the left of the home screen, click on the remote plug-in sample starter.

   The vSphere Client displays a plug-in welcome screen.