You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Pack is the unit of deployment for integrations and automations that extend |st2|. Typically a pack is organized along service or product boundaries e.g. AWS, Docker, Sensu etc. A pack can contain :doc:`Actions </actions>`, :doc:`Workflows </workflows>`,
:doc:`Rules </rules>`, :doc:`Sensors </sensors>`, and :doc:`Aliases <chatops/aliases>`. StackStorm content is always part of a pack, so it's important to understand how to create packs and work with them.
8
8
9
-
Some packs extend |st2| to integrate it with external systems -
`JIRA <https://github.com/StackStorm-Exchange/stackstorm-jira>`_. We call
13
-
them "`integration packs`". Some packs capture user's automation patterns - they contain
14
-
workflows rules and actions for a specific automation - like
15
-
`st2 demo pack <https://github.com/StackStorm/st2incubator/tree/master/packs/st2-demos>`_. We call them "`automation packs`". It is a convention to keep automation and integration separate better reuse
16
-
and dependency management.
9
+
Some packs extend |st2| to integrate it with external systems — like
We call them "`automation packs`". This naming is mostly a convention: StackStorm
17
+
makes no distinction between the two.
17
18
18
-
Any automation or integration you create will be a part of a pack, so read on and learn.
19
+
Integration packs can be shared and reused by anyone who uses a service the pack is meant
20
+
for, and you will find a lot of those on `StackStorm Exchange <https://exchange.stackstorm.org>`_.
21
+
Automation packs are often very specific and have little use outside of a particular team
22
+
or company; they are usually shared internally.
19
23
20
24
21
25
Managing Packs
@@ -25,14 +29,15 @@ Managing Packs
25
29
26
30
Everything about packs got better and easier in |st2| 2.1! There are new API endpoints, CLI
27
31
commands, repository structure for hosting packs, and an awesome pack collection on `StackStorm
28
-
Exchange <https://exchange.stackstorm.org>`_. To make it happen, we deprecated few old things.
32
+
Exchange <https://exchange.stackstorm.org>`_. To make it happen, a few things had to be deprecated.
29
33
Check the :doc:`upgrade notes </upgrade_notes>` and :doc:`/reference/pack_management_transition`.
30
34
31
-
|st2| packs are managed through ``st2 pack ...`` commands: ``st2 pack -h`` will give you a useful
32
-
overview if you just need a quick start.
35
+
|st2| packs are managed through ``st2 pack <...>`` commands: ``st2 pack -h`` will give you a useful
36
+
overview.
33
37
34
38
A few packs (such as the ``core`` pack for basic StackStorm actions) come pre-installed
35
-
with StackStorm. ``list`` and ``get`` are the primary commands to work with local packs:
39
+
with StackStorm. ``list`` and ``get`` are the primary commands to get information about
40
+
local packs:
36
41
37
42
.. code-block:: bash
38
43
@@ -48,8 +53,11 @@ system packs directory which defaults to ``/opt/stackstorm/packs``.
48
53
Discovering Packs
49
54
-----------------
50
55
51
-
There's over a hundred StackStorm packs already available to you! `StackStorm Exchange <https://exchange.stackstorm.org>`__ is a collection of ready-made packs submitted by StackStorm users and maintained by StackStorm engineers. There are packs for most of the popular cloud providers and
52
-
DevOps tools.
56
+
There's over a hundred StackStorm packs already available to you!
57
+
`StackStorm Exchange <https://exchange.stackstorm.org>`__ is a collection of
58
+
ready-made packs submitted and maintained by the StackStorm community. There are
59
+
packs for most of the popular cloud providers and DevOps tools, as well as more
60
+
peculiar integrations (hello, ``tesla`` and ``hue``).
53
61
54
62
You can browse the pack listing at `exchange.stackstorm.org <exchange.stackstorm.org>`__,
55
63
or search the pack index in CLI with ``st2 pack search`` and ``st2 pack show``:
@@ -68,6 +76,7 @@ or search the pack index in CLI with ``st2 pack search`` and ``st2 pack show``:
68
76
st2 pack search "Jon Middleton"
69
77
70
78
# Show an index entry for the pack
79
+
# with the exact name match
71
80
st2 pack show sensu
72
81
73
82
Installing a Pack
@@ -77,6 +86,7 @@ Installing a pack is simple:
77
86
78
87
.. code-block:: bash
79
88
89
+
# Install from the Exchange by pack name
80
90
st2 pack install sensu
81
91
82
92
# You can also install multiple packs:
@@ -88,18 +98,27 @@ Essentially, ``st2 pack install`` works with git repositories: there is one for
By default, the latest version of a pack will be installed, but you can specify a particular version, branch, tag, or even a commit hash. Exact version with ``=`` is required.
Running ``st2 pack install`` on already installed pack will **upgrade** it:
102
-
your pack will be replaced with the version you're asking |st2| to install.
117
+
Running ``st2 pack install`` on an already installed pack will **replace**
118
+
it with the requested version or **upgrade to latest** if the version is not
119
+
specified. Your config file will not be overwritten, so you can revert to an
120
+
older version just as easily, but for production deployments we recommend to
121
+
always specify versions in case there are major changes in ``latest``.
103
122
104
123
To uninstall a pack, use ``remove``:
105
124
@@ -110,7 +129,10 @@ To uninstall a pack, use ``remove``:
110
129
Configuring a Pack
111
130
------------------
112
131
113
-
Integration packs often require configuration to adjust to the environment. e.g. you will need to specify SMTP server for email, a puppet master URL for Puppet, or a Keystone endpoint and tenant credentials for OpenStack.
132
+
Integration packs often require configuration to adjust to the environment.
133
+
For example, you need to specify an SMTP server to use the email pack, a puppet
134
+
master URL to use the Puppet pack, or a Keystone endpoint and tenant credentials
135
+
for OpenStack.
114
136
115
137
Most packs that require configuration can be configured interactively:
116
138
@@ -120,48 +142,19 @@ Most packs that require configuration can be configured interactively:
120
142
121
143
You will be prompted for configuration parameters in an interactive tool with descriptions,
122
144
suggestions, and defaults. You will also be asked to verify your final config file in a text editor
123
-
before saving it: it's optional, and most packs don't require more than two or three fields, but we
145
+
before saving it; it's optional, and most packs don't require more than two or three fields, but we
124
146
have to comply with Health and Safety. The generated file will be placed in
125
-
``/opt/stackstorm/configs/<pack>.yaml``, and config will be loaded.
147
+
``/opt/stackstorm/configs/<pack>.yaml`` and loaded.
126
148
127
-
Some old packs that have not transitioned to using ```config.schema.yaml``` will require you to
128
-
edit a ``config.yaml`` file inside the ``/opt/stackstorm/packs/<pack>`` directory, and reload the
129
-
pack with ``st2 pack register <pack>``. Your config will not be overwritten on pack upgrades, and to
130
-
be extra safe, you can save it as ``/opt/stackstorm/configs/<pack>.yaml`` to keep it away from the
131
-
pack source, which is something we recommend.
149
+
The interactive configuration works for all packs that have a ``config.schema.yaml`` file,
150
+
that has been a standard for a while now, but some older packs might require you to edit
151
+
a ``config.yaml`` file inside the ``/opt/stackstorm/packs/<pack>`` directory, and reload the
152
+
pack with ``st2 pack register <pack>``. Move the config file to ``/opt/stackstorm/configs/<pack>.yaml``
153
+
after you perform the configuration to keep the config file away from the pack source and
154
+
ensure compatibility with future versions.
132
155
133
156
There are more nice tricks on pack configuration, see :doc:`/reference/pack_configs`.
134
157
135
-
Under the Hood: Pack Basics
136
-
---------------------------
137
-
138
-
The pack management described above is our opinionated convenience layer on top of pack basics.
139
-
Once you understand it, you can use your config management tool of choice to directly operate
140
-
the content.
141
-
142
-
Packs are placed in a system pack directory which defaults to ``/opt/stackstorm/packs``. A
143
-
``virtualenv`` needs to be created for each Python pack under ``/opt/stackstorm/virtualenv``
144
-
145
-
When |st2| loads the content, it looks into the system packs directory and
146
-
into any additional directories specified in the ``packs_base_paths`` config value
147
-
in ``st2.conf`` (typically in :github_st2:`/etc/st2/st2.conf <conf/st2.prod.conf>`.
148
-
The value must be a colon delimited string of directory paths. For example:
Directories are always searched from left to right in the order they are
204
+
specified, with the system packs directory always searched first.
205
+
206
+
A pack configuration file must be stored as ``/opt/stackstorm/configs/<pack_ref>.yaml``
207
+
and follow a schema defined in ``/opt/stackstorm/packs/<pack_dir>/config.schema.yaml``.
208
+
See the :doc:`/reference/pack_configs` section for details.
209
+
210
+
When the pack content changes, it has to be registered again (reloaded). To register
211
+
individual packs, use ``st2 pack register --packs=pack1,pack2``. To register everything
212
+
at once, use ``st2ctl reload`` (run it with ``-h`` to explore the fine-tuning flags).
213
+
187
214
Installing packs from private repositories
188
215
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
189
216
190
-
If you're installing a pack from a private repository on GitHub, you can use https auth with a `personal access token <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`__, or create a `deploy key <https://github.com/blog/2024-read-only-deploy-keys>`__ to use SSH.
217
+
If you're installing a pack from a private repository on GitHub, you can use HTTPS auth
218
+
with a `personal access token <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`__,
219
+
or create a `deploy key <https://github.com/blog/2024-read-only-deploy-keys>`__ to use SSH.
191
220
192
-
Access tokens are used with HTTPS auth: ``st2 pack install https://<user>:<token>@github.com/username/repo.git``.
221
+
Access tokens are used with HTTPS URLs: ``st2 pack install https://<user>:<token>@github.com/username/repo.git``.
222
+
Be advised that your token will be logged in StackStorm, git, your shell history, and probably some other
223
+
log files, including git error logs if anything fails. Using SSH auth is a much better idea most of the time.
193
224
194
-
Deploy keys are used with ``git@`` urls, and require the system user running the command (stanley or root, depending on your configuration) to have a private key, but they are more secure and can be configured on the per-repo basis.
225
+
For SSH (URLs starting with ``git@``) auth you have to create a
226
+
`deploy key <https://github.com/blog/2024-read-only-deploy-keys>`__, and
227
+
require the system user running the command (stanley or root,
228
+
depending on your configuration) to have a private key. Deploy keys are more secure
229
+
than personal access tokens and can be configured on the per-repo basis.
195
230
196
-
Other git hosting services should also support either SSH or HTTPS auth, and would be configured in a similar fashion.
231
+
Other git hosting services should also support either SSH or HTTPS auth,
232
+
and would be configured in a similar fashion.
197
233
198
234
199
-
Hosting your Private Pack Index
200
-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
235
+
Hosting your own pack index
236
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
201
237
202
-
When you run pack management commands like ``st2 pack install sensu`` or ``st2 pack search git``, |st2| uses a pack index file to resolve short names and perform searches. A pack index is, essentially, a JSON object: it contains metadata and URLs for all available packs.
238
+
When you run pack management commands like ``st2 pack install sensu``
239
+
or ``st2 pack search git``, |st2| uses a pack index file to resolve
240
+
short names and perform searches. A pack index is, essentially, a JSON
241
+
object: it contains metadata and URLs for all available packs.
203
242
204
-
`The StackStorm Exchange index file <https://index.stackstorm.org/v1/index.json>`__ is a default file used by all |st2| instances, and a good example of the index format. The file is hosted on GitHub (`StackStorm-Exchange/index <https://github.com/stackstorm-exchange/index>`__) and proxied through CloudFlare CDN.
243
+
`The StackStorm Exchange index file <https://index.stackstorm.org/v1/index.json>`__
244
+
is a default file used by all |st2| instances, and a good example of the index format.
245
+
The file is hosted on GitHub (`StackStorm-Exchange/index <https://github.com/stackstorm-exchange/index>`__)
246
+
and proxied through CloudFlare CDN.
205
247
206
-
The index path is specified in ``st2.conf`` as ``content.index_url``. You can replace the default index, or even use more than one with a comma-separated list:
248
+
The index path is specified in ``st2.conf`` as ``content.index_url``. You can
249
+
replace the default index, or even use more than one with a comma-separated list:
Contents from all specified indexes will merge, priority arranged left to right. In the example above, ``sensu`` pack in your own index would override ``sensu`` pack from the Exchange.
256
+
Contents from all specified indexes will merge with descending priority (left to right).
257
+
In the example above, ``sensu`` pack in your own index would override ``sensu`` pack
258
+
from the Exchange.
214
259
215
-
There are multiple reasons to consider hosting your own index, especially with HA deployments or multi-server setups:
260
+
There are multiple reasons to consider hosting your own index, especially with HA deployments
261
+
or multi-server setups:
216
262
217
263
* mirroring: in case the main index is not available, your mirror will be used;
218
-
* forking: if you fork Exchange packs, you can create an index that is going to use your forks;
264
+
* forking: if you fork Exchange packs often, you can create an index that is going to list your forks;
219
265
* enterprise restrictions: if you need pack names to resolve, but can't install from github, you can specify your own index as the only source;
220
266
* a centralized resolver: in a multi-server deployment, you can host an index to keep repo URLs in a centralized location;
221
267
* bragging rights: get your own packs resolvable by short names because the cool kids are doing it.
222
268
223
-
In most cases there are many other ways to solve the same problem, but sometimes a pack index is a viable alternative. Create your index file and make it accessible over HTTPS, change the config—and you're good!
269
+
In most cases there are many other ways to solve the same problem, but sometimes a pack index
270
+
is a viable alternative. Create your index file and make it accessible over HTTPS,
271
+
change ``st2.conf``—and you're good!
224
272
225
-
When you have to monitor index health, the ``/packs/index/health`` API endpoint will show you the state of all indexes used by your |st2| instance.
273
+
When you have to monitor index health, the ``/packs/index/health`` API endpoint will show
274
+
you the state of all indexes used by your |st2| instance.
0 commit comments