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 development and testing environments in Skytap

Sections in this document:

Table of Contents
maxLevel2

Introduction

The Skytap Cloud CI Plugin for Jenkins allows you to create and configure Skytap Cloud environments environments as part of your Jenkins-based continuous integration workflow. In  

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. 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:

  • Add Configuration to Project
  • Change Configuration State
  • Connect to Network in another Configuration (ICNR)
  • Connect to VPN Tunnel
  • Create Configuration from Template
  • Create Published 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 actions is described in more detail below.

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 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:1.

  1. Navigate to the Jenkins

...

  1. Manage Plugins page.
    Image Modified

...

  1. Select the

...

  1. Available tab and filter for “Skytap”
    Image Modified

...

  1. Select the “Install” checkbox next to

...

  1. “Skytap Cloud CI Plugin for Jenkins.”

...

  1. Click

...

  1. 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 do not see an API security token listed for your account, 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/

...

  1. #Access_

...

  1. Policy.html to enable API security tokens

...

  1. in your account

...

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

...

  1. .
  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 Environment 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 environment.  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 environments 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, such as a database or Active Directory server. The network subnets in the two environments 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 the Skytap Help Documentation.

Image Removed

Parameters

Source Configuration ID --or- Source Configuration Data File

The user can specify a specific Skytap Environment  

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 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 Environment.
Image Removed

Parameters

Configuration ID --or- Configuration File

The user can specify a specific Skytap Environment 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 Skytap

...

Image Removed

VPN ID

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

Create Configuration from Template

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

Parameters

Template ID --or- Template File

...

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 Environment metadata in json format.  This metadata contains the Skytap Environment ID as well as the other metadata that defines the Skytap Environment.  This file can then be used as input to Skytap Actions that require a Skytap Environment ID or other Skytap Environment metadata.

Create Published URL

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

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 Published 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 environment specified by the “Configuration ID” or “Configuration File” parameter.

If the specified environment 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 environment metadata will be used.

If the specified environment 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 environment 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 Environment ID 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 a Skytap Environment from which to create a Skytap Template.

Image Removed

Parameters

Configuration ID --or- Configuration File

The user can specify a specific Skytap Environment ID action creates a Skytap template from 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.

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 Environment.  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 Environment.

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

...

List Published URL for Configuration

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

Image Removed

Parameters

Configuration ID --or- Configuration File

...

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.

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

...

Published URL Name

...

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.

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 environment 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 environment 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 environment metadata will be used.

If the specified environment 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 environment 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 Environment ID 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 Environment 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

...

Configuration Data Save File

...

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.