by Dmitri Zimine and st2 team
Nov 29, 2016
Dear stormers and friends!
We are almost ready with a new and quite exciting platform release. This is a big release and we are really looking forward to it, and you should, too – just check out exchange.stackstorm.org to get excited about what is coming. As usual, you will soon see an announcement, a blog describing the highlights of what we’ve done, and a back-story on how and why we did it.
This, however, is an unusual “head’s up”. The changes around pack management we are introducing in 2.1 are so substantial that it’s fair to give you time to review the new features, read the changelog, and adjust your private packs or automation around StackStorm if needed. We’re inviting you to contribute – EASILY – by trying out the new functionality and sharing feedback, or helping us catch last-minute bugs.
The transition notes are drafted here. The full list of changes is in the change log. Please help us improve the docs wherever you find them unclear, confusing or imprecise – we are actively testing as we write this.
The biggest change is introducing StackStorm Exchange. All integration packs from st2contrib, as well as other packs scattered around, are being moved under StackStorm Exchange. Once the transfer is complete, you will be submitting your new packs as PRs against StackStorm-Exchange/exchange-incubator repo, as described in README.md. Making features and fixes on existing community packs will be much easier now that each pack is in it’s own GitHub repo.
Shiny new StackStorm Pack Exchange.
The other big change is with the pack management CLI, previously known as the “packs” pack. Version 2.1 introduces a new command – st2 pack – to StackStorm CLI. It contains sub-commands for managing your packs and searching for new ones: try st2 pack help for the full listing. The new commands work with the new StackStorm Exchange, as well as with any pack on Github or on private Git servers. We encourage using git: you will see how our new features take advantage of this “each pack is a git repo” model.
The packs pack is still here, but has been changed to reflect this new model. As a result – WARNING! – subtree repositories (repositories containing multiple packs inside the packs/ subdir) are no longer supported. The subtree parameter in packs.install is removed. If you happen to use subtrees with your private packs, they will have to be split into multiple single-pack repositories in order for st2 pack install to be able to install the packs.
There is a lot of advantages to this approach, but what if you prefer a different one? Go for it! The st2 pack command, the packs pack, and the pack management API endpoints only make up an opinionated layer on top of st2 fundamentals, and you don’t have to use it. The fundamentals remain intact: place packs under /opt/stackstorm/packs, virtualenv per pack if they are Python, tell the system to load the content – and your content is running. If your opinion on “how many packs should one repo contain” differs from ours – suit yourself, use your favorite deployment tool to put the content in the right place, register, and run. Do tell us “why” – we are making design decisions based on what users tell us and want to count your opinion and learn from your way of running StackStorm.
Lastly, for all pack writers: please validate your custom packs against these two changes:
version field must conform to semver (semantic versioning): 0.2.5, not 0.2. If it does not, the pack registration will throw an error. Please check and update.name field in pack.yaml should now only contain contain letters, digits, and underscores.^ No dashes! hpe-icsp is no good, hpe_icsp is fine.Some other changes to take advantage from:
contributors field. This field is an array and contains a list of people who have contributed to the pack. These days most of the packs have more than one contributor so author field is not sufficient anymore and we want to give credit where credit is due.stackstorm_version field has been added. It is optional and can contain a semver string which tells with which versions of StackStorm this pack works with (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 you can now specify that and users won’t be able to install a pack unless they are running a version which is compatible with the pack.name or ref field from pack.yaml is always used. Name your repository whatever you want (the recommended form for StackStorm Exchange is stackstorm-pack_name).That’s enough for the head’s up, more details in the docs.
Please give this a try. To install the 2.1dev and try the new st2 pack along with other goodies – pick one of:
unstable in the name, it will get you something that passed automated tests.curl -sSL /packages/install.sh | sudo bash -s -- --user=st2admin --password=secret --unstable
RELEASE="unstable" ST2PASSWORD="secret" vagrant up
We are looking forward to your feedback on StackStorm Slack channel (registration here), at moc.mrotskcatsnull@troppus, or in the blog comments right here.