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>

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

@@ -1,118 +1,98 @@
<?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 limitations under the License.
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.
-->
<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"
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">
<title>Architecture</title>
<section xml:id="architecture">
<title>Architecture</title> <title>Architecture</title>
<para> <para>
The Murano Service communicates with the following OpenStack components: The Murano Service communicates with the following OpenStack
<itemizedlist> components:
<listitem> <itemizedlist>
<para>Horizon - provides a GUI with ability to use all Murano features;</para> <listitem>
</listitem> <para>Horizon - provides a GUI with ability to use all Murano
<listitem> features;</para>
<para>Keystone - authenticates users and provides the security token that is used to work with </listitem>
OpenStack, hence limiting the user abilities in Murano based on OpenStack privileges; <listitem>
</para> <para>Keystone - authenticates users and provides the security
</listitem> token that is used to work with OpenStack, hence limiting the user
<listitem> abilities in Murano based on OpenStack privileges;</para>
<para>Heat - is used to provision VMs and other OpenStack resources for Windows Environments; </listitem>
</para> <listitem>
</listitem> <para>Heat - is used to provision VMs and other OpenStack resources</para>
<listitem> </listitem>
<para>Glance - stores Windows Server VM images, with each image containing an installed OS and a <listitem>
set of scripts <para>Glance - stores VM images, with preconfigured OS and a containing sets of initial scripts</para>
</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
<para>Agent - provides agent functionality to communicate with the Orchestration Engine and Orchestration Engine and executes tasks on VMs</para>
executes tasks on VMs </listitem>
</para> </itemizedlist>
</listitem> </para>
</itemizedlist> <figure xml:id="muranoarchitecture">
</para> <title>Architecture</title>
<figure xml:id="muranoarchitecture"> <mediaobject><imageobject role="fo">
<title>Architecture</title> <imagedata contentwidth="5in" fileref="../figures/architecture_diagram.png"/>
<mediaobject> </imageobject><imageobject role="html">
<imageobject role="fo"> <imagedata fileref="../figures/architecture_diagram.png"/></imageobject></mediaobject>
<imagedata fileref="../figures/architecture_diagram.png" </figure>
contentwidth="5in"/> <para><emphasis role="bold">REST API</emphasis></para>
</imageobject> <para>
<imageobject role="html"> Murano exposes a service endpoint for communication with a
<imagedata fileref="../figures/architecture_diagram.png"/> client. It exposes API functions to manipulate objects such as
</imageobject> environment and service. This component is responsible for translating
</mediaobject> API function parameters to Object Model attributes and propagating the
</figure> deployment status from the Orchestration Engine.</para>
<section> <para><emphasis role="bold">Object Model</emphasis></para>
<title>REST API</title> <para>
<para>Murano exposes a service endpoint for communication with a client. It exposes API functions to An internal representation of Services and Environments.
manipulate objects such as environment and service. All attributes and entities are described in the API
</para> specification.
<para>This component is responsible for translating API function parameters to Object Model attributes </para>
and propagating the deployment status from the Orchestration Engine. <para><emphasis role="bold">Orchestration Engine</emphasis></para>
</para> <para>
</section> This is the core component which evaluates Object Model changes
<section> and creates a plan for implementing these changes on the instances or
<title>Object Model</title> in the cloud. This component will support extensions via plug-ins.
<para>An internal representation of Windows Services and Environments. All attributes and entities are Plugins can add new services and extend existing services for
described in the API specification. integration.
</para> </para>
</section> <para><emphasis role="bold">Metadata Repository</emphasis></para>
<section> <para>
<title>Orchestration Engine</title> Murano Repository operates with metadata objects: store,
<para>This is the core component which evaluates Object Model changes and creates a plan for display, group and use for deployment. Custom objects can be uploaded
implementing these changes on the instances or in the cloud. This component will support extensions to the Murano Metadata Server and these data will be accessible to all
via plug-ins. Plugins can add new services and extend existing services for integration. Murano components.
</para> </para>
</section> <para><emphasis role="bold">Integration with Heat</emphasis></para>
</section> <para>
<section> Heat is a cloud resource management engine that allows you to
<title>Integration with Heat</title> manipulate resources that represent OpenStack entities (Security
<para>Heat is a cloud resource management engine that allows you to manipulate resources that represent Groups, Instances, Floating IPs, Volumes, etc.) and some entities such
OpenStack entities (Security Groups, Instances, Floating IPs, Volumes, etc.) and some entities such as as AutoScaling groups from a single point of control.
AutoScaling groups from a single point of control. </para>
</para> <para>
<para>OpenStack resource provisioning is one of the steps required for environment deployment and Heat will OpenStack resource provisioning is one of the steps required for
be used for that purpose. Heat allows you to define all OpenStack resources in a single document that environment deployment and Heat will be used for that purpose. Heat
will be easy to maintain and will not require resorting to multiple OpenStack APIs while keeping the allows you to define all OpenStack resources in a single document that
software configuration separate. will be easy to maintain and will not require resorting to multiple
</para> OpenStack APIs while keeping the software configuration
</section> separate.
<section> </para>
<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>

