Skip to content

Deprecate mistral in reference chapter #1010

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
arm4b merged 6 commits into from
Aug 20, 2020
Merged

Deprecate mistral in reference chapter #1010

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9cd24af
Remove mistral & postgres from the HA deployment docs
winem Aug 13, 2020
9a38f1c
deprecate mistral in the jinja.rst
winem Aug 13, 2020
4371334
deprecate mistral in the monitoring.rst
winem Aug 13, 2020
e9da3e0
deprecate mistral in the runners.rst
winem Aug 13, 2020
29c788d
Remove PostgreSQL from monitoring.rst
winem Aug 13, 2020
b6c5bc9
Merge branch 'master' into deprecate-mistral-in-reference-chapter
winem Aug 20, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 23 additions & 101 deletions docs/source/reference/ha.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,8 +179,9 @@ have failed to be scheduled by a failed ``st2scheduler`` instance.

st2resultstracker
^^^^^^^^^^^^^^^^^
Tracks results of execution handed over to Mistral. It requires access to MongoDB and RabbitMQ to
perform its function.
Tracks results of execution handed over to Orquesta or 3rd pary intergations that implement the
result tracker to provide the results. It requires access to MongoDB and RabbitMQ to perform its
function.

Multiple ``st2resultstracker`` processes will co-operate with each other to perform work. At
startup there is a possibility of extra work however there are no negative consequences of this
Expand Down Expand Up @@ -210,27 +211,6 @@ By design it is a singleton process. Running multiple instances in active-active
much benefit, but will not do any harm. The ideal configuration is active-passive but |st2| itself
does not provide the ability to run this in active-passive.


mistral-api
^^^^^^^^^^^
Mistral API is served by this aptly named process. It needs access to PostgreSQL and RabbitMQ.

Multiple ``mistral-api`` processes can run in an active-active configuration by using a load
balancer to distribute at its front end. This is similar to ``st2api``. In a typical single box
deployment ``mistral-api`` is local to the box and |st2| communicates via a direct HTTP connection.
For HA setup we recommend putting ``mistral-api`` behind a load balancer and setting up |st2| to
communicate via the load balancer.

mistral-server
^^^^^^^^^^^^^^
``mistral-server`` is the worker engine for mistral i.e. the process which actually manages
executions. The |st2| plugin to mistral (``st2mistral``) communicates back to the |st2| API. This
process needs access to PostgreSQL and RabbitMQ.

Multiple ``mistral-server`` processes can run and co-ordinate work in an active-active
configuration. In an HA deployment all communication with the |st2| API must be via the configured
load balancer.

