stackforge-attic/murano-docs
Code Issues Proposed changes

Update developers guide

Browse Source 
Add info about app catalog
Add info about Repository in Architecture

Change-Id: I1a6dd98cd2447e57da17918f8c05274d5c9e8e12
This commit is contained in:
Ekaterina Fedorova
2013-12-09 13:57:39 +04:00
parent 890c9d61cb
commit 292906f2d0
7 changed files with 302 additions and 233 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
src/developers-guide/pom.xml
View File

@@ -20,7 +20,7 @@
<modelVersion>4.0.0</modelVersion> <modelVersion>4.0.0</modelVersion>
<groupId>com.mirantis.murano</groupId> <groupId>com.mirantis.murano</groupId>
<artifactId>developers-guide</artifactId> <artifactId>developers-guide</artifactId>
<version>0.3</version> <version>0.4</version>
<packaging>jar</packaging> <packaging>jar</packaging>
<name>Murano Developers Guide</name> <name>Murano Developers Guide</name>
<build> <build>

3
src/developers-guide/src/docbkx/content/api-specification.xml
View File

@@ -21,7 +21,8 @@
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd" http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
version="5.0"> version="5.0"
xml:id="api-specification">
<title>API Specification</title> <title>API Specification</title>
<informaltable rules="all"> <informaltable rules="all">
<thead> <thead>

144
src/developers-guide/src/docbkx/content/architecture.xml
View File

