Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Wiki Markup
{jenkins-plugin-info:pluginId=skytap|sourceDir=skytap-cloud-plugin}
Excerpt

This plugin allows you to use Jenkins to run continuous integration and automated testing workflows using dynamically-created complex development and testing environments in Skytap Cloud

Sections in this document:

Table of Contents
maxLevel2

Introduction

The Skytap Cloud is a self-service cloud that makes it easy for CI Plugin for Jenkins allows you to create development and test environments on demand within minutes. The environments can be as simple as a client application running on a single VM to a multi-component distributed application running on multiple VMs across multiple networks. Skytap makes it easy for you to set up these environments and save them off as golden templates. These templates in turn can be used to create clones, as many as needed, to run your test passes, be it configure Skytap Cloud environments as part of your Jenkins-based continuous integration workflow. 

In a matter of minutes, you can create a Skytap virtual environment from a golden template and then use that environment to develop your application or run test passes for unit testing, functional testing, integration testing, stress/performance testing or user acceptance testing.

The Skytap Cloud CI Plugin for Jenkins provides a set of pre-packed Skytap Cloud actions for use in configuring a Jenkins based continuous integration workflow. These pre-packaged Skytap Cloud actions provide the user with actions that are commonly needed in provisioning environment resources during a CI run. 

Specifically, the Skytap Cloud Actions provided in the plugin are as follows:

  • Add Configuration to Project
  • Change Configuration State
  • Connect to Network in another Configuration (ICNR)
  • Connect to VPN Tunnel
  • Create Configuration from Template
  • Create Publish URL
  • Create Template from Configuration
  • Delete Configuration
  • Add Template to Project
  • Merge Template into Configuration
  • Create Published Service
  • List Published URL for Configuration
  • List VM Published Service

Each of these Skytap Actions is described in detail in this document.

...

 All of the VM and network settings are saved with the template, so once you've created an environment, the network is already set up and you're ready to go. 

With Skytap Cloud CI Plugin for Jenkins, you can add the following actions to your Jenkins build steps:

Table of Contents
minLevel3
maxLevel3

Before You Begin

To use the Skytap Cloud CI Plugin for Jenkins, you must have a Skytap account.

If you do not have a Skytap account, you can sign up for a demo account at http://www.skytap.com/

Step 1: Installing the Skytap Cloud CI Plugin for Jenkins

From the Jenkins Web UI

You can install the Skytap Cloud CI Plugin for Jenkins directly You can install the plugin from the Jenkins web UI, or you can download the plugin from the plugin repository. 

Option 1:
To install the plugin from the Jenkins Web UI by navigating :

  1. Navigate to the Jenkins

...

  1. Manage Plugins page.
    Image Modified

...

  1. Select the Available tab and filter for “Skytap”

...

  1. Image Added

...

  1. Select the “Install” checkbox next to “Skytap Cloud CI Plugin for

...

  1. Jenkins.”
  2. Click Download now and install after

...

When Jenkins restarts, you will have access to Skytap Cloud Actions in the Jenkins Project Configuration screen “Add Build Step” dropdown menu.

From a Downloaded Skytap Cloud CI Plugin for Jenkins file

...

  1. restart.

Option 2:
To install the plugin from the Jenkins plugin repository:

  1. Download the "skytap.hpi" plugin file

...

  1. from the Jenkins plugin repository

...

  1. .
  2. Navigate to the Jenkins

...

  1. Manage Plugins page.
  2. Select the Advanced tab.
    Image Added
  3. From the “Upload Plugin” section

...

  1. , click Choose File
    Image Added
  2. Navigate to the downloaded plugin file (skytap.hpi)

...

  1. and select it. 

...

  1. Click Upload
  2. After the plugin is uploaded, restart Jenkins by

...

  1. navigating to http://_your-jenkins-server_/jenkins/restart

...

  1. Click Yes to confirm.
    Image Added 

Step 2: Configuring the Plugin

Skytap Cloud Authentication

To use configure the Skytap Cloud CI plugin for Jenkins you must first be able to authenticate with Skytap Cloud.  This authentication requires a Skytap Cloud user ID and an API Token.  This is needed so that the plugin can make API calls on your behalf to manage resources in your account on Skytap Cloud. Assuming you already have a Skytap Cloud account, you can retrieve your API Token in your Skytap Account Settings:

