[WIP] Packs documentation #312

emedvedev · 2016-11-11T15:51:34Z

This is honestly way bigger docs change than I anticipated, with st2contrib references and all, so I'll upload everything in chunks.

LindsayHill · 2016-11-11T15:57:11Z

docs/source/packs.rst

@@ -6,114 +6,182 @@ What is a Pack?
 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>`, :doc:`Aliases <chatops/aliases>`.

-It is best to view a pack as the means to extend |st2| and allow it to integrate with an external systems. See `next section` to learn more about pack management.
+It is best to view a pack as the means to extend |st2| and allow it to integrate with an external systems. Everything you create will also be part of a pack.


I would say "...integrate with external systems."

LindsayHill · 2016-11-11T15:58:36Z

docs/source/packs.rst

+
+|st2| packs are managed through ``st2 pack ...`` commands: ``st2 pack -h`` will give you a useful overview if you just need a quick start.
+
+A few packs (such as the ``core`` pack for basic StackStorm actions) come pre-installed with StackStorm. ``list`` and ``get`` are primary commands to work with local packs:


slight change - "...list and get are the primary commands to work with local packs"

humblearner · 2016-11-15T23:04:09Z

docs/source/chatops/notifications.rst

@@ -4,7 +4,7 @@ Notifications
 If you read through the :ref:`ref-chatops` section, you are familiar with notifications.
 Even without ChatOps, notifications can be used to post messages to external systems
 like Chat clients, send emails etc. Notifications require an action that is registered with
-|st2| (e.g., the `post_message <https://github.com/StackStorm/st2contrib/blob/master/packs/slack/actions/post_message.yaml>`_ action in the the ``slack`` pack)
+|st2| (e.g., the `post_message <https://github.com/StackStorm-Exchange/slack/tree/master/actions/post_message.yaml>`_ action in the the ``slack`` pack)


s/slack/stackstorm-slack

humblearner · 2016-11-16T00:07:20Z

Can we add a section for backward compatibility ?
Example: setup virtual_env, pack.install without subtree etc..

Also, a note that we don't support subtree.

LindsayHill · 2016-11-16T18:05:53Z

Looking at those test failures, the problem is that we have a couple of extra things in st2contrib/extra. We changed that macro to point to exchange, but we've still got a couple of github_contrib references left. Maybe we should move those example syslog + logstash configs to another repo?

# Conflicts: # docs/source/upgrade_notes.rst

… notes" section

LindsayHill · 2016-11-23T20:13:43Z

well there we go, all checks passed.

We may want to include /reference/exchange.rst in /reference/index.rst, but it will be OK left out for now. Can review structure once we've finished the new packs docs

dzimine · 2016-11-24T02:49:46Z

docs/source/reference/packs.rst

@@ -149,18 +149,18 @@ Copy the following content to policies/policy1.yaml

 .. literalinclude:: /../../st2/contrib/hello_st2/policies/policy1.yaml

-7. Deploy this pack manually:
+7. Install this pack manually. Your pack should be versioned in git for this step to work.


Your pack should be versioned in git for this step to work.
Than we should have had it as a step. Besides, copy will continue to work. We need to think through the proper flow and describe it. I mean:

if I first git init, then install, THEN try to run it the first time, most likely (certainly) something won't work, I edit, then what? install again?

if I copy first, work with this till I am happy in place, than git init and push to github?

or we leave it up to the user here to figure out their flow (e.g., mounts, symlinks, rsync, etc.), just as it was before.

or we leave it up to the user here to figure out their flow (e.g., mounts, symlinks, rsync, etc.), just as it was before.

I would leave up to the user, that's why there's just "your pack should be versioned with git." We've discussed this with Kirill, actually: while I wouldn't mind being more descriptive, we'll just end up teaching people how to use git, and that's just not what we want. :)

dzimine · 2016-11-24T02:50:46Z

docs/source/reference/packs.rst

-   # Create virtual environment for hello_st2.
-   st2 run packs.setup_virtualenv packs=hello_st2
+   # If hello_st2 is hosted on github.
+   st2 pack install https://github.com/<your pack URL>


same here: the story breaks, it can not be on github if user has follows instructions above.

dzimine · 2016-11-24T03:03:03Z

docs/source/upgrade_notes.rst

+* Support for ``.gitinfo`` file has been removed and as such ``packs.info`` action has also been
+  removed. All the local pack directories are now direct git checkouts of the corresponding pack
+  repositories so this file is not needed anymore.
+


Because st2 run packs.install subtree=True is not mentioned here, I worry what else is missed?

Suggest we consolidate all pack-related changes for good readibility, give a brief but complete description here, and leverage "transition to new pack" document, /reference/exchange.

StackStorm Exchange and st2contrib should be links.

dzimine · 2016-11-24T03:51:39Z

docs/source/reference/exchange.rst

@@ -0,0 +1,44 @@
+:orphan:


I am thinking make it "Pack management migration" or like this; and reserve StackStorm exchange for a permanent doc entry about the exchange, how it works, etc.

some of the stuff here will live, and some only live for 1 version.

lakshmi-kannan · 2016-11-24T03:54:51Z