@@ -1,21 +1,15 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version='1.0' encoding='UTF-8'?>
<!-- <!--
Copyright (c) 2013 Mirantis, Inc. Copyright (c) 2013 Mirantis, Inc. Licensed under the Apache License,
Version 2.0 (the &quot;License&quot;); you may not use this file
Licensed under the Apache License, Version 2.0 (the "License"); except in compliance with the License. You may obtain a copy of the
you may not use this file except in compliance with the License. License at http://www.apache.org/licenses/LICENSE-2.0 Unless required
You may obtain a copy of the License at by applicable law or agreed to in writing, software distributed under
the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT
http://www.apache.org/licenses/LICENSE-2.0 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
the License for the specific language governing permissions and
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. limitations under the License.
--> -->
<chapter xmlns="http://docbook.org/ns/docbook" <chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
@@ -23,96 +17,82 @@
http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd" http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
version="5.0"> version="5.0">
<title>Architecture</title> <title>Architecture</title>
<section xml:id="architecture">
<title>Architecture</title>
<para> <para>
The Murano Service communicates with the following OpenStack components: The Murano Service communicates with the following OpenStack
components:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>Horizon - provides a GUI with ability to use all Murano features;</para> <para>Horizon - provides a GUI with ability to use all Murano
features;</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Keystone - authenticates users and provides the security token that is used to work with <para>Keystone - authenticates users and provides the security
OpenStack, hence limiting the user abilities in Murano based on OpenStack privileges; token that is used to work with OpenStack, hence limiting the user
</para> abilities in Murano based on OpenStack privileges;</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Heat - is used to provision VMs and other OpenStack resources for Windows Environments; <para>Heat - is used to provision VMs and other OpenStack resources</para>
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Glance - stores Windows Server VM images, with each image containing an installed OS and a <para>Glance - stores VM images, with preconfigured OS and a containing sets of initial scripts</para>
set of scripts
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Quantum - provides the network configuration API</para> <para>Quantum - provides the network configuration API</para>
</listitem> </listitem>
<listitem> <listitem>
<para>Agent - provides agent functionality to communicate with the Orchestration Engine and <para>Agent - provides agent functionality to communicate with the
executes tasks on VMs Orchestration Engine and executes tasks on VMs</para>
</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
<figure xml:id="muranoarchitecture"> <figure xml:id="muranoarchitecture">
<title>Architecture</title> <title>Architecture</title>
<mediaobject> <mediaobject><imageobject role="fo">
<imageobject role="fo"> <imagedata contentwidth="5in" fileref="../figures/architecture_diagram.png"/>
<imagedata fileref="../figures/architecture_diagram.png" </imageobject><imageobject role="html">
contentwidth="5in"/> <imagedata fileref="../figures/architecture_diagram.png"/></imageobject></mediaobject>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/architecture_diagram.png"/>
</imageobject>
</mediaobject>
</figure> </figure>
<section> <para><emphasis role="bold">REST API</emphasis></para>
<title>REST API</title> <para>
<para>Murano exposes a service endpoint for communication with a client. It exposes API functions to Murano exposes a service endpoint for communication with a
manipulate objects such as environment and service. client. It exposes API functions to manipulate objects such as
environment and service. This component is responsible for translating
API function parameters to Object Model attributes and propagating the
deployment status from the Orchestration Engine.</para>
<para><emphasis role="bold">Object Model</emphasis></para>
<para>
An internal representation of Services and Environments.
All attributes and entities are described in the API
specification.
</para> </para>
<para>This component is responsible for translating API function parameters to Object Model attributes <para><emphasis role="bold">Orchestration Engine</emphasis></para>
and propagating the deployment status from the Orchestration Engine. <para>
This is the core component which evaluates Object Model changes
and creates a plan for implementing these changes on the instances or
in the cloud. This component will support extensions via plug-ins.
Plugins can add new services and extend existing services for
integration.
</para> </para>
</section> <para><emphasis role="bold">Metadata Repository</emphasis></para>
<section> <para>
<title>Object Model</title> Murano Repository operates with metadata objects: store,
<para>An internal representation of Windows Services and Environments. All attributes and entities are display, group and use for deployment. Custom objects can be uploaded
described in the API specification. to the Murano Metadata Server and these data will be accessible to all
Murano components.
</para> </para>
</section> <para><emphasis role="bold">Integration with Heat</emphasis></para>
<section> <para>
<title>Orchestration Engine</title> Heat is a cloud resource management engine that allows you to
<para>This is the core component which evaluates Object Model changes and creates a plan for manipulate resources that represent OpenStack entities (Security
implementing these changes on the instances or in the cloud. This component will support extensions Groups, Instances, Floating IPs, Volumes, etc.) and some entities such
via plug-ins. Plugins can add new services and extend existing services for integration. as AutoScaling groups from a single point of control.
</para> </para>
</section> <para>
</section> OpenStack resource provisioning is one of the steps required for
<section> environment deployment and Heat will be used for that purpose. Heat
<title>Integration with Heat</title> allows you to define all OpenStack resources in a single document that
<para>Heat is a cloud resource management engine that allows you to manipulate resources that represent will be easy to maintain and will not require resorting to multiple
OpenStack entities (Security Groups, Instances, Floating IPs, Volumes, etc.) and some entities such as OpenStack APIs while keeping the software configuration
AutoScaling groups from a single point of control. separate.
</para> </para>
<para>OpenStack resource provisioning is one of the steps required for environment deployment and Heat will
be used for that purpose. Heat allows you to define all OpenStack resources in a single document that
will be easy to maintain and will not require resorting to multiple OpenStack APIs while keeping the
software configuration separate.
</para>
</section>
<section>
<title>Windows on OpenStack</title>
<para>Windows works on KVM pretty smoothly, and with the RedHat-created open-source VirtIO drivers for
Windows, it’s possible to work efficiently with KVM exposed devices.
</para>
<para>In OpenStack’s Grizzly release, Microsoft’s hypervisor Hyper-V will be supported. The Hyper-V virtual
switch will be also supported as a Quantum plug-in. From the performance viewpoint, Hyper-V Server 2012
compares very favorably with bare metal, processing just over 6% fewer transactions per second compared
to the same workload running on a similarly configured physical server.
</para>
<para>Also, unlike the current OpenStack, Hyper-V also natively supports Windows Clusters.
</para>
</section>
</chapter> </chapter>

7
src/developers-guide/src/docbkx/content/installation-guide.xml
View File

