stackforge-attic
/
murano-docs
Code Issues Proposed changes

Move installation chapter to admin guide 

Change-Id: I7c33a55de13a5974f41676ee9a77010d73a12050
This commit is contained in:
Ekaterina Fedorova 2013-09-20 14:26:48 +04:00
parent 70f28b0030
commit 87be5e3fff
9 changed files with 3248 additions and 2061 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1347
src/administrators-guide/src/docbkx/administrators-guide.xml
View File

File diff suppressed because it is too large Load Diff

956
src/administrators-guide/src/docbkx/administrators-guide.xml.orig Normal file
View File

@ -0,0 +1,956 @@
<?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: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">
<info>
<title>Murano Administrator's Guide</title>
<author>
<affiliation>
<orgname></orgname>
</affiliation>
</author>
<copyright>
<year></year>
<holder></holder>
</copyright>
<releaseinfo>v0.2</releaseinfo>
<productname>Murano</productname>
<pubdate>2013-09-09</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 install and 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>
<chapter xml:id="_general_deployment_steps">
<title>General Deployment Steps</title>
<section xml:id="_configure_your_environment">
<title>Prepare A Lab For Murano</title>
<para>This section provides basic information about lab's system requirements. It also
contains a description of a test which you may use to check if your hadrware fits
the requirements. To do this, run the test and compare the results with baseline
data provided.</para>
<section xml:id="_lab_requirements">
<title>Lab Requirements</title>
<table xml:id="_hardware_requirements" frame="all">
<title>Hardware requirements</title>
<tgroup cols="3" align="left" rowsep="1" colsep="1">
<colspec colname="col1" colwidth="1*"/>
<colspec colname="col2" colwidth="3*"/>
<colspec colname="col3" colwidth="3*"/>
<thead>
<row>
<entry>Criteria</entry>
<entry>Minimal</entry>
<entry>Recommended</entry>
</row>
</thead>
<tbody>
<row>
<entry>CPU</entry>
<entry>4 core @ 2.4 GHz</entry>
<entry>24 core @ 2.67 GHz</entry>
</row>
<row>
<entry>RAM</entry>
<entry>8 GB</entry>
<entry>24 GB or more</entry>
</row>
<row>
<entry>HDD</entry>
<entry>2 x 500 GB (7200 rpm)</entry>
<entry>4 x 500 GB (7200 rpm)</entry>
</row>
<row>
<entry>RAID</entry>
<entry>Software RAID-1 (use mdadm as it will improve read
performance almost two times)
</entry>
<entry>Hardware RAID-10</entry>
</row>
</tbody>
</tgroup>
</table>
<para>There are a few possible storage configurations except the shown above. All of
them were tested and were working well.</para>
<para>
<itemizedlist>
<listitem>
<para>1x SSD 500+ GB</para>
</listitem>
<listitem>
<para>1x HDD (7200 rpm) 500+ GB and 1x SSD 250+ GB (install the system
onto the HDD and mount the SSD drive to folder where VM images
are)</para>
</listitem>
<listitem>
<para>1x HDD (15000 rpm) 500+ GB</para>
</listitem>
</itemizedlist>
</para>
<para>The list of OSes which we used in our lab is shown below.</para>
<table xml:id="_software_requirements" frame="all">
<title>OS Requirements</title>
<tgroup cols="1" align="left" rowsep="1" colsep="1">
<colspec colname="col1" colwidth="1*"/>
<thead>
<row>
<entry>List</entry>
</row>
</thead>
<tbody>
<row>
<entry>Ubuntu Server 12.04 LTS</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section xml:id="_how_to_test_your_host_performance">
<title>Test Your Lab Host Performance</title>
<para>We have measured time required to boot 1 to 5 instances of Windows system simultaneously. You
can use this data as the baseline to check if your system is fast enough.
</para>
<para>You should use sysprepped images for this test, to simulate VM first boot.</para>
<para>Steps to reproduce test:</para>
<orderedlist numeration="arabic">
<listitem>
<para>
Prepare Windows 2012 Standard (with GUI) image in QCOW2 format. Let's assume that its
name is ws-2012-std.qcow2
</para>
</listitem>
<listitem>
<para> Ensure that there is NO KVM PROCESSES on the host. To do this, run
command:
<screen>># ps aux | grep kvm </screen></para>
</listitem>
<listitem>
<para>
Make 5 copies of Windows image file:
</para>
<screen>># for i in $(seq 5); do cp ws-2012-std.qcow2 ws-2012-std-$i.qcow2; done</screen>
</listitem>
<listitem>
<para>
Create script start-vm.sh in the folder with .qcow2 files:
</para>
<screen>#!/bin/bash
[ -z $1 ] || echo "VM count not provided!"; exit 1
for i in $(seq $1); do
echo "Starting VM $i ..."
kvm \
-m 1024 \
-drive file=ws-2012-std-$i.qcow2,if=virtio \
-net user -net nic,model=virtio \
-nographic \
-usbdevice tablet \
-vnc :$i &amp;
done </screen>
</listitem>
<listitem>
<para>
Start ONE instance with command below (as root) and measure time between VM&#8217;s launch
and the moment when Server Manager window appears. To view VM&#8217;s desktop, connect with
VNC viewer to your host to VNC screen :1 (port 5901):
</para>
<screen>># ./start-vm.sh 1</screen>
</listitem>
<listitem>
<para>
Turn VM off. You may simply kill all KVM processes by
</para>
<screen>># killall kvm</screen>
</listitem>
<listitem>
<para>
Start FIVE instances with command below (as root) and measure time interval between ALL VM&#8217;s
launch and the moment when LAST Server Manager window appears. To view VM&#8217;s desktops,
connect with VNC viewer to your host to VNC screens :1 thru :5 (ports 5901-5905):
</para>
<screen>># ./start-vm.sh 5</screen>
</listitem>
<listitem>
<para>
Turn VMs off. You may simply kill all KVM processes by
</para>
<screen>># killall kvm</screen>
</listitem>
</orderedlist>
</section>
<section xml:id="_baseline_data">
<title>Baseline Bata</title>
<para>The table below provides baseline data which we've got in our
environment.</para>
<para><emphasis role="bold">Avg. Time</emphasis> refers to the lab with recommended
hardware configuration, while <emphasis role="bold">Max. Time</emphasis> refers
to minimal hardware configuration.</para>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="3">
<colspec colname="col_1" colwidth="33*"/>
<colspec colname="col_2" colwidth="33*"/>
<colspec colname="col_3" colwidth="33*"/>
<thead>
<row>
<entry/>
<entry>Boot ONE instance</entry>
<entry>Boot FIVE instances</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top">
<para>Avg. Time</para>
</entry>
<entry align="left" valign="top">
<para>3m:40s</para>
</entry>
<entry align="left" valign="top">
<para>8m</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>Max. Time</para>
</entry>
<entry align="left" valign="top">
<para>5m</para>
</entry>
<entry align="left" valign="top">
<para>20m</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="_host_optimizations">
<title>Host Optimizations</title>
<para>Default KVM installation could be improved to provide better
performance.</para>
<para>The following optimizations may improve host performance up to 30%:</para>
<itemizedlist>
<listitem>
<para>
change default scheduler from
<emphasis role="strong">CFQ</emphasis>
to
<emphasis role="strong">Deadline</emphasis>
</para>
</listitem>
<listitem>
<para>
use
<emphasis role="strong">ksm</emphasis>
</para>
</listitem>
<listitem>
<para>
use
<emphasis role="strong">vhost-net</emphasis>
</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="_install_software">
<title>Install OpenStack</title>
<para>Currently we use Devstack (<link xlink:href="http://devstack.org/">http://devstack.org/</link>) to
build our lab environment.
</para>
<para>Use Devstack's guide to install single VM OpenStack (<link
xlink:href="http://devstack.org/guides/single-vm.html">
http://devstack.org/guides/single-vm.html</link>) </para>
<formalpara>
<title>localrc example</title>
<para>
<screen>HOST_IP=
FLAT_INTERFACE=
FLOATING_RANGE=
ADMIN_PASSWORD=swordfish
MYSQL_PASSWORD=swordfish
RABBIT_PASSWORD=swordfish
SERVICE_PASSWORD=swordfish
SERVICE_TOKEN=tokentoken
ENABLED_SERVICES+=,heat,h-api,h-api-cfn,h-api-cw,h-eng
# Image's cache is in $TOP_DIR/files
IMAGE_URLS+=",http://fedorapeople.org/groups/heat/prebuilt-jeos-images/F17-x86_64-cfntools.qcow2"
# /etc/nova/nova.conf
EXTRA_OPTS=(force_config_drive=true libvirt_images_type=qcow2 force_raw_images=false)
# Logging
SCREEN_LOGDIR=/opt/stack/log/
LOGFILE=$SCREEN_LOGDIR/stack.sh.log </screen>
</para>
</formalpara>
<para>If you need to image builder only, then install only packages required to run
<emphasis role="strong">KVM</emphasis>
.
</para>
</section>
<section xml:id="_configure_openstack_installation">
<title>Configure OpenStack</title>
<para>New OpenStack installation requires configuration. However, if you are using
Devstack, then it's have been done.</para>
<para>Otherwise, configure your OpenStack before proceed.</para>
</section>
</chapter>
<chapter>
<title>Install Murano Components</title>
<para>Murano Components installation notes are described in Murano developer's guide. Please
consult that document.</para>
</chapter>
<chapter xml:id="_build_windows_image">
<title>Prepare Image Builder</title>
<para>Murano requires a Windows Image in QCOW2 format to be builded and uploaded into
Glance.</para>
<para>The easiest way to build Windows image for use with Murano is to build it right on the
host where your OpenStack is installed.</para>
<section xml:id="_image_builder">
<title>Image Builder</title>
<para>The following packages should be installed on any host which will be used to build
Windows Image.</para>
<section>
<title>Install Required Packages</title>
<note>
<para>Please check that hardware virtualization supported and enabled in
BIOS.</para>
</note>
<table frame="all" rowsep="1" colsep="1">
<title>Required Packages</title>
<tgroup cols="2">
<colspec colname="col_1" colwidth="50*"/>
<colspec colname="col_2" colwidth="50*"/>
<thead>
<row>
<entry>Package Name</entry>
<entry>Package Version</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top">
<para>ipxe-qemu</para>
</entry>
<entry align="left" valign="top">
<para>1.0.0+git-4.d6b0b76-0ubuntu2</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>kvm-ipxe</para>
</entry>
<entry align="left" valign="top">
<para>1.0.0+git-4.d6b0b76-0ubuntu2</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>qemu-kvm</para>
</entry>
<entry align="left" valign="top">
<para>1.4.0+dfsg-1expubuntu4</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>munin-libvirt-plugins</para>
</entry>
<entry align="left" valign="top">
<para>0.0.6-1</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>python-libvirt</para>
</entry>
<entry align="left" valign="top">
<para>1.0.2-0ubuntu11</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>libvirt-bin</para>
</entry>
<entry align="left" valign="top">
<para>1.0.2-0ubuntu11</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>libvirt0</para>
</entry>
<entry align="left" valign="top">
<para>1.0.2-0ubuntu11</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>munin-libvirt-plugins</para>
</entry>
<entry align="left" valign="top">
<para>0.0.6-1</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>python-libvirt</para>
</entry>
<entry align="left" valign="top">
<para>1.0.2-0ubuntu11</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>virt-goodies</para>
</entry>
<entry align="left" valign="top">
<para>0.4-2</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>virt-manager</para>
</entry>
<entry align="left" valign="top">
<para>0.9.4-2ubuntu3</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>virt-top</para>
</entry>
<entry align="left" valign="top">
<para>1.0.7-1</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>virt-what</para>
</entry>
<entry align="left" valign="top">
<para>1.12-1</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>virtinst</para>
</entry>
<entry align="left" valign="top">
<para>0.600.3-3ubuntu1</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>python</para>
</entry>
<entry align="left" valign="top">
<para>2.7.4-0ubuntu1</para>
</entry>
</row>
</tbody>
</tgroup>
</table>
<screen>># apt-get install ipxe-qemu kvm-ipxe qemu-kvm virt-goodies \
virtinst virt-manager libvirt0 libvirt-bin \
munin-libvirt-plugins python python-libvirt \
python-libxml2 python-minimal python-pycurl \
python-pyorbit python-requests python-six \
samba samba-common openssh-server virt-top virt-what </screen>
</section>
<section>
<title>Configure Shared Resource</title>
<formalpara>
<title>Configure samba based share</title>
<para>
<screen>># mkdir -p /opt/samba/share
># chown -R nobody:nogroup /opt/samba/share </screen>
</para>
</formalpara>
<formalpara>
<title>Configure samba server (/etc/samba/smb.conf)</title>
<para>
<screen>...
[global]
...
security = user
...
[share]
comment = Deployment Share
path = /opt/samba/share
browsable = yes
read only = no
create mask = 0755
guest ok = yes
guest account = nobody
... </screen>
</para>
</formalpara>
<formalpara>
<title>Restart services</title>
<para>
<screen>># service smbd restart
># service nmbd restart</screen>
</para>
</formalpara>
</section>
</section>
<section xml:id="_additional_software">
<title>Additional Software</title>
<para>This section describes additional software which is required to build an Windows
Image.</para>
<section xml:id="_windows_adk">
<title>Windows ADK</title>
<para><emphasis role="italic">Windows Assessment and Deployment Kit (ADK) for
Windows® 8</emphasis> is required to build your own answer files for auto
unattended Windows installation.</para>
<para>You can dowload it from <link
xlink:href="http://www.microsoft.com/en-us/download/details.aspx?id=30652">
http://www.microsoft.com/en-us/download/details.aspx?id=30652 </link>
.</para>
</section>
<section xml:id="_putty">
<title>Putty</title>
<para>PuTTY is a useful tool to manage your Linux boxes via SSH.</para>
<para>You can download it from <link
xlink:href="http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html"
> http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html </link>
</para>
</section>
<section xml:id="_windows_server_2012_iso_image">
<title>Windows Server 2012 ISO image</title>
<para>We use the following Windows installation images:</para>
<informaltable frame="all" rowsep="1" colsep="1">
<tgroup cols="2">
<colspec colname="col_1" colwidth="1*"/>
<colspec colname="col_2" colwidth="2.28*"/>
<thead>
<row>
<entry>Windows Version</entry>
<entry>Image Name</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top">
<para>Windows Server 2008 R2</para>
</entry>
<entry align="left" valign="top">
<para>7601.17514.101119-1850_x64fre_server_eval_en-us-GRMSXEVAL_EN_DVD.iso
</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>Windows Server 2012</para>
</entry>
<entry align="left" valign="top">
<para>
9200.16384.WIN8_RTM.120725-1247_X64FRE_SERVER_EVAL_EN-US-HRM_SSS_X64FREE_EN-US_DV5.iso
</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>You may download them using one of the following links:</para>
<informaltable frame="all" rowsep="1" colsep="1">
<tgroup cols="2">
<colspec colname="col_1" colwidth="1*"/>
<colspec colname="col_2" colwidth="2.3*"/>
<thead>
<row>
<entry>Windows Version</entry>
<entry>Download Link</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top">
<para>Windows Server 2008 R2</para>
</entry>
<entry align="left" valign="top">
<para>
<link
xlink:href="http://www.microsoft.com/en-us/download/details.aspx?id=11093"
>
http://www.microsoft.com/en-us/download/details.aspx?id=11093
</link>
</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>Windows Server 2012</para>
</entry>
<entry align="left" valign="top">
<para>
<link
xlink:href="http://technet.microsoft.com/en-US/evalcenter/hh670538.aspx?ocid=&amp;wt.mc_id=TEC_108_1_33"
>
http://technet.microsoft.com/en-US/evalcenter/hh670538.aspx?ocid=&amp;wt.mc_id=TEC_108_1_33
</link>
</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section xml:id="_virtio_red_hat_drivers_iso_image">
<title>VirtIO Red Hat drivers ISO image</title>
<para>Download drivers from <link
xlink:href="http://alt.fedoraproject.org/pub/alt/virtio-win/stable/">
http://alt.fedoraproject.org/pub/alt/virtio-win/stable/ </link>
</para>
<para>Please, choose stable version instead of latest, we&#8217;ve got errors with
unstable drivers during guest unattended install. </para>
</section>
<section xml:id="_create_floppy_drive_image">
<title>Floppy Image With Unattended File</title>
<para>Run following commands as root:</para>
<orderedlist numeration="arabic">
<listitem>
<para> Create empty floppy image in your home folder </para>
<screen>># dd bs=512 count=2880 \
if=/dev/zero of=~/floppy.img \
mkfs.msdos ~/floppy.img </screen>
</listitem>
<listitem>
<para> Mount the image to <emphasis role="strong">/media/floppy</emphasis>
</para>
<screen>># mkdir /media/floppy mount -o loop \
~/floppy.img /media/floppy </screen>
</listitem>
<listitem>
<para> Download <emphasis role="strong">autounattend.xml</emphasis> file
from <link
xlink:href="https://raw.github.com/stackforge/murano-deployment/master/image-builder/share/files/ws-2012-std/autounattend.xml"
>
https://raw.github.com/stackforge/murano-deployment/master/image-builder/share/files/ws-2012-std/autounattend.xml
</link>
</para>
<screen>># cd ~
># wget https://raw.github.com/stackforge/murano-deployment\
/master/image-builder/share/files/ws-2012-std/autounattend.xml </screen>
</listitem>
<listitem>
<para> Copy our <emphasis role="strong">autounattend.xml</emphasis> to
<emphasis role="strong">/media/floppy</emphasis>
</para>
<screen>># cp ~/autounattend.xml /media/floppy</screen>
</listitem>
<listitem>
<para> Unmount the image </para>
<screen>># umount /media/floppy</screen>
</listitem>
</orderedlist>
</section>
</section>
</chapter>
<chapter xml:id="_automated_build">
<title>Build Windows Image (Automatic Way)</title>
<orderedlist numeration="arabic">
<listitem>
<para> Clone <emphasis role="strong">murano-deployment</emphasis> repository </para>
<screen>># git clone git://github.com/stackforge/murano-deployment.git</screen>
</listitem>
<listitem>
<para> Change directory to <emphasis role="strong"
>murano-deployment/image-builder</emphasis> folder. </para>
</listitem>
<listitem>
<para> Create folder structure for image builder </para>
<screen>># make build-root</screen>
</listitem>
<listitem>
<para> Create shared resource </para>
<formalpara>
<title>Add to /etc/samba/smb.conf</title>
<para>
<screen>[image-builder-share]
comment = Image Builder Share
browsable = yes
path = /opt/image-builder/share
guest ok = yes
guest user = nobody
read only = no
create mask = 0755 </screen>
</para>
</formalpara>
<formalpara>
<title>Restart samba services</title>
<para>
<screen>># restart smbd &amp;&amp; restart nmbd</screen>
</para>
</formalpara>
</listitem>
<listitem>
<para> Test that all required files are in place </para>
<screen>># make test-build-files</screen>
</listitem>
<listitem>
<para> Get list of available images </para>
<screen>># make</screen>
</listitem>
<listitem>
<para> Run image build process </para>
<screen>># make ws-2012-std</screen>
</listitem>
<listitem>
<para> Wait until process finishes </para>
</listitem>
<listitem>
<para> The image file <emphasis role="strong">ws-2012-std.qcow2</emphasis> should be
stored under <emphasis role="strong">/opt/image-builder/share/images</emphasis>
folder. </para>
</listitem>
</orderedlist>
</chapter>
<chapter xml:id="_manual_build">
<title>Build Windows Image (Manual Way)</title>
<warning>
<para>Please note that the preferred way to build images is to use <emphasis
role="strong">Automated Build</emphasis> described later in this book. </para>
</warning>
<section xml:id="_get_windows_post_install_script">
<title>Get Windows Post Install script</title>
<para>All post-install actions are performed by script named <emphasis role="strong"
>wpi.ps1</emphasis>. You may download it using the link <link
xlink:href="https://raw.github.com/stackforge/murano-deployment/master/image-builder/share/scripts/ws-2012-std/wpi.ps1"
>
https://raw.github.com/stackforge/murano-deployment/master/image-builder/share/scripts/ws-2012-std/wpi.ps1
</link>
</para>
<para>To finish image preparation <emphasis role="strong">Start-Sysprep.ps1</emphasis>
script is used. You may download it using the link <link
xlink:href="https://raw.github.com/stackforge/murano-deployment/master/image-builder/share/scripts/ws-2012-std/Start-Sysprep.ps1"
>
https://raw.github.com/stackforge/murano-deployment/master/image-builder/share/scripts/ws-2012-std/Start-Sysprep.ps1
</link>
</para>
<note>
<para>There are a few scripts named <emphasis role="strong">wpi.ps1</emphasis>, each
supports only one version of Windows image. The script above is intended to be
used to create Windows Server 2012 Standard. To build other version of Windows
please use appropriate script from <emphasis role="strong">scripts</emphasis>
folder. </para>
</note>
</section>
<section xml:id="_copy_scripts_to_the_shared_folder">
<title>Copy scripts to the shared folder</title>
<para>All scripts should be copied to the shared resource folder, subfolder<emphasis
role="strong"> Scripts</emphasis>. </para>
</section>
<section xml:id="_create_guest_vm">
<title>Create guest VM</title>
<section xml:id="_way_1_from_console">
<title>Way 1 - from console</title>
<para>Run all commands as root.</para>
<formalpara>
<title>Preallocate disk image</title>
<para>
<screen>># qemu-img create -f qcow2 -o preallocation=metadata \
/var/lib/libvirt/images/winserv_vio.qcow2 20G </screen>
</para>
</formalpara>
<formalpara>
<title>Start guest install</title>
<para>
<screen>># virt-install --connect qemu:///system --hvm --name WinServ \
--ram 2048 --vcpus 2 --cdrom /opt/samba/share/9200.16384.WIN8_RTM\
.120725-1247_X64FRE_SERVER_EVAL_EN-US-HRM_SSS_X64FREE_EN-US_DV5.ISO \
--disk path=/opt/samba/share/virtio-win-0.1-52.iso,device=cdrom \
--disk path=/opt/samba/share/flop.img,device=floppy \
--disk path=/var/lib/libvirt/images/winserv_vio.qcow2\
,format=qcow2,bus=virtio,cache=none \
--network network=default,model=virtio \
--memballoon model=virtio --vnc --os-type=windows \
--os-variant=win2k8 --noautoconsole \
--accelerate --noapic --keymap=en-us --video=cirrus --force </screen>
</para>
</formalpara>
</section>
<section xml:id="_way_2_from_virt_manager_ui">
<title>Way 2 - from virt-manager UI</title>
<itemizedlist>
<listitem>
<para> launch virt-manager from shell as root </para>
</listitem>
<listitem>
<para> set Guest VM name and Local install media </para>
</listitem>
<listitem>
<para> add 1 cdrom - Windows Server ISO image </para>
</listitem>
<listitem>
<para> set OS type: Windows and version: Windows Server 2008 </para>
</listitem>
<listitem>
<para> set CPU and RAM amount </para>
</listitem>
<listitem>
<para> deselect Enable storage for this virtual machine </para>
</listitem>
<listitem>
<para> select Customize configuration before install </para>
</listitem>
<listitem>
<para> add 2 cdrom - virtio ISO image </para>
</listitem>
<listitem>
<para> add floppy - our floppy image </para>
</listitem>
<listitem>
<para> add/or create HDD image with Disk bus: VirtIO and storage format:
QCOW2 </para>
</listitem>
<listitem>
<para> set network device model: VirtIO </para>
</listitem>
<listitem>
<para> If everything OK - start installation process, guest vm screen
accessible through Console button </para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="_finish_process">
<title>Finish process</title>
<para>After install process finished for reference image compression run as root</para>
<screen>># qemu-img convert -O qcow2 /var/lib/libvirt/images/winserv_vio.qcow2 \
/var/lib/libvirt/images/winserv_vio_ref.qcow2 </screen>
</section>
</chapter>
<chapter xml:id="_post_building_setup">
<title>Upload Image Into Glance</title>
<para>
Services deployed by Murano require specially prepared images, that can be created manually or via
automated scripts. Please refer to corresponding chapters of this book to create image. After images are
created they should be registered in Openstack Glance - image operation service.
</para>
<orderedlist>
<listitem>
<para> Use the glance image-create command to import your disk image to Glance:
<<<<<<< HEAD
<screen width="50">>$ glance image-create --name &lt;NAME> --is-public true \
--disk-format qcow2 --container-format bare --file &lt;IMAGE_FILE> \
--property &lt;IMAGE_METADATA></screen>
=======
<screen>>$ glance image-create --name &lt;NAME> --is-public true \
--disk-format qcow2 --container-format bare --file &lt;IMAGE_FILE> \
--property &lt;IMAGE_METADATA></screen>
>>>>>>> 33f5a6d52739bea6bc661c7b12c37b0b4dcb5b84
</para>
<para>
Replace the command line arguments to glance image-create with the
appropriate values for your environment and disk image:
</para>
<itemizedlist>
<listitem>
<para>Replace <emphasis role="bold">&lt;NAME></emphasis> with the name that
users will refer to the disk image by. E.g. '<emphasis role="bold"
>ws-2012-std</emphasis>'</para>
</listitem>
<listitem>
<para> Replace <emphasis role="bold">&lt;IMAGE_FILE></emphasis> with the
local path to the image file to upload. E.g. '<emphasis role="bold"
>ws-2012-std.qcow2</emphasis>'.</para>
</listitem>
<listitem>
<para> Replace IMAGE_METADATA with the following property string
<<<<<<< HEAD
<screen width="50">murano_image_info='{"title": "Windows 2012 Core Edition", "type": "ws-2012-core"}</screen>where<itemizedlist>
=======
<screen>murano_image_info='{"title": "Windows 2012 Core Edition", "type": "ws-2012-core"}</screen>where<itemizedlist>
>>>>>>> 33f5a6d52739bea6bc661c7b12c37b0b4dcb5b84
<listitem>
<para>title - user-friendly description of the image</para>
</listitem>
<listitem>
<para>type - one of possible image types<itemizedlist>
<listitem>
<para>ws-2012-std - Windows Server 2012 Standart
Edition</para>
</listitem>
<listitem>
<para>ws-2012-core - Windows 2012 Core
Edition</para>
</listitem>
<listitem>
<para>ws-2008r2-std - Windows Server 2008R2 Standart
Edition</para>
</listitem>
<listitem>
<para>ws-2008r2 - Windows Server 2012R2</para>
</listitem>
</itemizedlist></para>
</listitem>
</itemizedlist><warning>
<para>Setting <emphasis>murano_image_info</emphasis> property is
required to pick up image from Murano Dashboard.</para>
</warning>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>To update metadata of the existing image run the command:</para>
<screen>>$ glance image-update &lt;IMAGE-ID> --property &lt;IMAGE_MATADATA></screen>
<itemizedlist>
<listitem>
<para>Replace <emphasis role="bold">&lt;IMAGE-ID></emphasis> with image id
from the previous command output.</para>
</listitem>
<listitem>
<para> Replace <emphasis role="bold">&lt;IMAGE_METADATA></emphasis> with
murano_image_info property,
<<<<<<< HEAD
e.g.<screen width="50">murano_image_info='{"title": "Windows 2012 Core Edition","type": "ws-2012-core"}'</screen></para>
=======
e.g.<screen>murano_image_info='{"title": "Windows 2012 Core Edition","type": "ws-2012-core"}'</screen></para>
>>>>>>> 33f5a6d52739bea6bc661c7b12c37b0b4dcb5b84
</listitem>
</itemizedlist>
</listitem>
</orderedlist>
<para>After these steps desired image can be chosen in Murano dashboard and used for services platform.</para>
</chapter>
</book>

43
src/developers-guide/src/docbkx/content/appendix.xml → src/administrators-guide/src/docbkx/content/appendix.xml
View File

@ -48,39 +48,26 @@
</listitem>
<listitem>
<para>Enable Cloud Archive repository</para>
</listitem>
<listitem>
<para>Update installed OS and packages</para>
</listitem>
<listitem>
<para>Create and add the following lines to the
<filename>/etc/apt/sources.list.d/grizzly.list</filename>
file
<programlisting>
<para>Create and add the following lines to the
<filename>/etc/apt/sources.list.d/grizzly.list</filename>
file
<programlisting>
deb http://ubuntu-cloud.archive.canonical.com/ubuntu \
precise-updates/grizzly main
deb http://archive.gplhost.com/debian grizzly main
deb http://archive.gplhost.com/debian grizzly-backports main
</programlisting>
</para>
</programlisting>
</para>
</listitem>
<listitem>
<para>Update the system
<para>Update installed OS and packages</para>
<programlisting>
># apt-get update
># apt-get install ubuntu-cloud-keyring
># apt-get install gplhost-archive-keyring
># apt-get install mc unzip git make gcc python-setuptools python-pip
># apt-get upgrade
</programlisting>
</para>
</listitem>
<listitem>
<para>Install additional packages
<programlisting>
># apt-get install mc unzip git make gcc
python-setuptools python-pip
</programlisting>
</para>
</listitem>
</itemizedlist>
<para>
@ -101,28 +88,18 @@ deb http://archive.gplhost.com/debian grizzly-backports main
<para>Enable RedHat Openstack and Epel repository</para>
</listitem>
<listitem>
<para>Update installed OS and packages</para>
</listitem>
<listitem>
<para>Add repositories and update OS
<para>Update system and add repositories and update OS
<programlisting>
># yum install -y http://rdo.fedorapeople.org/openstack/\
openstack-grizzly/rdo-release-grizzly.rpm
># yum install -y http://mirror.us.leaseweb.net/\
epel/6/x86_64/epel-release-6-8.noarch.rpm
># yum install -y mc unzip git make gcc python-setuptools python-pip upstart
># yum update
># yum upgrade
</programlisting>
</para>
</listitem>
<listitem>
<para>Install additional packages
<programlisting>
># yum install -y mc unzip git make gcc python-setuptools \
python-pip upstart
</programlisting>
</para>
</listitem>
</itemizedlist>
<para>
Most of dependent packages will be installed

358
src/administrators-guide/src/docbkx/content/general.xml Normal file
View File

@ -0,0 +1,358 @@
<?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>General Deployment Steps</title>
<section>
<title>Prepare A Lab For Murano</title>
<para>
This section provides basic information about lab's system requirements. It also contains a description
of a test which you may use to check if your hardware fits the requirements. To do this, run the test
and compare the results with baseline data provided.
</para>
<section>
<title>Lab Requirements</title>
<table xml:id="_hardware_requirements" frame="all">
<title>Hardware requirements</title>
<tgroup cols="3" align="left" rowsep="1" colsep="1">
<colspec colname="col1" colwidth="1*"/>
<colspec colname="col2" colwidth="3*"/>
<colspec colname="col3" colwidth="3*"/>
<thead>
<row>
<entry>Criteria</entry>
<entry>Minimal</entry>
<entry>Recommended</entry>
</row>
</thead>
<tbody>
<row>
<entry>CPU</entry>
<entry>4 core @ 2.4 GHz</entry>
<entry>24 core @ 2.67 GHz</entry>
</row>
<row>
<entry>RAM</entry>
<entry>8 GB</entry>
<entry>24 GB or more</entry>
</row>
<row>
<entry>HDD</entry>
<entry>2 x 500 GB (7200 rpm)</entry>
<entry>4 x 500 GB (7200 rpm)</entry>
</row>
<row>
<entry>RAID</entry>
<entry>Software RAID-1 (use mdadm as it will improve read performance almost two times)</entry>
<entry>Hardware RAID-10</entry>
</row>
</tbody>
</tgroup>
</table>
<para>
There are a few possible storage configurations except the shown above. All of them were tested and were working well.
</para>
<para>
<itemizedlist>
<listitem>
<para>
1x SSD 500+ GB
</para>
</listitem>
<listitem>
<para>
1x HDD (7200 rpm) 500+ GB and 1x SSD 250+ GB (install the system onto the HDD and mount the SSD drive to folder where VM images are)
</para>
</listitem>
<listitem>
<para>
1x HDD (15000 rpm) 500+ GB
</para>
</listitem>
</itemizedlist>
</para>
<para>
The list of OSes which we used in our lab is shown below.
</para>
<table xml:id="_software_requirements" frame="all">
<title>OS Requirements</title>
<tgroup cols="1" align="left" rowsep="1" colsep="1">
<colspec colname="col1" colwidth="1*"/>
<thead>
<row>
<entry>List</entry>
</row>
</thead>
<tbody>
<row>
<entry>Ubuntu Server 12.04 LTS</entry>
</row>
</tbody>
</tgroup>
</table>
</section>
<section>
<title>Test Your Lab Host Performance</title>
<para>
We have measured time required to boot 1 to 5 instances of Windows system simultaneously. You can use
this data as the baseline to check if your system is fast enough.
</para>
<para>
You should use sysprepped images for this test, to simulate VM first boot.
</para>
<para>
Steps to reproduce test:
</para>
<orderedlist numeration="arabic">
<listitem>
<para>
Prepare Windows 2012 Standard (with GUI) image in QCOW2 format. Let's assume that its name is ws-2012-std.qcow2
</para>
</listitem>
<listitem>
<para>
Ensure that there is NO KVM PROCESSES on the host. To do this, run command:
<screen>
># ps aux | grep kvm
</screen>
</para>
</listitem>
<listitem>
<para>
Make 5 copies of Windows image file:
</para>
<screen>
># for i in $(seq 5); do \
cp ws-2012-std.qcow2 ws-2012-std-$i.qcow2; done
</screen>
</listitem>
<listitem>
<para>
Create script start-vm.sh in the folder with .qcow2 files:
</para>
<screen>
#!/bin/bash
[ -z $1 ] || echo "VM count not provided!"; exit 1
for i in $(seq $1); do
echo "Starting VM $i ..."
kvm \
-m 1024 \
-drive file=ws-2012-std-$i.qcow2,if=virtio \
-net user -net nic,model=virtio \
-nographic \
-usbdevice tablet \
-vnc :$i &amp;
done
</screen>
</listitem>
<listitem>
<para>
Start ONE instance with command below (as root) and measure time between VM&#8217;s launch and
the moment when Server Manager window appears. To view VM&#8217;s desktop, connect with VNC viewer to your host to VNC screen :1 (port 5901):
</para>
<screen>
># ./start-vm.sh 1
</screen>
</listitem>
<listitem>
<para>
Turn VM off. You may simply kill all KVM processes by
</para>
<screen>
># killall kvm
</screen>
</listitem>
<listitem>
<para>
Start FIVE instances with command below (as root) and measure time interval between ALL VM&#8217;s
launch and the moment when LAST Server Manager window appears. To view VM&#8217;s desktops, connect with
VNC viewer to your host to VNC screens :1 thru :5 (ports 5901-5905):
</para>
<screen>
># ./start-vm.sh 5
</screen>
</listitem>
<listitem>
<para>
Turn VMs off. You may simply kill all KVM processes by
</para>
<screen>
># killall kvm
</screen>
</listitem>
</orderedlist>
</section>
<section>
<title>Baseline Bata</title>
<para>
The table below provides baseline data which we've got in our environment.
</para>
<para>
<emphasis role="bold">Avg. Time</emphasis> refers to the lab with recommended hardware configuration, while
<emphasis role="bold">Max. Time</emphasis> refers to minimal hardware configuration.
</para>
<informaltable
frame="all"
rowsep="1" colsep="1"
>
<tgroup cols="3">
<colspec colname="col_1" colwidth="33*"/>
<colspec colname="col_2" colwidth="33*"/>
<colspec colname="col_3" colwidth="33*"/>
<thead>
<row>
<entry/>
<entry>Boot ONE instance</entry>
<entry>Boot FIVE instances</entry>
</row>
</thead>
<tbody>
<row>
<entry align="left" valign="top">
<para>Avg. Time</para>
</entry>
<entry align="left" valign="top">
<para>3m:40s</para>
</entry>
<entry align="left" valign="top">
<para>8m</para>
</entry>
</row>
<row>
<entry align="left" valign="top">
<para>Max. Time</para>
</entry>
<entry align="left" valign="top">
<para>5m</para>
</entry>
<entry align="left" valign="top">
<para>20m</para>
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</section>
<section>
<title>Host Optimizations</title>
<para>
Default KVM installation could be improved to provide better performance.
</para>
<para>
The following optimizations may improve host performance up to 30%:
</para>
<itemizedlist>
<listitem>
<para>
change default scheduler from <emphasis role="strong">CFQ</emphasis> to
<emphasis role="strong">Deadline</emphasis>
</para>
</listitem>
<listitem>
<para>
use <emphasis role="strong">ksm</emphasis>
</para>
</listitem>
<listitem>
<para>
use <emphasis role="strong">vhost-net</emphasis>
</para>
</listitem>
</itemizedlist>
</section>
</section>
<section>
<title>Install OpenStack</title>
<para>
We use Devstack (<link xlink:href="http://devstack.org/">http://devstack.org/</link>) to build our lab environment.
</para>
<para>
Devstack is a set of scripts to automate OpenStack installation using sources from Git repositories.
No packages are built and installed during this process, all OpenStack components are executed in separate consoles (via screen utility).
</para>
<para>
It is a great tool to quickly install and start to develop OpenStack on you server. However, it has a few caveats that should be kept in mind:
</para>
<itemizedlist>
<listitem>
<para>
Devstack scripts must be executed each time the host reboots. This also reset your OpenStack environment to it’s ‘just installed’ state.
</para>
</listitem>
<listitem>
<para>
Multi-node configurations are not as easy in installation as single-node.
</para>
</listitem>
</itemizedlist>
<para>
Below are the general steps that required to install OpenStack using Devstack in a Single-node mode.
</para>
<para>
Use Devstack's guide to install single VM OpenStack (<link xlink:href="http://devstack.org/guides/single-vm.html"> http://devstack.org/guides/single-vm.html</link>)
</para>
<formalpara>
<title>localrc example</title>
<para>
<screen width="80">
HOST_IP=
FLAT_INTERFACE=
FLOATING_RANGE=
ADMIN_PASSWORD=swordfish
MYSQL_PASSWORD=swordfish
RABBIT_PASSWORD=swordfish
SERVICE_PASSWORD=swordfish
SERVICE_TOKEN=tokentoken
ENABLED_SERVICES+=,heat,h-api,h-api-cfn,h-api-cw,h-eng
# Image's cache is in $TOP_DIR/files
IMAGE_URLS+=",http://fedorapeople.org/groups/heat/prebuilt-jeos-images/"
IMAGE_URLS+="F17-x86_64-cfntools.qcow2"
# /etc/nova/nova.conf
EXTRA_OPTS=(force_config_drive=true libvirt_images_type=qcow2 force_raw_images=false)
# Logging
SCREEN_LOGDIR=/opt/stack/log/
LOGFILE=$SCREEN_LOGDIR/stack.sh.log
</screen>
</para>
</formalpara>
<para>
If you need to image builder only, then install only packages required to run <emphasis role="strong">KVM</emphasis> (see below).
</para>
</section>
<section>
<title>Configure OpenStack</title>
<note>
<para>
Additional OpenStack configuration usually doesn't required in case you've installed OpenStack with Devstack scripts.
</para>
</note>
<para>
To configure OpenStack is not a simple task and depends on various options (hardware configuration, network layout, and so on) and in general is out of scope of this document.
</para>
</section>
</chapter>

794
src/administrators-guide/src/docbkx/content/image-bulder.xml Normal file
View File

@ -0,0 +1,794 @@
<?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>Image Builder</title>
<para>
Murano requires a Windows Image in QCOW2 format to be builded and uploaded into Glance.
</para>
<para>
The easiest way to build Windows image for Murano is to build it on the host where your OpenStack is installed.
</para>
<section>
<title>Install Required Packages</title>
<note>
<para>
Please check that hardware virtualization supported and enabled in BIOS.
</para>
</note>
<para>
The following packages should be installed on any host which will be used to build Windows Image:
<itemizedlist>
<listitem>
<para>
ipxe-qemu
</para>
</listitem>
<listitem>
<para>
kvm-ipxe
</para>
</listitem>
<listitem>
<para>
qemu-kvm
</para>
</listitem>
<listitem>
<para>
munin-libvirt-plugins
</para>
</listitem>
<listitem>
<para>
python-libvirt
</para>
</listitem>
<listitem>
<para>
libvirt-bin
</para>
</listitem>
<listitem>
<para>
libvirt0
</para>
</listitem>
<listitem>
<para>
munin-libvirt-plugins
</para>
</listitem>
<listitem>
<para>
python-libvirt
</para>
</listitem>
<listitem>
<para>
virt-goodies
</para>
</listitem>
<listitem>
<para>
virt-manager
</para>
</listitem>
<listitem>
<para>
virt-top
</para>
</listitem>
<listitem>
<para>
virt-what
</para>
</listitem>
<listitem>
<para>
virtinst
</para>
</listitem>
<listitem>
<para>
python
</para>
</listitem>
</itemizedlist>
</para>
<para>
On Ubuntu you could install them using the command below:
</para>
<screen>
># apt-get install ipxe-qemu kvm-ipxe qemu-kvm virt-goodies \
virtinst virt-manager libvirt0 libvirt-bin \
munin-libvirt-plugins python python-libvirt \
python-libxml2 python-minimal python-pycurl \
python-pyorbit python-requests python-six \
samba samba-common openssh-server virt-top virt-what
</screen>
</section>
<section>
<title>Configure Shared Resource</title>
<formalpara>
<title>Configure samba based share</title>
<para>
<screen>
># mkdir -p /opt/samba/share
># chown -R nobody:nogroup /opt/samba/share
</screen>
</para>
</formalpara>
<formalpara>
<title>Configure samba server (/etc/samba/smb.conf)</title>
<para>
<screen>
...
[global]
...
security = user
...
[share]
comment = Deployment Share
path = /opt/samba/share
browsable = yes
read only = no
create mask = 0755
guest ok = yes
guest account = nobody
...
</screen>
</para>
</formalpara>
<formalpara>
<title>Restart services</title>
<para>
<screen>
># service smbd restart
># service nmbd restart
</screen>
</para>
</formalpara>
</section>
<section>
<title>Prerequisites</title>
<para>Download the files below and copy them into their places in your <emphasis
role="bold">${SHARE_PATH}</emphasis> folder (we usually use <emphasis
role="bold">/opt/samba/share</emphasis> as <emphasis role="bold"
>${SHARE_PATH}</emphasis>):<itemizedlist>
<listitem>
<para>Windows 2012 Server ISO evaluation version<itemizedlist>
<listitem>
<para>${SHARE_PATH}/libvirt/images/ws-2012-eval.iso</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://technet.microsoft.com/en-us/evalcenter/hh670538.aspx">
http://technet.microsoft.com/en-us/evalcenter/hh670538.aspx
</link>
</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>VirtIO drivers for Windows<itemizedlist>
<listitem>
<para>${SHARE_PATH}/libvirt/images/virtio-win-0.1-52.iso</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://alt.fedoraproject.org/pub/alt/virtio-win/stable/virtio-win-0.1-52.iso">
http://alt.fedoraproject.org/pub/alt/virtio-win/stable/virtio-win-0.1-52.iso
</link>
</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>CloudBase-Init for Windows<itemizedlist>
<listitem>
<para>${SHARE_PATH}/share/files/CloudbaseInitSetup_Beta.msi</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://www.cloudbase.it/downloads/CloudbaseInitSetup_Beta.msi">
http://www.cloudbase.it/downloads/CloudbaseInitSetup_Beta.msi
</link>
</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>Far Manager<itemizedlist>
<listitem>
<para>${SHARE_PATH}/share/files/Far30b3367.x64.20130426.msi</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://www.farmanager.com/files/Far30b3525.x64.20130717.msi">
http://www.farmanager.com/files/Far30b3525.x64.20130717.msi
</link>
</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>Git client<itemizedlist>
<listitem>
<para>${SHARE_PATH}/share/files/Git-1.8.1.2-preview20130201.exe</para>
</listitem>
<listitem>
<para>
<link xlink:href="https://msysgit.googlecode.com/files/Git-1.8.3-preview20130601.exe">
https://msysgit.googlecode.com/files/Git-1.8.3-preview20130601.exe
</link>
</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>Sysinternals Suite<itemizedlist>
<listitem>
<para>${SHARE_PATH}/share/files/SysinternalsSuite.zip</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://download.sysinternals.com/files/SysinternalsSuite.zip">
http://download.sysinternals.com/files/SysinternalsSuite.zip
</link>
</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>unzip.exe tool<itemizedlist>
<listitem>
<para>${SHARE_PATH}/share/files/unzip.exe</para>
</listitem>
<listitem>
<para>
<link xlink:href="https://www.dropbox.com/sh/zthldcxnp6r4flm/-k1Om_V6XR">
https://www.dropbox.com/sh/zthldcxnp6r4flm/-k1Om_V6XR
</link>
</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>PowerShell v3<itemizedlist>
<listitem>
<para>${SHARE_PATH}/share/files/Windows6.1-KB2506143-x64.msu</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://www.microsoft.com/en-us/download/details.aspx?id=34595">
http://www.microsoft.com/en-us/download/details.aspx?id=34595
</link>
</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>.NET 4.0<itemizedlist>
<listitem>
<para>${SHARE_PATH}/share/files/dotNetFx40_Full_x86_x64.exe</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://www.microsoft.com/en-us/download/details.aspx?id=17718">
http://www.microsoft.com/en-us/download/details.aspx?id=17718
</link>
</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>.NET 4.5<itemizedlist>
<listitem>
<para>${SHARE_PATH}/share/files/dotNetFx45_Full_setup.exe</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://www.microsoft.com/en-us/download/details.aspx?id=30653">
http://www.microsoft.com/en-us/download/details.aspx?id=30653
</link>
</para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>Murano Agent<itemizedlist>
<listitem>
<para>${SHARE_PATH}/share/files/MuranoAgent.zip</para>
</listitem>
<listitem>
<para>
<link xlink:href="https://www.dropbox.com/sh/zthldcxnp6r4flm/-k1Om_V6XR">
https://www.dropbox.com/sh/zthldcxnp6r4flm/-k1Om_V6XR
</link>
</para>
</listitem>
</itemizedlist></para>
</listitem>
</itemizedlist></para>
</section>
<section>
<title>Additional Software</title>
<para> This section describes additional software which is required to build an Windows
Image.</para>
<para><emphasis role="bold">Windows ADK</emphasis></para>
<para>
<emphasis role="italic">Windows Assessment and Deployment Kit (ADK) for Windows®
8</emphasis> is required to build your own answer files for auto unattended
Windows installation. </para>
<para>
You can dowload it from <link xlink:href="http://www.microsoft.com/en-us/download/details.aspx?id=30652">
http://www.microsoft.com/en-us/download/details.aspx?id=30652</link>.
</para>
<para><emphasis role="bold">PuTTY</emphasis></para>
<para>PuTTY is a useful tool to manage your Linux boxes via SSH.</para>
<para>
You can download it from <link xlink:href="http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html">
http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html</link>.
</para>
<para><emphasis role="bold">Windows Server 2012 ISO image</emphasis></para>
<para>We use the following Windows installation images:<itemizedlist>
<listitem>
<para>Windows Server 2008 R2<itemizedlist>
<listitem>
<para>Image Name:
7601.17514.101119-1850_x64fre_server_eval_en-us-GRMSXEVAL_EN_DVD.iso</para>
</listitem>
<listitem>
<para>URL: <link
xlink:href="http://www.microsoft.com/en-us/download/details.aspx?id=11093"
>
http://www.microsoft.com/en-us/download/details.aspx?id=11093
</link></para>
</listitem>
</itemizedlist></para>
</listitem>
<listitem>
<para>Windows Server 2012<itemizedlist>
<listitem>
<para>Image Name:
9200.16384.WIN8_RTM.120725-1247_X64FRE_SERVER_EVAL_EN-US-HRM_SSS_X64FREE_EN-US_DV5.iso</para>
</listitem>
<listitem>
<para>URL: <link
xlink:href="http://technet.microsoft.com/en-US/evalcenter/hh670538.aspx?ocid=&amp;wt.mc_id=TEC_108_1_33"
>
http://technet.microsoft.com/en-US/evalcenter/hh670538.aspx?ocid=&amp;wt.mc_id=TEC_108_1_33
</link></para>
</listitem>
</itemizedlist></para>
</listitem>
</itemizedlist></para>
<para><emphasis role="bold">VirtIO Red Hat drivers ISO image</emphasis></para>
<warning>
<para>
Please, choose stable version instead of latest, We&#8217;ve got errors with unstable drivers during guest unattended install.
</para>
</warning>
<para>Download drivers from <link xlink:href="http://alt.fedoraproject.org/pub/alt/virtio-win/stable/">
http://alt.fedoraproject.org/pub/alt/virtio-win/stable/</link>
</para>
<para><emphasis role="bold">Floppy Image With Unattended File</emphasis></para>
<para>
Run following commands as root:
</para>
<orderedlist numeration="arabic">
<listitem>
<para>
Create emtpy floppy image in your home folder
</para>
<screen>
># dd bs=512 count=2880 \
if=/dev/zero of=~/floppy.img \
mkfs.msdos ~/floppy.img
</screen>
</listitem>
<listitem>
<para>
Mount the image to <emphasis role="strong">/media/floppy</emphasis>
</para>
<screen>
># mkdir /media/floppy mount -o loop \
~/floppy.img /media/floppy
</screen>
</listitem>
<listitem>
<para>
Download <emphasis role="strong">autounattend.xml</emphasis> file from <link
xlink:href="https://raw.github.com/stackforge/murano-deployment/master/image-builder/share/files/ws-2012-std/autounattend.xml">
https://raw.github.com/stackforge/murano-deployment/master/image-builder/share/files/ws-2012-std/autounattend.xml
</link>
</para>
<screen>
># cd ~
># wget https://raw.github.com/stackforge/murano-deployment\
/master/image-builder/share/files/ws-2012-std/autounattend.xml
</screen>
</listitem>
<listitem>
<para>
Copy our <emphasis role="strong">autounattend.xml</emphasis> to <emphasis role="strong">/media/floppy</emphasis>
</para>
<screen>
># cp ~/autounattend.xml /media/floppy
</screen>
</listitem>
<listitem>
<para>
Unmount the image
</para>
<screen>
># umount /media/floppy
</screen>
</listitem>
</orderedlist>
</section>
<section>
<title>Build Windows Image (Automatic Way)</title>
<orderedlist numeration="arabic">
<listitem>
<para>Clone <emphasis role="strong">murano-deployment</emphasis> repository </para>
<screen>
># git clone git://github.com/stackforge/murano-deployment.git
</screen>
</listitem>
<listitem>
<para>Change directory to <emphasis role="strong"
>murano-deployment/image-builder</emphasis> folder. </para>
</listitem>
<listitem>
<para>Create folder structure for image builder </para>
<screen>
># make build-root
</screen>
</listitem>
<listitem>
<para>Create shared resource </para>
<formalpara>
<title>Add to /etc/samba/smb.conf</title>
<para>
<screen>
[image-builder-share]
comment = Image Builder Share
browsable = yes
path = /opt/image-builder/share
guest ok = yes
guest user = nobody
read only = no
create mask = 0755
</screen>
</para>
</formalpara>
<formalpara>
<title>Restart samba services</title>
<para>
<screen>
># restart smbd &amp;&amp; restart nmbd
</screen>
</para>
</formalpara>
</listitem>
<listitem>
<para>Test that all required files are in place </para>
<screen>
># make test-build-files
</screen>
</listitem>
<listitem>
<para>Get list of available images </para>
<screen>
># make
</screen>
</listitem>
<listitem>
<para>Run image build process </para>
<screen>
># make ws-2012-std
</screen>
</listitem>
<listitem>
<para>Wait until process finishes </para>
</listitem>
<listitem>
<para>The image file <emphasis role="strong">ws-2012-std.qcow2</emphasis> should be
stored under <emphasis role="strong">/opt/image-builder/share/images</emphasis>
folder. </para>
</listitem>
</orderedlist>
</section>
<section>
<title>Build Windows Image (Manual Way)</title>
<warning>
<para> Please note that the preferred way to build images is to use <emphasis
role="strong">Automated Build</emphasis> described in the previous chapter. </para>
</warning>
<para><emphasis role="strong">Get Post-Install Scripts</emphasis></para>
<para>There are a few scripts which perform all the required post-installation tasks. </para>
<para>Package installation tasks are performed by script named <emphasis role="strong"
>wpi.ps1</emphasis>. </para>
<para>Download it from <link
xlink:href="https://raw.github.com/stackforge/murano-deployment/master/image-builder/share/scripts/ws-2012-std/wpi.ps1"
>
https://raw.github.com/stackforge/murano-deployment/master/image-builder/share/scripts/ws-2012-std/wpi.ps1</link>
</para>
<note>
<para>There are a few scripts named <emphasis role="strong">wpi.ps1</emphasis>, each
supports only one version of Windows image. The script above is intended to be
used to create Windows Server 2012 Standard. To build other version of Windows
please use appropriate script from <emphasis role="strong">scripts</emphasis>
folder. </para>
</note>
<para>Clean-up actions to finish image preparation are performed by <emphasis role="strong">Start-Sysprep.ps1</emphasis>
script.</para>
<para>Download it from <link
xlink:href="https://raw.github.com/stackforge/murano-deployment/master/image-builder/share/scripts/ws-2012-std/Start-Sysprep.ps1"
>
https://raw.github.com/stackforge/murano-deployment/master/image-builder/share/scripts/ws-2012-std/Start-Sysprep.ps1</link>
</para>
<para>These scripts should be copied to the shared resource folder, subfolder <emphasis
role="strong">Scripts</emphasis>.</para>
<para><emphasis role="strong">Create a VM</emphasis></para>
<para>This section describes steps required to build an image of Windows Virtual Machine
which could be used with Murano. There are two possible ways to create it - from
CLI or using GUI tools. We describe both in this section. </para>
<note>
<para>
Run all commands as root.
</para>
</note>
<para><emphasis role="strong">Way 1: Using CLI Tools</emphasis></para>
<para>This section describes the required step to launch a VM using CLI tools only. </para>
<para>
<orderedlist>
<listitem>
<para>
Preallocate disk image
</para>
<screen>
># qemu-img create -f raw /var/lib/libvirt/images/ws-2012.img 40G
</screen>
</listitem>
<listitem>
<para>
Start the VM
</para>
<screen>
># virt-install --connect qemu:///system --hvm --name WinServ \
--ram 2048 --vcpus 2 --cdrom /opt/samba/share/9200.16384.WIN8_RTM\
.120725-1247_X64FRE_SERVER_EVAL_EN-US-HRM_SSS_X64FREE_EN-US_DV5.ISO \
--disk path=/opt/samba/share/virtio-win-0.1-52.iso,device=cdrom \
--disk path=/opt/samba/share/floppy.img,device=floppy \
--disk path=/var/lib/libvirt/images/ws-2012.qcow2\
,format=qcow2,bus=virtio,cache=none \
--network network=default,model=virtio \
--memballoon model=virtio --vnc --os-type=windows \
--os-variant=win2k8 --noautoconsole \
--accelerate --noapic --keymap=en-us --video=cirrus --force
</screen>
</listitem>
</orderedlist>
</para>
<para><emphasis role="strong">Way 2: Using virt-manager UI</emphasis></para>
<para>A VM also could be lauched via GUI tools like virt-manager. </para>
<para>
<orderedlist>
<listitem>
<para>Launch <emphasis role="italic">virt-manager</emphasis> from shell
as root </para>
</listitem>
<listitem>
<para>Set a name for VM and select Local install media</para>
</listitem>
<listitem>
<para>Add one cdrom and attach Windows Server ISO image to it</para>
</listitem>
<listitem>
<para>Select OS type <emphasis role="bold">Windows</emphasis> and it's
version <emphasis role="bold">Windows Server 2008</emphasis>
</para>
</listitem>
<listitem>
<para>Set CPU and RAM amount </para>
</listitem>
<listitem>
<para>Deselect option <emphasis role="bold">Enable storage for this
virtual machine</emphasis>
</para>
</listitem>
<listitem>
<para>Select option <emphasis role="bold">Customize configuration before
install</emphasis>
</para>
</listitem>
<listitem>
<para>Add second cdrom for ISO image with virtio drivers</para>
</listitem>
<listitem>
<para>Add a floppy drive and attach our floppy image to it</para>
</listitem>
<listitem>
<para>Add (or create new) HDD image with Disk bus <emphasis role="bold"
>VirtIO</emphasis> and storage format <emphasis role="bold"
>RAW</emphasis>
</para>
</listitem>
<listitem>
<para>Set network device model <emphasis role="bold">VirtIO</emphasis>
</para>
</listitem>
<listitem>
<para>Start installation process and open guest vm screen through
<emphasis role="bold">Console</emphasis> button </para>
</listitem>
</orderedlist>
</para>
<formalpara>
<title>Convert the image from RAW to QCOW2 format</title>
<para>The image must be converted from RAW format to QCOW2 before being imorted into
Glance. </para>
</formalpara>
<para>
<screen>
># qemu-img convert -O qcow2 /var/lib/libvirt/images/ws-2012.raw \
/var/lib/libvirt/images/ws-2012-ref.qcow2
</screen>
</para>
</section>
<section>
<title>Upload Image Into Glance</title>
<para>
Services deployed by Murano require specially prepared images, that can be created manually or via automated scripts.
Please refer to corresponding chapters of this book to create image. After images are created they should be registered in Openstack Glance - image operation service.
</para>
<orderedlist>
<listitem>
<para>
Use the glance image-create command to import your disk image to Glance:
<screen>
>$ glance image-create --name &lt;NAME> \
--is-public true --disk-format qcow2 \
--container-format bare \
--file &lt;IMAGE_FILE> \
--property &lt;IMAGE_METADATA>
</screen>
</para>
<para>
Replace the command line arguments to glance image-create with the appropriate values for your environment and disk image:
</para>
<itemizedlist>
<listitem>
<para>
Replace <emphasis role="bold">&lt;NAME></emphasis> with the name that users will refer to the disk image by.
E.g. '<emphasis role="bold">ws-2012-std</emphasis>'
</para>
</listitem>
<listitem>
<para>
Replace <emphasis role="bold">&lt;IMAGE_FILE></emphasis> with the local path to the image file to upload.
E.g. '<emphasis role="bold">ws-2012-std.qcow2</emphasis>'.
</para>
</listitem>
<listitem>
<para> Replace <emphasis role="bold">&lt;IMAGE_METADATA></emphasis> with the
following property string
<screen>
murano_image_info='{"title": "Windows 2012 Core Edition", "type": "ws-2012-core"}
</screen>
where <itemizedlist>
<listitem>
<para> title - user-friendly description of the image
</para>
</listitem>
<listitem>
<para> type - one of possible image types <itemizedlist>
<listitem>
<para> ws-2012-std - Windows Server 2012 Standart
Edition </para>
</listitem>
<listitem>
<para> ws-2012-core - Windows 2012 Core Edition
</para>
</listitem>
<listitem>
<para> ws-2008r2-std - Windows Server 2008R2
Standart Edition </para>
</listitem>
<listitem>
<para> ws-2008r2 - Windows Server 2012R2 </para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para> To update metadata of the existing image run the command:</para>
<screen>
>$ glance image-update &lt;IMAGE-ID> --property &lt;IMAGE_MATADATA>
</screen>
<itemizedlist>
<listitem>
<para>
Replace <emphasis role="bold">&lt;IMAGE-ID></emphasis> with image id from the previous command output.
</para>
</listitem>
<listitem>
<para> Replace <emphasis role="bold">&lt;IMAGE_METADATA></emphasis> with
murano_image_info property, e.g.
<screen>
murano_image_info='{"title": "Windows 2012 Core Edition", "type": "ws-2012-core"}'
</screen>
</para>
</listitem>
</itemizedlist>
</listitem>
</orderedlist>
<warning>
<para>The value of the <emphasis role="bold"
>--property</emphasis> argument named <emphasis
role="bold">murano_image_info</emphasis> is a JSON
string. Only double quotes are valid in JSON, so please type
the string exactly as in the example above. </para>
</warning>
<para>
After these steps desired image can be chosen in Murano dashboard and used for services platform.
</para>
</section>
</chapter>

963
src/administrators-guide/src/docbkx/content/installation-guide.xml Normal file
View File

@ -0,0 +1,963 @@
<?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>Install Murano Components</title>
<para>This chapter describes how to install Murano components on a
separate devbox. We
strongly recommend to use a separate host (virtual machine or real
host) for Murano
devbox as it prevents you from various dependency conflicts.
</para>
<section>
<title>Automatic Installation</title>
<para>There is a script to automate Murano installation onto
devbox.
<itemizedlist>
<listitem>
<para>Create a folder to hold cloned
repositories
<screen>># mkdir -p /opt/git</screen>
</para>
</listitem>
<listitem>
<para>Clone murano-deployment
repository
<screen>
># cd /opt/git
># git clone git://github.com/stackforge/murano-deployment.git
</screen>
</para>
</listitem>
<listitem>
<para>Change directory to
<emphasis role="bold">murano-deployment</emphasis>
and switch to required branch (e.g.<emphasis
role="bold"
>master</emphasis>)
<screen>
># cd /opt/git/murano-deployment
># git checkout -b master origin/master
</screen>
</para>
</listitem>
<listitem>
<para>Install
prerequisites
<screen>
># cd /opt/git/murano-deployment/devbox-scripts
># ./murano-git-install.sh prerequisites
</screen>
</para>
</listitem>
<listitem>
<para>Configure the following parameters in lab binding
configuration file
<emphasis role="bold"
>/etc/murano-deployment/lab-binding.rc
</emphasis>
<itemizedlist>
<listitem>
<para>
<emphasis role="bold">LAB_HOST
</emphasis>
- IP or nostname
of the lab. Actually, this address/name
should point to the
host where Keystone is installed.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">ADMIN_USER
</emphasis>
- OpenStack
<emphasis role="bold">admin</emphasis>
user
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">ADMIN_PASSWORD
</emphasis>
- A password for OpenStack
<emphasis role="bold"
>admin
</emphasis>
user
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">RABBITMQ_USER
</emphasis>
- User to connect to RabbitMQ host
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">
RABBITMQ_PASSWORD
</emphasis>
- Password for that user
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">RABBITMQ_VHOST
</emphasis>
- vHost
which will be used by Murano
components. Provides additional
layer of isolation from other devboxes.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">RABBITMQ_HOST
</emphasis>
-
(optional) IP address or hostname of
the host where RabbitMQ
is installed IF it is not the same host
as LAB_HOST points
to
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">
RABBITMQ_HOST_ALT
</emphasis>
-
(optional) IP address or hostname of
the RabbitMQ host to
connect from inside the Windows
instance. In some cases the
addresses like LAB_HOST or
RABBITMQ_HOST are inaccessible
from instances, and they must use
different address.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">FILE_SHARE_HOST
</emphasis>
-
(optional) IP address or hostname of
the host where file
share with prerequisites is located IF
it is not the same
host as LAB_HOST points to.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">BRANCH_NAME
</emphasis>
- branch name
from which all Murano components will
be fetched for
installation
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">SSL_ENABLED
</emphasis>
- Set
<emphasis role="bold">'true'</emphasis>
if OpenStack is
configured with SSL support and
<emphasis role="bold"
>'false'
</emphasis>
otherwise.
</para>
</listitem>
<listitem>
<para>
<emphasis role="bold">SSL_CA_FILE
</emphasis>
- Path to CA
certificate for certificate validation
on client
side.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>Install Murano
components
<screen>
># ./murano-git-install.sh install</screen>
</para>
</listitem>
<listitem>
<para>Login to the Dashboard using URL
<emphasis role="bold">http://&lt;your
VM IP>/dashboard
</emphasis>
or
<emphasis role="bold">http://&lt;your
VM IP>/horizon
</emphasis>
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section>
<title>Manual Installation</title>
<para>This chapter describes manual installation and configuration of Murano services.</para>
<para>Note that all Murano modules can be downloaded from
<link xlink:href="https://launchpad.net/murano/">our page</link>
on launchpad.
</para>
<para>
<note>
<title>Automatic installation</title> Murano can be installed in automatic way. Script will install all
necessary packages to your system. Find out more about this in
<link xlink:href='http://murano-docs.github.io/0.2/getting-started/content/ch04s02.html'>
Getting Started Guide</link>
</note>
</para>
<section xml:id="prerequisites">
<title>Pre-Requisites</title>
<para>Murano supports the following operating systems:</para>
<orderedlist>
<listitem>
<para>Ubuntu 12.04</para>
</listitem>
<listitem>
<para>RHEL/CentOS 6.4</para>
</listitem>
</orderedlist>
<para>These system packages are required for Murano:</para>
<para><emphasis>Ubuntu</emphasis></para>
<orderedlist>
<listitem>
<para>gcc</para>
</listitem>
<listitem>
<para>python-pip</para>
</listitem>
<listitem>
<para>python-dev</para>
</listitem>
<listitem>
<para>libxml2-dev</para>
</listitem>
<listitem>
<para>libxslt-dev</para>
</listitem>
<listitem>
<para>libffi-dev</para>
</listitem>
</orderedlist>
<para>
<emphasis>CentOS</emphasis>
</para>
<orderedlist>
<listitem>
<para>gcc</para>
</listitem>
<listitem>
<para>python-pip</para>
</listitem>
<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>
<para>
All these packages will be installed in murano-installation scripts. In addition to these packages some repositories are required.
Please follow the instructions in <link linkend="Appendix">the appendix</link> to prepare your environment for murano installation.
</para>
</section>
<section>
<title>Murano API Service</title>
<para>Murano API provides access to the Murano orchestration engine via API.</para>
<para>This chapter describes the procedure of installation and condiguration of Murano API. </para>
<section>
<title>Install</title>
<itemizedlist spacing="compact">
<listitem>
<para>Superuser privileges is required to install and configure system packages. Let's switch to root account:</para>
<programlisting>
<![CDATA[
sudo su -
]]>
</programlisting>
</listitem>
<listitem>
<para>Make sure that additional linux repositories are installed. See <link linkend="Appendix">the appendix</link> for information about preparing a virtual machine for murano installation.
</para>
</listitem>
<listitem>
<para>Clone Murano API git repository:</para>
<programlisting>
<![CDATA[
git clone https://github.com/stackforge/murano-api
]]>
</programlisting>
<para>Stable version one of our <link xlink:href="http://murano-docs.github.io/latest/developers-guide/content/ch03s02.html"> releases</link> can be checked by tag:</para>
<programlisting>
<![CDATA[
git checkout 0.2
]]>
</programlisting>
</listitem>
<listitem>
<para>Switch to just created directory and then perform installation</para>
<para>
<emphasis>Ubuntu</emphasis>
</para>
<programlisting>
<![CDATA[
sh murano-api/setup.sh install
]]>
</programlisting>
<para>
<emphasis>CentOS</emphasis>
</para>
<programlisting>
<![CDATA[
sh murano-api/setup-centos.sh install
]]>
</programlisting>
</listitem>
<listitem>
<para>Successful installation ends with message like this:</para>
<programlisting>
<![CDATA[
Successfully installed muranoapi
Cleaning up...
LOG:> Making sample configuration files at "/etc/murano-api"
LOG:> Reloading initctl
LOG:> Please, make proper configuration,located at "/etc/murano-api", before starting the "murano-api" daemon!
]]>
</programlisting>
</listitem>
</itemizedlist>
</section>
<section xml:id="configure_api">
<title>Configure</title>
<itemizedlist spacing="compact">
<listitem>
<para>Copy and edit configuration files:</para>
<programlisting>
<![CDATA[
cd /etc/murano-api
cp murano-api.conf.sample murano-api.conf
cp murano-api-paste.ini.sample murano-api-paste.ini
vi murano-api.conf
]]>
</programlisting>
</listitem>
<listitem>
<para>Configure it according to your environment:
<itemizedlist>
<listitem>
<para><emphasis>[DEFAULT]</emphasis> section sets up logging.
</para>
</listitem>
<listitem>
<para>
<emphasis>[reports]</emphasis>
section allows you to set up names for new rabbitMQ queues.
</para>
</listitem>
<listitem>
<para>In
<emphasis>[rabbitmq]</emphasis>
section you can set up host configuration where rabbitMQ
with just created user and vhost is running.
If you consider to use Murano in production it;sbetter to use seperate vhosts in RabbitMQ.
To add new vhost and user with
administrator rights preform:
</para>
<programlisting>
<![CDATA[
rabbitmqctl add_user muranouser murano
rabbitmqctl set_user_tags muranouser administrator
rabbitmqctl add_vhost muranovhost
rabbitmqctl set_permissions -p muranovhost muranouser ".*" ".*" ".*"
]]>
</programlisting>
</listitem>
<listitem>
<para>In <emphasis>[filter:authtoken]</emphasis>
configure keystone auth_token. For more information see
<link xlink:href="http://docs.openstack.org/developer/keystone/configuringservices.html">
Auth-Token Middleware with Username and Password
</link>
</para>
</listitem>
<listitem>
<para>Another murano-api configuration file located at
<filename>./etc/murano-api-paste.ini
</filename>
not requires any changes.
</para>
</listitem>
</itemizedlist>
</para>
<para> For more information how to configure SSL take a look at <link linkend="ssl"> SSL configuration chapter </link></para>
</listitem>
<listitem>
<anchor xml:id="murano_api_endpoint"></anchor>
<para>Register murano-api service in Openstack. </para>
<para>Note: you need to be authorized in Openstack to run this commands. To do this, you can run something like (having changed variables to appropriate values)</para>
<programlisting>
<![CDATA[
source $(YOUR_OPENSTACK_DIR)/openrc $(LOGIN) $(PASSWORD)
]]>
</programlisting>
<programlisting>
<![CDATA[
keystone service-create --name muranoapi --type murano --description "Murano-Api Service"
keystone endpoint-create
--region RegionOne
--service-id The ID field returned by the keystone service-create
--publicurl http://x.x.x.x:8082 (where x.x.x.x - host ip where murano-api installed)
--internalurl the same as publicurl
--adminurl the same as publicurl
]]>
</programlisting>
</listitem>
</itemizedlist>
</section>
<section>
<title>Run</title>
<itemizedlist>
<listitem>
<para>Run Murano API service:</para>
<para>
<emphasis>Ubuntu</emphasis>
</para>
<programlisting>
<![CDATA[
service murano-api start
]]>
</programlisting>
<para>
<emphasis>CentOS</emphasis>
</para>
<programlisting>
<![CDATA[
initctl start murano-api
]]>
</programlisting>
</listitem>
</itemizedlist>
</section>
</section>
<section>
<title>Conductor Service</title>
<para>Conductor is a Murano orchestration engine that transforms object model sent by REST API service into
a series of Heat and Murano-Agent commands.
</para>
<para>This chapter describes Conductor for contributors of the project.</para>
<section>
<title>Install</title>
<itemizedlist spacing="compact">
<listitem>
<para>Murano Conductor 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
successful deployment.
</para>
<para>The detailed information about Heat configuration is described
<link xlink:href="http://docs.openstack.org/developer/heat/getting_started/index.html">here.
</link>
</para>
</listitem>
<listitem>
<para>OpenStack Heat require Key Pair for Load Balancer instances. Murano Conductor uses
LoadBalancer for IIS Farms and ASP.NET Farms. The default name for Key Pair is "murano-lb-key",
you can change this parameter in file
<![CDATA[
/etc/murano-conductor/data/templates/cf/Windows.template
]]>
</para>
</listitem>
<listitem>
<para>Superuser privileges is required to install and configure system packages. Let's switch to root account:</para>
<programlisting>
<![CDATA[
sudo su -
]]>
</programlisting>
</listitem>
<listitem>
<para>Make sure that additional repositories are installed.
See
<link linkend="Appendix">the appendix</link>
for information about preparing a virtual machine for murano installation.
</para>
</listitem>
<listitem>
<para>Clone Murano Conductor repository from the github.</para>
<programlisting>
<![CDATA[
git clone https://github.com/stackforge/murano-conductor
]]>
</programlisting>
<para>Stable version one of our
<link xlink:href="http://murano-docs.github.io/latest/developers-guide/content/ch03s02.html">releases</link>
can be checked out by tag:
</para>
<programlisting>
<![CDATA[
git checkout 0.2
]]>
</programlisting>
</listitem>
<listitem>
<para>Switch to just created directory and then perform installation</para>
<para>
<emphasis>Ubuntu</emphasis>
</para>
<programlisting>
<![CDATA[
sh murano-conductor/setup.sh install
]]>
</programlisting>
<para>
<emphasis>CentOS</emphasis>
</para>
<programlisting>
<![CDATA[
sh murano-conductor/setup-centos.sh install
]]>
</programlisting>
</listitem>
</itemizedlist >
</section>
<section xml:id="configure_conductor">
<title>Configure</title>
<itemizedlist spacing="compact">
<listitem>
<para>Edit configuration file and take a look at inline comments:</para>
<programlisting>
<![CDATA[
cd /etc/murano-conductor
cp conductor.conf.sample conductor.conf
]]>
</programlisting>
</listitem>
<listitem>
<para>Change configuration file according to your environment.
<programlisting>
<![CDATA[
vi conductor.conf
]]>
</programlisting>
<itemizedlist >
<listitem>
<para><emphasis>[DEFAULT]</emphasis>section is responsible for logging.
</para>
</listitem>
<listitem>
<para><emphasis>[heat]</emphasis>points where heat is running.
</para>
</listitem>
<listitem>
<para><emphasis>[rabbitmq]</emphasis>section points where your rabbitMQ installed and
configured.
</para>
</listitem>
</itemizedlist>
</para>
<programlisting>
<![CDATA[
[DEFAULT]
# Path where log will be written
log_file = /var/log/murano-conductor.log
# Log verbosity
debug=True
verbose=True
data_dir = /etc/murano-conductor
# Maximum number of environments that can be processed simultaneously
max_environments = 20
[keystone]
auth_url = http://localhost:5000/v2.0
ca_file =
cert_file =
key_file =
insecure = False
[heat]
# Heat SSL parameters
# Optional CA cert file to use in SSL connections
ca_file =
# Optional PEM-formatted certificate chain file
cert_file =
# Optional PEM-formatted file that contains the private key
key_file =
# If set then the server's certificate will not be verified
insecure = False
# Valid endpoint types: publicURL (default), internalURL, adminURL
endpoint_type = publicURL
[rabbitmq]
# Connection parameters to RabbitMQ service
# Hostname or IP address where RabbitMQ is located.
# !!! Change localhost to your real IP or hostname as this address must be reachable from VMs !!!
host = localhost
# RabbitMQ port (5672 is a default)
port = 5672
# Use SSL for RabbitMQ connections (True or False)
ssl = False
# Path to SSL CA certificate or empty to allow self signed server certificate
ca_certs =
# RabbitMQ credentials. Fresh RabbitMQ installation has "guest" account with "guest" password.
# It is recommended to create dedicated user account for Murano using RabbitMQ web console or command line utility
login = quest
password = quest
# RabbitMQ virtual host (vhost). Fresh RabbitMQ installation has "/" vhost preconfigured.
# It is recommended to create dedicated vhost for production use
virtual_host = /
]]>
</programlisting>
</listitem>
</itemizedlist>
</section>
<section>
<title>Run</title>
<itemizedlist>
<listitem>
<para>Run Murano Conductor service:</para>
<para>
<emphasis>Ubuntu</emphasis>
</para>
<programlisting>
<![CDATA[
service murano-conductor start
]]>
</programlisting>
<para>
<emphasis>CentOS</emphasis>
</para>
<programlisting>
<![CDATA[
initctl start murano-conductor
]]>
</programlisting>
</listitem>
</itemizedlist>
</section>
</section>
<section>
<title>Murano Dashboard</title>
<para>Murano Dashboard provides Web UI for Murano Project.</para>
<warning>
<para>This installation is not capable with Horizon installed by devstack</para>
</warning>
<section>
<title>Install</title>
<itemizedlist>
<listitem>
<para>Superuser privileges is required to install and configure system packages. Let's switch to root account:</para>
<programlisting>
<![CDATA[
sudo su -
]]>
</programlisting>
</listitem>
<listitem>
<para>Make sure that additional repositories are installed.
See <link linkend="Appendix">the appendix</link>
for information about preparing a virtual machine for murano installation.
</para>
</listitem>
<listitem>
<para>If there is no openstack dashboard package in your environment install it now with all dependencies.
Deleting an Ubuntu theme is an optional step but recommended.</para>
<note>
<para>
Horizon installed by devstack is not capable for a murano installation.
</para>
</note>
<para><emphasis>CentOS</emphasis></para>
<programlisting>
yum install -y make gcc memcached python-memcached \
mod_wsgi openstack-dashboard python-netaddr.noarch
</programlisting>
<para>
<emphasis>Ubuntu</emphasis>
</para>
<programlisting>
apt-get install -y memcached libapache2-mod-wsgi openstack-dashboard
dpkg --purge openstack-dashboard-ubuntu-theme
</programlisting>
</listitem>
<listitem>
<para>Clone Murano Dashboard repository from the github:</para>
<programlisting>
<![CDATA[
git clone https://github.com/stackforge/murano-dashboard
]]>
</programlisting>
</listitem>
<listitem>
<para>Stable version one of our
<link xlink:href="http://murano-docs.github.io/latest/developers-guide/content/ch03s02.html">releases</link>
can be checked out by tag:
</para>
<programlisting>
git checkout 0.2
</programlisting>
</listitem>
<listitem>
<para>Switch to just created directory and run installation script</para>
<para>
<emphasis>Ubuntu</emphasis>
</para>
<programlisting>
<![CDATA[
sh murano-dashboard/setup.sh install
]]>
</programlisting>
<para>
<emphasis>CentOS</emphasis>
</para>
<programlisting>
<![CDATA[
sh murano-dashboard/setup-centos.sh install
]]>
</programlisting>
</listitem>
</itemizedlist>
</section>
<section xml:id="configure_dashboard">
<title>Configure</title>
<itemizedlist spacing="compact">
<listitem>
<para>
Murano installation script makes all needed changes in horizon (openstack dashboard) configs.
All you have to do is to configure horizon in appropriate way. Set OPENSTACK_HOST in your
horizon local settings which located in
<filename>/etc/openstack-dashboard/local_settings.py.</filename>.
<link xlink:href="http://docs.openstack.org/developer/horizon/">
For more information visit official horizon documentation. </link>
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Run</title>
<para>
Since all required settings are made Apache service need to be restarted to apply all changes.
</para>
<itemizedlist>
<listitem>
<para>
<emphasis>CentOS</emphasis>
<programlisting>
# service httpd restart
</programlisting>
</para>
</listitem>
<listitem>
<para>
<emphasis>Ubuntu</emphasis>
<programlisting>
# service apache2 restart
</programlisting>
</para>
</listitem>
<listitem>
<para>
Check that "Environments" panel appears at the horizon "Project" tab.
To see how to operate with Murano dashboard plugin check out
<link xlink:href="http://murano-docs.github.io/latest/user-guide/content/ch01.html">
Murano User Guide.
</link>
</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="ssl">
<title>SSL configuration</title>
<para>
Murano components are able to work with SSL. This chapter will
help your to make proper settings with SSL configuration.
</para>
<section>
<title>HTTPS for Murano API</title>
<para>
SSL for Murano API service can be configured in <emphasis>ssl</emphasis> section in
<emphasis>/etc/murano-api/murano-api.conf</emphasis>. Just point to a valid SSL certificate.
See the example below:
</para>
<programlisting>
<![CDATA[
[ssl]
cert_file = PATH
key_file = PATH
ca_file = PATH
]]>
</programlisting>
<itemizedlist>
<listitem>
<para>
<emphasis>cert_file=PATH:</emphasis>
Path to the certificate file the server should use when binding to an SSL-wrapped socket.
</para>
</listitem>
<listitem>
<para>
<emphasis>key_file=PATH:</emphasis> Path to the private key file the server should
use when binding to an SSL-wrapped socket.
</para>
</listitem>
<listitem>
<para>
<emphasis>ca_file=PATH:</emphasis>
Path to the CA certificate file the server should use to validate
client certificates provided during an SSL handshake. This is
ignored if cert_file and "key_file" are not set.
</para>
</listitem>
</itemizedlist>
<para>
The use of SSL is automatically started after point to HTTPS protocol instead of HTTP during registration Murano API service in endpoints
(Change publicurl argument to start with https://). See <link linkend="murano_api_endpoint">here</link>
how to register Murano API in Openstack Keystone.
</para>
<simpara>
SSL for Murano API is implemented like in any other Openstack component.
This realization is based on ssl python module so more information about it can be found
<link xlink:href="http://docs.python.org/2/library/ssl.html"> here.</link>
</simpara>
</section>
<section>
<title>SSL for RabbitMQ</title>
<para>
All Murano components communicate with each other
by RabbitMQ. This interaction can be encrypted with SSL. By
default all messages in Rabbit MQ are not encrypted.
Each RabbitMQ Exchange should be configured separately.
</para>
<section>
<title>Murano API -> Rabbit MQ exchange</title>
<para>
Edit <emphasis>rabbitmq</emphasis> section in <emphasis>/etc/murano-api/murano-api.conf</emphasis>
and set ssl option to True to enable SSL. Specify the path to the
SSL CA certificate in regular format: /path/to/file without quotes or leave it empty to allow
self-signed certificates.
</para>
<programlisting>
<![CDATA[
[rabbitmq]
# Use SSL for RabbitMQ connections (True or False)
ssl = True
# Path to SSL CA certificate or empty to allow self signed server certificate
ca_certs =
]]>
</programlisting>
</section>
<section>
<title>Rabbit MQ -> Murano Conductor exchange</title>
<para>
Open <emphasis>/etc/murano-conductor/conductor.conf</emphasis>
and configure <emphasis>rabbitmq</emphasis> section in the same way:
enable ssl option to True and set CA certificate path or leave it empty to allow
self-signed certificates.
</para>
<programlisting>
<![CDATA[
[rabbitmq]
# Use SSL for RabbitMQ connections (True or False)
ssl = True
# Path to SSL CA certificate or empty to allow self signed server certificate
ca_certs = /home/user/certificates/example.crt
]]>
</programlisting>
</section>
<section>
<title>Murano Agent -> Rabbit MQ exchange</title>
<para>
By default all Murano Conductor configuration settings apply to Murano Agent.
If you want to configure Murano Agent in a different way change the default template. It can be found
here:<emphasis>/etc/murano-conductor/data/templates/agent-config/Default.template.</emphasis>
Take a look at appSettings section:
</para>
<programlisting>
<![CDATA[
<appSettings>
<add key="rabbitmq.host" value="%RABBITMQ_HOST%"/>
<add key="rabbitmq.port" value="%RABBITMQ_PORT%"/>
<add key="rabbitmq.user" value="%RABBITMQ_USER%"/>
<add key="rabbitmq.password"
value="%RABBITMQ_PASSWORD%"/>
<add key="rabbitmq.vhost" value="%RABBITMQ_VHOST%"/>
<add key="rabbitmq.inputQueue"
value="%RABBITMQ_INPUT_QUEUE%"/>
<add key="rabbitmq.resultExchange" value=""/>
<add key="rabbitmq.resultRoutingKey"
value="%RESULT_QUEUE%"/>
<add key="rabbitmq.durableMessages" value="true"/>
<add key="rabbitmq.ssl" value="%RABBITMQ_SSL%"/>
<add key="rabbitmq.allowInvalidCA" value="true"/>
<add key="rabbitmq.sslServerName" value=""/>
</appSettings>
]]>
</programlisting>
<para>
Desired parameter should be set directly to the value of the key
that you want to change. Quotes are need to be kept.
Thus you can change "rabbitmq.ssl" and "rabbitmq.port" values to
make Rabbit MQ work with this exchange in a different from
Murano-Conductor way.
</para>
</section>
</section>
</section>
</section>
</chapter>

139
src/administrators-guide/src/docbkx/content/troubleshooting.xml Normal file
View File

@ -0,0 +1,139 @@
<?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>Troubleshooting</title>
<formalpara>
<title>General Notes</title>
<para>The following debug sequence should be used when you have no idea about why the
system isn't working. If you have one, you may skip unnecessary sections.</para>
</formalpara>
<para>Set debug options to "True" in the following Murano configuration files:<itemizedlist>
<listitem>
<para>/etc/murano-api/murano-api.conf</para>
</listitem>
<listitem>
<para>/etc/murano-conductor/conductor.conf</para>
</listitem>
</itemizedlist></para>
<para>Stop both <emphasis role="bold">murano-api</emphasis> and <emphasis role="bold"
>murano-conductor</emphasis> services. We will start them one by one from the
console.</para>
<formalpara>
<title>murano-api</title>
<para>First, the murano-api must be started.</para>
</formalpara>
<para>
<itemizedlist>
<listitem>
<para>Open new console</para>
</listitem>
<listitem>
<para>Start <emphasis role="bold">murano-api</emphasis> service
manually<screen>># murano-api --config-dir /etc/murano-api 2>&amp;1 \
> /var/log/murano-api-live.log &amp;
># tailf /var/log/murano-api-live.log</screen></para>
</listitem>
<listitem>
<para>Open dashboard, create and send to deploy some simple
environment.</para>
</listitem>
<listitem>
<para>Open RabbitMQ web console, open your vhost and ensure that queues were
created and there is at least one message.</para>
</listitem>
<listitem>
<para>Check log for errors - there shouldn't be any</para>
</listitem>
<listitem>
<para>Keep <emphasis role="bold">murano-api</emphasis> service
running</para>
</listitem>
</itemizedlist>
</para>
<formalpara>
<title>murano-conductor</title>
<para>Next to the <emphasis role="bold">murano-api</emphasis> the <emphasis role="bold"
>murano-conductor</emphasis> should be started
</para>
</formalpara>
<para>
<itemizedlist>
<listitem>
<para>Open new console</para>
</listitem>
<listitem>
<para>Start conductor from
console<screen>># muranoconductor --config-dir /etc/murano-conductor \
> /var/log/murano-conductor-live.log &amp;
># tailf /var/log/murano-conductor-live.log</screen></para>
</listitem>
<listitem>
<para>Check that there is no python exceptions in the log. Some errors like
404 are ok, as conductor tries to delete environment that doesn't
exist</para>
</listitem>
<listitem>
<para>Check heat stack status. It should not be in FAILED state. If it is -
check heat and nova error log to find the cause.</para>
</listitem>
<listitem>
<para>Keep murano-conductor service running.</para>
</listitem>
</itemizedlist>
</para>
<formalpara>
<title>Log Files</title>
<para>There are various log files which will help you to debug the system.</para>
</formalpara>
<para><emphasis role="bold">Murano Log Files</emphasis>
<itemizedlist>
<listitem>
<para>/var/log/murano-api.log</para>
</listitem>
<listitem>
<para>/var/log/murano-conductor.log</para>
</listitem>
<listitem>
<para>/var/log/apache2/errors.log</para>
</listitem>
<listitem>
<para>/var/log/httpd/errors.log</para>
</listitem>
</itemizedlist>
</para>
<para><emphasis role="bold">Windows Log Files</emphasis>
<itemizedlist>
<listitem>
<para>C:\Program Files (x86)\CloudBase Solutions\logs\log.txt</para>
</listitem>
<listitem>
<para>C:\Murano\Agent\log.txt</para>
</listitem>
<listitem>
<para>C:\Murano\PowerShell.log</para>
</listitem>
</itemizedlist>
</para>
</chapter>

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

@ -1,26 +1,26 @@
<?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 "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
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
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.
-->
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"
http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"
version="5.0">
<title>Installation Guide</title>
<para>This chapter describes manual installation and configuration of Murano services.</para>
@ -30,10 +30,13 @@
</para>
<para>
<note>
<title>Automatic installation</title> Murano can be installed in automatic way. Script will install all
<title>Automatic installation</title>
<para>
Murano can be installed in automatic way. Script will install all
necessary packages to your system. Find out more about this in
<link xlink:href='http://murano-docs.github.io/0.2/getting-started/content/ch04s02.html'>
Getting Started Guide</link>
</para>
</note>
</para>
<section xml:id="prerequisites">
@ -94,535 +97,8 @@
</orderedlist>
<para>
All these packages will be installed in murano-installation scripts. In addition to these packages some repositories are required.
Please follow the instructions in <link linkend="Appendix">the appendix</link> to prepare your environment for murano installation.
Please follow the instructions in the appendix to admin guide to prepare your environment for murano installation.
</para>
</section>
<section>
<title>Murano API Service</title>
<para>Murano API provides access to the Murano orchestration engine via API.</para>
<para>This chapter describes the procedure of installation and condiguration of Murano API. </para>
<section>
<title>Install</title>
<itemizedlist spacing="compact">
<listitem>
<para>Superuser privileges is required to install and configure system packages. Let's switch to root account:</para>
<programlisting>
<![CDATA[
sudo su -
]]>
</programlisting>
</listitem>
<listitem>
<para>Make sure that additional linux repositories are installed. See <link linkend="Appendix">the appendix</link> for information about preparing a virtual machine for murano installation.
</para>
</listitem>
<listitem>
<para>Clone Murano API git repository:</para>
<programlisting>
<![CDATA[
git clone https://github.com/stackforge/murano-api
]]>
</programlisting>
<para>Stable version one of our <link linkend="releases"> releases</link> can be checked by tag:</para>
<programlisting>
<![CDATA[
git checkout 0.2
]]>
</programlisting>
</listitem>
<listitem>
<para>Switch to just created directory and then perform installation</para>
<para>
<emphasis>Ubuntu</emphasis>
</para>
<programlisting>
<![CDATA[
sh murano-api/setup.sh install
]]>
</programlisting>
<para>
<emphasis>CentOS</emphasis>
</para>
<programlisting>
<![CDATA[
sh murano-api/setup-centos.sh install
]]>
</programlisting>
</listitem>
<listitem>
<para>Successful installation ends with message like this:</para>
<programlisting>
<![CDATA[
Successfully installed muranoapi
Cleaning up...
LOG:> Making sample configuration files at "/etc/murano-api"
LOG:> Reloading initctl
LOG:> Please, make proper configuration,located at "/etc/murano-api", before starting the "murano-api" daemon!
]]>
</programlisting>
</listitem>
</itemizedlist>
</section>
<section xml:id="configure_api">
<title>Configure</title>
<itemizedlist spacing="compact">
<listitem>
<para>First configure rabbitMQ by adding vhost and user with administrator rights:</para>
<programlisting>
<![CDATA[
rabbitmqctl add_user muranouser murano
rabbitmqctl set_user_tags muranouser administrator
rabbitmqctl add_vhost muranovhost
rabbitmqctl set_permissions -p muranovhost muranouser ".*" ".*" ".*"
]]>
</programlisting>
</listitem>
<listitem>
<para>Copy and edit configuration files:</para>
<programlisting>
<![CDATA[
cd /etc/murano-api
cp murano-api.conf.sample murano-api.conf
cp murano-api-paste.ini.sample murano-api-paste.ini
vi murano-api.conf
]]>
</programlisting>
</listitem>
<listitem>
<para>Configure it according to your environment:
<itemizedlist>
<listitem>
<para><emphasis>[DEFAULT]</emphasis> section sets up logging.
</para>
</listitem>
<listitem>
<para>
<emphasis>[reports]</emphasis>
section allows you to set up names for new rabbitMQ queues.
</para>
</listitem>
<listitem>
<para>In
<emphasis>[rabbitmq]</emphasis>
section you can set up host configuration where rabbitMQ
with just created user and vhost is running.
</para>
</listitem>
</itemizedlist>
</para>
<para> For more information how to configure SSL take a look at <link linkend="ssl"> SSL configuration chapter </link></para>
</listitem>
<listitem>
<para>Configure keystone auth_token in murano-api-paste.ini file.
For more information see
<link xlink:href="http://docs.openstack.org/developer/keystone/configuringservices.html">
Auth-Token Middleware with Username and Password
</link>
</para>
<programlisting>
<![CDATA[
vim murano-api-paste.ini
[pipeline:muranoapi]
pipeline = authtoken context apiv1app
[app:apiv1app]
paste.app_factory = muranoapi.api.v1.router:API.factory
[filter:context]
paste.filter_factory = muranoapi.api.middleware.context:ContextMiddleware.facto$
#For more information see Auth-Token Middleware with Username and Password
#http://docs.openstack.org/developer/keystone/configuringservices.html
[filter:authtoken]
paste.filter_factory = keystoneclient.middleware.auth_token:filter_factory
auth_host = localhost
auth_port = 35357
auth_protocol = http
admin_tenant_name = admin
admin_user = admin
admin_password = password
]]>
</programlisting>
</listitem>
<listitem>
<anchor xml:id="murano_api_endpoint"></anchor>
<para>Register murano-api service in Openstack. </para>
<para>Note: you need to be authorized in Openstack to run this commands. To do this, you can run something like (having changed variables to appropriate values)</para>
<programlisting>
<![CDATA[
source $(YOUR_OPENSTACK_DIR)/openrc $(LOGIN) $(PASSWORD)
]]>
</programlisting>
<programlisting>
<![CDATA[
keystone service-create --name muranoapi --type murano --description "Murano-Api Service"
keystone endpoint-create
--region RegionOne
--service-id The ID field returned by the keystone service-create
--publicurl http://x.x.x.x:8082 (where x.x.x.x - host ip where murano-api installed)
--internalurl the same as publicurl
--adminurl the same as publicurl
]]>
</programlisting>
</listitem>
</itemizedlist>
</section>
<section>
<title>Run</title>
<itemizedlist>
<listitem>
<para>Run Murano API service:</para>
<para>
<emphasis>Ubuntu</emphasis>
</para>
<programlisting>
<![CDATA[
service murano-api start
]]>
</programlisting>
<para>
<emphasis>CentOS</emphasis>
</para>
<programlisting>
<![CDATA[
initctl start murano-api
]]>
</programlisting>
</listitem>
</itemizedlist>
</section>
</section>
<section>
<title>Conductor Service</title>
<para>Conductor is a Murano orchestration engine that transforms object model sent by REST API service into
a series of Heat and Murano-Agent commands.
</para>
<para>This chapter describes Conductor for contributors of the project.</para>
<section>
<title>Install</title>
<itemizedlist spacing="compact">
<listitem>
<para>Murano Conductor 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
successful deployment.
</para>
<para>The detailed information about Heat configuration is described
<link xlink:href="http://docs.openstack.org/developer/heat/getting_started/index.html">here.
</link>
</para>
</listitem>
<listitem>
<para>OpenStack Heat require Key Pair for Load Balancer instances. Murano Conductor uses
LoadBalancer for IIS Farms and ASP.NET Farms. The default name for Key Pair is "murano-lb-key",
you can change this parameter in file
<![CDATA[
/etc/murano-conductor/data/templates/cf/Windows.template
]]>
</para>
</listitem>
<listitem>
<para>Superuser privileges is required to install and configure system packages. Let's switch to root account:</para>
<programlisting>
<![CDATA[
sudo su -
]]>
</programlisting>
</listitem>
<listitem>
<para>Make sure that additional repositories are installed.
See
<link linkend="Appendix">the appendix</link>
for information about preparing a virtual machine for murano installation.
</para>
</listitem>
<listitem>
<para>Clone Murano Conductor repository from the github.</para>
<programlisting>
<![CDATA[
git clone https://github.com/stackforge/murano-conductor
]]>
</programlisting>
<para>Stable version one of our
<link linkend="releases">releases</link>
can be checked out by tag:
</para>
<programlisting>
<![CDATA[
git checkout 0.2
]]>
</programlisting>
</listitem>
<listitem>
<para>Switch to just created directory and then perform installation</para>
<para>
<emphasis>Ubuntu</emphasis>
</para>
<programlisting>
<![CDATA[
sh murano-conductor/setup.sh install
]]>
</programlisting>
<para>
<emphasis>CentOS</emphasis>
</para>
<programlisting>
<![CDATA[
sh murano-conductor/setup-centos.sh install
]]>
</programlisting>
</listitem>
</itemizedlist >
</section>
<section xml:id="configure_conductor">
<title>Configure</title>
<itemizedlist spacing="compact">
<listitem>
<para>Edit configuration file and take a look at inline comments:</para>
<programlisting>
<![CDATA[
cd /etc/murano-conductor
cp conductor.conf.sample conductor.conf
]]>
</programlisting>
</listitem>
<listitem>
<para>Change configuration file according to your environment.
<programlisting>
<![CDATA[
vi conductor.conf
]]>
</programlisting>
<itemizedlist >
<listitem>
<para><emphasis>[DEFAULT]</emphasis>section is responsible for logging.
</para>
</listitem>
<listitem>
<para><emphasis>[heat]</emphasis>points where heat is running.
</para>
</listitem>
<listitem>
<para><emphasis>[rabbitmq]</emphasis>section points where your rabbitMQ installed and
configured.
</para>
</listitem>
</itemizedlist>
</para>
<programlisting>
<![CDATA[
[DEFAULT]
# Path where log will be written
log_file = /var/log/murano-conductor.log
# Log verbosity
debug=True
verbose=True
data_dir = /etc/murano-conductor
# Maximum number of environments that can be processed simultaneously
max_environments = 20
[keystone]
auth_url = http://localhost:5000/v2.0
ca_file =
cert_file =
key_file =
insecure = False
[heat]
# Heat SSL parameters
# Optional CA cert file to use in SSL connections
ca_file =
# Optional PEM-formatted certificate chain file
cert_file =
# Optional PEM-formatted file that contains the private key
key_file =
# If set then the server's certificate will not be verified
insecure = False
# Valid endpoint types: publicURL (default), internalURL, adminURL
endpoint_type = publicURL
[rabbitmq]
# Connection parameters to RabbitMQ service
# Hostname or IP address where RabbitMQ is located.
# !!! Change localhost to your real IP or hostname as this address must be reachable from VMs !!!
host = localhost
# RabbitMQ port (5672 is a default)
port = 5672
# Use SSL for RabbitMQ connections (True or False)
ssl = False
# Path to SSL CA certificate or empty to allow self signed server certificate
ca_certs =
# RabbitMQ credentials. Fresh RabbitMQ installation has "guest" account with "guest" password.
# It is recommended to create dedicated user account for Murano using RabbitMQ web console or command line utility
login = muranouser
password = murano
# RabbitMQ virtual host (vhost). Fresh RabbitMQ installation has "/" vhost preconfigured.
# It is recommended to create dedicated vhost for Murano using RabbitMQ web console or command line utility
virtual_host = muranovhost
]]>
</programlisting>
</listitem>
</itemizedlist>
</section>
<section>
<title>Run</title>
<itemizedlist>
<listitem>
<para>Run Murano Conductor service:</para>
<para>
<emphasis>Ubuntu</emphasis>
</para>
<programlisting>
<![CDATA[
service murano-conductor start
]]>
</programlisting>
<para>
<emphasis>CentOS</emphasis>
</para>
<programlisting>
<![CDATA[
initctl start murano-conductor
]]>
</programlisting>
</listitem>
</itemizedlist>
</section>
</section>
<section>
<title>Murano Dashboard</title>
<para>Murano Dashboard provides Web UI for Murano Project.</para>
<warning>
<para>This installation is not capable with Horizon installed by devstack</para>
</warning>
<section>
<title>Install</title>
<itemizedlist>
<listitem>
<para>Superuser privileges is required to install and configure system packages. Let's switch to root account:</para>
<programlisting>
<![CDATA[
sudo su -
]]>
</programlisting>
</listitem>
<listitem>
<para>Make sure that additional repositories are installed.
See <link linkend="Appendix">the appendix</link>
for information about preparing a virtual machine for murano installation.
</para>
</listitem>
<listitem>
<para>If there is no openstack dashboard package in your environment install it now with all dependencies.
Deleting an Ubuntu theme is an optional step but recommended.</para>
<note>
<para>
Horizon installed by devstack is not capable for a murano installation.
</para>
</note>
<para><emphasis>CentOS</emphasis></para>
<programlisting>
yum install -y make gcc memcached python-memcached \
mod_wsgi openstack-dashboard python-netaddr.noarch
</programlisting>
<para>
<emphasis>Ubuntu</emphasis>
</para>
<programlisting>
apt-get install -y memcached libapache2-mod-wsgi openstack-dashboard
dpkg --purge openstack-dashboard-ubuntu-theme
</programlisting>
</listitem>
<listitem>
<para>Clone Murano Dashboard repository from the github:</para>
<programlisting>
<![CDATA[
git clone https://github.com/stackforge/murano-dashboard
]]>
</programlisting>
</listitem>
<listitem>
<para>Stable version one of our
<link linkend="releases">releases</link>
can be checked out by tag:
</para>
<programlisting>
git checkout 0.2
</programlisting>
</listitem>
<listitem>
<para>Switch to just created directory and run installation script</para>
<para>
<emphasis>Ubuntu</emphasis>
</para>
<programlisting>
<![CDATA[
sh murano-dashboard/setup.sh install
]]>
</programlisting>
<para>
<emphasis>CentOS</emphasis>
</para>
<programlisting>
<![CDATA[
sh murano-dashboard/setup-centos.sh install
]]>
</programlisting>
</listitem>
</itemizedlist>
</section>
<section xml:id="configure_dashboard">
<title>Configure</title>
<itemizedlist spacing="compact">
<listitem>
<para>
Murano installation script makes all needed changes in horizon (openstack dashboard) configs.
All you have to do is to configure horizon in appropriate way. Set OPENSTACK_HOST in your horizon local settings.
<link xlink:href="http://docs.openstack.org/developer/horizon/">
For more information visit official horizon documentation. </link>
</para>
</listitem>
</itemizedlist>
</section>
<section>
<title>Run</title>
<para>
Since all required settings are made Apache service need to be restarted to apply all changes.
</para>
<itemizedlist>
<listitem>
<para>
<emphasis>CentOS</emphasis>
<programlisting>
# service httpd restart
</programlisting>
</para>
</listitem>
<listitem>
<para>
<emphasis>Ubuntu</emphasis>
<programlisting>
# service apache2 restart
</programlisting>
</para>
</listitem>
<listitem>
<para>
Check that "Environments" panel appears at the horizon "Project" tab.
To see how to operate with Murano dashboard plugin check out
<link xlink:href="http://murano-docs.github.io/latest/user-guide/content/ch01.html">
Murano User Guide.
</link>
</para>
</listitem>
</itemizedlist>
</section>
</section>
<section xml:id="venv">
<title>Installing with virtual environment</title>
@ -727,8 +203,8 @@ $ python tools/install_venv.py
<listitem>
<para>
Config files for the development infrastructure of murano-api and murano-conductor can be found at <filename>etc</filename>
under folder with component repository. Follow the links to see how config files should be configured:
<link linkend="configure_api">Murano API</link> and <link linkend="configure_conductor">Murano Conductor</link>.
under folder with component repository. In murano-api and murano-conductor config file (located under ./etc directory)
just point out IP address where your RabbitMQ is running. All other possible configuration described in the Murano Admin Guide.
To configure Murano Dashboard copy
<programlisting>
# cp muranodashboard/local/local_settings.py.example muranodashboard/local/local_settings.py
@ -764,146 +240,4 @@ $ python tools/install_venv.py
</listitem>
</itemizedlist>
</section>
<section xml:id="ssl">
<title>SSL configuration</title>
<para>
Murano components are able to work with SSL. This chapter will
help your to make proper settings with SSL configuration.
</para>
<section>
<title>HTTPS for Murano API</title>
<para>
SSL for Murano API service can be configured in <emphasis>ssl</emphasis> section in
<emphasis>/etc/murano-api/murano-api.conf</emphasis>. Just point to a valid SSL certificate.
See the example below:
</para>
<programlisting>
<![CDATA[
[ssl]
cert_file = PATH
key_file = PATH
ca_file = PATH
]]>
</programlisting>
<itemizedlist>
<listitem>
<para>
<emphasis>cert_file=PATH:</emphasis>
Path to the certificate file the server should use when binding to an SSL-wrapped socket.
</para>
</listitem>
<listitem>
<para>
<emphasis>key_file=PATH:</emphasis> Path to the private key file the server should
use when binding to an SSL-wrapped socket.
</para>
</listitem>
<listitem>
<para>
<emphasis>ca_file=PATH:</emphasis>
Path to the CA certificate file the server should use to validate
client certificates provided during an SSL handshake. This is
ignored if cert_file and "key_file" are not set.
</para>
</listitem>
</itemizedlist>
<para>
The use of SSL is automatically started after point to HTTPS protocol instead of HTTP during registration Murano API service in endpoints
(Change publicurl argument to start with https://). See <link linkend="murano_api_endpoint">here</link>
how to register Murano API in Openstack Keystone.
</para>
<simpara>
SSL for Murano API is implemented like in any other Openstack component.
This realization is based on ssl python module so more information about it can be found
<link xlink:href="http://docs.python.org/2/library/ssl.html"> here.</link>
</simpara>
</section>
<section>
<title>SSL for RabbitMQ</title>
<para>
All Murano components communicate with each other
by RabbitMQ. This interaction can be encrypted with SSL. By
default all messages in Rabbit MQ are not encrypted.
Each RabbitMQ Exchange should be configured separately.
</para>
<section>
<title>Murano API -> Rabbit MQ exchange</title>
<para>
Edit <emphasis>rabbitmq</emphasis> section in <emphasis>/etc/murano-api/murano-api.conf</emphasis>
and set ssl option to True to enable SSL. Specify the path to the
SSL CA certificate in regular format: /path/to/file without quotes or leave it empty to allow
self-signed certificates.
</para>
<programlisting>
<![CDATA[
[rabbitmq]
# Use SSL for RabbitMQ connections (True or False)
ssl = True
# Path to SSL CA certificate or empty to allow self signed server certificate
ca_certs =
]]>
</programlisting>
</section>
<section>
<title>Rabbit MQ -> Murano Conductor exchange</title>
<para>
Open <emphasis>/etc/murano-conductor/conductor.conf</emphasis>
and configure <emphasis>rabbitmq</emphasis> section in the same way:
enable ssl option to True and set CA certificate path or leave it empty to allow
self-signed certificates.
</para>
<programlisting>
<![CDATA[
[rabbitmq]
# Use SSL for RabbitMQ connections (True or False)
ssl = True
# Path to SSL CA certificate or empty to allow self signed server certificate
ca_certs = /home/user/certificates/example.crt
]]>
</programlisting>
</section>
<section>
<title>Murano Agent -> Rabbit MQ exchange</title>
<para>
By default all Murano Conductor configuration settings apply to Murano Agent.
If you want to configure Murano Agent in a different way change the default template. It can be found
here:<emphasis>/etc/murano-conductor/data/templates/agent-config/Default.template.</emphasis>
Take a look at appSettings section:
</para>
<programlisting>
<![CDATA[
<appSettings>
<add key="rabbitmq.host" value="%RABBITMQ_HOST%"/>
<add key="rabbitmq.port" value="%RABBITMQ_PORT%"/>
<add key="rabbitmq.user" value="%RABBITMQ_USER%"/>
<add key="rabbitmq.password"
value="%RABBITMQ_PASSWORD%"/>
<add key="rabbitmq.vhost" value="%RABBITMQ_VHOST%"/>
<add key="rabbitmq.inputQueue"
value="%RABBITMQ_INPUT_QUEUE%"/>
<add key="rabbitmq.resultExchange" value=""/>
<add key="rabbitmq.resultRoutingKey"
value="%RESULT_QUEUE%"/>
<add key="rabbitmq.durableMessages" value="true"/>
<add key="rabbitmq.ssl" value="%RABBITMQ_SSL%"/>
<add key="rabbitmq.allowInvalidCA" value="true"/>
<add key="rabbitmq.sslServerName" value=""/>
</appSettings>
]]>
</programlisting>
<para>
Desired parameter should be set directly to the value of the key
that you want to change. Quotes are need to be kept.
Thus you can change "rabbitmq.ssl" and "rabbitmq.port" values to
make Rabbit MQ work with this exchange in a different from
Murano-Conductor way.
</para>
</section>
</section>
</section>
</chapter>
</chapter>

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

@ -75,5 +75,4 @@
xlink:href="https://launchpad.net/murano">launchpad page</link>.
</para>
</chapter>
<xi:include href="./content/appendix.xml" xlink:title="Appendix"/>
</book>