Image Removed

If you don’t have a Skytap Cloud account, you can sign up for one here: http://www.skytap.com/

Once you have your security token, you will need to enter it along with your Skytap User ID in the Skytap Cloud Plugin configuration panel for your Jenkins build project.

Image Removed

Skytap Action Logging

The Skytap Cloud Plugin configuration panel on the “Manage Jenkins->Configure System” page controls logging of Skytap Actions.

Image Removed

If the checkbox is checked, verbose output on the operation of Skytap Actions , you will need to enter to your Skytap credentials. Optionally, you can also enable verbose logging.

  1. To enter your Skytap credentials:## Navigate to the configuration page for your Jenkins build project.## Under Build Environment, enter your Skytap User ID and API security token. 
      Image Added
    NOTE: You can retrieve your user ID (user name) and API security token from your Skytap account settings page (https://cloud.skytap.com/account). If you do not have an API security token listed, use the instructions at http://help.skytap.com/#Access_Policy.html to enable API security tokens in your account.
  2. To enable verbose logging for Skytap actions:##  Navigate to Manage Jenkins > Configure System.
    Image Added## In the Skytap Cloud Plugin settings, select Enable Console Logging of Skytap Actions
    Logs will be sent to the Jenkins Project build console.
    Image Modified

Supported Actions for Skytap Cloud

The Skytap Cloud Actions that are available for use in Jenkins project builds are exposed in the Jenkins Project Configuration screen in the “Add Build Step” dropdown menu as an “Execute Skytap Action” menu pick:
Image Removed
Once you select “Execute Skytap Action” you will be presented with a “Skytap Action” dropdown menu listing the available actions:

Image Removed
 
Depending on which action you select you will be presented with a set of input and output parameters to specify in order to enable execution of the Skytap Action.  The specific input and output parameters that are required differ depending on which Skytap Action you select.  These parameters are described below in the discussion of individual Skytap Actions.

Add Configuration to Project

This Skytap Action allows the user to specify a Skytap Configuration to add to a Skytap Project.

Image Removed
 

Parameters

Configuration ID --or- Configuration File

...

Step 3: Adding Skytap Actions to Your Build Steps

Once the plugin is installed and configured, you can add Skytap actions to your Jenkins build steps:

  1. Navigate to the Jenkins Project Configuration screen.
  2. From the Add build step dropdown menu, select Execute Skytap Action
    Image Added
  3. Select an available action:
    Image Added
  4. Enter any required parameters. For a description of each action and the required parameters, see the sections below. 

Reference: Skytap Actions and Required Parameters

NOTE: If you see different action names, please update the Skytap Cloud CI Plugin to the latest version.

Add Environment to Project

This action adds a Skytap environment to a Skytap project.

Image Added
 

Required Parameters

Description

Environment ID or Environment File

Enter a Skytap Environment ID (an integer), if one is known. 
If the

...

environment was created in an earlier step (using the

...

"Create Environment from Template” Skytap

...

action),

...

enter the Environment Data Save File created from that step.

Project ID

...

or

...

Project Name

...

Enter a

...

Skytap

...

project ID (an integer) or a Skytap

...

project name. The project must already exist and be accessible

...

from your Skytap account.

Add Template to Project

This Skytap Action allows the user to specify action adds a Skytap Template template to add to a Skytap Projectproject.

Image RemovedImage Added

Required Parameters

Description

Template ID

...

or

...

Template File

...

Enter a

...

Skytap

...

template ID (an integer), if one is known. 
If the template was created in an earlier step (using the

...

"Create Template from

...

Environment” Skytap

...

action),

...

enter the Template Data Save File created from that step.

Project ID

...

or

...

Project Name

...

Enter a

...

Skytap

...

project ID (an integer) or a Skytap

...

project name. The project must already exist and be accessible

...

from your Skytap account.

Change

...

Environment State

When this Skytap Action is selected, the user must then select the desired state to which they wish to transition the configuration.  Choices are “Run Configuration”, “Suspend Configuration”, and Shutdown Configuration”.
Image Removed

Once a state change action is specified the user can fill out the remaining parameters.
Image Removed

Parameters

This action will run, suspend, or shut down a Skytap environment.

Image Added

Parameters

Description

Action (Required)

Select "Run Environment", "Suspend Environment", or "Shutdown Environment"

Power off VM if shutdown fails

...

(Optional)

If this option is checked,

...

Configuration ID --or- Configuration File

...

Skytap will forcibly power off any VMs that do not shut down within 5 minutes.

Environment ID or Environment File (Required)

Enter a Skytap environment ID (an integer), if one is known. 
If the

...

environment was created in an earlier step (using the

...

"Create Environment from Template” Skytap

...

action),

...

enter the Environment Data Save File created from that step.

Connect to Network in another

...

Environment (ICNR)

When this Skytap Action is selected, the specified networks in the two specified configurations will be connected using the Internal Configuration Network Routing (ICNR) protocol.  This feature is useful during testing, where one or more test environments need to access a central resource, like a database or Active Directory server. The network subnets in the two configurations This action connects two networks in different Skytap environments. The networks must already be configured to allow an Inter-Configuration Network Routing (ICNR) connection to occur. You can read more about ICNR in Skytap Help Docs.

Image Removed

Parameters

Source Configuration ID --or- Source Configuration Data File

The user can specify a specific Skytap Configuration  

Image Added

Required Parameters

Description

Source Environment ID or Source Environment Data File

Enter a Skytap environment ID (an integer), if one is known.

...

  
If the

...

environment was created in an earlier step (using the

...

"Create Environment from Template” Skytap

...

action),

...

enter the Environment Data Save File created from that step.

Source Network Name

...

Enter the name of the network in the

...

Target Configuration ID --or- Target Configuration Data File

...

source environment.

Target Environment ID or Target EnvironmentData File

Enter a Skytap environment ID (an integer), if one is known.

...

  
If the

...

environment was created in an earlier step (using the

...

"Create Environment from Template” Skytap

...

action),

...

enter the Environment Data Save File created from that step.

Target Network Name

...

Enter the name of the network in the

...

target environment. This network must be visible to other networks.

...

 

NOTE: If there is more than one network in the environment with the specified name (not recommended), the plugin will use the first network encountered in the metadata associated with the environment.

Connect to VPN Tunnel

When this Skytap Action is selected, the specified Skytap VPN definition will be connected to the specified network in the specified Skytap Configuration.
Image Removed

Parameters

Configuration ID --or- Configuration File

The user can specify a specific Skytap Configuration This action will connect a Skytap environment to a Skytap VPN.
Image Added

Required Parameters

Description

Environment ID or EnvironmentFile)