@@ -10,8 +10,11 @@
the License for the specific language governing permissions and the License for the specific language governing permissions and
limitations under the License. limitations under the License.
--> -->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <chapter xmlns="http://docbook.org/ns/docbook"
version="5.0" xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"> xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
version="5.0">
<title>Install Murano</title> <title>Install Murano</title>
<para>This chapter describes Murano services installation in virtual <para>This chapter describes Murano services installation in virtual
environment.</para> environment.</para>

115
src/developers-guide/src/docbkx/content/overview.xml
View File

@@ -1,82 +1,93 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version='1.0' encoding='UTF-8'?>
<!-- <!--
Copyright (c) 2013 Mirantis, Inc. Copyright (c) 2013 Mirantis, Inc. Licensed under the Apache License,
Version 2.0 (the &quot;License&quot;); you may not use this file
Licensed under the Apache License, Version 2.0 (the "License"); except in compliance with the License. You may obtain a copy of the
you may not use this file except in compliance with the License. License at http://www.apache.org/licenses/LICENSE-2.0 Unless required
You may obtain a copy of the License at by applicable law or agreed to in writing, software distributed under
the License is distributed on an &quot;AS IS&quot; BASIS, WITHOUT
http://www.apache.org/licenses/LICENSE-2.0 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See
the License for the specific language governing permissions and
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. limitations under the License.
--> -->
<chapter xmlns="http://docbook.org/ns/docbook" <chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
version="5.0"
xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd" http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
version="5.0"> xml:id="overview">
<title>Overview</title> <title>Overview</title>
<para>Welcome to Murano Project. <para>Welcome to Murano Project. Full information about Murano in
Full information about Murano in openstack wiki <link xlink:href="https://wiki.openstack.org/wiki/Murano">Openstack wiki page</link>.</para>
<link xlink:href="https://wiki.openstack.org/wiki/Murano"> page.</link> <para>Murano Project introduces an application catalog, which allows
</para> application developers and cloud administrators to publish various
<para> cloud-ready applications in a browsable categorised catalog, which may
Murano is intended to get opportunity for non-experienced be used by the cloud users (including the unexperienced ones) to
users to deploy reliable Windows-based environments with 1-Click. pick-up the needed applications and services and composes the reliable
Key goal is to provide UI and API which environments out of them in a “push-the-button” manner. Key goal is to
allows to deploy and operate Windows environments on the "Windows provide UI and API which allows to compose and deploy composite
Services" abstraction level. The Service should be able to orchestrate environments on the Application abstraction level and then manage
complex circular dependent cases in order to setup complete Windows their lifecycle</para>
environments with many dependant services.
</para>
<section> <section>
<title>Intended Audience</title> <title>Intended Audience</title>
<para>This guide is intended to individuals who want to contribute <para>This guide is intended to individuals who want to contribute to
to our our project.</para>
project.
</para>
</section> </section>
<section> <section>
<title>Document Change History</title> <title>Document Change History</title>
<para>This version of the Murano Manual replaces and obsoletes all <para>This version of the Murano Manual replaces and obsoletes all
previous versions. The previous versions. The most recent changes are described in the table
most recent changes are described in the table below: below:</para>
</para>
<informaltable rules="all"> <informaltable rules="all">
<tgroup cols='2'>
<colspec colname="col1" colnum="1" colwidth="1*"/>
<colspec colname="col2" colnum="2" colwidth="1*"/>
<thead> <thead>
<tr> <row>
<td align="center" colspan="1">Revision Date</td> <entry>Revision Date</entry>
<td align="center" colspan="4">Summary of Changes</td> <entry>Summary of Changes</entry>
</tr> </row>
</thead> </thead>
<tbody> <tbody>
<tr> <row>
<td colspan="1" align="center">April. 4, 2013</td> <entry>
<td colspan="4"> April. 4, 2013
</entry>
<entry>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem> <listitem>
<para>Initial document creation.</para> <para>Initial document creation</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</td> </entry>
</tr> </row>
<tr> <row>
<td colspan="1" align="center">September. 4, 2013</td> <entry>
<td colspan="4"> September. 4, 2013
</entry>
<entry>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem> <listitem>
<para>update for Release-0.2</para> <para>Update for Release-0.2</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</td> </entry>
</tr> </row>
<row>
<entry>
December. 9, 2013
</entry>
<entry>
<itemizedlist spacing="compact">
<listitem>
<para>Update for Release-0.4</para>
</listitem>
</itemizedlist>
</entry>
</row>
</tbody> </tbody>
</tgroup>
</informaltable> </informaltable>
</section> </section>
</chapter> </chapter>