docs/source/packs.rst

+
+.. note::
+
+    Everything about packs got better and easier in |st2| 2.1! Packs are naturally growing into a full package management solution inside |st2|. There are new API endpoints, CLI commands, repository 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>`.


package management is incorrect. I'd skip that sentence entirely.

lakshmi-kannan · 2016-11-24T03:56:19Z

docs/source/packs.rst

-The integration packs often require configurations 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. The installation process is:
+    st2 pack install cloudflare=77ee04e
+    st2 pack install cloudflare=0.1.0
+    st2 pack install https://github.com/emedvedev/chatops-training=testing


Missing #. URL should be https://github.com/emedvedev/chatops-training#=testing

Mmm. Why exactly? https://github.com/emedvedev/chatops-training=training is not a url, it's a [pack]=[version] with pack name as url and tag\branch as version. [pack]#[version] might have worked as url in some scenarios, but the team decided # is not a good delimiter for that purpose.

lakshmi-kannan · 2016-11-24T03:57:02Z

docs/source/packs.rst


-.. note:: Pack management is implemented as a pack of st2 actions. Check out :github_st2:`/opt/stackstorm/packs </contrib/packs>` for examples of defining actions and workflows.
+Packs may contain automation rules. Rules are not loaded by default, because you may want to review and adjust them before loading. Use ``st2 pack register`` to register rules in the pack.


st2ctl now loads rules by default. Why is it different here?

bigmstone

I saw nothing glaring to add. LGTM.

emedvedev added 2 commits November 11, 2016 22:28

Update pack docs

3b5f757

Refinements

c440961

LindsayHill reviewed Nov 11, 2016

View reviewed changes

Kami and others added 3 commits November 11, 2016 17:41

Update upgrade notes.

878cd6a

Fix most of the contrib references

45c9713

Fix @LindsayHill's comments

18cc330

humblearner reviewed Nov 15, 2016

View reviewed changes

arm4b mentioned this pull request Nov 20, 2016

LWRP for st2 pack install StackStorm/chef-stackstorm#43

Open

8 tasks

Kirill Izotov and others added 5 commits November 23, 2016 14:40

Bring back dontrib reference and fix a typo

d4176b0

Merge remote-tracking branch 'origin/master' into packs-docs

8057b10

# Conflicts: # docs/source/upgrade_notes.rst

Fix the installation step for "working with packs"

ec0265c

Add the new page for migration notes and reference it in the "upgrade…

d85b184

… notes" section

added orphan to reference/exchange so tests pass

2b14ecc

dzimine reviewed Nov 24, 2016

View reviewed changes

lakshmi-kannan reviewed Nov 24, 2016

View reviewed changes

emedvedev added 4 commits November 29, 2016 01:54

Addressing comments

020ddd1

ChatOps section

c1b807b

Fix the new image links

cf43e79

Remove extra deploy reference

1880d85

emedvedev merged commit 6a81435 into master Nov 28, 2016

bigmstone reviewed Nov 28, 2016

View reviewed changes

dzimine deleted the packs-docs branch December 6, 2016 07:09

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[WIP] Packs documentation #312

[WIP] Packs documentation #312

emedvedev commented Nov 11, 2016 •

edited

LindsayHill Nov 11, 2016

LindsayHill Nov 11, 2016

humblearner Nov 15, 2016

humblearner commented Nov 16, 2016

LindsayHill commented Nov 16, 2016

LindsayHill commented Nov 23, 2016

dzimine Nov 24, 2016 •

edited by enykeev

emedvedev Nov 24, 2016

dzimine Nov 24, 2016

dzimine Nov 24, 2016

dzimine Nov 24, 2016

lakshmi-kannan Nov 24, 2016

lakshmi-kannan Nov 24, 2016

enykeev Nov 24, 2016

lakshmi-kannan Nov 24, 2016

bigmstone left a comment


		\|st2\| packs are managed through ``st2 pack ...`` commands: ``st2 pack -h`` will give you a useful overview if you just need a quick start.

		A few packs (such as the ``core`` pack for basic StackStorm actions) come pre-installed with StackStorm. ``list`` and ``get`` are primary commands to work with local packs:


		.. note::

		Everything about packs got better and easier in \|st2\| 2.1! Packs are naturally growing into a full package management solution inside \|st2\|. There are new API endpoints, CLI commands, repository 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>`.


		.. note:: Pack management is implemented as a pack of st2 actions. Check out :github_st2:`/opt/stackstorm/packs </contrib/packs>` for examples of defining actions and workflows.
		Packs may contain automation rules. Rules are not loaded by default, because you may want to review and adjust them before loading. Use ``st2 pack register`` to register rules in the pack.

[WIP] Packs documentation #312

[WIP] Packs documentation #312

Conversation

emedvedev commented Nov 11, 2016 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

humblearner commented Nov 16, 2016

LindsayHill commented Nov 16, 2016

LindsayHill commented Nov 23, 2016

dzimine Nov 24, 2016 • edited by enykeev

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bigmstone left a comment

Choose a reason for hiding this comment

emedvedev commented Nov 11, 2016 •

edited

dzimine Nov 24, 2016 •

edited by enykeev