Blueprints Script and Software Package Management

Updated by Trent Anderson on Dec 18, 2014
Article Code: kb/907

Last updated: 2/3/2015 03:05 PST

Description

Software and script packages (henceforth referred to as "packages") are one way that Blueprint Designers can customize their environments. They can be configured to run scripts and executables 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. Lumen Cloud supports the following executable types:

- Standard .exe

- Command line scripts (anything that can be run from cmd.exe for Windows or the shell on Linux)

- PowerShell scripts (.ps1 files)

* Note: The permissions of this file for Linux scripts must be set to be executable (chmod 755). In order to best achieve this, the file must be created and zipped on a Linux or Unix-based platform.

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

Note: The zip file should be created on a comparable environment to the one in which the script will be running. In other words, for a script that will run on Linux, it should be created on a Unix-based platform, and for a Windows script, it should be created on a Windows machine.

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

<Manifest> Element

The root node for the package manifest.

<Manifest>
<Metadata>
<Parameters>
<Execution>
</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.

<Metadata>
<UUID>
<Parameters>
<Name>
<Description>
</Manifest>

Parent Element

<Manifest>

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>
<Parameter>
</Parameters>

Parent Element

<Manifest>

Attributes

None.

Child Elements

Name

Description

Parameter

See <Parameter> Element.

<Parameter> Element

Defines how a Parameter will be presented in the UI.

<Parameter Name= Type= Variable= Hint= Prompt= Global= Regex= >
<Option>
</Parameter>

Parent Element

<Parameters>

Attributes

Name

Description

Required?

Name

Display name for the Parameter.

Ignored if Prompt = ‘none’.

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 Lumen Cloud 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 = ‘none’

No

Default

Sets the default parameter value. If you specify a default it cannot be empty.

No

Prompt

  • None: Parameter will have no representation in the UI
  • Build: Parameter will be prompted for when a Blueprint is being built
  • Design: Parameter will be prompted for when Blueprint is being designed/deployed
  • Global: Parameter will be prompted only once when it exists in multiple packages

Default = ‘None’

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

Required

A Boolean value indicating if this parameter requires a value or not.

Default = 'true'

No

Parameter Type

Type

Description

UI Element

Network

The Lumen Cloud 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 Lumen Cloud that can be accessed from within the Package.
To use a System Parameter it must be defined in the Parameter list with Prompt=’none’

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.

T3.Identity.Account

The account alias that this Blueprint is being deployed under.

T3.Datacenter

The data center that the Blueprint is being deployed in.

<Option> Element

Defines the options for Option and MultiSelect Parameters

<Option Name= Value= />

Parent Element

<Parameter>

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.

<Execution> Element

Defines how the Package should be executed.

<Metadata>
<Mode>
<Command>
</Manifest>

Parent Element

<Manifest>

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

Supported on Linux

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.

RebootOnSuccess

(Boolean) - Valid values are: ‘true’ or ‘false’

true – Specify ‘true’ to reboot the server once the package has executed.

false – (default) The server will not reboot.

Persistent

(Boolean) - Valid values are: ‘true’ or ‘false’

true – Specify ‘true’ to persist the package on the server.

false – (default) The package will not be persisted after execution.

Example package.manifest

<?xml version="1.0" encoding="UTF-8"?>
<Manifest>
  <Metadata>
    <UUID>d1672b23-6157-11e5-9d63-60030891ee48</UUID>
    <Name>Install Script with License Key</Name>
    <Description>Install script for your license based agent</Description>
  </Metadata>
  <Parameters>
    <Parameter Name="LicenseKey" Type="String" Variable="LicenseKey" Hint="License Key" Prompt="Build" Required="true"/>
  </Parameters>
  <Execution>
    <Mode>Ssh</Mode>
    <Command>./install-agent.sh ${LicenseKey}</Command>
    <Persistent>false</Persistent> 
    <RebootOnSuccess>false</RebootOnSuccess> 
  </Execution>
</Manifest>
  

Uploading and Publishing a Package

Once the package.manifest has been created, validated, and zipped with the all other required files, the following steps should be followed to get the package uploaded and published to the Control Portal.

  1. Login to control portal and navigate to the Scripts page.
    2014-06-05-001-Scripts-Menu.png
  2. Click on the "+ new script" button.
    2014-06-05-002-New-Script.png
  3. You will be presented with two options for uploading the package: Browser or FTP. For packages less than 4MB, you can easily upload directly through your web browser by choosing "Browser Upload". For packages larger than 4MB, they must be uploaded using the "FTP Upload" option, but this option is available for smaller packages as well. Selecting the "FTP Upload" option will create an FTP account and path and display the credentials and URL to use for uploading. (Note that you may create your own FTP users for this purpose. Packages must be placed in the root folder as indicated by the display. Once uploaded, Package zip files will appear in the Unpublished list.)
    upload-package.png
  4. If you chose "Browser Upload" you will see a prompt allowing you to browse for the file. Select the zip file that contains the package.manifest and supporting files and then click "upload script package" to upload it to the server. (If you chose the "FTP Upload" option, after uploading the package to the folder using an FTP client, click on the "Unpublished" tab and move on to step 5.)
    2014-06-05-005-Upload-File.png
  5. Now publish the package by clicking the "publish" button next to the package name in the list of unpublished packages.
    2014-06-05-006-Publish.png
  6. The publication process will then 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. If everything looks right, click the "next" button to move on.
  7. You will be presented with a page where you can specify additional metadata for the package. First, choose to publish the package as a "Script" or "Software". (There is no functional difference here, just categorization.) Then choose the desired Operating System flavor (Linux or Windows) followed by checking the box next to the specific versions of the OS that the package supports (i.e. Windows 2003 or 2008, Ubuntu vs. Redhat, etc.). The last step is to select the visibility of the package. Private packages are only visible to users in the account where it was created, Shared packages are visible to users in the account where it was created and all sub-accounts underneath, and Public packages are available to all accounts. (Please review Creating Public Blueprint Packages before publishing a public package.) Finally, click the "Publish" button to kick off the publishing process.
    2014-06-05-008-Package-Details.png
  8. The package is then queued for asynchronous publishing and the deploy time will depend upon the size of the package. Once the publish operation is complete, it will appear in the package library. (You can click the "Details Page" link to check the status of the publish.)

    2014-06-05-009-Package-Done.png