44
src/developers-guide/src/docbkx/content/repository-specification.xml
View File

@@ -10,28 +10,36 @@
the License for the specific language governing permissions and the License for the specific language governing permissions and
limitations under the License. limitations under the License.
--> -->
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" <chapter xmlns="http://docbook.org/ns/docbook"
version="5.0" xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"> xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
version="5.0" >
<title>Metadata-Repository API Specification</title> <title>Metadata-Repository API Specification</title>
<informaltable rules="all"> <informaltable rules="all">
<tgroup align="left" cols="2" colsep="1" rowsep="1">
<colspec colname="col1" colnum="1" colwidth="1*"/>
<colspec colname="col2" colnum="2" colwidth="4*"/>
<thead> <thead>
<tr> <row>
<td align="center" colspan="1">Revision Date</td> <entry>Revision Date</entry>
<td align="center" colspan="4">Summary of Changes</td> <entry>Summary of Changes</entry>
</tr> </row>
</thead> </thead>
<tbody> <tbody>
<tr> <row>
<td align="center" colspan="1">February 2, 2013</td> <entry>December, 9th, 2013.</entry>
<td colspan="4"> <entry>
<itemizedlist spacing="compact"> <itemizedlist spacing="compact">
<listitem> <listitem>
<para>Initial</para> <para>Initial</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</td> </entry>
</tr> </row>
</tbody> </tbody>
</tgroup>
</informaltable> </informaltable>
<section> <section>
<title>Introduction</title> <title>Introduction</title>
@@ -113,6 +121,13 @@
</glossdef> </glossdef>
</glossentry> </glossentry>
</glossary> </glossary>
</section>
<section>
<title>v1</title>
<para>This chapter defines all available api calls for v1 version.
All definitions are listed without version prefix. Just add
&quot;v1&quot; to the beginning of any call. Example:
v1/client/ui</para>
<para><emphasis role="bold">Return codes and errors</emphasis></para> <para><emphasis role="bold">Return codes and errors</emphasis></para>
<para>All REST API calls return the natural HTTP response codes for <para>All REST API calls return the natural HTTP response codes for
the operations, e.g. a successful GET returns a HTTP 200, a the operations, e.g. a successful GET returns a HTTP 200, a
@@ -123,13 +138,6 @@
<para>All requests include a Keystone authentication token header <para>All requests include a Keystone authentication token header
(X-Auth-Token). Clients must authenticate with Keystone before (X-Auth-Token). Clients must authenticate with Keystone before
interacting with the Murano Repository Service.</para> interacting with the Murano Repository Service.</para>
</section>
<section>
<title>v1</title>
<para>This chapter defines all available api calls for v1 version.
All definitions are listed without version prefix. Just add
&quot;v1&quot; to the beginning of any call. Example:
v1/client/ui</para>
<section> <section>
<title>Client API</title> <title>Client API</title>
<para>This section describes API calls for Metadata Repository <para>This section describes API calls for Metadata Repository

94
src/developers-guide/src/docbkx/content/workflows.xml
View File

