The documentation you're currently reading is for version 2.3.0. Click here to view documentation for the latest stable version.
Pack Management Transition¶
In 2.1, with the introduction of the new pack management and
StackStorm Exchange, BWC validates
pack metadata in
pack.yaml and enforces certain versioning and naming
conventions. These changes may require users to update their custom Packs
if they do not follow the same standards.
All packs in StackStorm Exchange have been updated to work with BWC 2.1 and
maintain compatibility with older versions of BWC. Read the details and
make sure your packs are valid.
In BWC 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
st2 run packs.install as a part of your deployment — please read this
section through and through.
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> in the CLI.
Exchange packs are hosted in the
on GitHub, and you can open PRs against them just as you would open PRs to
before. To submit a new pack, follow the instructions in
All the 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 BWC content from multiple indexes. See “Advanced topics” in Packs for instructions.
Using StackStorm Exchange with pre-2.1 BWC¶
If you use BWC 2.0 or ealier, you can still get packs from
StackStorm Exchange with the old
stackstorm-exchange/<pack name> as
repo_url, and repeat the pack name in
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
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
Starting from 2.1, BWC enforces validation on
If you create your own packs, please validate them against these rules:
pack.yamlmust conform to semver:
0.2. Pack loading will fail if the version is not in the semver format.
pack.yamlmust only contain letters, digits, and underscores, since it is also used as a ref (UID) for the pack. You can set the
refvalue explicitly in
pack.yaml: in this case,
refis going to be validated against the rule above, and
nameis going to be used for display only and can contain any characters.
- The email attribute in
pack.yamlmust 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¶
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.
- A new
pack installcommand supports getting specific version, hash, branch, or tag of a pack.
- A new
pack confighelps 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 CLI.
- You can specify
pack.yaml: it should contain a version range to determine if the installed version of BWC 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
pack.yaml: it is an array that should contains a list of people who have contributed to the pack. These days most of the packs have more than one contributor, and the
authorfield 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
ref, if specified) field from
pack.yamlwill be used. The repository name is entirely up to you (a convention we use in StackStorm Exchange is
Questions? Problems? Suggestions? Engage!