diff --git a/src/developers-guide/pom.xml b/src/developers-guide/pom.xml index ad08628..c4a444d 100644 --- a/src/developers-guide/pom.xml +++ b/src/developers-guide/pom.xml @@ -20,7 +20,7 @@ 4.0.0 com.mirantis.murano developers-guide - 0.3 + 0.4 jar Murano Developers Guide diff --git a/src/developers-guide/src/docbkx/content/api-specification.xml b/src/developers-guide/src/docbkx/content/api-specification.xml index 575dd9d..36a0408 100644 --- a/src/developers-guide/src/docbkx/content/api-specification.xml +++ b/src/developers-guide/src/docbkx/content/api-specification.xml @@ -21,7 +21,8 @@ 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 http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd" - version="5.0"> + version="5.0" + xml:id="api-specification"> API Specification diff --git a/src/developers-guide/src/docbkx/content/architecture.xml b/src/developers-guide/src/docbkx/content/architecture.xml index 43c6c89..b07b63b 100644 --- a/src/developers-guide/src/docbkx/content/architecture.xml +++ b/src/developers-guide/src/docbkx/content/architecture.xml @@ -1,118 +1,98 @@ - + - - - Architecture -
+ Copyright (c) 2013 Mirantis, Inc. 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. +--> + Architecture - - The Murano Service communicates with the following OpenStack components: - - - Horizon - provides a GUI with ability to use all Murano features; - - - Keystone - authenticates users and provides the security token that is used to work with - OpenStack, hence limiting the user abilities in Murano based on OpenStack privileges; - - - - Heat - is used to provision VMs and other OpenStack resources for Windows Environments; - - - - Glance - stores Windows Server VM images, with each image containing an installed OS and a - set of scripts - - - - Quantum - provides the network configuration API - - - Agent - provides agent functionality to communicate with the Orchestration Engine and - executes tasks on VMs - - - - -
- Architecture - - - - - - - - -
-
- REST API - Murano exposes a service endpoint for communication with a 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. - -
-
- Object Model - An internal representation of Windows Services and Environments. All attributes and entities are - described in the API specification. - -
-
- Orchestration Engine - 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. - -
-
-
- Integration with Heat - Heat is a cloud resource management engine that allows you to manipulate resources that represent - OpenStack entities (Security Groups, Instances, Floating IPs, Volumes, etc.) and some entities such as - AutoScaling groups from a single point of control. - - 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. - -
-
- Windows on OpenStack - 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. - - 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. - - Also, unlike the current OpenStack, Hyper-V also natively supports Windows Clusters. - -
+ + The Murano Service communicates with the following OpenStack + components: + + + Horizon - provides a GUI with ability to use all Murano + features; + + + Keystone - authenticates users and provides the security + token that is used to work with OpenStack, hence limiting the user + abilities in Murano based on OpenStack privileges; + + + Heat - is used to provision VMs and other OpenStack resources + + + Glance - stores VM images, with preconfigured OS and a containing sets of initial scripts + + + Quantum - provides the network configuration API + + + Agent - provides agent functionality to communicate with the + Orchestration Engine and executes tasks on VMs + + + +
+ Architecture + + + + +
+ REST API + + Murano exposes a service endpoint for communication with a + 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. + Object Model + + An internal representation of Services and Environments. + All attributes and entities are described in the API + specification. + + Orchestration Engine + + 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. + + Metadata Repository + + Murano Repository operates with metadata objects: store, + display, group and use for deployment. Custom objects can be uploaded + to the Murano Metadata Server and these data will be accessible to all + Murano components. + + Integration with Heat + + Heat is a cloud resource management engine that allows you to + manipulate resources that represent OpenStack entities (Security + Groups, Instances, Floating IPs, Volumes, etc.) and some entities such + as AutoScaling groups from a single point of control. + + + 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. + diff --git a/src/developers-guide/src/docbkx/content/installation-guide.xml b/src/developers-guide/src/docbkx/content/installation-guide.xml index 7783e13..4ee7e25 100644 --- a/src/developers-guide/src/docbkx/content/installation-guide.xml +++ b/src/developers-guide/src/docbkx/content/installation-guide.xml @@ -10,8 +10,11 @@ the License for the specific language governing permissions and limitations under the License. --> - + Install Murano This chapter describes Murano services installation in virtual environment. diff --git a/src/developers-guide/src/docbkx/content/overview.xml b/src/developers-guide/src/docbkx/content/overview.xml index 7b3d591..26dccc1 100644 --- a/src/developers-guide/src/docbkx/content/overview.xml +++ b/src/developers-guide/src/docbkx/content/overview.xml @@ -1,82 +1,93 @@ - + - - Overview - Welcome to Murano Project. - Full information about Murano in openstack wiki - page. - - - Murano is intended to get opportunity for non-experienced - users to deploy reliable Windows-based environments with 1-Click. - Key goal is to provide UI and API which - allows to deploy and operate Windows environments on the "Windows - Services" abstraction level. The Service should be able to orchestrate - complex circular dependent cases in order to setup complete Windows - environments with many dependant services. - -
- Intended Audience - This guide is intended to individuals who want to contribute - to our - project. - -
-
- Document Change History - This version of the Murano Manual replaces and obsoletes all - previous versions. The - most recent changes are described in the table below: - - - - - Revision Date - Summary of Changes - - - - - April. 4, 2013 - - - - Initial document creation. - - - - - - September. 4, 2013 - - - - update for Release-0.2 - - - - - - -
- \ No newline at end of file + + Overview + Welcome to Murano Project. Full information about Murano in + Openstack wiki page. + Murano Project introduces an application catalog, which allows + application developers and cloud administrators to publish various + cloud-ready applications in a browsable categorised catalog, which may + be used by the cloud users (including the unexperienced ones) to + pick-up the needed applications and services and composes the reliable + environments out of them in a “push-the-button” manner. Key goal is to + provide UI and API which allows to compose and deploy composite + environments on the Application abstraction level and then manage + their lifecycle +
+ Intended Audience + This guide is intended to individuals who want to contribute to + our project. +
+
+ Document Change History + This version of the Murano Manual replaces and obsoletes all + previous versions. The most recent changes are described in the table + below: + + + + + + + Revision Date + Summary of Changes + + + + + + April. 4, 2013 + + + + + Initial document creation + + + + + + + September. 4, 2013 + + + + + Update for Release-0.2 + + + + + + + December. 9, 2013 + + + + + Update for Release-0.4 + + + + + + + +
+ diff --git a/src/developers-guide/src/docbkx/content/repository-specification.xml b/src/developers-guide/src/docbkx/content/repository-specification.xml index c34997d..af01c39 100644 --- a/src/developers-guide/src/docbkx/content/repository-specification.xml +++ b/src/developers-guide/src/docbkx/content/repository-specification.xml @@ -10,28 +10,36 @@ the License for the specific language governing permissions and limitations under the License. --> - + Metadata-Repository API Specification + + + - - Revision Date - Summary of Changes - + + Revision Date + Summary of Changes + - - February 2, 2013 - + + December, 9th, 2013. + Initial - - + + +
Introduction @@ -113,6 +121,13 @@ +
+
+ v1 + This chapter defines all available api calls for v1 version. + All definitions are listed without version prefix. Just add + "v1" to the beginning of any call. Example: + v1/client/ui Return codes and errors All REST API calls return the natural HTTP response codes for the operations, e.g. a successful GET returns a HTTP 200, a @@ -123,13 +138,6 @@ All requests include a Keystone authentication token header (X-Auth-Token). Clients must authenticate with Keystone before interacting with the Murano Repository Service. -
-
- v1 - This chapter defines all available api calls for v1 version. - All definitions are listed without version prefix. Just add - "v1" to the beginning of any call. Example: - v1/client/ui
Client API This section describes API calls for Metadata Repository diff --git a/src/developers-guide/src/docbkx/content/workflows.xml b/src/developers-guide/src/docbkx/content/workflows.xml index 20a196b..871dcf7 100644 --- a/src/developers-guide/src/docbkx/content/workflows.xml +++ b/src/developers-guide/src/docbkx/content/workflows.xml @@ -23,7 +23,7 @@ http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd" version="5.0"> Workflows XML DSL -
+
XML DSL 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: + ]]> - returns True + + ]]> - False + + ]]> - None + + ]]> - converts body to string (str(foo())) + + list - form list (array) object - item1 @@ -113,8 +122,10 @@ while that later form is more verbose it allows having dynamically evaluated val ]]> equals to ["item1", "item2", True] + + map - form dictionary (map) object @@ -128,6 +139,7 @@ For both list and map functions names of item nodes ("item" in examples above) i ]]> + @@ -177,7 +189,7 @@ For both list and map functions names of item nodes ("item" in examples above) i Send command to Murano Agent: ]]> - Report state to API: ]]> + Report state to API: ]]> @@ -274,20 +286,26 @@ For both list and map functions names of item nodes ("item" in examples above) i ]]> without path results in object pointed by current cursor position. - It also possible to select multiple values using JSONPath selection language (): + It also possible to select multiple values using JSONPath selection language: ]]> - returns array of all units of all services of type 'activeDirectory' 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 expression may start with one or more colon characters to perform query relative to current cursor parent (grandparent etc.) + + JSONPath expression may also start with slash as in example above to query the whole Model from the tree root + + Expressions may reference nonexistent Model attributes in the same way as ]]>function does. Such attributes considered to have None values + @@ -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: + match - JSONPath expression to be executed relative to current cursor position + + desc - optional human-readable free-form rule description + + id - optional rule ID (auto-generated if not provided) + for example @@ -352,9 +376,15 @@ For both list and map functions names of item nodes ("item" in examples above) i The logic of rule is simple: - Execute given JSONPath expression - For each of matched objects make current cursor position point to it and then execute function XML body - If JSONPath hasn't matched any object execute ... ]]> block if present + + Execute given JSONPath expression + + + For each of matched objects make current cursor position point to it and then execute function XML body + + + If JSONPath hasn't matched any object execute ... ]]> block if present + @@ -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: - update-cf-stack - updates Heat stack by substituting values into Heat template and merging it into Heat stack definition. It has the following parameters: + + update-cf-stack - updates Heat stack by substituting values into Heat template and merging it into Heat stack definition. It has the following parameters: + + template - Heat template filename without extension + + error - function context variable to be populated with command error info in case of command failure + + mappings - 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 + + arguments - optional dictionary of Heat template arguments ("Parameters" section of Heat templates) + update-cf-stack function also searches for 2 predefined tags in its body: + <success> - a block to be executed after successfull stack update + + <failure> - block that would be executed in case of function failure + - - Templates are located in data/cf directory + Templates are located in data/cf directory + send-command - sends an execution plan to Murano Agent on specific VM. It has the following parameters: + + template - execution plan template filename without extension + + error - function context variable to be populated with command error info in case of command failure + + service - ID of a service that target units belongs to + + unit - ID of target unit (VM) + + mappings - 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 + send-command function also searches for 2 predefined tags in its body: + <success> - a block to be executed after successfull stack update + + <failure> - block that would be executed in case of function failure + - - Templates are located in data/agent directory + Templates are located in data/agent directory - report - sends status report back to REST API service. It has the following parameters: + + report - sends status report back to REST API service. It has the following parameters: + - entity - entity type ("unit", "service", "environment") + entity - entity type ("unit", "service", "environment") - level - log level + level - log level - id - ID of unit/service/environment + id - ID of unit/service/environment - text - reported status text + text - reported status text @@ -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: + Commands array - list of functions to be executed. Each function has a "Name" property and "Arguments" dictionary which maps function argument names to parameter values. + + Scripts - 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. + + RebootOnCompletion - 0 = do not reboot, 1 = reboot only upon successful plan execution, 2 = reboot always. Murano Agent send execution result after system reboot. +