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/reference/pack_management_transition.rst
+71-19Lines changed: 71 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,23 +1,25 @@
1
1
Pack Management Transition
2
2
==========================
3
3
4
-
.. warning:: The introduction of new pack management and
5
-
`StackStorm Exchange <https://exchange.stackstorm.org/>`__ lead to the changes that may require users
6
-
to update their custom :doc:`/packs`. All community packs are updated to work with |st2| 2.1
7
-
(and will still work with older versions of |st2|). Read on for details.
4
+
.. warning:: With new pack management and
5
+
`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.
8
10
9
11
10
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
11
-
development platforms and Linux flavours. Installing, updating, and managing StackStorm packs has become a smoother, more streamlined experience.
13
+
development platforms and Linux flavors. Installing, updating, and managing StackStorm packs has become a smoother, more streamlined experience.
12
14
13
15
It's a big change, and you will surely enjoy the streamlined workflow for content management. By
14
-
assuming `git`, making ``one pack - one git repo`` convention, and building tooling around it, we
15
-
now streamlined pack development and lifecycle. Developing a pack, contributing a fix to Community,
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,
16
18
checking deviation between production and upstream origins, handling versions, sharing and
17
-
discovering your automations and integrations - all of it is becoming a breeze.
19
+
discovering your automations and integrations - all of it is now streamlined.
18
20
19
-
However we had to make some changes that will require you to
20
-
update your private packs, or to make or adjusting automation tools might use to
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
21
23
deploy and configure your packs on |st2|.
22
24
23
25
@@ -36,26 +38,76 @@ individual repositiroes at `StackStorm-Exchange organization <https://github.com
36
38
The `st2contrib <https://github.com/stackstorm/st2contrib>`__ repository is frozen. It is still
37
39
functional, but it will not receive updates anymore, and new submissions are not accepted.
38
40
41
+
You can host your own pack index, or even your own `Exchange`, and get your |st2| content
42
+
from multiple indexes. See "Advanced topics" in :doc:`/packs` for instructions.
39
43
40
-
Warnings - check your packs
41
-
---------------------------
44
+
Using StackStorm Exchange with pre-2.1 |st2|
45
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
42
46
43
-
Please validate your custom packs against these two changes:
47
+
If you are on 2.0 or ealier versions of |st2|, you can still get the packs
48
+
from `StackStorm Exchange <https://exchange.stackstorm.org/>`__. Using ``st2 run pack install``,
49
+
specify ``repo_url`` as ``http://index.stackstorm.org/repos/PACK_REF``, where
50
+
``PACK_REF`` matches a ``ref`` field of the pack. For example, for "cloudflare" pack, it
51
+
will be: ::
44
52
45
-
* The 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.
46
-
* The 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.
47
-
* The email attribute, if present in pack.yaml, must contain a properly formatted email address.
53
+
st2 --version
54
+
st2 2.0.1
55
+
st2 run packs.install packs=cloudflare repo_url="http://index.stackstorm.org/repos/cloudflare"
48
56
49
-
Fix your packs to conform to these rules; follow the steps in :doc:`/upgrade_notes` to upgrade.
57
+
Or you can just `git clone` them in place, making sure that the pack
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.
50
89
51
90
Subtree repositories (repositories containing multiple packs inside the packs/ subdir) are no longer
52
-
supported. The ``subtree`` parameter in packs.install is removed. If you happen to use subtrees with
91
+
supported. The ``subtree`` parameter in ``packs.install`` is removed. If you happen to use subtrees with
53
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.
54
93
55
94
Changes to take advantage
56
95
-------------------------
57
96
58
-
.. TODO:: DZ: finish this up...
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