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
Copy file name to clipboardExpand all lines: docs/source/packs.rst
+76-38Lines changed: 76 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,24 +1,38 @@
1
-
Integration Packs
2
-
===================
1
+
Packs
2
+
=====
3
3
4
4
What is a Pack?
5
5
---------------
6
6
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>`,
It is best to view a pack as the means to extend |st2| and allow it to integrate with external systems. Everything you create will also be part of a pack.
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.
17
+
18
+
Any automation or integration you create will be a part of a pack, so read on and learn.
19
+
10
20
11
21
Managing Packs
12
22
--------------
13
23
14
24
.. note::
15
25
16
-
Everything about packs got better and easier in |st2| 2.1! There are new API endpoints, CLI commands, repository
17
-
structure for hosting packs, and a pack collection called StackStorm Exchange. Some of the older things are now deprecated. If you're using a previous version, it's time to upgrade or at least read the :doc:`upgrade notes </upgrade_notes>` and :doc:`/reference/packmgmt`.
26
+
Everything about packs got better and easier in |st2| 2.1! There are new API endpoints, CLI
27
+
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.
29
+
Check the :doc:`upgrade notes </upgrade_notes>` and :doc:`/reference/pack_management_transition`.
18
30
19
-
|st2| packs are managed through ``st2 pack ...`` commands: ``st2 pack -h`` will give you a useful overview if you just need a quick start.
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.
20
33
21
-
A few packs (such as the ``core`` pack for basic StackStorm actions) come pre-installed with StackStorm. ``list`` and ``get`` are the primary commands to work with local packs:
34
+
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:
22
36
23
37
.. code-block:: bash
24
38
@@ -34,9 +48,11 @@ system packs directory which defaults to ``/opt/stackstorm/packs``.
34
48
Discovering Packs
35
49
-----------------
36
50
37
-
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 engineers, and there are packs for most of the popular cloud providers and DevOps tools.
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.
38
53
39
-
In addition to the pack listing at `exchange.stackstorm.org <exchange.stackstorm.org>`__, you can search the pack index in CLI with ``st2 pack search`` and ``st2 pack show``:
54
+
You can browse the pack listing at `exchange.stackstorm.org <exchange.stackstorm.org>`__,
55
+
or search the pack index in CLI with ``st2 pack search`` and ``st2 pack show``:
40
56
41
57
.. code-block:: bash
42
58
@@ -74,15 +90,16 @@ 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.
93
+
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.
Note that running ``st2 pack install`` on an installed pack will start an upgrade: your pack will be replaced with the version you're asking |st2| to install.
101
+
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.
86
103
87
104
To uninstall a pack, use ``remove``:
88
105
@@ -101,20 +118,60 @@ Most packs that require configuration can be configured interactively:
101
118
102
119
st2 pack config cloudflare
103
120
104
-
You will be prompted for configuration parameters in a nice 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.
121
+
You will be prompted for configuration parameters in an interactive tool with descriptions,
122
+
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
124
+
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.
105
126
106
-
Some packs will require old-school manual configuration: in that case, you will have to edit a ``config.yaml`` file inside the ``/opt/stackstorm/packs/<pack>`` directory and reload the pack with ``st2 pack register <pack>``. Your config will not be overwritten on pack upgrades, and to be extra safe, you can save it as ``/opt/stackstorm/configs/<pack>.yaml`` to keep it away from the pack source, which is something we recommend.
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.
107
132
108
-
If you edit files in a pack manually, make sure to reload its content for the file changes to be reflected in StackStorm:
133
+
There are more nice tricks on pack configuration, see :doc:`/reference/pack_configs`.
109
134
110
-
.. code-block:: bash
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
156
+
specified, with the system packs directory always searched first.
111
157
112
-
st2 pack register sensu
158
+
Pack configuration is represented by ```/opt/stackstorm/configs/<packname>.yaml``` and must
159
+
conform to a configuration schema, ```config.schema.yaml``` file in pack's directory.
160
+
Details of this powerful functionaltiy are in :doc:`/reference/pack_configs` section.
161
+
162
+
To register an individual packs, use ``pack register --packs=pack1,pack2``.
163
+
To reload all the content, use ``st2ctl reload``; run it with ``-h`` and explore fine-tuning flags.
113
164
114
165
Developing a Pack
115
166
-----------------
116
167
117
-
See :doc:`/reference/packs` 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 |st2| community. If you're planning to develop any |st2| 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!
168
+
See :doc:`/reference/packs` for details on how to package your integrations and automations in a
169
+
pack, how to fork a pack for development or create your own, how to publish it, and how to
170
+
contribute it to the |st2| community. If you're planning to develop any |st2| content, we would
171
+
strongly suggest getting yourself familiar with that page: every piece of content in StackStorm has
172
+
to belong to a pack, and a good understanding of pack workflow will make your development process
173
+
much easier!
174
+
118
175
119
176
.. rubric:: What's Next?
120
177
@@ -138,28 +195,9 @@ Deploy keys are used with ``git@`` urls, and require the system user running the
138
195
139
196
Other git hosting services should also support either SSH or HTTPS auth, and would be configured in a similar fashion.
140
197
141
-
Pack location
142
-
~~~~~~~~~~~~~
143
-
144
-
When |st2| searches for available packs, it looks into the system packs directory and
145
-
into any additional directories which are specified in the ``packs_base_paths`` setting.
146
-
147
-
To look for packs in additional directories, set the value of ``packs_base_paths`` in ``st2.conf``
148
-
(typically in :github_st2:`/etc/st2/st2.conf <conf/st2.prod.conf>`, as described in
149
-
:doc:`Configuration </install/config/config>`). The value must be a colon delimited string of directory paths.
Note: Directories are always searched from left to right in the order they are
159
-
specified, with the system packs directory always searched first.
160
198
161
-
Working with pack indexes
162
-
~~~~~~~~~~~~~~~~~~~~~~~~~
199
+
Hosting your Private Pack Index
200
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
163
201
164
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.
`StackStorm Exchange <https://exchange.stackstorm.org/>`__, |st2| begins to validate and enforce
6
+
pack schema and conventions. These changes may require users
7
+
to update their custom :doc:`/packs` which do not confirm.
8
+
All community packs are updated to work with |st2| 2.1,
9
+
while still work with older versions of |st2|). Read the details and check your packs.
10
+
11
+
12
+
In |st2| 2.1, pack management have received significant overhaul. With new dedicated tools, working with packs becomes very close to the "usual" package management you know from working with
13
+
development platforms and Linux flavors. Installing, updating, and managing StackStorm packs has become a smoother, more streamlined experience.
14
+
15
+
It's a big change, and you will surely enjoy the streamlined workflow for content management. By
16
+
assuming `git`, making `one pack - one git repo` convention, and building tooling around it, we
17
+
now streamlined pack development and life-cycle. Developing a pack, contributing a fix to Community,
18
+
checking deviation between production and upstream origins, handling versions, sharing and
19
+
discovering your automations and integrations - all of it is now streamlined.
20
+
21
+
However some changes introduced in 2.1 may require you to
22
+
update your custom packs, or to make or adjusting automation tools might use to
23
+
deploy and configure your packs on |st2|.
24
+
25
+
26
+
Good bye st2contrib, long live StackStorm Exchange
`StackStorm Exchange <https://exchange.stackstorm.org/>`__ is the new pack index maintained by the StackStorm team. Any pack from StackStorm Exchange can be installed with ``st2 pack install <pack>``
30
+
in the CLI.
31
+
32
+
Exchange packs are hosted in the `StackStorm-Exchange organization
33
+
<https://github.com/stackstorm-exchange>`__ on GitHub. To submit **a new pack** to the StackStorm Exchange, follow the instructions in
From 2.1 on, |st2| enforces validation on ``pack.yaml``.
70
+
Please check and adjust your custom packs against these rules:
71
+
72
+
* The version field must conform to semver (semantic versioning): ``0.2.5``, not ``0.2``.
73
+
In 2.1, the system will attempt to automatically convert it to semver. If the attempt
74
+
fails, the pack loaing will error out. NOTE: In future releases there will be no auto-correct.
75
+
Save yourself surprises: convert your custom packs to `semver` yourself.
76
+
* The ``ref`` in ``pack.yaml`` should now only contain contain letters, digits, and underscores. No
77
+
dashes! ``hpe-icsp`` is no good, ``hpe_icsp`` is fine. If ``ref`` is not present, the same rule
78
+
applies to the ``name`` attribute. If validation fails, pack load will error out.
79
+
* The email attribute in ``pack.yaml`` must contain a properly formatted email address.
80
+
If validation fails, pack loading will error out.
81
+
82
+
Fix your custom packs to conform to these rules; follow the steps in :doc:`/upgrade_notes` to upgrade.
83
+
Exchange community packs have been updated to reflect these changes, please get the newer versions
84
+
of community pack from `st2contrib <https://github.com/stackstorm/st2contrib>`__
85
+
86
+
New pack management assumes each pack to be a vaild git repo. If this is not for your case, it's OK:
87
+
rely on |st2| basics, and use your favorite tools to place the packs under ``/opt/stackstorm/packs``,
88
+
set virtualenv per pack if they are Python, and tell the system to load the content.
89
+
90
+
Subtree repositories (repositories containing multiple packs inside the packs/ subdir) are no longer
91
+
supported. The ``subtree`` parameter in ``packs.install`` is removed. If you happen to use subtrees with
92
+
your private packs on git/GitHub, they will have to be split into multiple single-pack repositories in order for ``st2 pack install`` to be able to install the packs.
93
+
94
+
Changes to take advantage
95
+
-------------------------
96
+
97
+
Read :doc:`Pack management </packs>` doc to learn the benefits of the new pack management.
98
+
Some highlights:
99
+
100
+
* ``pack install`` CLI supports getting specific version, hash, or tag of a pack.
101
+
102
+
* ``pack config`` helps create, validate, and load pack configurations conforming to new :doc:`/reference/pack_configs`.
103
+
104
+
* There is a CLI and API for pack discovery: you can search the packs right from CLI.
105
+
106
+
* The ``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.
107
+
108
+
* Packs are no longer named and referenced by the parent directory or git repository containing the pack: name or ref field from pack.yaml is used. Name your repository as you pleased (the recommended form for StackStorm Exchange is stackstorm-pack_name).
109
+
110
+
* Pack metadata ``pack.yaml`` file can now contain a new optional 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.
0 commit comments