@@ -23,7 +23,7 @@
http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd" http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
version="5.0"> version="5.0">
<title>Workflows XML DSL</title> <title>Workflows XML DSL</title>
<section> <section xml:id="workflows">
<title>XML DSL</title> <title>XML DSL</title>
<para> <para>
Workflows are written using XML markup language. This XML has no fixed structure but instead XML tags are translated into Python function calls. Thus such XML can be considered as a simplified programming language. Workflows are written using XML markup language. This XML has no fixed structure but instead XML tags are translated into Python function calls. Thus such XML can be considered as a simplified programming language.
@@ -94,18 +94,27 @@ while that later form is more verbose it allows having dynamically evaluated val
There are a number of functions in Murano Conductor that can be used in XML DSL: There are a number of functions in Murano Conductor that can be used in XML DSL:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>
<code><![CDATA[ <true/> ]]></code> - returns True <code><![CDATA[ <true/> ]]></code> - returns True
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<code><![CDATA[ <false/> ]]></code> - False <code><![CDATA[ <false/> ]]></code> - False
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<code><![CDATA[ <null/> ]]></code> - None <code><![CDATA[ <null/> ]]></code> - None
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<code><![CDATA[ <text><foo/></text> ]]></code> - converts body to string <code>(str(foo()))</code> <code><![CDATA[ <text><foo/></text> ]]></code> - converts body to string <code>(str(foo()))</code>
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
list - form list (array) object - list - form list (array) object -
<programlisting><![CDATA[<list> <programlisting><![CDATA[<list>
<item>item1</item> <item>item1</item>
@@ -113,8 +122,10 @@ while that later form is more verbose it allows having dynamically evaluated val
<item><true/></item> <item><true/></item>
</list> </list>
]]></programlisting> equals to <code>["item1", "item2", True]</code> ]]></programlisting> equals to <code>["item1", "item2", True]</code>
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
map - form dictionary (map) object map - form dictionary (map) object
<programlisting><![CDATA[ <programlisting><![CDATA[
<map> <map>
@@ -128,6 +139,7 @@ For both list and map functions names of item nodes ("item" in examples above) i
<set name="key"><null/></set> <set name="key"><null/></set>
</map> </map>
]]></programlisting> ]]></programlisting>
</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@@ -177,7 +189,7 @@ For both list and map functions names of item nodes ("item" in examples above) i
<para>Send command to Murano Agent: <![CDATA[ <send-command> ]]></para> <para>Send command to Murano Agent: <![CDATA[ <send-command> ]]></para>
</listitem> </listitem>
<listitem> <listitem>
Report state to API: <![CDATA[ <report> ]]> <para>Report state to API: <![CDATA[ <report> ]]></para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@@ -274,20 +286,26 @@ For both list and map functions names of item nodes ("item" in examples above) i
<code><![CDATA[ <select/> ]]></code> without path results in object pointed by current cursor position. <code><![CDATA[ <select/> ]]></code> without path results in object pointed by current cursor position.
</para> </para>
<para> <para>
It also possible to select multiple values using JSONPath selection language (<ulink url="http://goessner.net/articles/JsonPath/"/>): It also possible to select multiple values using JSONPath selection language:
<programlisting><![CDATA[ <select-all path="/$.services[?(@.type == 'activeDirectory')].units[*]"/> ]]></programlisting> - returns array of all units of all services of type 'activeDirectory' <programlisting><![CDATA[ <select-all path="/$.services[?(@.type == 'activeDirectory')].units[*]"/> ]]></programlisting> - returns array of all units of all services of type 'activeDirectory'
</para> </para>
<para> <para>
JSONPath expressions by default select data relative to current cursor position and has no way for navigating up the Model tree. But Conductor has several improvements to JSONPath language: JSONPath expressions by default select data relative to current cursor position and has no way for navigating up the Model tree. But Conductor has several improvements to JSONPath language:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>
JSONPath expression may start with one or more colon characters to perform query relative to current cursor parent (grandparent etc.) JSONPath expression may start with one or more colon characters to perform query relative to current cursor parent (grandparent etc.)
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
JSONPath expression may also start with slash as in example above to query the whole Model from the tree root JSONPath expression may also start with slash as in example above to query the whole Model from the tree root
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
Expressions may reference nonexistent Model attributes in the same way as <code><![CDATA[ <select/> ]]></code>function does. Such attributes considered to have None values Expressions may reference nonexistent Model attributes in the same way as <code><![CDATA[ <select/> ]]></code>function does. Such attributes considered to have None values
</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>
@@ -331,13 +349,19 @@ For both list and map functions names of item nodes ("item" in examples above) i
Workflow consists of rules. Rule is a function with the following parameters: Workflow consists of rules. Rule is a function with the following parameters:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>
<emphasis role="bold">match</emphasis> - JSONPath expression to be executed relative to current cursor position <emphasis role="bold">match</emphasis> - JSONPath expression to be executed relative to current cursor position
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">desc</emphasis> - optional human-readable free-form rule description <emphasis role="bold">desc</emphasis> - optional human-readable free-form rule description
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">id</emphasis> - optional rule ID (auto-generated if not provided) <emphasis role="bold">id</emphasis> - optional rule ID (auto-generated if not provided)
</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
for example for example
@@ -352,9 +376,15 @@ For both list and map functions names of item nodes ("item" in examples above) i
<para> <para>
The logic of rule is simple: The logic of rule is simple:
<orderedlist> <orderedlist>
<listitem>Execute given JSONPath expression</listitem> <listitem>
<listitem>For each of matched objects make current cursor position point to it and then execute function XML body</listitem> <para>Execute given JSONPath expression</para>
<listitem>If JSONPath hasn't matched any object execute <code><![CDATA[ <empty>...</empty> ]]></code> block if present</listitem> </listitem>
<listitem>
<para>For each of matched objects make current cursor position point to it and then execute function XML body</para>
</listitem>
<listitem>
<para>If JSONPath hasn't matched any object execute <code><![CDATA[ <empty>...</empty> ]]></code> block if present</para>
</listitem>
</orderedlist> </orderedlist>
</para> </para>
<para> <para>
@@ -388,80 +418,110 @@ For both list and map functions names of item nodes ("item" in examples above) i
The following actions are available for workflow rules: The following actions are available for workflow rules:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>
<emphasis role="bold">update-cf-stack</emphasis> - updates Heat stack by substituting values into Heat template and merging it into Heat stack definition. It has the following parameters: <emphasis role="bold">update-cf-stack</emphasis> - updates Heat stack by substituting values into Heat template and merging it into Heat stack definition. It has the following parameters:
</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>
<emphasis role="bold">template</emphasis> - Heat template filename without extension <emphasis role="bold">template</emphasis> - Heat template filename without extension
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">error</emphasis> - function context variable to be populated with command error info in case of command failure <emphasis role="bold">error</emphasis> - function context variable to be populated with command error info in case of command failure
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">mappings</emphasis> - dictionary to be used for values substitution into template. All values in JSON template file in the form of "$myKey" are replaced with a value under key "myKey" in this parameter <emphasis role="bold">mappings</emphasis> - dictionary to be used for values substitution into template. All values in JSON template file in the form of "$myKey" are replaced with a value under key "myKey" in this parameter
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">arguments</emphasis> - optional dictionary of Heat template arguments ("Parameters" section of Heat templates) <emphasis role="bold">arguments</emphasis> - optional dictionary of Heat template arguments ("Parameters" section of Heat templates)
</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para> <para>
update-cf-stack function also searches for 2 predefined tags in its body: update-cf-stack function also searches for 2 predefined tags in its body:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>
<emphasis role="bold">&lt;success&gt;</emphasis> - a block to be executed after successfull stack update <emphasis role="bold">&lt;success&gt;</emphasis> - a block to be executed after successfull stack update
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">&lt;failure&gt;</emphasis> - block that would be executed in case of function failure <emphasis role="bold">&lt;failure&gt;</emphasis> - block that would be executed in case of function failure
</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> Templates are located in data/cf directory</para>
<para>Templates are located in data/cf directory</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">send-command</emphasis> - sends an execution plan to Murano Agent on specific VM. It has the following parameters: <emphasis role="bold">send-command</emphasis> - sends an execution plan to Murano Agent on specific VM. It has the following parameters:
</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>
<emphasis role="bold">template</emphasis> - execution plan template filename without extension <emphasis role="bold">template</emphasis> - execution plan template filename without extension
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">error</emphasis> - function context variable to be populated with command error info in case of command failure <emphasis role="bold">error</emphasis> - function context variable to be populated with command error info in case of command failure
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">service</emphasis> - ID of a service that target units belongs to <emphasis role="bold">service</emphasis> - ID of a service that target units belongs to
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">unit</emphasis> - ID of target unit (VM) <emphasis role="bold">unit</emphasis> - ID of target unit (VM)
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">mappings</emphasis> - dictionary to be used for values substitution into template. All values in JSON template file in the form of "$myKey" are replaced with a value under key "myKey" in this parameter <emphasis role="bold">mappings</emphasis> - dictionary to be used for values substitution into template. All values in JSON template file in the form of "$myKey" are replaced with a value under key "myKey" in this parameter
</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
<para> <para>
send-command function also searches for 2 predefined tags in its body: send-command function also searches for 2 predefined tags in its body:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>
<emphasis role="bold">&lt;success&gt;</emphasis> - a block to be executed after successfull stack update <emphasis role="bold">&lt;success&gt;</emphasis> - a block to be executed after successfull stack update
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">&lt;failure&gt;</emphasis> - block that would be executed in case of function failure <emphasis role="bold">&lt;failure&gt;</emphasis> - block that would be executed in case of function failure
</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> Templates are located in data/agent directory</para>
<para>Templates are located in data/agent directory</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">report</emphasis> - sends status report back to REST API service. It has the following parameters: <emphasis role="bold">report</emphasis> - sends status report back to REST API service. It has the following parameters:
</para>
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<emphasis role="bold">entity</emphasis> - entity type ("unit", "service", "environment") <para><emphasis role="bold">entity</emphasis> - entity type ("unit", "service", "environment")</para>
</listitem> </listitem>
<listitem> <listitem>
<emphasis role="bold">level</emphasis> - log level <para><emphasis role="bold">level</emphasis> - log level</para>
</listitem> </listitem>
<listitem> <listitem>
<emphasis role="bold">id</emphasis> - ID of unit/service/environment <para><emphasis role="bold">id</emphasis> - ID of unit/service/environment</para>
</listitem> </listitem>
<listitem> <listitem>
<emphasis role="bold">text</emphasis> - reported status text <para><emphasis role="bold">text</emphasis> - reported status text</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</listitem> </listitem>
@@ -503,13 +563,19 @@ For both list and map functions names of item nodes ("item" in examples above) i
Execution plans is a JSON document that has 3 keys: Execution plans is a JSON document that has 3 keys:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para>
<emphasis role="bold">Commands</emphasis> array - list of functions to be executed. Each function has a "Name" property and "Arguments" dictionary which maps function argument names to parameter values. <emphasis role="bold">Commands</emphasis> array - list of functions to be executed. Each function has a "Name" property and "Arguments" dictionary which maps function argument names to parameter values.
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">Scripts</emphasis> - list of PowerShell script file names to be included into execution plans. The scripts contain function implementations that can be referenced in Command array.Script files need to be located in data/templates/agent/scripts directory. <emphasis role="bold">Scripts</emphasis> - list of PowerShell script file names to be included into execution plans. The scripts contain function implementations that can be referenced in Command array.Script files need to be located in data/templates/agent/scripts directory.
</para>
</listitem> </listitem>
<listitem> <listitem>
<para>
<emphasis role="bold">RebootOnCompletion</emphasis> - 0 = do not reboot, 1 = reboot only upon successful plan execution, 2 = reboot always. Murano Agent send execution result after system reboot. <emphasis role="bold">RebootOnCompletion</emphasis> - 0 = do not reboot, 1 = reboot only upon successful plan execution, 2 = reboot always. Murano Agent send execution result after system reboot.
</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</para> </para>