Merge "Document murano actions"

doc/source/draft/appdev-guide/murano_pl.rst

@@ -15,3 +15,4 @@ YAQL languages. The sections below describe these languages.
 .. include:: murano_pl/yaql.rst
 .. include:: murano_pl/class_templ.rst
 .. include:: murano_pl/core_classes.rst
+.. include:: murano_pl/actions.rst

doc/source/draft/appdev-guide/murano_pl/actions.rst

@@ -0,0 +1,77 @@
+.. _actions:
+
+.. toctree::
+   :maxdepth: 2
+
+==============
+Murano actions
+==============
+
+Murano action is a type of MuranoPL method. The differences from a regular
+MuranoPL method are:
+
+* Action is executed on deployed objects.
+* Action execution is initiated by API request, you do not have to call
+  the method manually.
+
+So murano action allows performing any operations on objects:
+
+* Getting information from the VM, like a config that is generated during the
+  deployment
+* VM rebooting
+* Scaling
+
+A list of available actions is formed during the environment deployment.
+Right after the deployment is finished, you can call action asynchronously.
+Murano engine generates a task for every action. Therefore, the action status
+can be tracked.
+
+.. note::
+ Actions may be called against any MuranoPL object, including ``Environment``,
+ ``Application``, and any other objects.
+
+To mark a method as an action, use ``Usage: Action``.
+
+The following example shows an action that returns an archive with a
+configuration file:
+
+::
+
+ exportConfig:
+     Usage: Action
+     Body:
+       - $._environment.reporter.report($this, 'Action exportConfig called')
+       - $resources: new(sys:Resources)
+       - $template: $resources.yaml('ExportConfig.template')
+       - $result: $.masterNode.instance.agent.call($template, $resources)
+       - $._environment.reporter.report($this, 'Got archive from Kubernetes')
+       - Return: new(std:File, base64Content => $result.content,
+                     filename => 'application.tar.gz')
+
+List of available actions can be found with environment details or application
+details API calls. It's located in object model special data.
+Take a look at the following example:
+
+Request:
+``http://localhost:8082/v1/environments/<id>/services/<id>``
+
+Response:
+
+.. code-block:: javascript
+
+    {
+      "name": "SimpleVM",
+      "?": {
+        "_26411a1861294160833743e45d0eaad9": {
+          "name": "SimpleApp"
+        },
+        "type": "io.murano.apps.Simple",
+        "id": "e34c317a-f5ee-4f3d-ad2f-d07421b13d67",
+        "_actions": {
+          "e34c317a-f5ee-4f3d-ad2f-d07421b13d67_exportConfig": {
+            "enabled": true,
+            "name": "exportConfig"
+          }
+        }
+      }
+    }

doc/source/specification/murano-api.rst

@@ -850,3 +850,84 @@ General Request Statistics
         }
     ]
 
+
+Actions API
+===========
+
+Murano Actions are simple MuranoPL methods, that can be called on deployed applications.
+Application contains a list with available actions. Actions may return a result.
+
+Execute an action
+-----------------
+
+Generate task with executing specified action. Input parameters may be provided.
+
+*Request*
+
+**Content-Type**
+  application/json
+
++----------------+-----------------------------------------------------------+------------------------------------+
+| Method         | URI                                                       | Header                             |
++================+===========================================================+====================================+
+| POST           | /environments/<env_id>/actions/<action_id>                |                                    |
++----------------+-----------------------------------------------------------+------------------------------------+
+
+**Parameters:**
+
+* `env_id` - environment ID, required
+* `actions_id` - action ID to execute, required
+
+::
+
+  "{<action_property>: value}"
+
+  or
+
+  "{}" in case action has no properties
+
+*Response*
+
+Task ID that executes specified action is returned
+
+**Content-Type**
+  application/json
+
+::
+
+  {
+      "task_id": "620e883070ad40a3af566d465aa156ef"
+  }
+
+GET action result
+-----------------
+
+Request result value after action execution finish. Not all actions have return values.
+
+
+*Request*
+
++----------------+-----------------------------------------------------------+------------------------------------+
+| Method         | URI                                                       | Header                             |
++================+===========================================================+====================================+
+| GET            | /environments/<env_id>/actions/<task_id>                  |                                    |
++----------------+-----------------------------------------------------------+------------------------------------+
+
+**Parameters:**
+
+* `env_id` - environment ID, required
+* `task_id` - task ID, generated on desired action execution
+
+*Response*
+
+Json, describing action result is returned. Result type and value are provided.
+
+**Content-Type**
+  application/json
+
+::
+
+    {
+      "isException": false,
+        "result": ["item1", "item2"]
+    }