stackforge-attic/murano-docs
Code Issues Proposed changes

Add user-guide draft. Exclude screenshots

Browse Source 
Change-Id: I1d5fa671b8a2eefcc4887ec177702c9e04ef8584
This commit is contained in:
Ekaterina Fedorova
2013-09-04 19:58:16 +04:00
parent b5f7b95fd2
commit 247f1484e3
18 changed files with 172 additions and 216 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
src/developers-guide/src/docbkx/content/blueprint.xml → src/developers-guide/src/docbkx/content/architecture.xml
View File

@@ -22,100 +22,7 @@
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>Blueprint</title>
<section>
<title>Project Background</title>
<para>Enterprise customers frequently use Windows-based environments for their internal and external
products. Configuration of the Windows environment is a complex task which usually requires a lot of
effort from administrators. Windows setup consists of numerous services which might be tightly coupled
to each other. While the automated installation of Windows services can be fairly straightforward,
service configuration can be hard to automate because it requires a well-designed Windows architecture
and deep knowledge of Windows services configuration.
</para>
<para>Currently several open source solutions exists that can help to partially solve automation of Windows
environment provisioning. In the world of OpenStack there is the Heat project, which is similar to
Amazon Cloud Formation. Heat is an excellent tool for managing OpenStack cloud resources such as VM
instances, security groups, and so on. It allows you to define all cloud resources in a single JSON
template, then later maintain all of those resources by editing that template. Although the declarative
template approach is well suited to OpenStack resources, it quickly becomes complex when it comes to
application management.
</para>
<para>Another option is a tool such as Chef or Puppet. These tools are flexible, but require you to have a
deep knowledge of scripting and require a significant amount of effort to manually script or modify
cookbooks for your specific environment configuration. This is manageable in a stable environment, but
it becomes time-consuming and involves manual script coding when one needs to deploy various
environments with rapidly changing configurations. Also Chef and Puppet require additional
infrastructure to support them.
</para>
<para>The biggest problem for both approaches above is in supporting multi-step configuration of services
with circular dependencies required for correct configuration of Windows services. This can be solved by
using external orchestration.
</para>
<para>Another potential problem is the lack of UI functionality enabling creation and configuration of an
environment without writing a script.
</para>
<section>
<title>Proposal</title>
<para>Mirantis proposes to introduce a new service which will allow a non-experienced user to deploy
reliable Windows based environments in a “push-the-button” manner. The key goal is to provide a UI
and API enabling the deployment and operation of Windows Environments at the Windows Services
abstraction level. The service should be able to orchestrate complex circular dependent cases in
order to set up a complex Windows Environment with multiple dependant services.
</para>
<para>The service will address following use cases:
<itemizedlist spacing="compact">
<listitem>
<para>Self-provisioning of predefined Windows services with their dependencies</para>
</listitem>
<listitem>
<para>Automation of administrative tasks during data center roll-out</para>
</listitem>
<listitem>
<para>Custom windows application as a windows service</para>
</listitem>
</itemizedlist>
</para>
<para>
The solution will provide higher level of abstraction for manipulation Windows Environments. Key
concepts are:
<itemizedlist spacing="compact">
<listitem>
<para>Windows Service - a service such as Active Directory, MSSQL, or IIS, which usually
consists of multiple virtual machines and has multiple dependencies.
</para>
</listitem>
<listitem>
<para>Windows Environment - a logical unit for all Services and represents a classical
Windows Datacenter
</para>
</listitem>
<listitem>
<para>Windows VM instance - a VM which hosts a Windows Service. A Windows Service might be
deployed
</para>
</listitem>
</itemizedlist>
</para>
<para>
The Key Features of the Service are the following:
<orderedlist>
<listitem>
<para>Native to OpenStack</para>
</listitem>
<listitem>
<para>Introduces abstraction level for Windows Environments</para>
</listitem>
<listitem>
<para>Supports Availability Zones and Disaster Recovery scenarios</para>
</listitem>
<listitem>
<para>Uses native Windows features for HA solutions</para>
</listitem>
</orderedlist>
</para>
</section>
</section>
<title>Architecture</title>
<section xml:id="architecture">
<title>Architecture</title>
<para>
@@ -152,11 +59,11 @@
<title>Architecture</title>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="figures/architecture_diagram.png"
<imagedata fileref="../figures/architecture_diagram.png"
contentwidth="5in"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="figures/architecture_diagram.png"/>
<imagedata fileref="../figures/architecture_diagram.png"/>
</imageobject>
</mediaobject>
</figure>
@@ -179,9 +86,7 @@
<title>Orchestration Engine</title>
<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. Currently
there are two services which are already implemented as plugins. They are Active Directory and IIS
Service.
via plug-ins. Plugins can add new services and extend existing services for integration.
</para>
</section>
</section>
@@ -190,18 +95,16 @@
<itemizedlist>
<listitem>
<para> <emphasis>Release-0.1</emphasis>
has 0.1 tag in all Murano repositories. Released 2013-06-19.
has 0.1 tag in all Murano repositories. Released 2013-05-30.
</para>
</listitem>
<listitem>
<para>
<emphasis>Release-0.2</emphasis>
has 0.2 tag in all Murano repositories. Released
2013-05-30.
has 0.2 tag in all Murano repositories. Released 2013-09-05.
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Integration with Heat</title>

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