Enter a Skytap environment ID (an integer), if one is known. 
If the

...

environment was created in an earlier step (using the

...

"Create Environment from Template” Skytap

...

action),

...

Configuration Network Name

...

enter the Environment Data Save File created from that step.

Environment Network Name

Enter the name of the network in the

...

Image Removed

VPN ID

This parameter is the Integer ID of the Skytap VPN definition to which to connect the specified network in the configuration.

Create Configuration from Template

This Skytap Action allows the user to specify a Skytap Template from which to create a Skytap Configuration.
Image Removed

Parameters

Template ID --or- Template File

...

Skytap environment.
NOTE: If the environment contains multiple networks with the same name (not recommended), the first network encountered in the metadata associated with the environment will be used.

VPN ID

Enter the Skytap VPN ID (an integer).

Create Environment from Template

This action creates a Skytap environment from a Skytap template.
Image Added

Required Parameters

Description

Template ID or Template File

Enter a Skytap template ID (an integer), if one is known. 
If the template was created in an earlier step (using the

...

"Create Template from

...

Environment” Skytap

...

action),

...

Configuration Name

...

enter the Template Data Save File created from that step.

Environment Name

Enter a name for the

...

new environment.

...

Environment Data Save File

This output file contains the Skytap Configuration metadata in json format.  This metadata contains the Skytap Configuration ID as well as the other metadata that defines the Skytap Configuration.  This file can then be used as input to Skytap Actions that require a Skytap Configuration ID or other Skytap Configuration metadata.

Create Publish URL

When this Skytap Action is selected, a Skytap Published URL will be created and associated with the specified Configuration.

Image Removed

Parameters

Configuration ID --or- Configuration File

...

Enter a name for the output file (for example, env.json). The plugin will create the output file and populate it with Skytap environment metadata in JSON format. The metadata includes the Skytap environment ID and other information about the environment. This file can be used in Skytap actions that require a Skytap environment ID or other environment metadata.

