Last updated: 2/3/2015 03:05 PST
DescriptionSoftware 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 FormatPackages 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> ElementThe 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 |
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 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. |
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 |
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’ |
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. |
Defines how the Package should be executed.
<Metadata>
<Mode>
<Command>
</Manifest>
Parent Element
<Manifest>
Attributes
None.
Child Elements
Name |
Description |
||||||||
Mode |
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.
- Login to control portal and navigate to the Scripts page.
- Click on the "+ new script" button.
- 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.)
- 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.)
- Now publish the package by clicking the "publish" button next to the package name in the list of unpublished packages.
- 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.
- 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.
- 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.)