@@ -39,7 +39,8 @@
<para>RHEL/CentOS 6.4</para>
</listitem>
</orderedlist>
<para>These system packages are requred for Murano:</para>
<para>These system packages are required for Murano:</para>
<para><emphasis>Ubuntu</emphasis></para>
<orderedlist>
<listitem>
<para>python-dev</para>
@@ -54,6 +55,23 @@
<para>libffi-dev</para>
</listitem>
</orderedlist>
<para>
<emphasis>CentOS</emphasis>
</para>
<orderedlist>
<listitem>
<para>python-devel</para>
</listitem>
<listitem>
<para>libxml2-devel</para>
</listitem>
<listitem>
<para>libxslt-devel</para>
</listitem>
<listitem>
<para>libffi-devel</para>
</listitem>
</orderedlist>
</section>
<section>
@@ -62,7 +80,7 @@
<para>This chapter describes the procedure of installation and condiguration of Murano API. </para>
<section>
<title>Install</title>
<itemizedlist>
<itemizedlist spacing="compact">
<listitem>
<para>Superuser privileges is required to install and configure system packages. Let's switch to root account:</para>
<programlisting>
@@ -123,7 +141,7 @@ LOG:> Please, make proper configuration,located at "/etc/murano-api", before sta
</section>
<section>
<title>Configure</title>
<itemizedlist>
<itemizedlist spacing="compact">
<listitem>
<para>First configure rabbitMQ by adding vhost and user with administrator rights:</para>
<programlisting>
@@ -214,7 +232,6 @@ source $(YOUR_OPENSTACK_DIR)/openrc $(LOGIN) $(PASSWORD)
]]>
</programlisting>
<anchor xml:id="murano_api_endpoint"></anchor>
<programlisting>
<![CDATA[
@@ -265,7 +282,7 @@ initctl start murano-api
<para>This chapter describes Conductor for contributors of the project.</para>
<section>
<title>Install</title>
<itemizedlist>
<itemizedlist spacing="compact">
<listitem>
<para>Murano Condutor uses OpenStack Heat for new virtual machines creation, therefore Heat should
been installed and configured. Some services require the Internet access for virtual machines to
@@ -333,11 +350,11 @@ sh setup-centos.sh install
]]>
</programlisting>
</listitem>
</itemizedlist>
</itemizedlist >
</section>
<section>
<title>Configure</title>
<itemizedlist>
<itemizedlist spacing="compact">
<listitem>
<para>Edit configuration file and take a look at inline comments:</para>
<programlisting>
@@ -354,7 +371,7 @@ cp conductor.conf.sample conductor.conf
vi conductor.conf
]]>
</programlisting>
<itemizedlist>
<itemizedlist >
<listitem>
<para><emphasis>[DEFAULT]</emphasis>section is responsible for logging.
</para>