Create Sharing Portal

This action creates a Sharing Portal for a Skytap environment.

Image Added

Required Parameters

Description

Environment ID or Environment File

Enter a Skytap environment ID (an integer), if one is known. 
If the

...

environment was created in an earlier step (using the

...

"Create Environment from Template” Skytap

...

action),

...

enter the Environment Data Save File created from that step.

URL Save Filename

When the Publish URL is created, the text of the URL will be written into the file specified in the Filename specified in this parameter.

Select Permissions

Image Removed

...

Enter a name for the output file (for example, puburl.txt). The plugin will create the output file and populate it with the sharing portal's address. 

Select Permissions

Select a permission level for VMs in the sharing portal. For more information about permissions, see the Skytap Help Documentation.

Require Password for Access

...

If

...

checked,

...

enter a password

...

to restrict access to the sharing portal.

Create Published Service

When this Skytap Action is selected, a Skytap Published Service will be added to the port number specified by the “Port Number” parameter in the network with the name specified by the “Network Name” parameter in the virtual machine specified by the “VM ID” or “VM Name” parameter in the configuration specified by the “Configuration ID” or “Configuration File” parameter.

If the specified configuration has more than one Virtual Machine with the name specified by the “Virtual Machine Name” parameter, the first Virtual Machine with the specified name that is listed in the configuration metadata will be used.

If the specified configuration has more than one network with the name specified by the “Network Name” parameter, the first network with the specified name that is listed in the configuration metadata will be used.

The text of the public URL and port in the form “public-URL:port-number” is saved in a file with the name specified in the file specified by the “Published Service Save Filename” parameter.  Image Removed

Parameters

Configuration ID --or- Configuration File

The user can specify a specific Skytap Configuration This action creates a Published Service port opening on a VM's network adapter. This is commonly used to open RDP or SSH access to a VM.
     Image Added

Required Parameters

Description

Environment ID or Environment File

Enter a Skytap environment ID (an integer), if one is known. 
If the

...

environment was created in an earlier step (using the

...

"Create Environment from Template” Skytap

...

action),

...

enter the Environment Data Save File created from that step.

VM ID

...

or

...

VM Name

...

Enter the ID or name of the virtual machine you want to attach the published service to. Note: If the environment has more than one VM with the same name, the first VM

...

in the Skytap

...

environment metadata definition will be selected.

Network Name

...

Enter the name of the network you want to attach the published service to.
NOTE: If the VM contains multiple networks with the same name, the first network

...

in the Skytap

...

environment metadata definition will be selected.

Port Number

...

Enter the port number you want to connect the published service to (for example, 3389 for RDP access).

Published Service Save Filename

...

Enter a name for the output file (for example, pubservice.txt). The plugin will create the output file and populate it with the “public-URL:port-number”.
NOTE: The port number in this text will be different than the port number specified above. Skytap uses port mappings to obscure the port openings on the public Internet.

Create Template from

...

Environment

This Skytap Action allows the user to specify action creates a Skytap Configuration template from which to create a Skytap Templateenvironment.

Image RemovedImage Added

Required Parameters

Configuration ID --or- Configuration File

...

Description

Environment ID or Environment File

Enter a Skytap environment ID (an integer), if one is known. 
If the

...

environment was created in an earlier step (using the

...

"Create Environment from Template” Skytap

...

action),

...

enter the Environment Data Save File created from that step.

Template Name

...

Enter a name for the

...

new template.

Template

...

This parameter allows the user to specify a description for the created template.

Template Data Save Filename

This output file contains the Skytap Template metadata in json format.  This metadata contains the Skytap Template ID as well as the other metadata that defines the Skytap Configuration.  This file can then be used as input to Skytap Actions that require a Skytap Template ID or other Skytap Template metadata.

Delete Configuration

This Skytap Action allows a user to delete the specified Skytap Configuration.

Image Removed

Parameters

Configuration ID --or- Configuration File

...

Data Save File

Enter a name for the output file (for example, template.json). The plugin will create the output file and populate it with Skytap template metadata in JSON format. The metadata includes the Skytap template ID and other information about the template. This file can be used in Skytap actions that require a Skytap template ID or other template metadata.

Delete Environment

This action deletes a Skytap environment.

Image Added

Required Parameter

Description

Environment ID or Environment File

Enter a Skytap environment ID (an integer), if one is known. 
If the