Required Dependencies
---------------------
This section has some HA recommendations for the dependencies required by |st2| components. This
Expand All @@ -254,15 +234,6 @@ simply loading the content (through ``st2ctl reload --register-all`` and ``st2 k
access to old ActionExecutions will be lost but all the data of old ActionExecutions will still
be available in audit logs.

PostgreSQL
^^^^^^^^^^
Used primarily by ``mistral-api`` and ``mistral-server``. To deploy PostgreSQL in HA please see
`the PostgreSQL documentation <http://www.postgresql.org/docs/9.4/static/high-availability.html>`__.

The data stored in PostgreSQL is operational for Mistral, therefore starting from a brand new
PostgreSQL in case of loss of a cluster will bring automation services back instantly. There will
be downtime while a new DB cluster is provisioned.

RabbitMQ
^^^^^^^^
RabbitMQ is the communication hub for |st2| to co-ordinate and distribute work. See
Expand All @@ -287,8 +258,8 @@ See `this <http://redis.io/topics/sentinel>`__ to understand Redis deployments u

Nginx and Load Balancing
^^^^^^^^^^^^^^^^^^^^^^^^
An load balancer is required to reverse proxy each instance of ``st2api``, ``st2auth``,
``st2stream`` and ``mistral-api``. In the reference setup, Nginx is used for this. This server
An load balancer is required to reverse proxy each instance of ``st2api``, ``st2auth`` and
``st2stream``. In the reference setup, Nginx is used for this. This server
terminates SSL connections, shields clients from internal port numbers of various services
and only require ports 80 and 443 to be open on containers.

Expand Down Expand Up @@ -345,12 +316,11 @@ This box runs all the shared required dependencies and some |st2| components:

* Nginx as load balancer
* MongoDB
* PostgreSQL
* RabbitMQ
* st2chatops
* st2web

In practice ``MongoDB``, ``PostgreSQL`` and ``RabbitMQ`` will usually be on standalone clusters
In practice ``MongoDB`` ``RabbitMQ`` will usually be on standalone clusters
managed outside of |st2|. The two shared components (``st2chatops`` and ``st2web``) are placed here
for the sake of convenience. They could be placed anywhere with the right configuration.

Expand All @@ -367,18 +337,13 @@ Follow these steps to provision a controller box on Ubuntu 16.04:
Install Required Dependencies
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Install ``MongoDB``, ``PostgreSQL`` and ``RabbitMQ``:
1. Install ``MongoDB`` and ``RabbitMQ``:

.. code-block:: bash

$ sudo apt-get install -y mongodb-server rabbitmq-server postgresql
$ sudo apt-get install -y mongodb-server rabbitmq-server


2. Fix the listen address in ``/etc/postgresql/9.3/main/postgresql.conf`` and have PostgreSQL
listen on an interface that has an IP address reachable from ``st2-multi-node-1`` and
``st2-multi-node-2``.

3. Fix ``bind_ip`` in ``/etc/mongodb.conf`` to bind MongoDB to an interface that has an IP address
2. Fix ``bind_ip`` in ``/etc/mongodb.conf`` to bind MongoDB to an interface that has an IP address
reachable from ``st2-multi-node-1`` and ``st2-multi-node-2``.

4. Restart MongoDB:
Expand All @@ -387,47 +352,25 @@ Install Required Dependencies

$ sudo service mongodb restart

5. Add an ACL rule to ``/etc/postgresql/9.3/main/pg_hba.conf``. In this example we're allowing
access from the subnet ``10.0.3.0/24``

.. code-block:: bash

host all all 10.0.3.0/24 trust

6. Restart PostgreSQL:

.. code-block:: bash

$ sudo service postgresql restart

7. Create Mistral DB in PostgreSQL:

.. code-block:: bash

$ cat << EHD | sudo -u postgres psql
CREATE ROLE mistral WITH CREATEDB LOGIN ENCRYPTED PASSWORD 'StackStorm';
CREATE DATABASE mistral OWNER mistral;
EHD

8. Add stable |st2| repos:
5. Add stable |st2| repos:

.. code-block:: bash

$ curl -s https://packagecloud.io/install/repositories/StackStorm/stable/script.deb.sh | sudo bash

9. Setup ``st2web`` and SSL termination. Follow :ref:`install webui and setup
6. Setup ``st2web`` and SSL termination. Follow :ref:`install webui and setup
ssl<ref-install-webui-ssl-deb>`. You will need to stop after removing the default Nginx config
file.

10. A sample configuration for Nginx as load balancer for the controller box is provided below.
With this configuration Nginx will load balance all requests between the two blueprint boxes
``st2-multi-node-1`` and ``st2-multi-node-2``. This includes requests to ``st2api``,
``st2auth`` and ``mistral-api``. Nginx also serves as the webserver for ``st2web``.
7. A sample configuration for Nginx as load balancer for the controller box is provided below.
With this configuration Nginx will load balance all requests between the two blueprint boxes
``st2-multi-node-1`` and ``st2-multi-node-2``. This includes requests to ``st2api`` and
``st2auth``. Nginx also serves as the webserver for ``st2web``.

.. literalinclude:: /../../st2/conf/HA/nginx/st2.conf.controller.sample
:language: none

11. Create the st2 logs directory and the st2 user:
8. Create the st2 logs directory and the st2 user:

.. code-block:: bash

Expand All @@ -449,38 +392,20 @@ also be made to offer different services.

$ curl -s https://packagecloud.io/install/repositories/StackStorm/stable/script.deb.sh | sudo bash

2. Install all |st2| components and mistral:
2. Install all |st2| components:

.. code-block:: bash

$ sudo apt-get install -y st2 st2mistral
$ sudo apt-get install -y st2

3. Install Nginx:

.. code-block:: bash

$ sudo apt-get install -y nginx

4. Update Mistral connection to PostgreSQL in ``/etc/mistral/mistral.conf`` by changing the
``database.connection`` property.

5. Update Mistral connection to RabbitMQ in ``/etc/mistral/mistral.conf`` by changing the
``default.transport_url`` property.

6. Setup Mistral database:

.. code-block:: bash

$ /opt/stackstorm/mistral/bin/mistral-db-manage --config-file /etc/mistral/mistral.conf upgrade head

7. Register mistral actions:

.. code-block:: bash

$ /opt/stackstorm/mistral/bin/mistral-db-manage --config-file /etc/mistral/mistral.conf populate | grep -v -e openstack -e keystone

8. Replace ``/etc/st2/st2.conf`` with the sample ``st2.conf`` provided below. This config points to
the controller node or configuration values of ``database``, ``messaging`` and ``mistral``.
the controller node or configuration values of ``database`` and ``messaging``.

.. literalinclude:: /../../st2/conf/HA/st2.conf.sample
:language: ini
Expand All @@ -494,22 +419,19 @@ also be made to offer different services.
-days XXX -nodes -subj "/C=US/ST=California/L=Palo Alto/O=StackStorm/OU=Information \
Technology/CN=$(hostname)"

10. If you are using self-signed certificates you will need to add ``insecure = true`` to the
``mistral`` section of ``/etc/st2/st2.conf``.

11. Configure users & authentication as per :ref:`this documentation<ref-config-auth-deb>`. Make
10. Configure users & authentication as per :ref:`this documentation<ref-config-auth-deb>`. Make
sure that user configuration on all boxes running ``st2auth`` is identical. This ensures
consistent authentication from the entire |st2| install since the request to authenticate a
user can be forwarded by the load balancer to any of the ``st2auth`` processes.

12. Use the sample Nginx config that is provided below for the blueprint boxes. In this config
11. Use the sample Nginx config that is provided below for the blueprint boxes. In this config
Nginx will act as the SSL termination endpoint for all the REST endpoints exposed by
``st2api``, ``st2auth`` and ``mistral-api``:
``st2api`` and ``st2auth``:

.. literalinclude:: /../../st2/conf/HA/nginx/st2.conf.blueprint.sample
:language: nginx

13. To use Timer triggers with Mistral, enable them on only one server. Make this change in
12. To use Timer triggers, enable them on only one server. Make this change in
``/etc/st2/st2.conf``:

.. code-block:: yaml
Expand Down
20 changes: 2 additions & 18 deletions docs/source/reference/jinja.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ more information on accessing key-value pairs from Actions see:
:ref:`Referencing Key-Value Pairs in Action Definitions<referencing-key-value-pairs-in-action-definitions>`

Accessing ``numbers``, ``integers``, ``objects`` and ``arrays`` in other places,
such as Mistral workflows, utilizing ``from_json_string`` is still necessary.
such as workflows, utilizing ``from_json_string`` is still necessary.

.. _jinja-jinja-filters:

Expand Down Expand Up @@ -66,10 +66,6 @@ templates/#builtin-filters>`_ available in Jinja, |st2| also comes with some cus

**For Developers:** These filters are defined in
:github_st2:`st2/st2common/st2common/expressions/functions <st2common/st2common/expressions/functions>`.
The equivalent Mistral filters are located in the ``st2mistral`` repo at
:github_st2mistral:`st2mistral/st2mistral/functions/ <st2mistral/functions/>`.
To ensure filters maintain parity across StackStorm workflows, changes to one location must be
replicated to the other in a separate PR.

For brevity, only simple Jinja patterns for each filter are documented below. "Real-world" usage
will depend on the type of content where the filters are being applied (sensors, triggers, rules,
Expand All @@ -78,21 +74,9 @@ in the ``examples`` pack:
:github_st2:`st2/contrib/examples/actions/chains/ <contrib/examples/actions/chains/>`.

.. TODO We should consider separating each specific usage into individual ActionChains and refer to
it using literalinclude (i.e. .. literalinclude:: /../../st2/contrib/examples/actions/workflows/mistral-jinja-branching.yaml)
it using literalinclude (i.e. .. literalinclude:: /../../st2/contrib/examples/actions/workflows/orquesta-join.yaml)
so we can just use the code as the source of truth. Then, we can remove the above note.

In |st2| 2.4, all custom filters were made available to Mistral workflows as well, with one notable
exception: the ``decrypt_kv`` filter. That filter is not necessary in Mistral, as the ``st2kv``
function in Mistral workflows natively supports decryption via the ``decrypt`` parameter.

.. note::

Because of a bug in Mistral, these filters do not currently support the "pipe" operator filter
format (`|`) So, instead of ``'{{ _.input_str | regex_match(_.regex_pattern) }}'`` you would
call the filter like a regular function, moving the previously input value into the first
positional argument position: ``'{{ regex_match(_.input_str, _.regex_pattern) }}'``. This will
be addressed in a future release.

from_json_string
~~~~~~~~~~~~~~~~

Expand Down
5 changes: 0 additions & 5 deletions docs/source/reference/monitoring.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,10 +58,6 @@ You can use ``sudo st2ctl status`` to get a quick overview of current process st
st2timersengine PID: 925
st2sensorcontainer PID: 907
st2chatops is not running.
mistral-server PID: 1031
mistral.api PID: 1006
mistral.api PID: 1228
mistral.api PID: 1231
$

In a distributed system, only some of these processes will be running on each system. In the
Expand All @@ -78,7 +74,6 @@ system should account for this behavior.
Additional processes to monitor:

* RabbitMQ - ``rabbitmq-server``
* PostgreSQL - ``postgres``
* MongoDB - ``mongod``
* Nginx (if used for web/API frontend) - ``nginx``
* Postfix/Sendmail (if local mail relay configured)
Expand Down