10
src/developers-guide/src/docbkx/content/knownissues.xml
View File

@@ -46,10 +46,16 @@
</para>
</listitem>
<listitem>
<para>Active Directory service can not be created on Win2008 image.</para>
<para>Murano-Conductor doesn't work with python-heatclient>0.2.1.</para>
</listitem>
<listitem>
<para>Murano-Conductor doesn't work with python-heatclient>0.2.1.</para>
<para>
Farm services can't be deployed without KeyPair. If KeyPair is not set
load balancer won't be created and these messages will show up in logs:
2013-08-06 09:10:07 - Unable to deploy instance ipkrmhk0vzq4b6 (asp-farm_instance_0) due to Unexpected state
2013-08-06 09:10:07 - Unable to create a Server Farm load balancer on unit ipkrmhk0vzq4b6 (asp-farm_instance_0) due to Unexpected state
And deploy will hang up.
</para>
</listitem>
</itemizedlist>

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

@@ -62,6 +62,16 @@
</itemizedlist>
</td>
</tr>
<tr>
<td colspan="1" align="center">September. 4, 2013</td>
<td colspan="4">
<itemizedlist spacing="compact">
<listitem>
<para>update for Release-0.2</para>
</listitem>
</itemizedlist>
</td>
</tr>
</tbody>
</informaltable>
</section>

98
src/developers-guide/src/docbkx/content/screenshots.xml
View File

@@ -1,98 +0,0 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
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.
-->
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
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">
<title>Screenshots</title>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="../figures/screens/1.png"
contentwidth="5in"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/screens/1.png"/>
</imageobject>
</mediaobject>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="../figures/screens/2.png"
contentwidth="5in"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/screens/2.png"/>
</imageobject>
</mediaobject>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="../figures/screens/3.png"
contentwidth="5in"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/screens/3.png"/>
</imageobject>
</mediaobject>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="../figures/screens/4.png"
contentwidth="5in"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/screens/4.png"/>
</imageobject>
</mediaobject>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="../figures/screens/5.png"
contentwidth="5in"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/screens/5.png"/>
</imageobject>
</mediaobject>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="../figures/screens/6.png"
contentwidth="5in"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/screens/6.png"/>
</imageobject>
</mediaobject>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="../figures/screens/7.png"
contentwidth="5in"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/screens/7.png"/>
</imageobject>
</mediaobject>
<mediaobject>
<imageobject role="fo">
<imagedata fileref="../figures/screens/1.png"
contentwidth="5in"/>
</imageobject>
<imageobject role="html">
<imagedata fileref="../figures/screens/1.png"/>
</imageobject>
</mediaobject>
</chapter>

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

@@ -36,7 +36,7 @@
<td colspan="4">
<itemizedlist spacing="compact">
<listitem>
<para>Initial document creation</para>
<para>Initial</para>
</listitem>
</itemizedlist>
</td>
@@ -2584,7 +2584,7 @@
</tgroup>
</table>
<table frame="all">
<title>ASP.NET Application Farm Unit Object</title>
<title>SQL Server Unit object</title>
<tgroup cols="3" align="left" colsep="1" rowsep="1">
<colspec colnum="1" colname="col1" colwidth="2*"/>
<colspec colnum="2" colname="col2" colwidth="1*"/>
@@ -2609,7 +2609,7 @@
<section>
<title>Create Object Specs</title>
<table frame="all">
<title>ASP.NET Application Farm Object</title>
<title>SQL Server Unit object</title>
<tgroup cols="4" align="left" colsep="1" rowsep="1">
<colspec colnum="1" colname="col1" colwidth="2*"/>
<colspec colnum="2" colname="col2" colwidth="1*"/>