...

environment was created in an earlier step (using the

...

"Create Environment from Template” Skytap

...

action),

...

List Published URL for Configuration

The configuration desktops URL with the specified Published URL Name for the specified configuration is written into the file specified by the “Published URL Save Filename” parameter.  Published URLs for individual VMs in a configuration are not supported.

Image Removed

Parameters

Configuration ID --or- Configuration File

...

enter the Environment Data Save File created from that step.

List Sharing Portal for Environment

This action returns the address for an existing sharing portal in a Skytap environment.

Image Added

Required Parameters

Description

Environment ID or Environment File

Enter a Skytap environment ID (an integer), if one is known. 
If the

...

environment was created in an earlier step (using the

...

"Create Environment from Template” Skytap

...

action),

...

Published URL Name

...

enter the Environment Data Save File created from that step.

Sharing Portal Name

Enter the name of the desired

...

sharing portal.
NOTE: If the environment has multiple sharing portals with the same name, the first URL encountered in the

...

environment metadata will be selected.

...

Sharing Portal Save Filename

...

Enter a name for the output file (for example, puburl.txt).  The plugin will populate this file with the sharing portal's address.

List VM Published Service

The Skytap Published Service for the port specified in the “Port Number” parameter in the network with the name specified by the “Network Name” parameter in the virtual machine specified by the “VM ID” or “VM Name” parameter in the configuration specified by the “Configuration ID” or “Configuration File” parameter is written into the file specified by the “Published Service Save Filename” parameter.

If the specified configuration has more than one Virtual Machine with the name specified by the “Virtual Machine Name” parameter, the first Virtual Machine with the specified name that is listed in the configuration metadata will be used.

If the specified configuration has more than one network with the name specified by the “Network Name” parameter, the first network with the specified name that is listed in the configuration metadata will be used.

The text of the public URL and port in the form “publicThis action returns the "public-URL:port-number” is saved in a file with the name specified in the file specified by the “Published Service Save Filename” parameter.

Image Removed
 

Parameters

Configuration ID --or- Configuration File

The user can specify a specific Skytap Configuration number" for an existing published service in a Skytap environment.

Image Added

Required Parameters

Description

Environment ID or Environment File

Enter a Skytap environment ID (an integer), if one is known. 
If the

...

environment was created in an earlier step (using the

...

"Create Environment from Template” Skytap

...

action),

...

enter the Environment Data Save File created from that step.

VM ID

...

or

...

VM Name

...

Enter the ID or name of the virtual machine the published service is attached to.
NOTE: If the environment has multiple VMs with the same name, the first VM

...

in the Skytap

...

environment metadata definition will be selected.

Network Name

...

Enter the name of the network the published service is attached to.
NOTE: If the VM has multiple networks with the same name, the first network

...

in the Skytap

...

environment metadata definition will be selected.

Port Number

...

Enter the port number the published service is attached to (for example, 3389 for RDP access).

Published Service Save Filename

...

Enter a name for the output file (for example, pubservice.txt). The plugin will create and populate this file with the "public-URL:port-

...

number.

...

Merge Template into Configuration

The Virtual Machines contained in the Skytap Template identified by the specified Skytap Template ID or Template Data File are added to the Skytap Configuration identified by the specified Skytap Configuration ID or Configuration Data File.

  Image Removed

Parameters

Configuration ID --or- Configuration File

...

"
NOTE: The port number in this text will be different than the port number specified above. Skytap uses port mappings to obscure the port openings on the public Internet.

Merge Template into Environment

This action will copy VMs from a Skytap template into a Skytap environment.
   Image Added

Parameters

Description

Environment ID or Environment File (Required)

Enter a Skytap environment ID (an integer), if one is known. 
If the

...

environment was created in an earlier step (using the

...

"Create Environment from Template” Skytap

...

action),

...

enter the Environment Data Save File created from that step.

Template ID

...

or

...

Template File

...

(Required)

Enter a Skytap template ID (an integer), if one is known. 
If the

...

template was created in an earlier step (using the

...

"Create Template from Environment” Skytap action), enter the Template Data Save File created from that step.

Environment Data Save File (Optional)

To create a new Environment Data Save File with updated environment metadata, enter a new file name (updatedenv.json). This file can be used in actions that require a Skytap environment ID or other environment metadata.