What is a Pack?

A “pack” is the unit of deployment for integrations and automations that extend StackStorm. Typically a pack is organized along service or product boundaries e.g. AWS, Docker, Sensu etc. A pack can contain Actions, Workflows, Rules, Sensors, and Aliases. StackStorm content is always part of a pack, so it’s important to understand how to create packs and work with them.

Some packs extend StackStorm to integrate it with external systems — like AWS, GitHub, or JIRA. We call them “integration packs”. Some packs capture automation patterns — they contain workflows, rules, and actions for a specific automation process — like the st2 demo pack. We call them “automation packs”. This naming is mostly a convention: StackStorm itself makes no distinction between the two.

Integration packs can be shared and reused by anyone who uses the service that pack is built for. You can find many examples of these at the StackStorm Exchange. Automation packs are often very site-specific and have little use outside of a particular team or company; they are usually shared internally.

Managing Packs

StackStorm packs are managed through st2 pack <...> commands: st2 pack -h will give you a useful overview.

Some (such as the core pack for basic StackStorm actions) come pre-installed with StackStorm. All other packs need to be installed by you. Luckily this is pretty easy!

list and get are the primary commands to get information about local packs:

# List all installed packs
st2 pack list

# Get detailed information about an installed pack
st2 pack get core

When using StackStorm and pack management actions, all packs are installed into the system packs directory, which defaults to /opt/stackstorm/packs.

Discovering Packs

There’s over a hundred StackStorm packs already available to you! StackStorm Exchange is a collection of ready-made packs submitted and maintained by the StackStorm community. There are packs for most of the popular cloud providers and DevOps tools, as well as more peculiar integrations (hello, tesla and hue).

You can browse the pack listing at exchange.stackstorm.org, or search the pack index via CLI with st2 pack search and st2 pack show:

# Search query is applied across all pack parameters.

# It will search through pack names:
st2 pack search sensu
# And keywords:
st2 pack search monitoring
# And description (use quotes for multi-word search):
st2 pack search "Amazon Web Services"
# And even pack author:
st2 pack search "Jon Middleton"

# Show an index entry for the pack
# with the exact name match
st2 pack show sensu

As of StackStorm v2.4, you can also do this via the Web UI! Explore the new “Packs” tab to see more.

Installing a Pack

Installing a pack is simple:

# Install from the Exchange by pack name
st2 pack install sensu

# You can also install multiple packs:
st2 pack install datadog github

This command will download packs from the StackStorm Exchange organization on GitHub, place them under /opt/stackstorm/packs, and register them with StackStorm.

Essentially, st2 pack install works with git repositories: there is one for every pack in the Exchange, and you can install your own packs from git just as easily.

# Install your own pack from git using http(s)
st2 pack install https://github.com/emedvedev/chatops_tutorial

# Install your own pack from git using ssh
st2 pack install [email protected]/emedvedev/chatops_tutorial

# Install your own pack using gitlab URL (added in release 3.4)
st2 pack install [email protected]:example/examplepack

By default, the latest release of the pack will be installed, but you can specify a particular version, branch, tag, or even a commit hash. Just use =:

# Fetch a specific commit
st2 pack install cloudflare=776b9a4

# Or a version tag
st2 pack install cloudflare=0.1.0

# Or a branch
st2 pack install https://github.com/emedvedev/chatops_tutorial=testing

Finally, you can install a pack from existing local dir:

# Install a pack from '/home/stanley/bitcoin' dir
st2 pack install file:///home/stanley/bitcoin

Running st2 pack install on an already installed pack will replace it with the requested version or upgrade to latest if the version is not specified. Your config file will not be overwritten, so you can revert to an older version just as easily, but for production deployments we recommend to always specify versions in case there are major changes in latest.

dependencies:
  - excel
  - powerpoint=0.2.2
  - https://github.com/StackStorm/stackstorm-ms.git

st2 pack install --skip-dependencies my-custom-pack

st2 pack remove sensu

Configuring a Pack

Integration packs often require configuration for your environment. For example, you need to specify an SMTP server to use the email pack, a puppet master URL to use the Puppet pack, or a Keystone endpoint and tenant credentials for OpenStack.

Most packs that require configuration can be configured interactively:

st2 pack config cloudflare

You will be prompted for configuration parameters in an interactive tool with descriptions, suggestions, and defaults. You will also be asked to verify your final config file in a text editor before saving it; it’s optional, and most packs don’t require more than two or three fields, but we have to comply with Health and Safety. The generated file will be placed in /opt/stackstorm/configs/<pack>.yaml and loaded.

For more nice tricks on pack configuration, see Pack Configuration.

Overriding Pack Defaults

When installing a pack the state of the resources is taken from the metadata files in the pack. Occassionally, when installing community packs you might not want all resources enabled, e.g. you only want to use a subset of actions, or want to disable the sensors.

Prior, to StackStorm 3.7.0 then this state can be altered, by:

• using the StackStorm APIs to disable the resource. However, this will be forgotten upon a st2ctl reload or pack reinstall.

• changing the metadata file manually. This would be lost upon an upgrade, and cannot be easily tracked.

In StackStorm 3.7.0 we have introduced the override feature, so that the metadata of a packs resources can be overridden by configuration files. This will always be read upon a reload or pack install. The ST2 APIs will still allow you to override this, but as before any changes made by the StackStorm APIs to enable/disable resources is forgotten upon reload or re-install.

The override facility is currently restricted to allowing the enabled property to be overridden only for resources of type: action, alias, rule and sensor. It is controlled by the /opt/stackstorm/overrides directory.

Upon a pack install or reload resource state is managed as follows:

