diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst index 68b08edd3..d6fcd8e59 100644 --- a/doc/source/configuration/index.rst +++ b/doc/source/configuration/index.rst @@ -1,9 +1,9 @@ Mistral Configuration and Policy Guide --------------------------------------- +====================================== .. toctree:: - :maxdepth: 2 + :maxdepth: 2 - config-guide.rst - policy-guide.rst - samples/index.rst + ../configuration/config-guide.rst + ../configuration/policy-guide.rst + ../configuration/samples/index.rst diff --git a/doc/source/install/get_started.rst b/doc/source/install/get_started.rst new file mode 100644 index 000000000..ad9326bc5 --- /dev/null +++ b/doc/source/install/get_started.rst @@ -0,0 +1,37 @@ +================================= +Workflow service overview +================================= + +Mistral is a workflow service that enables setting up and scheduling tasks and +task relations that have to be executed in a particular order, called workflows. +During execution, Mistral handles state management, correct execution order, +parallelism, synchronization and high availability. + +Mistral can be used, for example, for Cloud Cron-style task scheduling, +Cloud Environment Deployment, handling long-running business processes, managing +BigData analysis and tasks, and live migration. + +The Workflow service consists of the following components: + +``Mistral API`` service + Provides a REST API for operating and monitoring workflow executions. + +``mistral-dashboard`` service + Mistral Dashboard is a Horizon plugin. + +``Mistral Engine`` service + Controls workflow executions and handles their data flow, places finished + tasks in a queue, transfers data from task to task, and deals with condition + transitions, and so on. + +``Mistral Executor`` service + Executes task actions, picks up the tasks from the queue, runs actions, and + sends results back to the engine. + +``Mistral Notifier`` service + +``python-mistralclient`` + Python client API and Command Line Interface. + + ``mistral-lib`` + A library to support writing custom Mistral actions. diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index c1380d1c9..a8ea283c5 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -2,8 +2,19 @@ Mistral Installation Guide ========================== .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - installation_guide + get_started.rst + install.rst + verify.rst + next-steps.rst dashboard_guide + installation_guide mistralclient_guide + +The Workflow service (mistral) enables setting up task relations that have to be + executed in a particular order, called workflows. + +This chapter assumes a working setup of OpenStack following the +`OpenStack Installation Tutorial +`_. diff --git a/doc/source/install/install-obs.rst b/doc/source/install/install-obs.rst new file mode 100644 index 000000000..c058eb1ef --- /dev/null +++ b/doc/source/install/install-obs.rst @@ -0,0 +1,10 @@ +.. _install-obs: + + +Install and configure for openSUSE and SUSE Linux Enterprise +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For information on how to install and configure the Workflow service +for openSUSE and SUSE Linux Enterprise, refer to the :doc:`Installation guide +for Ubuntu `. Note that some commands vary by distribution and +might differ from the ones described, for instance, package management. diff --git a/doc/source/install/install-rdo.rst b/doc/source/install/install-rdo.rst new file mode 100644 index 000000000..cd7353e03 --- /dev/null +++ b/doc/source/install/install-rdo.rst @@ -0,0 +1,10 @@ +.. _install-rdo: + +Install and configure for Red Hat Enterprise Linux and CentOS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +For information on how to install and configure the Workflow service +for Red Hat Enterprise Linux 7 and CentOS 7, refer to the :doc:`Installation +guide for Ubuntu `. Note that some commands vary by distribution +and might differ from the ones described, for instance, package management. diff --git a/doc/source/install/install-ubuntu.rst b/doc/source/install/install-ubuntu.rst new file mode 100644 index 000000000..961bf26cf --- /dev/null +++ b/doc/source/install/install-ubuntu.rst @@ -0,0 +1,209 @@ +.. _install-ubuntu: + +Install and configure for Ubuntu +================================ + +This section describes how to install and configure the Workflow Service +service for Ubuntu. + + + +Prerequisites +------------- + +#. Install the packages: + + .. code-block:: console + + # apt-get update + + # apt-get install python-setuptools python-pip libffi-dev libxslt1-dev \ + libxml2-dev libyaml-dev libssl-dev python3-dev tox mistral-common + + + +Installation +------------ + +**NOTE**: For instructions on how to install Mistral using devstack, refer to +:doc:`Mistral Devstack Installation ` + +Clone the repo and go to the repo directory: + +.. code-block:: console + + $ git clone https://git.openstack.org/openstack/mistral + $ cd mistral + +Generate the configuration file: + +.. code-block:: console + + $ tox -egenconfig + +Create the mistral directory and copy the example configuration file: + +.. code-block:: console + + $ mkdir /etc/mistral + $ cp etc/mistral.conf.sample /etc/mistral/mistral.conf + + +Edit the configuration file: + + .. code-block:: console + + $ vi /etc/mistral/mistral.conf + + + +**Virtualenv installation**: + +.. code-block:: console + + $ tox + +This installs the necessary virtual environments and runs all the project +tests. Installing the virtual environments may take significant time (~10-15 +mins). + +**Local installation**: + +.. code-block:: console + + $ pip install -e . + +or: + +.. code-block:: console + + $ pip install -r requirements.txt + $ python setup.py install + +**NOTE**: There are some differences between *pip install -e* and *setup.py +install*. **pip install -e** works similarly to **setup.py install** +or the EasyInstall tool, however, it does not actually install anything. +Instead, it creates a special .egg-link file in the deployment directory that +links to your project’s source code. + + +.. include:: ../configuration/index.rst + + +Before the first run +-------------------- + +After the installation, you will see the **mistral-server** and +**mistral-db-manage** commands in your environment, either in system or virtual +environment. + +**NOTE**: If you use **virtualenv**, all Mistral-related commands can be +accessed with **tox -evenv --**. For example, *mistral-server* is available via +*tox -evenv -- mistral-server*. + +The **mistral-db-manage** command can be used for migrations. + +Updating the database to the latest revision type: + +.. code-block:: console + + $ mistral-db-manage --config-file upgrade head + +Before starting the Mistral server, run the *mistral-db-manage populate* +command. It creates the DB with all the standard actions and standard workflows +that Mistral provides to all Mistral users.: + +.. code-block:: console + + $ mistral-db-manage --config-file populate + +For more detailed information on the *mistral-db-manage* script, see +the :doc:`Mistral Upgrade Guide `. + +**NOTE**: For users who want a dry run with an **SQLite** database backend (not +used in production), the *mistral-db-manage* script is not recommended for +database initialization because of +`SQLite limitations `_. +Use the sync_db script described below for database +initialization instead. + +**If you use virtualenv**: + +.. code-block:: console + + $ tools/sync_db.sh --config-file + +**Or run sync_db directly**: + +.. code-block:: console + + $ python tools/sync_db.py --config-file + +Running Mistral API server +-------------------------- + +To run the Mistral API server, execute the following command in a shell: + +.. code-block:: console + + $ mistral-server --server api --config-file + +Running Mistral Engines +----------------------- + +To run the Mistral Engine, execute the following command in a shell: + +.. code-block:: console + + $ mistral-server --server engine --config-file + +Running Mistral Executors +------------------------- +To run the Mistral Executor instance, execute the following command in a +shell: + +.. code-block:: console + + $ mistral-server --server executor --config-file + +Note that at least one Engine instance and one Executor instance should be +running so that workflow tasks are processed by Mistral. + +Mistral Notifier +---------------- + +To run the Mistral Notifier, execute the following command in a shell: + +.. code-block:: console + + $ mistral-server --server notifier --config-file + +Running Multiple Mistral Servers Under the Same Process +------------------------------------------------------- +To run more than one server (API, Engine, or Task Executor) on the same process, +execute the following command in a shell: + +.. code-block:: console + + $ mistral-server --server api,engine --config-file + +The --server command line option can be a comma delimited list. The valid +options are "all" (by default if not specified) or any combination of "api", +"engine", and "executor". It is important to note that the "fake" transport for +the rpc_backend defined in the config file should only be used if "all" the +Mistral servers are launched on the same process. Otherwise, messages do not +get delivered if the Mistral servers are launched on different processes +because the "fake" transport is using an in-process queue. + + +.. include:: mistralclient_guide.rst + + +Finalize installation +--------------------- + +Restart the Workflow services: + +.. code-block:: console + + # service openstack-mistral-api restart diff --git a/doc/source/install/install.rst b/doc/source/install/install.rst new file mode 100644 index 000000000..ee4071614 --- /dev/null +++ b/doc/source/install/install.rst @@ -0,0 +1,24 @@ +.. _install: + +Install and configure +~~~~~~~~~~~~~~~~~~~~~ + +This section describes how to install and configure the +Workflow Service, code-named mistral, on the controller node. + +**NOTE:** **Mistral can be used in standalone mode or it can work +with OpenStack.** + +If Mistral is used with OpenStack, you must already have a working OpenStack +environment with at least the following components installed: + +- Keystone with API v3 support + +Note that installation and configuration vary by distribution. + +.. toctree:: + :maxdepth: 2 + + install-ubuntu.rst + install-rdo.rst + install-obs.rst diff --git a/doc/source/install/mistralclient_guide.rst b/doc/source/install/mistralclient_guide.rst index 61e635155..b629a88dd 100644 --- a/doc/source/install/mistralclient_guide.rst +++ b/doc/source/install/mistralclient_guide.rst @@ -1,5 +1,5 @@ Mistral Client Installation Guide -================================= +--------------------------------- To install ``python-mistralclient``, it is required to have ``pip`` (in most cases). Make sure that ``pip`` is installed. Then type:: @@ -15,7 +15,7 @@ After ``python-mistralclient`` is installed you will see command ``mistral`` in your environment. Configure authentication against Keystone ------------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If Keystone is used for authentication in Mistral, then the environment should have auth variables:: @@ -43,7 +43,7 @@ To make sure Mistral client works, type:: $ mistral workbook-list Configure authentication against Keycloak ------------------------------------------ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Mistral also supports authentication against Keycloak server via OpenID Connect protocol. @@ -80,7 +80,7 @@ to True:: $ export MISTRALCLIENT_INSECURE=True Targeting non-preconfigured clouds ----------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^- Mistral is capable of executing workflows on external OpenStack clouds, different from the one defined in the `mistral.conf` file in the @@ -114,7 +114,7 @@ service. Whereas the `OS_TARGET_*` parameters are used to define the user that executes the workflow on the external cloud, keystone2.example.com/. Use cases -^^^^^^^^^ +""""""""" **Authenticate in Mistral and execute OpenStack actions with different users** @@ -126,7 +126,7 @@ cloud. As a user of Mistral, I want to execute a workflow on a cloud of my choice. Special cases -^^^^^^^^^^^^^ +""""""""""""" **Using Mistral with zero OpenStack configuration**: diff --git a/doc/source/install/next-steps.rst b/doc/source/install/next-steps.rst new file mode 100644 index 000000000..511a588c2 --- /dev/null +++ b/doc/source/install/next-steps.rst @@ -0,0 +1,9 @@ +.. _next-steps: + +Next steps +~~~~~~~~~~ + +Your OpenStack environment now includes the Mistral service. + +To add additional services, see `OpenStack Pike Installation Tutorials and +Guides `_. diff --git a/doc/source/install/verify.rst b/doc/source/install/verify.rst new file mode 100644 index 000000000..202218d70 --- /dev/null +++ b/doc/source/install/verify.rst @@ -0,0 +1,51 @@ +.. _verify: + +Basic verification +~~~~~~~~~~~~~~~~~~ + +.. code-block:: console + + $ mistral run-action std.noop + + +Verify operation of the Workflow service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: + + Perform these commands on the controller node. + +#. Create a workflow file: + + .. code-block:: console + + $ cat >/tmp/test.wf.yaml <