Preface

This document describes the functionality provided by the vSphere plugin.

See the XL Deploy Reference Manual for background information on XL Deploy and deployment concepts.

Overview

The vSphere plugin is an XL Deploy plugin that supports launching, provisioning and terminating hosts and environments on VMWare vSphere platform.

The vSphere plugin is part of XL Scale. For more information about the XL Scale, see the XL Scale Manual.

Features

• Deploying vSphere templates as virtual machines from XL Deploy;
• Destroying previously deployed virtual machines;
• Combining vSphere virtual machines into environments which can be used for application deployment;
• Registering middleware as part of a created environment.

Requirements

• XL Deploy requirements

  • XL Deploy: version 4.0+
  • Other XL Deploy Plugins: XL Scale

• Infrastructural requirements

  • VMWare vSphere platform with vCenter 5.1+

Usage scenarios

This section describes the most common usage scenarios, further sections contain more detailed configuration instructions.

Creating a single host

In its simplest form, the vSphere plugin can deploy a single virtual machine from a template and register it in XL Deploy as a CI of type cloud.SshHost (when connecting to the host using SSH) or cloud.CifsHost (when connecting using CIFS). The resulting host CI can contain middleware CIs that are present on the host and can be used as a normal container for deployment. The host can also be destroyed, which causes XL Deploy to terminate the vSphere instance and remove the host CI and its children from the repository.

There is a special CI type vsphere.HostTemplate which is used as a template to define all information about the future virtual machine.

Creating an environment

For more information about combining cloud hosts into environments, see the XL Scale Manual.

Provisioning instantiated hosts

When deploying a virtual machine, the template may already have the desired middleware installed. If this is the case, a launched host will be ready for use as soon as it has finished booting. It is also possible to provision a host using Puppet, Chef or a shell command after launching it. This is supported via the the notion of a marker file. If the host template specifies a marker file, XL Deploy will poll the launched instance for its presence. When the file is found on the instance filesystem, XL Deploy will conclude the host is up and ready for deployment. The location of the marker file can be configured in the vsphere.HostTemplate.

See the section on the marker file in the XL Scale Manual for additional details on the polling process.

Note:

• it is the responsibility of the template to invoke the provisioning process and to create the marker file when provisioning is completed, signaling that the host and middleware are ready for deployment.
• marker files are only supported when the template is based on a Unix family OS.

Configuration instructions

vCenter credentials

The vSphere plugin requires access to vCenter in order to perform operations on vSphere platform. These credentials are specified under the Configuration root node in the repository using a vsphere.Credentials CI. The CI has a control task validateCredentials that can test that the credentials can be used to communicate with vCenter.

Host template

The next step is to define host template CIs (vsphere.HostTemplate). A host template describes a single host that can be launched on the vSphere platform. In addition to the generic host template properties, it allows some vSphere-specific properties.

See CI reference for list of vsphere.HostTemplate properties and their meaning.

See the XL Scale Manual for the generic properties.

Here is an example of an vSphere host descriptor:

<#escape x as x?xml>
  <list>
    <cloud.SshHost id="${hostsPath}/${hostTemplate.name}_${hostAddress}">
      <template ref="${hostTemplate.id}"/>
      <cloudId>${cloudId}</cloudId>
      <address>${hostAddress}</address>
      <#if hostTemplate.privateKeyFile??><privateKeyFile>${hostTemplate.privateKeyFile}</privateKeyFile></#if>
      <#if hostTemplate.username??><username>${hostTemplate.username}</username></#if>
      <#if hostTemplate.password??><password>${hostTemplate.password}</password></#if>
      <#if hostTemplate.os??><os>${hostTemplate.os}</os></#if>
      <#if hostTemplate.connectionType??><connectionType>${hostTemplate.connectionType}</connectionType></#if>
    </cloud.SshHost>
    <www.ApacheHttpdServer id="${hostsPath}/${hostTemplate.name}_${hostAddress}/httpd">
      <host ref="${hostsPath}/${hostTemplate.name}_${hostAddress}"/>
      <startCommand>sudo apachectl stop</startCommand>
      <startWaitTime>3</startWaitTime>
      <stopCommand>sudo apachectl stop</stopCommand>
      <stopWaitTime>3</stopWaitTime>
      <restartCommand>sudo apachectl restart</restartCommand>
      <restartWaitTime>10</restartWaitTime>
      <defaultDocumentRoot>/var/www</defaultDocumentRoot>
      <configurationFragmentDirectory>/etc/apache2/conf.d</configurationFragmentDirectory>
    </www.ApacheHttpdServer>
  </list>
</#escape>

Every vsphere.HostTemplate CI provides a validateDescriptor control task which processes the Freemarker template, parses the resulting XML and reports errors if something is wrong. No actual changes are made to the repository during execution of this control task.

Please note that:

• Hosts which you define here should be either cloud.SshHost or cloud.CifsHost.
• The cloud.SshHost or cloud.CifsHost in the template must contain the XML fragments for address, cloudId and template. These are needed for the proper functioning of the plugin.
• You should always use <list> as a parent XML element, even if you define only one CI.
• When you use references to ${hostTemplate.*} properties, make sure they are defined on host template when required by the appropriate CI types. E.g. cloud.SshHost requires connectionType, when ec2.HostTemplate does not.
• Since XML is being generated you have to make sure that values are properly encoded. You can achieve this by enclosing the template in <#escape x as x?xml>...</#escape>, or alternatively use ${exampleKey?xml}. See the Freemarker documentation for details.

Environment template

For more information about defining environment templates, see the XL Scale Manual.

Using the vSphere plugin

Please see the XL Scale manual for instructions on how to use the environment and host templates provided in the vSphere plugin.

Upgrade notes

Upgrading from version 3.9.4 or below

• Before installing the distribution please make sure that following libraries are not present in the plugins folder. Remove them if they are.
  • cloud-plugin-*.jar
  • dom4j-*.jar
  • vijava-*.jar
  • vsphere-plugin-*.jar
  • xml-apis-*.jar

Release notes

XL Scale plugin version 4.0.0

As a major change, Cloud plugin has been rebranded to XL Scale.

Improvements:

• [DEPL-5489] - How to update in case of connections of type WINRM, WINRM_HTTP, WINRM_HTTPS have been used.

Fixed Bugs:

• [DEPL-4909] - Cloud instances from the same template get the same instance ID

vSphere plugin version 4.0.0

Fixed Bugs:

• [DEPL-5636] - vsphere.HostTemplate can not be created when host name is not located in datacenter

Cloud plugin version 3.9.4

Fixed bugs:

• [DEPLOYITPB-5081] - environmentTemplate is not exposed in the template
• [DEPLOYITPB-4864] - Host template validation exposes password (improvement of the fix made in 3.9.3)

vSphere plugin version 3.9.3

Improvements:

• [DEPLOYITPB-4864] - Host template validation exposes password