From e58f80d94d476cbc3d1397b39f2dc3b6eb2f65c9 Mon Sep 17 00:00:00 2001 From: Vitalii Solodilov Date: Tue, 1 May 2018 23:07:29 +0400 Subject: [PATCH] Purge README.rst in favor of the generated documentation Change-Id: I805f680a48730da4698eb56032c5d2f74a7ca7d7 Closes-bug: #1735690 Signed-off-by: Vitalii Solodilov --- README.rst | 228 ++--------------------------------------------------- 1 file changed, 6 insertions(+), 222 deletions(-) diff --git a/README.rst b/README.rst index f3e0b3bd0..bab54142e 100644 --- a/README.rst +++ b/README.rst @@ -12,233 +12,17 @@ Workflow Service for OpenStack cloud. This project aims to provide a mechanism to define tasks and workflows without writing code, manage and execute them in the cloud environment. -Installation -~~~~~~~~~~~~ - -The following are the steps to install Mistral on debian-based systems. - -To install Mistral, you have to install the following prerequisites:: - - $ apt-get install python-dev python-setuptools libffi-dev \ - libxslt1-dev libxml2-dev libyaml-dev libssl-dev - -**Mistral can be used without authentication at all or it can work with -OpenStack.** - -In case of OpenStack, it works **only with Keystone v3**, make sure **Keystone -v3** is installed. - - -Install Mistral ---------------- - -First of all, clone the repo and go to the repo directory:: - - $ git clone https://git.openstack.org/openstack/mistral.git - $ cd mistral - - -**Devstack installation** - -Information about how to install Mistral with devstack can be found -`here `_. - -Configuring Mistral -~~~~~~~~~~~~~~~~~~~ - -Mistral configuration is needed for getting it work correctly with and without -an OpenStack environment. - -#. Install and configure a database which can be *MySQL* or *PostgreSQL* - (**SQLite can't be used in production.**). Here are the steps to connect - Mistral to a *MySQL* database. - - * Make sure you have installed ``mysql-server`` package on your Mistral - machine. - * Install *MySQL driver* for python:: - - $ pip install mysql-python - - or, if you work in virtualenv, run:: - - $ tox -evenv -- pip install mysql-python - - NOTE: If you're using Python 3 then you need to install ``mysqlclient`` - instead of ``mysql-python``. - - * Create the database and grant privileges:: - - $ mysql -u root -p - mysql> CREATE DATABASE mistral; - mysql> USE mistral - mysql> GRANT ALL PRIVILEGES ON mistral.* TO 'mistral'@'localhost' \ - IDENTIFIED BY 'MISTRAL_DBPASS'; - mysql> GRANT ALL PRIVILEGES ON mistral.* TO 'mistral'@'%' IDENTIFIED BY 'MISTRAL_DBPASS'; - -#. Generate ``mistral.conf`` file:: - - $ oslo-config-generator --config-file tools/config/config-generator.mistral.conf \ - --output-file etc/mistral.conf.sample - -#. Copy service configuration files:: - - $ sudo mkdir /etc/mistral - $ sudo chown `whoami` /etc/mistral - $ cp etc/event_definitions.yml.sample /etc/mistral/event_definitions.yml - $ cp etc/logging.conf.sample /etc/mistral/logging.conf - $ cp etc/policy.json /etc/mistral/policy.json - $ cp etc/wf_trace_logging.conf.sample /etc/mistral/wf_trace_logging.conf - $ cp etc/mistral.conf.sample /etc/mistral/mistral.conf - -#. Edit file ``/etc/mistral/mistral.conf`` according to your setup. Pay attention - to the following sections and options:: - - [DEFAULT] - # driver://[user:pass@]host:port[,[userN:passN@]hostN:portN]/virtual_host?query - transport_url = rabbit://guest:guest@localhost:5672// - - [database] - # Use the following line if *PostgreSQL* is used - # connection = postgresql://:@localhost:5432/mistral - connection = mysql://:@localhost:3306/mistral - -#. If you are not using OpenStack, add the following entry to the - ``/etc/mistral/mistral.conf`` file and **skip the following steps**:: - - [pecan] - auth_enable = False - -#. Provide valid keystone auth properties:: - - [keystone_authtoken] - auth_uri = http://keystone-host:port/v3 - auth_url = http://keystone-host:port - auth_type = password - username = - password = - user_domain_name = - project_name = - project_domain_name = - -#. Register Mistral service and Mistral endpoints on Keystone:: - - $ MISTRAL_URL="http://[host]:[port]/v2" - $ openstack service create --name mistral workflowv2 - $ openstack endpoint create mistral public $MISTRAL_URL - $ openstack endpoint create mistral internal $MISTRAL_URL - $ openstack endpoint create mistral admin $MISTRAL_URL - -#. Update the ``mistral/actions/openstack/mapping.json`` file which contains - all available OpenStack actions, according to the specific client versions - of OpenStack projects in your deployment. Please find more detailed - information in the ``tools/get_action_list.py`` script. - -Before the First Run --------------------- - -After local installation you will find the commands ``mistral-server`` and -``mistral-db-manage`` available in your environment. The ``mistral-db-manage`` -command can be used for migrating database schema versions. If Mistral is not -installed in system then this script can be found at -``mistral/db/sqlalchemy/migration/cli.py``, it can be executed using Python -command line. - -To update the database schema to the latest revision, type:: - - $ mistral-db-manage --config-file upgrade head - -To populate the database with standard actions and workflows, type:: - $ mistral-db-manage --config-file populate - -For more detailed information about ``mistral-db-manage`` script please check -file ``mistral/db/sqlalchemy/migration/alembic_migrations/README.md``. - -Running Mistral API server --------------------------- - -To run Mistral API server:: - - $ tox -evenv -- python mistral/cmd/launch.py --server api --config-file - -Running Mistral Engines ------------------------ - -To run Mistral Engine:: - - $ tox -evenv -- python mistral/cmd/launch.py --server engine --config-file - -Running Mistral Task Executors ------------------------------- - -To run Mistral Task Executor instance:: - - $ tox -evenv -- python mistral/cmd/launch.py --server executor --config-file - -Note that at least one Engine instance and one Executor instance should be -running in order for workflow tasks to be processed by Mistral. - -If you want to run some tasks on specific executor, the *task affinity* feature -can be used to send these tasks directly to a specific executor. You can edit -the following property in your mistral configuration file for this purpose:: - - [executor] - host = my_favorite_executor - -After changing this option, you will need to start (restart) the executor. Use -the ``target`` property of a task to specify the executor:: - - ... Workflow YAML ... - task1: - ... - target: my_favorite_executor - ... Workflow YAML ... - -Running Multiple Mistral Servers Under the Same Process -------------------------------------------------------- - -To run more than one server (API, Engine, or Task Executor) on the same -process:: - - $ tox -evenv -- python mistral/cmd/launch.py --server api,engine --config-file - -The value for the ``--server`` option can be a comma-delimited list. The valid -options are ``all`` (which is the default if not specified) or any combination -of ``api``, ``engine``, and ``executor``. - -It's important to note that the ``fake`` transport for the ``rpc_backend`` -defined in the configuration file should only be used if ``all`` Mistral -servers are launched on the same process. Otherwise, messages do not get -delivered because the ``fake`` transport is using an in-process queue. - -Project Goals 2018 ------------------- - -#. **Complete Mistral documentation**. - - Mistral documentation should be more usable. It requires focused work to - make it well structured, eliminate gaps in API/Mistral Workflow Language - specifications, add more examples and tutorials. - - *Definition of done*: - All capabilities are covered, all documentation topics are written using - the same style and structure principles. The obvious sub-goal of this goal - is to establish these principles. - -#. **Finish Mistral multi-node mode**. - - Mistral needs to be proven to work reliably in multi-node mode. In order - to achieve it we need to make a number of engine, executor and RPC - changes and configure a CI gate to run stress tests on multi-node Mistral. - - *Definition of done*: - CI gate supports MySQL, all critically important functionality (join, - with-items, parallel workflows, sequential workflows) is covered by tests. - Project Resources ----------------- * `Mistral Official Documentation `_ + * `Installation Guide `_ + + * `Configuration Guide `_ + + * `Workflow Language Specification `_ + * Project status, bugs, and blueprints are tracked on `Launchpad `_