From 88d55b24260a844b61fcf4798f6f77a6d508f696 Mon Sep 17 00:00:00 2001 From: Steve McLellan Date: Wed, 7 May 2014 16:33:08 -0500 Subject: [PATCH] Adds an explanation of the engine workflow An explanation of how the engine processes a workflow, using the telnet example. Adds some links to the telnet example in app_pkg.rst to use for demonstration. Change-Id: I51eff451497f09d4285de779495e194d0a84b221 --- doc/source/articles/app_pkg.rst | 7 +- doc/source/articles/core_classes.rst | 2 +- doc/source/articles/index.rst | 2 + doc/source/articles/workflow.rst | 112 +++++++++++++++++++++++++++ 4 files changed, 121 insertions(+), 2 deletions(-) create mode 100644 doc/source/articles/workflow.rst diff --git a/doc/source/articles/app_pkg.rst b/doc/source/articles/app_pkg.rst index 3f7a9492..bebe1f70 100644 --- a/doc/source/articles/app_pkg.rst +++ b/doc/source/articles/app_pkg.rst @@ -41,6 +41,8 @@ Besides the *Scripts* section the following sections must be presented in a reso * **Files** This is an optional array of additional files required for the script. Use *<>* to specify a relative path to the file. The root directory is *Resource/scripts*. * **Options** an optional argument of type contains additional options +.. _Telnet Agent: + Example *DeployTelnet.template* .. code-block:: yaml @@ -72,6 +74,7 @@ Step 2. Prepare MuranoPL class definitions =========================================== MuranoPL classes control application deployment workflow execution. Full information about MuranoPL classes see here: :ref:`MuranoPL Spec` +.. _Telnet Class: Example *telnet.yaml* @@ -111,7 +114,7 @@ Example *telnet.yaml* Note, that * *io.murano.system.Resources* is a system class, defined in MuranoPL. More information about MuranoPL system classes is available here: :ref:`class_definitions`. -* *io.murano.resources.Instance* is a class, defined in the core Murano library, which is available here. :ref:`This library ` contains Murano Agent templates and virtual machine initialization scripts. +* *io.murano.resources.Instance* is a class, defined in the core Murano library, which is available here. :ref:`This library ` contains Murano Agent templates and virtual machine initialization scripts. * $this.find(std:Environment).reporter.report($this, 'Creating VM for Telnet instance.') - this is the way of sending reports to Murano dashboard during deployment Step 3. Prepare dynamic UI form definition @@ -137,6 +140,8 @@ General application metadata should be described in the application manifest fil * **Classes** - MuranoPL class list, on which application deployment is based * **Tags** - list of words, associated with this application. Will be helpful during the search. *Optional* parameter +.. _Telnet Manifest: + Example *manifest.yaml* .. code-block:: yaml diff --git a/doc/source/articles/core_classes.rst b/doc/source/articles/core_classes.rst index 583a3f2a..b8eec091 100644 --- a/doc/source/articles/core_classes.rst +++ b/doc/source/articles/core_classes.rst @@ -13,7 +13,7 @@ License for the specific language governing permissions and limitations under the License. -.. _cory_library: +.. _core_library: ===================== MuranoPL Core Library diff --git a/doc/source/articles/index.rst b/doc/source/articles/index.rst index 7be82c43..079f274a 100644 --- a/doc/source/articles/index.rst +++ b/doc/source/articles/index.rst @@ -23,3 +23,5 @@ App Catalog murano_pl_index dynamic_ui app_pkg + + workflow diff --git a/doc/source/articles/workflow.rst b/doc/source/articles/workflow.rst new file mode 100644 index 00000000..9fed6521 --- /dev/null +++ b/doc/source/articles/workflow.rst @@ -0,0 +1,112 @@ +.. + Copyright 2014 Hewlett-Packard Development Company, L.P. + + Licensed under the Apache License, Version 2.0 (the "License"); you may + not use this file except in compliance with the License. You may obtain + a copy of the License at + + http//www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + License for the specific language governing permissions and limitations + under the License. + +=============== +Murano workflow +=============== +What happens when a component is being created in an environment? This document +will use the Telnet package referenced elsewhere as an example. It assumes the +package has been previously uploaded to Murano. + + +Step 1. Begin deployment +========================= +The API sends a message that instructs murano-engine, the workflow component of +Murano, to deploy an environment. The message consists of a JSON document +containing the class types required to create the environment, as well as any +parameters the user selected prior to deployment. Examples are: +* An :ref:`Environment` object (io.murano.Environment) with a *name* +* An object (or objects) referring to networks that need to be created + or that already exist +* A list of Applications (e.g. io.murano.apps.linux.Telnet). Each Application + will contain, or will reference, anything it requires. The Telnet example, + has a property called *instance* whose contract states it must be of type + io.murano.resources.Instance. In turn the Instance has properties it requires + (like a name, a flavor, a keypair name). + +Each object in this *model* has an ID so that the state of each can be tracked. + +The classes that are required are determined by the application's manifest. In +the :ref:`Telnet example ` only one class is explicitly +required; the telnet application definition. + +The :ref:`Telnet class definition ` refers to several other +classes. It extends :ref:`Application` and it requires an :ref:`Instance`. +It also refers to the :ref:`Environment` in which it will be contained, +sends reports through the environment's :ref:`io.murano.system.StatusReporter` +and adds security group rules to the :ref:`SecurityGroupManager`. + + +Step 2. Load definitions +========================= +The engine makes a series of requests to the API to download packages it +needs. These requests pass the class names the environment will require, and +during this stage the engine will validate that all the required classes exist +and are accessible, and will begin creating them. All Classes whose *workflow* +sections contain an *initialize* fragment are then initialized. A typical initialization +order would be (defined by the ordering in the *model* sent to the murano-engine): + +* :ref:`Network` +* :ref:`Instance` +* :ref:`Object` +* :ref:`Environment` + + +Step 3. Deploy resources +========================== +The workflow defined in Environment.deploy is now executed. The first step +typically is to initialize the messaging component that will pay attention +to murano-agent (see later). The next stage is to deploy each application the +environment knows about in turn, by running deploy() for each application. +This happens concurrently for all the applications belonging to an instance. + +In the :ref:`Telnet example ` (under *Workflow*), the workflow +dictates sending a status message (via the environment's *reporter*, and +configuring some security group rules. It is at this stage that the engine +first contacts Heat to request information about any pre-existing resources +(and there will be none for a fresh deploy) before updating the new Heat +template with the security group information. + +Next it instructs the engine to deploy the *instance* it relies on. A large +part of the interaction with Heat is carried out at this stage; the first +thing an Instance does is add itself to the environment's network. Since the +network doesn't yet exist, murano-engine runs the neutron network workflow +which pushes template fragments to Heat. These fragments can define: +* Networks +* Subnets +* Router interfaces + +Once this is done the Instance itself constructs a Heat template fragment and +again pushes it to Heat. The Instance will include a *userdata* script that +is run when the instance has started up, and which will configure and run +murano-agent. + + +Step 4. Software configuration via murano-agent +================================================ +If the workflow includes murano-agent components (and the telnet example does), +typically the application workflow will execute them as the next step. + +In the telnet example, the workflow instructs the engine to load +*DeployTelnet.yaml* as YAML, and pass it to the murano-agent running on the +configured instance. This causes the agent to execute the *EntryPoint* defined +in the agent script (which in this case deploys some packages and sets some +iptables rules). + + +Step 5. Done +============= +After execution is finished, the engine sends a last message indicating that +fact; the API receives it and marks the environment as deployed.