Merge "Create docs for the workflow namespaces feature"

doc/source/index.rst

@@ -34,6 +34,13 @@ User guide
    install/index
    configuration/index
 
+**Mistral features**
+
+.. toctree::
+   :maxdepth: 1
+
+   user/wf_namespaces
+
 **API**
 
 .. toctree::

doc/source/main_features.rst

@@ -333,3 +333,13 @@ or ``evaluation_interval`` options.
 
  Defines the maximum number of finished executions.
  It must be greater or equal to ``1``.
+
+
+Workflow namespaces
+-------------------
+
+Mistral allows creating workflows within a namespace. So it is possible to
+create many workflows with the same name as long as they are in different
+namespaces.
+
+See more at :doc:`Workflow namespaces <user/wf_namespaces>`

doc/source/user/wf_namespaces.rst

@@ -0,0 +1,195 @@
+Workflow namespaces
+===================
+
+General
+-------
+Mistral allows creating workflows within a namespace. So it is possible to
+create many workflows with the same name as long as they are in different
+namespaces. This is useful when a user already has many workflows that are
+connected to each other (some are sub workflows of others) and one of the
+workflow names is already in use and the user does not want to edit that
+workflow and all the ones referencing it or combine them into a workbook.
+This is possible because the namespace is not a part of the Mistral workflow
+language.
+
+If one wants to use a namespace she needs to provide an additional parameter
+to a corresponding operation run via REST API or CLI. If it's not provided,
+Mistral will be operating within the default namespace.
+
+
+REST API parameters
+-------------------
+
+In order to use namespaces Mistral a number of REST API methods have the
+optional **namespace** parameter:
+
+  * create workflow definition within a namespace::
+
+        POST /v2/workflows?namespace=<namespace>
+
+        <Workflow YAML text>
+
+  * delete workflow definition within a namespace::
+
+        DELETE /v2/workflows/<workflow id>?namespace=<namespace>
+
+  * get a workflow definition within a namespace::
+
+        GET /v2/workflows/<workflow id>?namespace=<namespace>
+
+  * get all workflow definitions within a given namespace::
+
+        GET /v2/workflows?namespace=<namespace>
+
+  * update a workflow definition within a given namespace::
+
+        PUT /v2/workflows?namespace=<namespace>
+
+        <Workflow YAML text>
+
+  * create an execution of a workflow that belongs to a non-default namespace::
+
+        POST /v2/executions
+
+        {
+          "workflow_name": "<workflow id or name>",
+          "workflow_namespace": "<namespace>",
+          ...
+        }
+
+Resolving a workflow definition
+-------------------------------
+
+It's important to understand how Mistral resolves a workflow definition taking
+namespaces into account when running workflows and how namespaces work in case
+of workflow hierarchies.
+
+The rules are the following:
+
+  * If a user launches a workflow via API (or CLI) then the workflow name
+    and the corresponding namespace are provided explicitly so Mistral
+    will look for a workflow definition with the given name under the provided
+    namespace. If a namespace is not specified then the default namespace
+    (empty namespace value) will be used. If Mistral doesn't find a workflow
+    definition with the given name and namespace it will return an error
+    response.
+  * If a workflow is launched as a sub workflow, i.e. it has a parent task
+    in a different workflow, then Mistral uses the namespace of the parent
+    workflow to resolve a workflow definition. In other words, Mistral
+    propagates namespace to its child workflows. However, **if a workflow
+    definition does not exist in the namespace of the parent workflow then
+    Mistral will try to find it in the default namespace.** This is different
+    from the previous case when a workflow is launched via API, Mistral would
+    return an error instead of trying to find a workflow definition in the
+    default namespace.
+  * Workflows declared as part of workbooks are always located in the default
+    namespace.
+
+To illustrate how this all works let's look at the following workflow
+definitions:
+
+  .. code-block:: mistral
+
+    ---
+    version: '2.0'
+
+    wf1:
+      tasks:
+        t1:
+          workflow: wf2
+
+
+  .. code-block:: mistral
+
+    ---
+    version: '2.0'
+
+    wf2:
+      tasks:
+        t2:
+          workflow: wf3
+
+  .. code-block:: mistral
+
+    ---
+    version: '2.0'
+
+    wf3:
+      tasks:
+        t3:
+          action: std.noop
+
+  .. code-block:: mistral
+
+    ---
+    version: '2.0'
+
+    wf3:
+      tasks:
+        should_not_run:
+          action: std.fail
+
+So the call chain looks like this:
+
+  .. code-block::
+
+   wf1 -> wf2 -> wf3
+
+However, notice that we have two workflows with the name "wf3".
+
+Let's assume that these workflow definitions are uploaded to Mistral under
+these namespaces:
+
+  +----+---------------------+-----------+
+  | ID | name                | namespace |
+  +----+---------------------+-----------+
+  | 1  | wf1                 | abc       |
+  +----+---------------------+-----------+
+  | 2  | wf2                 |           |
+  +----+---------------------+-----------+
+  | 3  | wf3                 | abc       |
+  +----+---------------------+-----------+
+  | 4  | wf3                 |           |
+  +----+---------------------+-----------+
+
+And we create a workflow execution like this via API:
+
+  .. code-block::
+
+    POST /v2/executions
+
+    {
+      "workflow_name": "wf1",
+      "workflow_namespace": "abc"
+    }
+
+
+In this case, Mistral will:
+
+  * Find "wf1" in the namespace "abc" (it doesn't exist in the default
+    namespace anyway)
+  * Try to find "wf2" in the namespace "abc" and since it doesn't exist
+    there Mistral will find it in the default namespace
+  * Find "wf3" in the namespace "abc" because it is propagated from "wf1"
+
+
+However, if we launch a workflow like this:
+
+  .. code-block::
+
+    POST /v2/executions
+
+    {
+      "workflow_name": "wf2"
+    }
+
+
+We'll get the call chain
+
+  .. code-block::
+
+   wf2 -> wf3
+
+
+And both workflow definitions will be taken from the default namespace
+because a non-default namespace wasn't provided to the endpoint.