167
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 limitations under the License.
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.
--> -->
<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"
xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd version="5.0"
http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd" xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd
version="5.0"> http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
<title>Overview</title> xml:id="overview">
<para>Welcome to Murano Project. <title>Overview</title>
Full information about Murano in openstack wiki <para>Welcome to Murano Project. Full information about Murano in
<link xlink:href="https://wiki.openstack.org/wiki/Murano"> page.</link> <link xlink:href="https://wiki.openstack.org/wiki/Murano">Openstack wiki page</link>.</para>
</para> <para>Murano Project introduces an application catalog, which allows
<para> application developers and cloud administrators to publish various
Murano is intended to get opportunity for non-experienced cloud-ready applications in a browsable categorised catalog, which may
users to deploy reliable Windows-based environments with 1-Click. be used by the cloud users (including the unexperienced ones) to
Key goal is to provide UI and API which pick-up the needed applications and services and composes the reliable
allows to deploy and operate Windows environments on the "Windows environments out of them in a “push-the-button” manner. Key goal is to
Services" abstraction level. The Service should be able to orchestrate provide UI and API which allows to compose and deploy composite
complex circular dependent cases in order to setup complete Windows environments on the Application abstraction level and then manage
environments with many dependant services. their lifecycle</para>
</para> <section>
<section> <title>Intended Audience</title>
<title>Intended Audience</title> <para>This guide is intended to individuals who want to contribute to
<para>This guide is intended to individuals who want to contribute our project.</para>
to our </section>
project. <section>
</para> <title>Document Change History</title>
</section> <para>This version of the Murano Manual replaces and obsoletes all
<section> previous versions. The most recent changes are described in the table
<title>Document Change History</title> below:</para>
<para>This version of the Murano Manual replaces and obsoletes all <informaltable rules="all">
previous versions. The <tgroup cols='2'>
most recent changes are described in the table below: <colspec colname="col1" colnum="1" colwidth="1*"/>
</para> <colspec colname="col2" colnum="2" colwidth="1*"/>
<informaltable rules="all"> <thead>
<thead> <row>
<tr> <entry>Revision Date</entry>
<td align="center" colspan="1">Revision Date</td> <entry>Summary of Changes</entry>
<td align="center" colspan="4">Summary of Changes</td> </row>
</tr> </thead>
</thead> <tbody>
<tbody> <row>
<tr> <entry>
<td colspan="1" align="center">April. 4, 2013</td> April. 4, 2013
<td colspan="4"> </entry>
<itemizedlist spacing="compact"> <entry>
<listitem> <itemizedlist spacing="compact">
<para>Initial document creation.</para> <listitem>
</listitem> <para>Initial document creation</para>
</itemizedlist> </listitem>
</td> </itemizedlist>
</tr> </entry>
<tr> </row>
<td colspan="1" align="center">September. 4, 2013</td> <row>
<td colspan="4"> <entry>
<itemizedlist spacing="compact"> September. 4, 2013
<listitem> </entry>
<para>update for Release-0.2</para> <entry>
</listitem> <itemizedlist spacing="compact">
</itemizedlist> <listitem>
</td> <para>Update for Release-0.2</para>
</tr> </listitem>
</tbody> </itemizedlist>
</informaltable> </entry>
</section> </row>
<row>
<entry>
December. 9, 2013
</entry>
<entry>
<itemizedlist spacing="compact">
<listitem>
<para>Update for Release-0.4</para>
</listitem>
</itemizedlist>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</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

98
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>
<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>
<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>
<emphasis role="bold">report</emphasis> - sends status report back to REST API service. It has the following parameters: <para>
<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>