• State is read from the pack’s resource metadata files that reside in /opt/stackstorm/packs/<packname>. These are downloaded from the relevant repository of the pack, e.g. GIT, StackStorm-Exchange.

• If /opt/stackstorm/overrides/_global.yaml is present, then any global overrides are applied. The _global.yaml allows you to specify the default state of a particular resource types, e.g. disable all sensors. The format of the _global.yaml is as follows (set to disable everything):

---
sensors:
  defaults:
    enabled: false
actions:
  defaults:
    enabled: false
aliases:
  defaults:
    enabled: false
rules:
  defaults:
    enabled: false

• If /opt/stackstorm/overrides/<packname>.yaml is present, then any pack defaults, or resource specific overrides are applied. The <pack>.yaml allows you to alter the state of all the resources of a particular type, via the defaults property (e.g. all sensors within the pack), or by individual resource type, via the exceptions property (e.g. only alter state of individual actions). As the pack name is determined by the name of the overrides file, the name of the resource in the file should omit the pack name, e.g. action1 in the pack1.yaml refers to the resource pack1.action1. The format of the <pack>.yaml is as follows (set to disable everything, except for individual resource of each type):

---
sensors:
  defaults:
    enabled: false
  exceptions:
    sensorname1:
      enabled: true
actions:
  defaults:
    enabled: false
  exceptions:
    actionname1:
      enabled: true
aliases:
  defaults:
    enabled: false
  exceptions:
    aliasname1:
      enabled: true
rules:
  defaults:
    enabled: false
  exceptions:
    rulename1:
      enabled: true

If overrides are taking place, then the number of resources affected will be output on the st2ctl reload output, for example:

$ st2ctl reload --register-all
Registering content...[flags = --config-file /etc/st2/st2.conf --register-all]
2022-02-07 12:56:43,694 INFO [-] Connecting to database "st2" @ "127.0.0.1:27017" as user "None".
2022-02-07 12:56:43,704 INFO [-] Successfully connected to database "st2" @ "127.0.0.1:27017" as user "None".
2022-02-07 12:56:44,254 INFO [-] =========================================================
2022-02-07 12:56:44,254 INFO [-] ############## Registering triggers #####################
2022-02-07 12:56:44,254 INFO [-] =========================================================
2022-02-07 12:56:44,549 INFO [-] Registered 1 triggers.
2022-02-07 12:56:44,549 INFO [-] =========================================================
2022-02-07 12:56:44,549 INFO [-] ############## Registering sensors ######################
2022-02-07 12:56:44,549 INFO [-] =========================================================
2022-02-07 12:56:44,832 INFO [-] Registered 9 sensors.
2022-02-07 12:56:44,832 INFO [-] 7 sensors had their metadata overridden.
...

On a pack install, then the number of resources that have their metadata overridden will be reported in the output of the register_pack action by the “(overridden)” entries. If no resources of that type have their metadata overridden, then there will be no correspdoning overridden entry outputted:

{
  "runners": 14,
  "rule_types": 2,
  "policy_types": 3,
  "triggers": 0,
  "sensors": 2,
  "sensors(overridden)": 2,
  "actions": 1,
  "rules": 1,
  "aliases": 0,
  "policies": 0,
  "configs": 0
 }

Example: Disabling all sensors in one pack

For example, to disable all sensors in an individual pack then we would create a /opt/stackstorm/overrides/<packname>.yaml that contained:

---
sensors:
  defaults:
    enabled: false

Example: Disabling all sensors in all packs, except for one pack

If, instead we wanted to override all sensors except for a single pack, then we would instead create a /opt/stackstorm/overrides/_global.yaml to disable all sensors:

---
sensors:
  defaults:
    enabled: false

And an /opt/stackstorm/overrides/<packname>.yaml to enable the sensors for the one pack we needed:

---
sensors:
  defaults:
    enabled: true

Example: Overriding state of individual resources

In this next example, we disable all actions in pack1, except for the actions pack1.action1 and pack1.action2. We also change the state of just a single rule to disabled. To do this, we create a /opt/stackstorm/overrides/pack1.yaml with:

---
actions:
  defaults:
    enabled: false
  exceptions:
    action1:
      enabled: true
    action2:
      enabled: true
rules:
  exceptions:
    rule1:
      enabled: false

Developing a Pack

See Create and Contribute a Pack for details on how to package your integrations and automations in a pack, how to fork a pack for development or create your own, how to publish it, and how to contribute it to the StackStorm community. If you’re planning to develop any StackStorm content, we would strongly suggest getting yourself familiar with that page: every piece of content in StackStorm has to belong to a pack, and a good understanding of pack workflow will make your development process much easier!

What’s Next?

• Explore existing packs for many common products and tools: StackStorm Exchange.

• Learn how to write a pack and contribute to the community - Create and Contribute a Pack.

• Learn how to write custom sensors and custom actions.

• Check out tutorials on stackstorm.com - a growing set of practical examples of automating with StackStorm.

• For information on pack testing, please see the Pack Testing page.

Advanced Topics

[content]
packs_base_paths=/home/myuser1/packs:/home/myuser2/packs

$ st2 pack install https://<user>:<token>@github.com/username/repo.git

http_proxy=http://proxy.server.io:port
https_proxy=http://proxy.server.io:port
no_proxy=localhost,127.0.0.1

http_proxy=http://proxy.server.io:port
https_proxy=http://proxy.server.io:port
proxy_ca_bundle_path=/etc/ssl/certs/proxy-ca.pem
no_proxy=localhost,127.0.0.1

$ sudo st2ctl restart-component st2api
$ sudo st2ctl restart-component st2actionrunner

[content]
index_url=https://my-super-index.org/index.json,https://exchange.stackstorm.org/v1/index.json