Creating StackPacks

StackPacks allow StackState to integrate with external systems with minimal to no configuration. In this guide we will explore the structure of a StackPack.

File format

A StackPack is a zip file with .sts extension, with the following structure.

├── provisioning
│   └── ExampleProvision.groovy
├── resources
│   ├── logo.png
│   └── overview.md
└── stackpack.conf
  • provisioning directory is where all the groovy scripts used for provisioning the Stackpack are stored. The provisioning can also be split into multiple groovy scripts and the provisioning directory is part of the classpath while provisioning the StackPack.
  • resources directory contains all the static resources and contents for the StackPack. They are generally available through /stackpack/{stackpack-name}/resources/{resource}.
  • stackpack.conf is where the StackPack is configured. It is in HOCON format, which is a superset of JSON so any json file will work as well. The configuration file is expected to have a set of mandatory fields, the structure of which is described below.

Configuration file

A StackPack should have a HOCON configuration file named stackpack.conf in the root directory. The structure of the file should look like this:

name = example
displayName = Example stackpack
version = "1.0.0"
isNew = yes
logoUrl = "http://url.to.the.logo"
categories = ["Infrastructure"]
overviewUrl = "overview.md"
detailedOverviewUrl = "detailed-overview.md"
configurationUrls = {
	INSTALLED = "installed.md"
	NOT_INSTALLED = "notinstalled.md"
	ERROR = "error.md"
	PROVISIONING = "provisioning.md"
	DEPROVISIONING = "deprovisioning.md"
	WAITING_FOR_DATA = "waitingfordata.md"
}
faqs = []
steps = [
  {
    name = "text"
    display = "Text"
    value {
      type = "text"
      default = "value"
    }
  },
  {
    name = "password"
    display = "Password"
    value {
      type = "password"
    }
  }
]
provision = "ExampleProvision"
  • name - Name of the Stackpack. This is what is used to uniquely identify the stackpack. (Required)
  • displayName - Name that is displayed on both the StackPack listing page and on the title of the StackPack page. (Required)
  • version - Semantic version of the StackPack. StackPacks with the same major version are considered compatible. (Required)
  • isNew - This specifies whether the StackPack is new, as in the StackPack version is the first publicly available version. The values can be yes/no/true/false. By default it is considered false.
  • logoUrl - Specifies the logo used as badge for the StackPack. It could be any of the resource url as defined here. (Required)
  • categories - These are keywords using which the StackPacks can be filtered. Any list of relavant labels could be passed here. It is recommended that the labels be capitalized.
  • overviewUrl- Markdown resource that describes the summary of the StackPack. By default its assumed to be /overview.md.
  • detailedOverviewUrl - Optional Markdown resource that described the StackPack in a bit more detailed fashion. This is displayed in two columns below the installed instances section in the StackPack page. Markdown comment, [comment]: # (split) is used to delimit the two columns in the markdown.
  • configurationUrls - Contains the Markdown resources relevant for various states of StackPack provisioning, See state-transitions.
  • faqs - Frequently asked questions with respect to the StackPack or its installation. It’s a list with each element having the following format. { question = "question" answer = "answer" }
  • steps - Describes the configuration fields. See Configuration input.
  • provision - Defines the provisioning script. For example, if the script is ExampleProvision then, provisioning/ExampleProvision.groovy is looked up to see if there is a groovy class named ExampleProvision which extends com.stackstate.stackpack.ProvisioningScript from stackpack-sdk.

URLs in Stackpack configuration

  • Any relative/absolute path is considered as a resource inside the resources directory in the stackpack.
  • Any absolute URL with scheme (http/https) refers to an externally hosted resource with the given URL.

Configuration input

A StackPack could prompt for some input from the user. The prompts can be configured in steps part of the StackPack configuration. Each step is rendered as an input field. There are two different types of inputs currently supported, a text or a password input field.

Text input

A text input field is described as below,

{
    name = "text"
    display = "Text"
    value {
        type = "text"
        default = "value"
    }
}

StackState assumes all the input fields in the StackPack mandatory. To circumvent that, an optional field could be provided with a default value.

Password input

A password input field is described exactly like the text input field except that there are no default values as below.

{
    name = "password"
    display = "Password"
    value {
      type = "password"
    }
}

If the user does not provide any value to any of the input fields defined in the steps, StackState will raise a validation error and prompt the user to enter the values. The input values of the entered fields are provided as a un-modifiable map to the provision function of the ProvisioningScript which can be used for further provisioning. The map is indexed by the names of the fields provided for each field.

Provision script

The provisioning script that is used for provisioning the StackPack should extend from com.stackstate.stackpack.ProvisioningScript. The provisioning script could be split into multiple groovy scripts. The provisioning directory inside the StackPack is part of the classpath, so any groovy script referred to inside the provisioning directory is also loaded.

A provisioning script is provided with a set of capabilities that it can execute in the StackState environment. The capabilities are restricted to those that are defined as part of com.stackstate.stackpack.ProvisioningContext which is passed as a constructor parameter for the ProvisioningScript.

Testkit

stackpack-sdk comes with a testkit, that allows one to test how the StackPack integrates with the StackState execution environment. The testkit is in test classifier for stackpack-sdk.

StackPack file upload

To upload your .sts file to StackState you need StackState CLI tool installed and use the following command: sts-cli stackpack upload -f path/to/file.sts