From 815d69608103e56f98cf092f3fd0b88581e3462c Mon Sep 17 00:00:00 2001 From: Ekaterina Chernova Date: Mon, 15 Jun 2015 18:08:37 +0300 Subject: [PATCH] Document murano actions * API spec was updated * New content to the dev guide was added Change-Id: I8794e56259bd9b1290987f2f0a8e63d0c9775c3f --- doc/source/draft/appdev-guide/murano_pl.rst | 1 + .../draft/appdev-guide/murano_pl/actions.rst | 77 ++++++++++++++++++ doc/source/specification/murano-api.rst | 81 +++++++++++++++++++ 3 files changed, 159 insertions(+) create mode 100644 doc/source/draft/appdev-guide/murano_pl/actions.rst diff --git a/doc/source/draft/appdev-guide/murano_pl.rst b/doc/source/draft/appdev-guide/murano_pl.rst index 9626b36d..709f4044 100644 --- a/doc/source/draft/appdev-guide/murano_pl.rst +++ b/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 \ No newline at end of file diff --git a/doc/source/draft/appdev-guide/murano_pl/actions.rst b/doc/source/draft/appdev-guide/murano_pl/actions.rst new file mode 100644 index 00000000..f6728f2d --- /dev/null +++ b/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//services/`` + +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" + } + } + } + } \ No newline at end of file diff --git a/doc/source/specification/murano-api.rst b/doc/source/specification/murano-api.rst index 47983c45..f39ebcc2 100644 --- a/doc/source/specification/murano-api.rst +++ b/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//actions/ | | ++----------------+-----------------------------------------------------------+------------------------------------+ + +**Parameters:** + +* `env_id` - environment ID, required +* `actions_id` - action ID to execute, required + +:: + + "{: 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//actions/ | | ++----------------+-----------------------------------------------------------+------------------------------------+ + +**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"] + }