3
src/developers-guide/src/docbkx/developers-guide.xml
View File

@@ -62,10 +62,9 @@
</info>
<xi:include href="./content/overview.xml" xlink:title="Overview" />
<xi:include href="./content/installation-guide.xml" xlink:title="Installation Guide" />
<xi:include href="./content/blueprint.xml" xlink:title="Blueprint" />
<xi:include href="content/architecture.xml" xlink:title="Blueprint" />
<xi:include href="./content/specification.xml" xlink:title="API Specification" />
<xi:include href="./content/workflows.xml" xlink:title="Workflows XML DSL" />
<xi:include href="./content/screenshots.xml" xlink:title="Screenshots" />
<xi:include href="./content/knownissues.xml" xlink:title="Known Issues" />
<chapter>
<title>How To Participate</title>

BIN
src/developers-guide/src/docbkx/figures/screens/1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 214 KiB

BIN
src/developers-guide/src/docbkx/figures/screens/2.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 36 KiB

BIN
src/developers-guide/src/docbkx/figures/screens/3.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 38 KiB

BIN
src/developers-guide/src/docbkx/figures/screens/4.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 234 KiB

BIN
src/developers-guide/src/docbkx/figures/screens/5.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 325 KiB

BIN
src/developers-guide/src/docbkx/figures/screens/6.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 278 KiB

BIN
src/developers-guide/src/docbkx/figures/screens/7.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 267 KiB

54
src/user-guide/pom.xml Normal file
View File

@@ -0,0 +1,54 @@
<!--
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.
-->
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.mirantis.murano</groupId>
<artifactId>user-guide</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>Murano User Guide</name>
<build>
<plugins>
<plugin>
<groupId>com.agilejava.docbkx</groupId>
<artifactId>docbkx-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>generate-pdf</goal>
<goal>generate-webhelp</goal>
</goals>
<phase>generate-sources</phase>
</execution>
</executions>
<configuration>
<xincludeSupported>true</xincludeSupported>
<chunkSectionDepth>100</chunkSectionDepth>
<postProcess>
<copy todir="target/docbkx/webhelp/user-guide/images">
<fileset dir="src/docbkx/images">
<include name="**/*.png"/>
</fileset>
</copy>
</postProcess>
</configuration>
</plugin>
</plugins>
</build>
</project>

BIN
src/user-guide/src/docbkx/images/1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
src/user-guide/src/docbkx/images/2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 20 KiB

65
src/user-guide/src/docbkx/user-guide.xml Normal file
View File

@@ -0,0 +1,65 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
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.
-->
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
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">
<title>Murano Developers Guide</title>
<info>
<author>
<personname>
<firstname/>
<surname/>
</personname>
<affiliation>
<orgname>Mirantis, Inc.</orgname>
</affiliation>
</author>
<copyright>
<year>2013</year>
<holder>Mirantis, Inc.</holder>
</copyright>
<releaseinfo>v0.1</releaseinfo>
<productname>Murano™</productname>
<pubdate>2013-09-04</pubdate>
<legalnotice role="apache2">
<annotation>
<remark>Copyright details are filled in by the template. Change
the value of the role
attribute on the legalnotice element to change the license.
</remark>
</annotation>
</legalnotice>
<abstract>
<para>This document is intended for individuals who wish to
use our product or intend to contribute.
</para>
</abstract>
<cover>
<para>this is a placeholder for the front cover</para>
</cover>
<cover>
<para>this is a placeholder for the back cover</para>
</cover>
</info>
<xi:include href="./content/overview.xml" xlink:title="Overview" />
<xi:include href="./content/murano-dashboard.xml" xlink:title="Murano Dashboard" />
</book>