Knowledge Base/Using Tier 3/Blueprints

Blueprints Script and Software Package Management

Jared Wray
posted this on August 09, 2011 14:37

Software and Script Packages (henceforth referred to as ‘Package’) are one way that Blueprint Designers can customize their Environments. They can be configured to run scripts and executable or install software. The definition of a Package is also responsible for generating the UI at Blueprint Deployment time to gather the requisite set of Parameters from the User.

Package Format

Packages must be .zip files and contain the following:

Name	Description
package.manifest	Defines the metadata, parameter list and execution guidelines for the Package. An Xml Schema (.xsd) is available to validate the package.manifest file before uploading. This file is required in all Packages.
[executable]	At least one executable file must be included in the Package. Tier 3 supports the following executable types: - Standard .exe - Command line scripts (anything that can be run from cmd.exe) - PowerShell scripts (.ps1 files)
[resources]	Any additional files that the main executable may require for proper execution. The executable is run from the Package root folder, so any file/folders should be accessed relative to the root.

This document will explain how to construct the package.manifest file and explain any what information is available to the Package at execution time.

<Manifest> Element

The root node for the package manifest.

</Manifest>

Parent Element

None.

Attributes

None.

Child Elements

Name	Description
Metadata	Provides descriptive information regarding the package, its contents and capabilities.
Parameters	Defines parameters that are used during execution of the package.
Execution	Defines how the package it to be executed

<Metadata> Element

Provides descriptive information to uniquely identify the package, its contents and capabilities.

<UUID>

<Name>

</Manifest>

Parent Element

Attributes

None.

Child Elements

Name	Description
UUID	A GUID that uniquely identifies the Package. This value is used internally by the Blueprint deployment process as well as to identify a Package when updates are submitted. This value should not be changed for minor updates (i.e. updated script logic). This value should be changed for major update (i.e. updated parameter list).
Name	The name of the Package. Max length: 100 characters
Description	A detailed description of the Package. This value is used to display information to designers who choose to add this Package to their Blueprint.

<Parameters> Element

Defines the list of parameters required to execute the Package.

</Parameters>

Parent Element

Attributes

None.

Child Elements

Name	Description
Parameter	See <Parameter> Element.

<Parameter> Element

Defines how a Parameter will be presented in the UI.

</Parameter>

Parent Element

Attributes

Name	Description	Required?
Name	Display name for the Parameter. Ignored if Prompt = ‘false’.	Yes
Type	The Parameter type. See below for values	Yes
Variable	This is a variable name which you can refer to in the execution command for your package. Our recommendation is that you name your variables to include your Tier 3 account alias and your Package Name (e.g. T3.install-ad.DomainName) to ensure that you don’t encounter any name conflicts with other scripts you’ve included in a Blueprint.	Yes
Hint	Additional description to communicate the meaning/use of the Parameter. If specified this will be displayed below the input field on the Blueprint deployment form. Ignored if Prompt = ‘false’	No
Prompt	True to prompt for user input at Blueprint deployment. If false, Parameter will have to representation in the UI at Blueprint Deployment. Default = ‘true’	No
Global	True to indicate that is Parameter is defined in multiple Packages but should only be prompted for once at Blueprint Deployment. Default = ‘false’ All reference to this Parameter in all Packages will have the same value.	No
Regex	A Regular Expression to validate user input for a String Parameter. Ignored if Type != ‘String’	No

Parameter Type

Type	Description	UI Element
Network	The Tier 3 internal network name. The list contains all networks that belong to the account, and the user is required to select one. It is unlikely that a Package would ever need this piece of information.	Drop Down List
Numeric	A numeric value. The text is validated to ensure only numeric values are accepted.	Textbox
Option	A list of values where one item must be selected. 1 or more Option elements must be defined.	Drop Down List
MultiSelect	A list of values where any number of items may be selected. 1 or more Option elements must be defined.	Checkbox List
Password	A masked string value Strong password validation will be enforced.	Password box
Server	A list of server names. The list will include all existing servers as well as any servers that will be built as part of the Blueprint.	Drop Down List
ServerIP	A list of server name where the selected value is IP Address. The list will include all existing servers, all servers that will be deployed as part of the Blueprint as well as an option to manually enter an IP Address.	Drop Down List
String	A generic string. If Regex is supplied, the value will be validated using the specified regular expression	Textbox

System Parameters

Named Parameters defined by Tier 3 that can be accessed from within the Package.
To use a System Parameter it must be defined in the Parameter list with Prompt=’false’

Name	Description
T3.Identity.User	The username of the individual initiating the Blueprint deployment.
T3.Server.Name	The name of the current server being built.
T3.Server.IPAddress	The IP Address of the current server being built.
T3.Server.Password	The local Administrator password of the current server being built.

<Option> Element

Defines the options for Option and MultiSelect Parameters

Parent Element

Attributes

Name

Description

Name

The name of the option.

This value is used to label the option in the UI

Value

The value of the option.

Child Elements

None.

<Execution> Element

Defines how the Package should be executed.

<Mode>

</Manifest>

Parent Element

Attributes

None.

Child Elements

Name

Description

Mode

Name	Details
Command	Windows Only Executes the package as the local administrator by calling the command specified from a command prompt.
PowerShell	Windows Only Executes the package via Remote PowerShell as the local administrator. Note: ‘Negotiate’ Authentication mode is used when establishing the remote connection.
SSH	Not Supported

Package is copied to remote server and executed from the root of the Package directory.

Command

The command to be executed.

You can specify Parameters to be passed to the Package using the following format:

${Parameter.Variable}

All Parameters specified in the Parameter list will be replaced with the appropriate values at runtime.

Command must be relative to the root of the Package directory.

Example:

/dir/my.cmd ${My.Custom.Value}

Executes the my.cmd file located in a sub folder called ‘dir’, replacing ${My.Custom.Value} with its runtime value.

Uploading and Publishing

Once the package.manifest has been created, validated, and zipped with the all other required files, there are two options supported for uploading. For packages less than 15MB, upload directly through a web browser via the Tier 3 Control Portal. Packages larger than 15MB can be uploaded via FTP. The FTP option is available for smaller packages as well.

The Upload Package option is located in the Manage Scripts and Manage Software menu items under Blueprints. If you select the FTP option, an FTP Account and directory will be created for your account and the credentials and URL will be displayed. The default URL is ftp://ftp.farmpool.net. Packages must be placed in the default folder otherwise they will not appear in the Pending List. Once uploaded, Package zip files will appear in the Pending List and can be published to the Package Library.

The publication process will first load and perform basic validation of the Package. If successful, you will be presented with a form showing the contents of your Manifest as well as a sample UI form with the parameters that will be prompted for at deployment time. Finally, you will be able to specify additional metadata for the Package, such as supported Operating Systems and Visibility. Currently we support Public and Private Visibility. Public allows any Blueprint designer to add the Package to their Blueprint, and Private restricts the Package to your account only.

The publish process is performed asynchronously and the deploy time will depend upon the size of the package. Once published, it will appear in the Published Scripts or Software list. If you chose to make it Public it will also appear in the Public Scripts or Software library.