Pack Management Transition

Warning

In 2.1, with the introduction of the new pack management and StackStorm Exchange, StackStorm validates pack metadata in pack.yaml and enforces certain versioning and naming conventions. These changes may require users to update their custom Packs.

All packs in StackStorm Exchange have been updated to work with StackStorm 2.1 and maintain compatibility with older versions.

In StackStorm 2.1, pack management has received a significant overhaul. With new dedicated tools, working with packs becomes very close to the “usual” package management you know from working with development platforms and Linux flavors. Installing, updating, and managing StackStorm packs has become a smoother, more streamlined experience.

It’s a big change, and you will surely enjoy how easy it is to install and maintain your packs now, especially if you’re upgrading from an earlier version. Installing packs, contributing fixes, handling pack versions, sharing and discovering — nearly everything about StackStorm packs is better than before.

Some of the changes require special attention: if you create your own packs or deploy packs from st2contrib — either through configuration management or by running st2 run packs.install as a part of your deployment — please read this section carefully.

StackStorm Exchange

StackStorm Exchange is a new pack directory maintained by the StackStorm team. Any pack from the Exchange can be installed with st2 pack install <pack>.

Exchange packs are hosted in the StackStorm-Exchange organization on GitHub, and you can open PRs against them just as you would open PRs to st2contrib before. To submit a new pack, follow the instructions in exchange-incubator.

All packs from st2contrib have been transferred to individual repositories inside the StackStorm-Exchange organization. The st2contrib repository is frozen: it is still functional, but it will not receive updates anymore, and new submissions are not accepted.

You can host your own pack index alongside (or even instead of) the Exchange, and get your StackStorm content from multiple indexes. See “Advanced topics” in Packs for instructions.

Using StackStorm Exchange with pre-2.1 StackStorm

If you use StackStorm 2.0 or earlier, you can still get packs from StackStorm Exchange with the old packs.install action: use stackstorm-exchange/<pack name> as repo_url, and repeat the pack name in packs. As an example, for the Cloudflare pack, the full CLI command would be:

$ st2 --version
st2 2.0.1
$ st2 run packs.install packs=cloudflare repo_url=stackstorm-exchange/cloudflare

Alternatively, you can just git clone the packs, making sure that the pack directory name matches the pack ref:

cd /opt/stackstorm/packs
git clone https://github.com/StackStorm-Exchange/stackstorm-cloudflare.git cloudflare
chown -R root:st2packs cloudflare
st2 run packs.setup_virtualenv packs=cloudflare
st2ctl reload

Deprecation Warnings

Validation Rules

Starting from 2.1, StackStorm enforces validation on pack.yaml. If you create your own packs, please validate them against these rules:

  • The version value in pack.yaml must conform to semver: 0.2.5, not 0.2. Pack loading will fail if the version is not in semver format.

  • The name value in pack.yaml must only contain letters, digits, and underscores, since it is also used as a ref (UID) for the pack. You can set the ref value explicitly in pack.yaml: in this case, ref is going to be validated against the rule above, and name is going to be used for display only and can contain any characters.

  • The email attribute in pack.yaml must contain a properly formatted email address.

Make sure your custom packs are compatible, then follow the steps in Upgrade Notes to upgrade to 2.1. All packs in the Exchange have been updated to reflect these changes.

Git Repositories for Packs

When using st2 pack install <URL>, the URL is assumed to be a valid git repository containing your pack in its root (see StackStorm-Exchange on GitHub).

This structure is required to support most of the newer pack management features, and we strongly encourage pack developers to follow it. However, if your deployment is different (maybe you don’t use git, or place multiple packs in a repository, or install packs through a configuration management tool), you aren’t required to use the st2 pack subcommands at all: refer to the “Under the Hood: Pack Basics” section of the pack documentation.

Subtree repositories (repositories containing multiple packs inside the packs/ subdir) are no longer supported, and the subtree parameter in packs.install is removed. If you happen to use a single repository to host multiple packs, it will have to be split into multiple single-pack repositories in order for st2 pack install to be able to install the packs. Alternatively, deploy them manually as described above.

Changes to Take Advantage Of

Read the Pack management doc to learn more about the new pack management.

Some highlights:

  • A new pack install command supports getting the specific version, hash, branch, or tag of a pack.

  • A new pack config helps create, validate, and load pack configurations conforming to new Pack Configuration.

  • CLI and API for pack discovery: you can search the pack directory right from the CLI.

  • You can specify stackstorm_version in pack.yaml: it should contain a version range to determine if the installed version of StackStorm is compatible with your pack (e.g. >=1.6.0, <2.0.0, or just >1.6.0). If your pack relies on functionality which is only available in newer versions of StackStorm, we encourage you to specify the correct range.

  • You can specify contributors in pack.yaml: it is an array that should contain a list of people who have contributed to the pack. These days most of the packs have more than one contributor, and the author field just isn’t enough to give credit where credit is due.

  • A pack is no longer named and referenced by its parent directory or git source: the name (or ref, if specified) field from pack.yaml will be used. The repository name is entirely up to you (a convention we use in StackStorm Exchange is stackstorm-<pack name>).