diff --git a/src/developers-guide/src/docbkx/content/installation-guide.xml b/src/developers-guide/src/docbkx/content/installation-guide.xml index ddee0f8..fae8c8a 100644 --- a/src/developers-guide/src/docbkx/content/installation-guide.xml +++ b/src/developers-guide/src/docbkx/content/installation-guide.xml @@ -224,6 +224,7 @@ admin_password = password + Register murano-api service in Openstack. 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) @@ -231,8 +232,6 @@ admin_password = password source $(YOUR_OPENSTACK_DIR)/openrc $(LOGIN) $(PASSWORD) ]]> - - + + This script will supplement openstack dashboard configuration and the panel with Murano "Environments" should appear. + Don't forget to register + Murano API in keystone and set OPENSTACK_HOST in + horizon settings. +
diff --git a/src/getting-started/pom.xml b/src/getting-started/pom.xml index 1f00f43..0704684 100644 --- a/src/getting-started/pom.xml +++ b/src/getting-started/pom.xml @@ -22,7 +22,7 @@ murano-getting-started-guide 1.0.0-SNAPSHOT jar - Murano Deployment Guide + Murano Getting Started Guide @@ -38,6 +38,10 @@ + ${basedir}/src/docbkx/style/config.xsl + + ${basedir}/src/docbkx/style/getting-started.css + true 100 diff --git a/src/getting-started/src/docbkx/content/appendix.xml b/src/getting-started/src/docbkx/content/appendix.xml new file mode 100644 index 0000000..e24e62d --- /dev/null +++ b/src/getting-started/src/docbkx/content/appendix.xml @@ -0,0 +1,161 @@ + + + + Appendix + + Murano VM + + + Your VM MUST be attached to the network with Internet access + and openstack management network (lab network) access. + + + + + Ubuntu Server 12.04 LTS x86_64 + + Installation steps: + + + Install minimal version of the system + + + When prompted, mark OpenSSH Server to be installed + + + + Login as root + + + Enable Cloud Archive repository + + + Update installed OS and packages + + + Add lines below to the + /etc/apt/sources.list.d/grizzly.list + file + +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 + + + + + Update the system + +># apt-get update +># apt-get install ubuntu-cloud-keyring +># apt-get install gplhost-archive-keyring +># apt-get upgrade + + + + + Install additional packages + +># apt-get install mc unzip git make gcc + python-setuptools python-pip + + + + + + CentOS 6.4 x86_64 + + Installation steps: + + + Install minimal version of the system. + + + When prompted, mark OpenSSH Server to be installed + + + Login as root + + + Enable RedHat Openstack and Epel repository + + + Update installed OS and packages + + + Add repositories and update OS + +># yum install -y http://rdo.fedorapeople.org/openstack/ + openstack-grizzly/rdo-release-grizzly.rpm +># yum install -y http://mirror.yandex.ru/ + epel/6/x86_64/epel-release-6-8.noarch.rpm +># yum update +># yum upgrade + + + + + Install additional packages + +># yum install mc unzip git make gcc python-setuptools + python-pip upstart + + + + + + Most of dependent packages will be installed + automatically with setup scripts. + + + Some words about pip (python-pip) version. In order to have + proper versions of python dependency packages installed, + pip version MUST be 1.4 or higher! + + + + How-to determine python-pip version: + +># pip --version + + How-to upgrade pip to latest version: + +># pip install --upgrade pip +># pip install + https://pypi.python.org/packages/source/p/pip/pip-1.4.1.tar.gz + + + + You should pay attention to python-pip after upgrade to + version 1.4, because its filesystem location can change + from /usr/bin/pip to /usr/local/bin/pip! + + + + How to handle this situation: + +># rm /usr/bin/pip +># ln -s /usr/local/bin/pip /usr/bin/pip + + \ No newline at end of file diff --git a/src/getting-started/src/docbkx/content/before_you_begin.xml b/src/getting-started/src/docbkx/content/before_you_begin.xml index 659ace9..7686d3c 100644 --- a/src/getting-started/src/docbkx/content/before_you_begin.xml +++ b/src/getting-started/src/docbkx/content/before_you_begin.xml @@ -21,1036 +21,164 @@ 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"> - About Murano -
- About Murano - Murano is a new service which allows a non-experienced user to deploy reliable Windows based environments in a “push-the-button” manner. The key goal is to provide a UI and API enabling the deployment and operation of Windows Environments at the Windows Services abstraction level. The service is able to orchestrate complex circular dependent cases in order to set up a complex Windows Environment with multiple dependant services. - - The service addresses following use cases: - - - Self-provisioning of predefined Windows services with their dependencies - - - Automation of administrative tasks during data center roll-out - - - Custom windows application as a windows service - - - - The solution provides higher level of abstraction for manipulation Windows Environments. Key concepts are: - - - Windows Service - a service such as Active Directory, MSSQL, or IIS, which usually consists of multiple virtual machines and has multiple dependencies. - - - Windows Environment - a logical unit for all Services and represents a classical Windows Datacenter - - - Windows VM instance - a VM which hosts a Windows Service. A Windows Service might be deployed over several Windows VM instances. - - - - The Key Features of the Service are the following: - - - Native to OpenStack - - - Introduces abstraction level for Windows Environments - - - Supports Availability Zones and Disaster Recovery scenarios - - - Uses native Windows features for HA solutions - - -
-
- Before You Begin -
-
- Naming Conventions - To clearly separate commands and parts of configuration files we use boxes, like shown below: - - - ...# Part of config file here... - - - All commands start either with ‘>$’ mark or with ‘>#’ mark. The difference is that first should be executed as regular user, while second - as superuser (‘root’). - - - >$ echo ‘Execute this command as regular user’ - - - - ># echo ‘Execute this command as root’ - - -
-
- Use Appropriate Branch - There are a few branches that can be found in all Murano repositories: master, release-0.1, release-0.2 and so on. Branch master is the most recent between the releases, but not as stable as release-x.x branches. -
-
- Use Separate vHost in RabbitMQ - In general it is OK to configure Murano services to use the root (‘/’) vHost in RabbitMQ and use the same user credentials as OpenStack services use. - - However, we recommend to create a separate vHost with separate user for each Murano devbox. There are a few reasons for that: - - - this prevents queue name collisions - - - this prevents message stealing from queues - - - this simplify debugging - - - - If you are planning to use only one devbox then you may stay with ‘/’ vHost. - - Steps required to configure your own vHost are described in RabbitMQ Configuration Notes. -
-
- System Requirements -
-
- OpenStack Lab -
-
- Supported OS - - - Ubuntu Server 12.04 x64 - - -
-
- Hardware Requirements - - - CPU: 8+ cores - - - RAM: 12+ GB - - - HDD (select any option) - - - NIC: 1x Ethernet 1+ Gbps - - -
-
- Software Requirements - - - Heat installed - - - Denis Koryavov:This is Getting Started Guide, so is better to create an instruction how to create vhost in RabbitMQ.RabbitMQ configured (+ additional vhosts and user accounts) - - - Windows Server 2012 Standard image imported into Glance (described later) - - - Samba share with prerequisites (described later) - - - OpenStack metadata service. - - -
-
- Devbox - We suggest to use virtual machine for Murano, as it allows you to backup your VM easily. - - Any type of hypervisor software which supports linux as guest OS could be used. - KVM, VMWare and VirtualBox were tested with success. - - There is a Murano VM section in Appendix which contains steps to build your own VM. -
-
- Supported OS - - - Ubuntu Server 12.04 LTS x86_64 - - - CentOS 6.4 x86_64 - - -
-
- Hardware Requirements - - - RAM: 512 MB - - - CPU: 1 core - - - HDD: 20 GB - - - 1 NIC - - -
-
- Software Requirements - - - Packages: - - - X Server is NOT required and system runlevel 3 is preferred. - - -
-
- Setup Lab Environment -
-
- Install OpenStack - You need a working installation of OpenStack first. It could be your own installation which meets the requirements, or a new one using the installation method provided below. -
-
- Using Devstack - Currently the most simple way to build a lab is to use devstack. - - The steps are quite simple: - - - Install and configure OS on your hardware. The recommended OS is Ubuntu Server 12.04 x64. Minimal configuration would be enough. - - - Install all the latest updates. - - - - ># apt-get update># apt-get -y upgrade - - - - Create a user stack - - - - ># adduser stack - - - - Add user stack to sudoers - - - - ># echo ‘stack ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/stack># chmod 0440 /etc/sudoers.d/stack - - - - Create a folder for OpenStack installation files - - - - ># mkdir /opt/stack># chown stack:stack /opt/stack - - - - Clone the devstack repo - - - - ># su stack>$ cd>$ git clone https://github.com/openstack-dev/devstack.git - - - - Checkout the stable/grizzly branch - - - - >$ cd devstack>$ git checkout stable/grizzly - - - - Get localrc and local.sh files - - - - >$ wget https://raw.github.com/stackforge/murano-deployment/release-0.2/getting-started/localrc -O localrc>$ wget https://raw.github.com/stackforge/murano-deployment/release-0.2/getting-started/local.sh -O local.sh>$ chmod +x local.sh - - - - Start devstack - - - - >$ ./stack.sh - - - - When stack.sh finishes  execution your OpenStack installation is ready. - - -
-
- Prepare Shared Prerequisites -
-
- Configure Samba Share - - - Install SAMBA - - - - ># apt-get update># apt-get install samba - - - - Create shared folder - - - - ># mkdir -p /opt/samba/share># chown nobody:nogroup /opt/samba/share - - - - Edit /etc/samba/smb.conf - - - - ...[global]    ...    security = user...[share]    comment = Deployment Share    path = /opt/samba/share    browsable = yes    guest ok = yes    guest account = nobody    read only = no    create mask = 0755 - - - - Restart services - - - - ># restart smbd># restart nmdb - -
-
- Copy Prerequisites Into The Share - - - Create folder structure - - - - ># mkdir -p “/opt/samba/share/Prerequisites/IIS”># mkdir -p “/opt/samba/share/Prerequisites/SQL Server/2012”># mkdir -p “/opt/samba/share/Prerequisites/SQL Server/Tools” - - - - Add files to the folder structure under /opt/samba/share folder: - - -
-
- Build Windows Image - A pre-built Windows Image is required to create environments in Murano. Because of its size it’s better to build the image on the same host where OpenStack is installed. - - This section describe steps required to build such an image. -
-
- Prepare Build Environment - - - Samba should be already installed (See Configure samba share) - - - Clone murano-deployment repository - - - - ># cd /opt/git># git clone git://github.com/stackforge/murano-deployment.git - - - - Change directory to murano-deployment/image-builder folder - - - - ># cd /opt/git/murano-deployment/image-builder - - - - Create folder structure for image builder - - - - ># make build-root - - - - Add files into folder structure under /opt/image-builder folder: - - - Test that all required files are in place - - - - ># make test-build-files - -
-
- Build The Image - - - Get list of supported images - - - - ># make - - - - Run image build process - - - - ># make ws-2012-std - - - - Wait until process finishes - - - The image file ws-2012-std.qcow2 will be stored in /opt/image-builder/share/images folder. - - -
-
- Import Windows Image Into Glance - Now when you’ve built a Windows Image it must be imported into Glance. - - - - Import openrc file which contains environment variables definitions required by OpenStack components - - - - >$ source openrc - - - - Import the Windows Server 2012 image into Glance - - - - >$ cd /opt/image-builder/share/images>$ glance image-create \ --name ws-2012-std \ --disk-format qcow2 \ --container-type bare \ --file ws-2012-std.qcow2 \ --is-public true \ --property murano_image_info='{"type":"ws-2012-std",\ "title":"Windows Server 2012 Standard"}' - - - WARNING: the value of the --property argument named murano_image_info is a JSON string. Only double quotes are valid in JSON, so please type the string exactly as in the example above. -
-
- Setup Devbox - There are a few ways to install Murano devbox - - - using Vagrant automation tool - - - using a script to install all components automatically - - - install everything manually - - - - NOTE: The preferred way is to use script for automated installation. It is described in Automated Way section below. -
-
- Vagrant Way - There is a simple way to get working Murano devbox. This could be done using Vagrant tool. -
-
- Prepare Environment -
-
- Ubuntu - - - Install VirtualBox: - - - - ># apt-get install virtualbox - - - - Install VirtualBox Extension tsufiev:Where is the command for Extension Pack or instructions (if you mean Guest Additions)?Dmitry Teselkin:No, I mean Extension Pack. There is no simple command, the easiest way is to download it from the site and "run it" - VirtuaBox will open the file and imports the pack.tsufiev:Ok, let's leave it as an exercise to the user :)Pack. - - - Install Vagrant: - - - - ># apt-get install vagrant tsufiev:Actually, it is called --no-install-recommendsDmitry Teselkin:Thanks, fixed--no-install-recommends - - - - Upgrade the Vagrant: - - - - ># wget http://files.vagrantup.com/packages/7ec0ee1d00a916f80b109a298bab08e391945243/vagrant_1.2.7_x86_64.deb - - - - - - ># dpkg --install vagrant_1.2.7_x86_64.deb - -
-
- Launch The Box - - - Clone murano-vagrant repository - - - - >$ git clone https://github.comakuznetsova:I think you should change this repositoryDmitry Teselkin:I will, laterDmitry Teselkin:Done/stackforge/murano-deployment.git - - - - Change directory to cloned repository folder - - - - >$ cd murano-deployment/getting-started>$ git checkout -b release-0.2 origin/release-0.2 - - - - IMPORTANT STEP: Edit the lab-binding.rc file - replace all the markers ‘***’ tsufiev:It is reasonable to show here lab-binding.rc with places to be filled - or provide the link to the lab-binding.rc in text below.Dmitry Teselkin:Doneto your settings. For example: - - - - ...# Lab Settings#-------------# Address of the host which provides Keystone service.## LAB_HOST='192.168.1.2'LAB_HOST='***.***.***.***'... - - - - Launch the box: - - - - >$ ./launch-the-box.sh - - - - The script will do the following: - - - Vagrant will do the rest: - - - When everything is done open the http://127.0.0.1:8080/horizon link. - - -
-
- <note><remark>Denis Koryavov:</remark></note><note><remark>It is necessary to write that this way is recommended and Manual Way should be used ONLY if something got wrong with automated way.</remark></note>Automated Way - - Denis Koryavov: - - - It is necessary to write that this way is recommended and Manual Way should be used ONLY if something got wrong with automated way. - - Build your VM using instructions from Murano VM first. - - - - Create a folder to hold cloned repositories - - - - ># mkdir -p /opt/git - - - - Clone murano-deployment repository - - - - ># cd /opt/git># git clone git://github.com/stackforge/murano-deployment.git - - - - Change directory to murano-deployment and switch to release-0.2 branch - - - - ># cd /opt/git/murano-deployment># git checkout -b release-0.2 origin/release-0.2 - - - - Install prerequisites - - - - ># cd /opt/git/murano-deployment/devbox-scripts># ./murano-git-install.sh prerequisites - - - - Configure lab binding configuration file /etc/murano-deployment/lab-binding.rc - - - - LAB_HOST='***Denis Koryavov:I think there should be an other address..***.***.***'AUTH_URL="http://$LAB_HOST:5000/v2.0"ADMIN_USER='admin'ADMIN_PASSWORD='***'RABBITMQ_LOGIN='tsufiev:Is it really 'muranouser' and not 'murano' we use on our devboxes?muranouser'RABBITMQ_PASSWORD='murano'RABBITMQ_VHOST=tsufiev:Considering that most users are an idiots (or like me :)), I'd stress that 'muranovhost' must already exist.'muranovhost'BRANCH_NAME='release-0.Igor Yozhikov:In the release-0.2 default BRANCH_NAME='master' instad of 'release-0.2'2' - - - Please remember that recommend to Use separate vHost in RabbitMQ - - - Install Murano components - - - - ># ./murano-git-install.sh install - - - - Login to the Dashboard using URL http://<your VM IP>/dashboard - - -
-
- Manual Way - Build your VM using instructions fromDenis Myznikov:Link in nowhereDmitry Teselkin:Fixed Murano VM first. - - Package for Ubuntu and CentOS already in progress and will soon be accessible for users. While they are not available, we provide information about how to get and install all murano services from source code below. We made setup scripts for automated installation of our products which accepts install and uninstall command line arguments. Service startup jobs are handled by Upstart. - At first we need to create some kind of working directory. - - NOTE: All installation steps require the superuser rights. - - - ># mkdir -p /opt/git && cd /opt/git - - NOTE: Please, track actual projects stable branch, at the time of writing current stable branch is - release-0.2 -
-
- Murano-Api - - - Get source code - - - - ># git clone https://github.com/stackforge/murano-api -b release-0.2># chmod +x murano-api/setup*.sh - - - - Install the component - - - - ># murano-api/setup.sh install - - - - - - ># murano-api/setup-centos.sh install - - - Configuration: - - ># cd /etc/murano-api && cp murano-api-paste.ini.sample murano-api-paste.ini># cd /etc/murano-api && cp murano-api.conf.sample murano-api.conf - - NOTE: Denis Myznikov:IMHO need add 2 lines - vi murano-api-paste.ini and vi murano-api.conf for better understandingBefore start service, set proper configuration values in configuration files mentioned above. - - tsufiev:Looks like step-by-step instructions. Imagine the user saying to himself: why the hell am i doing this?! ))))Service control: - - ># start murano-api># stop murano-api># restart murano-api># status murano-api - -
-
- Murano-Conductor - - - Get source code - - - - Denis Myznikov:Need to add "cd /opt/git/"># git clone https://github.com/stackforge/murano-conductor -b release-0.2># chmod +x murano-conductor/setup*.sh - - - - Install the component - - - - ># murano-conductor/setup.sh install - - - - on CentOS - - - - ># murano-conductor/setup-centos.sh install - - Configuration - - ># cd /etc/murano-conductor && cp conductor-paste.ini.sample conductor-paste.ini># cd /etc/murano-conductor && cp conductor.conf.sample conductor.conf - - NOTE: Denis Myznikov:IMHO also line - vi conductor.conf, no need to edit the file conductor-paste.initsufiev:Also, s/start/starting the/Before start service, set proper configuration values in configuration files mentioned Denis Myznikov:and start the service by command ># start murano-conductorabove. - - Service control: - - ># start murano-conductor># stop murano-conductor># restart murano-conductor># status murano-conductor - -
-
- Murano-Dashboard - At first, Install OpenStack dashboard(Horizon)  and dependent packages. - - How-to do this: - - - On Ubuntu - - - - ># apt-get install -y memcached libapache2-mod-wsgi openstack-dashboard># dpkg --purge openstack-dashboard-ubuntu-theme # optional step - - After install is complete, openstack dashboard should be available at: http://<your VM IP>/horizon - - - - On CentOS - - - - ># yum install python-netaddr.noarch python-keystoneclient.noarch python-django-horizon.noarch python-django-openstack-auth.noarch  httpd.x86_64 mod_wsgi.x86_64 openstack-dashboard.noarch --assumeyes># chkconfig httpd on - - After install complete, openstack dashboard should be available at: http://<your VM IP>/dashboard - - Installation of the murano-dashboard is described below. - - - Get source code - - - - ># git clone https://github.com/stackforge/murano-dashboard -b release-0.2># chmod +x murano-dashboard/setup*.sh - - - - Install the component - - - - - - - ># murano-dashboard/setup.sh install - - - - - - ># murano-dashboard/setup-centos.sh install - -
-
- Murano Services Configuration -
-
- RabbitMQ Configuration Notes - OpenStack rabbitMQ credentials could be used for murano services, but prefered way is to make additional changes into rabbitMQ configuration, like own vhost, login and password. These steps require superuser rights and should be run on the OpenStack controller node where rabbitMQ service resides. - - How to do this: - - ># rabbitmqctl add_user muranouser muranopassword># rabbitmqctl set_user_tags muranouser administrator># rabbitmqctl add_vhost muranovhost># rabbitmqctl set_permissions -p muranovhost muranouser ".*" ".*" ".*" - -
-
- Keystone Configuration Notes - Service entry for murano-api and endpoint associated with it could also be  configured in the keystone. If there is no record about murano-api in the keystone murano-dashboard would try to reach murano-api service at localhost on the default murano-api port 8082. - - How to add service record into the keystone using python keystone client: - - ># keystone service-create --name muranoapi --type murano --description "Murano-Api Service" - - This command returns UUID of the created service record, which should be used below. - - - ># keystone endpoint-create \  --region RegionOne \  --service-id UUID_from_above \  --publicurl http://murano_vm_address:8082 \  --internalurl http://murano_vm_address:8082 \  --adminurl http://murano_vm_address:8082 - -
-
- Murano-Api - Configuration files of the murano-api service reside at /etc/murano-api directory. Basic configuration parameters are listed below. - - - murano-api.conf - - - - [DEFAULT]...bind_host = 0.0.0.0bind_port = 8082log_file = /var/log/murano-api.log...…[database]...#connection = mysql://mysqluser:mysqlpassword@mysqlhost:3306/muranoconnection = sqlite:////etc/murano-api/murano.sqlite…...[rabbitmq]host = <rabbitmq ip>port = 5672login = <rabbitmq login>password = <rabbitmq password>virtual_host = <rabbitmq vhost>... - - - - murano-api-paste.ini - - - - ...[filter:authtoken]auth_host = <keystone_ip>auth_port = 35357auth_protocol = httpadmin_tenant_name = adminadmin_user = adminadmin_password = admin_password... - -
-
- Murano-Conductor - Configuration files of the murano-conductor service reside at /etc/murano-conductor directory. Basic configuration parameters are listed below: - - - conductor.conf - - - - [DEFAULT]…log_file = /var/log/murano-conductor.log……[keystone]# URL of OpenStack KeyStone service REST API.# Typically only hostname (or IP) needs to be changedauth_url = http://keystone_ip:5000/v2.0......[rabbitmq]host = <rabbitmq ip>port = 5672login = <rabbitmq login>password = <rabbitmq password>virtual_host = <rabbitmq vhost>... - - - - conductor-paste.ini - - - It’s empty but must exist. -
-
- Murano-Dashboard -  Murano-dashboard does not need to be configured, but we need to set up proper OPENSTACK_HOST variable in the OpenStack dashboard configuration file, which resides at /etc/openstack-dashboard directory. It should point to the OpenStack controller node. - - - …# optional, but sometimes very useful to set DEBUG to ‘True’DEBUG = True...OPENSTACK_HOST = “openstack_controller_address” ... - -
-
- Troubleshooting - Set debug options to "true" in all config files - dashboard, api, conductor. - - NOTE: 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. - - First, stop both murano-api and murano-conductor services. We will start them one by one from the console. -
-
- Murano-Api - - - Open new console - - - Start api service manually - - - - ># murano-api --config-dir /etc/murano-api > /var/log/murano-api-live.log &># tailf /var/log/murano-api-live.log - - - - Open dashboard, create and send to deploy some simple environment. - - - Open RabbitMQ web console, open your vhost and ensure that queues were created and there is at least one message. - - - Check log for errors - there shouldn't be any - - - Keep murano-api service running. - - -
-
- Murano-Conductor - - - Open new console - - - Start conductor from console - - - - ># muranoconductor --config-dir /etc/murano-conductor > /var/log/murano-conductor-live.log &># tailf /var/log/murano-conductor-live.log - - - - 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. - - - Check heat stack status. It should not be in FAILED state. If it is - check heat and nova error log to find the cause. - - - Keep murano-conductor service running. - - - - Now, the environment should be created, and instance(s) launched. - - Next, check if instances were configured correctly by the cloudbase init tool. - - Log in to any instance and open powershell log file at C:\Murano\PowerShell.log. There shouldn't be any exceptions logged. Other symptoms of successful configuration is that the instance was renamed and you have to press <Ctrl>+<Alt>+<Del> to log into. Unconfigured instance has autologon enabled for the first logon, so if console is open, the instance is not configured (yet). - - Check that Murano Agent has correct config file. If there is a .bak file, then it was changed by the init script. Check the file,  ensure that it has correct values. - - Check Murano Agent log file. There should be logged all tasks received by the agent from the conductor. - - Check PowerShell log. There should be messages about all functions, executed on the instance. -
-
- Log files -
-
- Murano Log Files - - - /var/log/murano-api.log - - - /var/log/murano-conductor.log - - - akuznetsova:Also need to add info about new log file for dashboardtsufiev:Should be fixed for releases >0.2/var/log/apache2/errors.log - - - /var/log/httpd/errors.log - - -
-
- Windows Log Files - - - C:\Murano\PowerShell.log - - - C:\Murano\Agent\log.txt - - -
-
- Appendix -
-
- Murano VM - NOTE: Your VM MUST be attached to the network with Internet and openstack management network (lab network) access. -
-
- Ubuntu Server 12.04 LTS x86_64 - Installation steps: - - - Install minimal version of the system - - - When prompted, mark OpenSSH Server to be installed - - - Login as root - - - Enable Cloud Archive repository - - - Update installed OS and packages - - - - - - Add lines below to the /etc/apt/sources.list.d/grizzly.list file - - - - deb http://ubuntu-cloud.archive.canonical.com/ubuntu precise-updates/grizzly maindeb http://archive.gplhost.com/debian grizzly maindeb http://archive.gplhost.com/debian grizzly-backports main - - - - - Update the system - - - - ># apt-get update># apt-get install ubuntu-cloud-keyring># apt-get install gplhost-archive-keyringDenis Koryavov:Maybe add # reboot after this command?Denis Myznikov:No. It works.># apt-get upgrade - - - - Install additional packages - - - - ># apt-get install mc unzip git make gcc python-setuptools python-pip - -
-
- CentOS 6.4 x86_64 - Installation steps: - - - Install minimal version of the system. - - - When prompted, mark OpenSSH Server to be installed - - - Login as root - - - Enable RedHat Openstack and Epel repository - - - Update installed OS and packages - - - - - Add repositories and update OS - - - - ># yum install -y http://rdo.fedorapeople.org/openstack/openstack-grizzly/rdo-release-grizzly.rpm># yum install -y http://mirror.yandex.ru/epel/6/x86_64/epel-release-6-8.noarch.rpm># yum update># yum upgrade - - - - Install additional packages - - - - ># yum install mc unzip git make gcc python-setuptools python-pip upstart - - Most of dependent packages will be installed automatically with setup scripts. - - NOTE: Some words about pip (python-pip) version. In order to have proper versions of python dependency packages installed, pip version MUST be 1.4 or higher! - - How-to determine python-pip version: - - ># pip --version - - - How-to upgrade pip to latest version: - - ># pip install --upgrade pip - - or - - ># pip install https://pypi.python.org/packages/source/p/pip/pip-1.4.1.tar.gz - - - NOTE: you should pay attention to python-pip after upgrade to version 1.4, because its filesystem location can change from /usr/bin/pip to /usr/local/bin/pip ! - - How to handle this situation: - - ># rm /usr/bin/pip># ln -s /usr/local/bin/pip /usr/bin/pip - - -
+ Before You Begin + Naming Conventions + + To clearly separate commands and parts of configuration files we use boxes, like shown below: + +... +# Part of config file here + + + All commands start either with ‘>$’ mark or with ‘>#’ mark. + The difference is that first should be executed as regular user, while second - as superuser (‘root’). + + +>$ echo ‘Execute this command as regular user’ +># echo ‘Execute this command as root’ + + Use Appropriate Branch + There are a few branches that can be found in all Murano repositories: master, release-0.1, + release-0.2 and so on. Branch master is the most recent between the releases, but not as stable as release-x.x branches. + Use Separate vHost in RabbitMQ + + In general it is OK to configure Murano services to use the root (‘/’) vHost in RabbitMQ and use the same user credentials as OpenStack services use. + However, we recommend to create a separate vHost with separate user for each Murano devbox. There are a few reasons for that: + + + this prevents queue name collisions + + + this prevents message stealing from queues + + + this simplify debugging + + + + + If you are planning to use only one devbox then you may stay with ‘/’ + vHost. + Steps required to configure your own vHost are described in RabbitMQ Configuration Notes. + +
+ System Requirements + + + OpenStack Lab - a single node Openstack environment. + + + + Devbox - a mahine where all murano components and services are running. + This machine should have access to the Openstack Lab. + + + +
+ OpenStack Lab + + Supported OS + + + + Ubuntu Server 12.04 x64 + + + + Hardware Requirements + + + + CPU: 8+ cores + + + RAM: 12+ GB + + + HDD (select any option) + + + NIC: 1x Ethernet 1+ Gbps + + + + Software Requirements + + + + Heat installed + + + + RabbitMQ configured (+ additional vhosts and user + accounts) + + + + Windows Server 2012 Standard image imported into Glance + (described later) + + + + Samba share with prerequisites (described later) + + + OpenStack metadata service. + + +
+
+ Devbox + + We suggest to use virtual machine for Murano, as it allows you to + backup your VM easily. + Any type of hypervisor software which supports linux as guest OS + could be used. KVM, VMWare and VirtualBox were tested with success. + There is a Murano VM Appendix + which contains steps to build your own VM. + + + Supported OS + + + + Ubuntu Server 12.04 LTS x86_64 + + + CentOS 6.4 x86_64 + + + + Hardware Requirements + + + + RAM: 512 MB + + + CPU: 1 core + + + HDD: 20 GB + + + 1 NIC + + + + Software Requirements + + + + Packages: + + + X Server is NOT required and system runlevel 3 is + preferred. + + + +
+
\ No newline at end of file diff --git a/src/getting-started/src/docbkx/content/overview.xml b/src/getting-started/src/docbkx/content/overview.xml new file mode 100644 index 0000000..84ebfbb --- /dev/null +++ b/src/getting-started/src/docbkx/content/overview.xml @@ -0,0 +1,107 @@ + + + + About Murano + + Murano is a new service which allows a non-experienced user to deploy + reliable Windows based environments in a “push-the-button” manner. The + key goal is to provide a UI and API enabling the deployment and + operation of Windows Environments at the Windows Services abstraction + level. The service is able to orchestrate complex circular dependent + cases in order to set up a complex Windows Environment with multiple + dependant services. + + + The service addresses following use cases: + + + Self-provisioning of predefined Windows services with their dependencies + + + Automation of administrative tasks during data center roll-out + + + Custom windows application as a windows service + + + + + The solution provides higher level of abstraction for manipulation + Windows Environments. Key concepts are: + + + Windows Service - a service such as Active Directory, MSSQL, or IIS, which usually consists of multiple virtual machines and has multiple dependencies. + + + + Windows Environment - a logical unit for all Services and represents a classical Windows Datacenter. + + + + Windows VM instance - a VM which hosts a Windows Service. A Windows Service might be deployed over several Windows VM instances. + + + + + The Key Features of the Service are the following: + + + Native to OpenStack + + + Introduces abstraction level for Windows Environments + + + Supports Availability Zones and Disaster Recovery scenarios + + + Uses native Windows features for HA solutions + + + +
+ Document change history + The following table describes the most recent changes: + + + + Revision Date + Summary of Changes + + + + + September. 4, 2013 + + + + Initial document creation. + + + + + + +
+ + \ No newline at end of file diff --git a/src/getting-started/src/docbkx/content/setup_devbox.xml b/src/getting-started/src/docbkx/content/setup_devbox.xml new file mode 100644 index 0000000..dd58f4c --- /dev/null +++ b/src/getting-started/src/docbkx/content/setup_devbox.xml @@ -0,0 +1,559 @@ + + + + Setup Devbox + There are a few ways to install Murano devbox + + + using Vagrant automation tool + + + using a script to install all components automatically + + + + install everything manually + + + + + The preferred way is to use script for automated + installation. It is described in + Automated Way section below. + + +
+ Vagrant Way + The simplest way to get working Murano devbox is Vagrant tool. + Prepare Environment (Ubuntu) + + + Install VirtualBox: + + + +># apt-get install virtualbox + + + + Install VirtualBox Extension Pack. + + + + Install Vagrant: + + + +># apt-get install vagrant --no-install-recommends + + + + Upgrade the Vagrant: + + + +># wget http://files.vagrantup.com/ + packages/7ec0ee1d00a916f80b109a298bab08e391945243/ + vagrant_1.2.7_x86_64.deb + + +># dpkg --install vagrant_1.2.7_x86_64.deb + + Launch The Box + + + Clone murano-vagrant repository + + + +>$ git clone https://github.com/stackforge/murano-deployment.git + + + + Change directory to cloned repository folder + + + +>$ cd murano-deployment/getting-started +>$ git checkout -b release-0.2 origin/release-0.2 + + + + IMPORTANT STEP: Edit the lab-binding.rc file - replace + all the markers ‘***’ to your settings. For example: + + + + +# Lab Settings +#------------- +# Address of the host which provides Keystone service. +# +# LAB_HOST='192.168.1.2' +LAB_HOST='***.***.***.***' +... + + + + Launch the box: + + + +>$ ./launch-the-box.sh + + + + The script will do the following: + + + Vagrant will do the rest: + + + When everything is done open the http://127.0.0.1:8080/horizon link. + + + +
+
+ Automated Way + + Build your VM using instructions from Murano VM first. + + + + Create a folder to hold cloned repositories + + + +># mkdir -p /opt/git + + + + Clone murano-deployment repository + + + +># cd /opt/git># git clone git://github.com/stackforge/murano-deployment.git + + + + + Change directory to murano-deployment and switch to release-0.2 branch + + + + +># cd /opt/git/murano-deployment +># git checkout -b release-0.2 origin/release-0.2 + + + + Install prerequisites + + + +># cd /opt/git/murano-deployment/devbox-scripts +># ./murano-git-install.sh prerequisites + + + + Configure lab binding configuration file + /etc/murano-deployment/lab-binding.rc + + + + +LAB_HOST='***.***.***.***' + +AUTH_URL="http://$LAB_HOST:5000/v2.0" + +ADMIN_USER='admin' +ADMIN_PASSWORD='***' + +RABBITMQ_LOGIN='muranouser' +RABBITMQ_PASSWORD='murano' +RABBITMQ_VHOST='muranovhost' +BRANCH_NAME='release-0.2' + + It's recommended to use separate vHost in + RabbitMQ + + + + Install Murano components + + + +># ./murano-git-install.sh install + + + + Login to the Dashboard using URL http://uth_port = 35357;your VM IP>/dashboard + + +
+
+ Manual Way + Build your VM using instructions from + Murano VM + first. + + + Package for Ubuntu and CentOS already in progress and will soon + be accessible for users. While they are not available, we provide + information about how to get and install all murano services from + source code below. We made setup scripts for automated installation + of our products which accepts install and uninstall command line + arguments. Service startup jobs are handled by Upstart. + + At first we need to create a working directory. + + All installation steps require the superuser rights. + +># mkdir -p /opt/git && cd /opt/git + + + + Please, track actual projects stable branch, at the time of + writing current stable branch is - release-0.2 + + + + Murano-Api + + + Get source code + + + +># git clone https://github.com/stackforge/murano-api -b release-0.2 +># chmod +x murano-api/setup*.sh + + + + Install the component + + + +># murano-api/setup.sh install + + + + + +># murano-api/setup-centos.sh install + + Configuration: + +># cd /etc/murano-api && cp murano-api-paste.ini.sample \ + murano-api-paste.ini +># cd /etc/murano-api && cp murano-api.conf.sample murano-api.conf + + + + Before start service, set proper configuration values in + configuration files mentioned above. + + + + Service control: + + +># start murano-api +># stop murano-api +># restart murano-api +># status murano-api + + Murano-Conductor + + + Get source code + + + +># git clone https://github.com/stackforge/murano-conductor \ + -b release-0.2 +># chmod +x murano-conductor/setup*.sh + + + + Install the component + + + +># murano-conductor/setup.sh install + + + + on CentOS + + + +># murano-conductor/setup-centos.sh install + + Configuration + +># cd /etc/murano-conductor && cp \ + conductor-paste.ini.sample conductor-paste.ini +># cd /etc/murano-conductor && cp \ + conductor.conf.sample conductor.conf + + + + Before starting the service, set proper configuration values in + configuration files mentioned above. + + + Service control: + +># start murano-conductor +># stop murano-conductor +># restart murano-conductor +># status murano-conductor + + + Murano-Dashboard + At first, Install OpenStack dashboard(Horizon)  and dependent + packages. + + How-to do this: + + + On Ubuntu + + + +># apt-get install -y memcached libapache2-mod-wsgi openstack-dashboard +># dpkg --purge openstack-dashboard-ubuntu-theme # optional step + + After installation is complete, openstack dashboard should be + available at: http://<your VM IP>/horizon + + + + on CentOS + + + +># yum install python-netaddr.noarch \ + python-keystoneclient.noarch \ + python-django-horizon.noarch \ + python-django-openstack-auth.noarch \ +  httpd.x86_64 mod_wsgi.x86_64 \ + openstack-dashboard.noarch --assumeyes +># chkconfig httpd on + + After installation is complete, openstack dashboard should be available + at: http://<your VM IP>/dashboard + + Installation of the murano-dashboard is described below. + + + Get source code + + + +># git clone https://github.com/stackforge/murano-dashboard + -b release-0.2 +># chmod +x murano-dashboard/setup*.sh + + + + Install the component + On Ubuntu + +># murano-dashboard/setup.sh install + + + + on CentOS + +># murano-dashboard/setup-centos.sh install + + + + +
+
+ Murano Services Configuration + This chapter descrides how to configure Murano services + and services communicating with Murano. +
+ RabbitMQ Configuration Notes + OpenStack rabbitMQ credentials could be used for murano services, + but prefered way is to make additional changes into rabbitMQ + configuration, like own vhost, login and password. These steps + require superuser rights and should be run on the OpenStack + controller node where rabbitMQ service resides. + + How to do this: + +># rabbitmqctl add_user muranouser muranopassword +># rabbitmqctl set_user_tags muranouser administrator +># rabbitmqctl add_vhost muranovhost +># rabbitmqctl set_permissions -p muranovhost muranouser ".*" ".*" ".*" + + +
+
+ Keystone Configuration Notes + Service entry for murano-api and endpoint associated with it + could also be  configured in the keystone. If there is no record + about murano-api in the keystone murano-dashboard would try to + reach murano-api service at localhost on the default murano-api + port 8082. + + How to add service record into the keystone using python keystone + client: + +># keystone service-create --name muranoapi --type murano \ + --description "Murano-Api Service" + + This command returns UUID of the created service record, which + should be used below. + +># keystone endpoint-create \ +   --service-id UUID_from_above \ +   --publicurl http://murano_vm_address:8082 \ +   --internalurl http://murano_vm_address:8082 \ +   --adminurl http://murano_vm_address:8082 \ + + +
+
+ Murano-Api Configuration + Configuration files of the murano-api service reside at + /etc/murano-api directory. Basic configuration parameters are + listed below. + + + + murano-api.conf + + + +[DEFAULT] +... +bind_host = 0.0.0.0 +bind_port = 8082 +log_file = /var/log/murano-api.log +... +… +[database] +... +#connection = mysql://mysqluser:mysqlpassword@mysqlhost:3306/murano + +connection = sqlite:////etc/murano-api/murano.sqlite + +… +... +[rabbitmq] +host = <rabbitmq ip> +port = 5672 +login = <rabbitmq login> +password = <rabbitmq password> +virtual_host = <rabbitmq vhost> +... + + + + murano-api-paste.ini + + + +... +[filter:authtoken] +auth_host = <keystone_ip> +auth_port = 35357 +auth_protocol = http +admin_tenant_name = admin +admin_user = admin +admin_password = admin_password +... + +
+
+ Murano-Conductor + + Configuration files of the murano-conductor service reside at + /etc/murano-conductor directory. Basic configuration parameters are + listed below: + + + + conductor.conf + + + +[DEFAULT] +… +log_file = /var/log/murano-conductor.log + +… +… +[keystone] +# URL of OpenStack KeyStone service REST + API. + +# Typically only hostname (or IP) needs to be + changed + +auth_url = http://keystone_ip:5000/v2.0 +... +... +[rabbitmq] +host = <rabbitmq ip> +port = 5672 +login = <rabbitmq login> +password = <rabbitmq password> +virtual_host = <rabbitmq vhost> +... + + + + conductor-paste.ini + + + It’s empty but must exist. +
+
+ Murano-Dashboard +  Murano-dashboard does not need to be configured, but we need to + set up proper OPENSTACK_HOST variable in the OpenStack dashboard + configuration file, which resides at + /etc/openstack-dashboard + directory. It should point to the OpenStack controller node. + + +… +# optional, but sometimes very useful to set DEBUG to ‘True’ +DEBUG = True +... +OPENSTACK_HOST = + “openstack_controller_address” +... + +
+
+ + diff --git a/src/getting-started/src/docbkx/content/setup_lab_environment.xml b/src/getting-started/src/docbkx/content/setup_lab_environment.xml new file mode 100644 index 0000000..87c11fa --- /dev/null +++ b/src/getting-started/src/docbkx/content/setup_lab_environment.xml @@ -0,0 +1,405 @@ + + + + Setup Lab Environment +
+ Install OpenStack + + To install Murano you need a working copy of OpenStack. + If you already have a Openstack installation make sure it meets the requirements + described in this chapter. + To install Openstack that will be ready to use with Murano + follow the instructions below. + + Using Devstack + + Currently the most simple way to build a lab is to use + devstack. The steps are quite simple: + + + + + Install and configure OS on your hardware. The + recommended OS is Ubuntu Server 12.04 x64. Minimal + configuration would be enough. + + + + Install all the latest updates. + + + +># apt-get update +># apt-get -y upgrade + + + + Create a user stack + + + +># adduser stack + + + + Add user stack to sudoers + + + +># echo ‘stack ALL=(ALL) NOPASSWD:ALL' > /etc/sudoers.d/stack +># chmod 0440 /etc/sudoers.d/stack + + + + Create a folder for OpenStack installation files + + + + +># mkdir /opt/stack +># chown stack:stack /opt/stack + + + + Clone the devstack repo + + + +># su stack +>$ cd +>$ git clone https://github.com/openstack-dev/devstack.git + + + + Checkout the stable/grizzly branch + + + +>$ cd devstack +>$ git checkout stable/grizzly + + + + Get localrc and local.sh files + + + +>$ wget https://raw.github.com/stackforge/murano-deployment/release-0.2/ + getting-started/localrc +>$ wget https://raw.github.com/stackforge/murano-deployment/release-0.2/ + getting-started/local.sh -O local.sh-O local.sh +>$ chmod +x local.sh + + + + Start devstack + + + +>$ ./stack.sh + + + When stack.sh finishes execution your OpenStack + installation is ready. + +
+
+ Prepare Shared Prerequisites + Configure Samba Share + + + + Install SAMBA + + + +># apt-get update +># apt-get install samba + + + + Create shared folder + + + +># mkdir -p /opt/samba/share +>#chown nobody:nogroup /opt/samba/share + + + + Edit /etc/samba/smb.conf + + + +... +[global]     + ...     + security = user +... +[share] +    comment = Deployment Share + path = /opt/samba/share   + browsable = yes + guest ok = yes     + guest account = nobody +    read only = no + create mask = 0755 + + + + Restart services + + + +># restart smbd># restart nmdb + + + Copy Prerequisites Into The Share + + + Create folder structure + + + +># mkdir -p “/opt/samba/share/Prerequisites/IIS” +># mkdir -p “/opt/samba/share/Prerequisites/SQL Server/2012” +># mkdir -p “/opt/samba/share/Prerequisites/SQL Server/Tools” + + + + Add files to the folder structure under + /opt/samba/share folder: + + + +
+
+ Build Windows Image + A pre-built Windows Image is required to create environments + in Murano. Because of its size it’s better to build the image + on the same host where OpenStack is installed. This section describe + steps required to build such an image. + + Prepare Build Environment + + + + Samba should be already installed (See Configure samba share) + + + + Clone murano-deployment repository + + + +># cd /opt/git +># git clone git://github.com/stackforge/murano-deployment.git + + + + Change directory to murano-deployment/image-builder + folder + + + + +># cd /opt/git/murano-deployment/image-builder + + + + Create folder structure for image builder + + + +># make build-root + + + + + Download and put the following files to the specified paths under + /opt/image-builder folder: + + + + + Windows 2012 Server ISO evaluation version: libvirt/images/ws­2012­eval.iso + + + + + + VirtIO drivers + + should be placed to libvirt/images/virtio-win-0.1-52.iso + + + + + + + CloudBase-Init for Windows: + + share/files/CloudbaseInitSetup_Beta.msi + + + + + + Far Manager: + + share/files/Far30b3367.x64.20130426.msi + + + + + + Git client + + share/files/Git-1.8.1.2-preview20130201.exe + + + + + + Sysinternals + + Suiteshare/files/SysinternalsSuite.zip + + + + + + unzip.exe tool + + share/files/unzip.exe + + + + + + PowerShell v3 + + share/files/Windows6.1-KB2506143-x64.msu + + + + + + .NET 4.0: + + share/files/dotNetFx40_Full_x86_x64.exe + + + + + + .NET 4.5: + + share/files/dotNetFx45_Full_setup.exe + + + + + + Murano Agent + + share/files/MuranoAgent.zip + + + + + + + Test that all required files are in place + + + +># make test-build-files + + + + Build The Image + + + Get list of supported images + + + +># make + + + + Run image build process + + + + ># make ws-2012-std + + + + Wait until process finishes + + + The image file ws-2012-std.qcow2 will be stored in + /opt/image-builder/share/images folder. + + + + Import Windows Image Into Glance + Now when you’ve built a Windows Image it must be imported into Glance. + + + + Import openrc file which contains environment + variables definitions required by OpenStack components + + + + +>$ source openrc + + + + + Import the Windows Server 2012 image into Glance + +>$ cd /opt/image-builder/share/images +>$ glance image-create --name ws-2012-std --disk-format qcow2 \ + --container-type bare --file ws-2012-std.qcow2 \ + --is-public true \ + --property murano_image_info='{"type":"ws-2012-std",\ + "title":"Windows Server 2012 Standard"}' + + + + + The value of the --property argument named + murano_image_info is a JSON string. Only double quotes are + valid in JSON, so please type the string exactly as in the + example above. + + + + +
+ \ No newline at end of file diff --git a/src/getting-started/src/docbkx/content/troubleshooting.xml b/src/getting-started/src/docbkx/content/troubleshooting.xml new file mode 100644 index 0000000..0455ccc --- /dev/null +++ b/src/getting-started/src/docbkx/content/troubleshooting.xml @@ -0,0 +1,155 @@ + + + + Troubleshooting + + Set debug options to "true" in all config files - dashboard, api, + conductor. + + + 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. + + + First, stop both murano-api and murano-conductor services. We + will start them one by one from the console. + + Murano-Api + + + Open new console + + + Start api service manually + + + +># murano-api --config-dir /etc/murano-api \ + > /var/log/murano-api-live.log & +># tailf /var/log/murano-api-live.log + + + + Open dashboard, create and send to deploy some simple + environment. + + + + Open RabbitMQ web console, open your vhost and ensure + that queues were created and there is at least one message. + + + + Check log for errors - there shouldn't be any + + + Keep murano-api service running. + + + Murano-Conductor + + + Open new console + + + Start conductor from console + + + +># muranoconductor --config-dir /etc/murano-conductor > \ + /var/log/murano-conductor-live.log & +># tailf /var/log/murano-conductor-live.log + + + + 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. + + + + Check heat stack status. It should not be in FAILED + state. If it is - check heat and nova error log to find the + cause. + + + + Keep murano-conductor service running. + + + Now, the environment should be created, and instance(s) + launched. + + + Next, check if instances were configured correctly by the + cloudbase init tool. + + + Log in to any instance and open powershell log file at + C:\Murano\PowerShell.log. There shouldn't be any exceptions logged. + Other symptoms of successful configuration is that the instance was + renamed and you have to press <Ctrl>+<Alt>+<Del> + to log into. Unconfigured instance has autologon enabled for the + first logon, so if console is open, the instance is not configured + (yet). + + Check that Murano Agent has correct config file. If there is a + .bak file, then it was changed by the init script. Check the file, +  ensure that it has correct values. + + Check Murano Agent log file. There should be logged all tasks + received by the agent from the conductor. + + Check PowerShell log. There should be messages about all + functions, executed on the instance. + +
+ Log files + Murano Log Files + + + /var/log/murano-api.log + + + /var/log/murano-conductor.log + + + /var/log/apache2/errors.log + + + + /var/log/httpd/errors.log + + + Windows Log Files + + + C:\Murano\PowerShell.log + + + C:\Murano\Agent\log.txt + + +
+ \ No newline at end of file diff --git a/src/getting-started/src/docbkx/getting-started.xml b/src/getting-started/src/docbkx/getting-started.xml new file mode 100644 index 0000000..4bb51f0 --- /dev/null +++ b/src/getting-started/src/docbkx/getting-started.xml @@ -0,0 +1,69 @@ + + + + Murano Getting Started Guide + + + + + + + + Mirantis, Inc. + + + + 2013 + Mirantis, Inc. + + v0.1 + Murano™ + 2013-09-04 + + + Copyright details are filled in by the template. Change + the value of the role + attribute on the legalnotice element to change the license. + + + + + This document is intended for individuals who wish to + use our product or intend to contribute. + + + + this is a placeholder for the front cover + + + this is a placeholder for the back cover + + + + + + + + + diff --git a/src/getting-started/src/docbkx/style/config.xsl b/src/getting-started/src/docbkx/style/config.xsl new file mode 100644 index 0000000..4e7f3d9 --- /dev/null +++ b/src/getting-started/src/docbkx/style/config.xsl @@ -0,0 +1,10 @@ + + + + + + + + \ No newline at end of file diff --git a/src/getting-started/src/docbkx/style/getting-started.css b/src/getting-started/src/docbkx/style/getting-started.css new file mode 100644 index 0000000..e41b4f9 --- /dev/null +++ b/src/getting-started/src/docbkx/style/getting-started.css @@ -0,0 +1,54 @@ +img { + max-width: 100%; + width: auto; + height: auto; +} + body { + font-family: luxi sans,sans-serif; +} + +.screen { + font-family: monospace; + font-size: 1em; + display: block; + padding: 10px; + border: 1px solid #bbb; + background-color: #eee; + color: #000; + overflow: auto; + border-radius: 2.5px; + -moz-border-radius: 2.5px; + margin: 0.5em 2em; + +} + +.programlisting { + font-family: monospace; + font-size: 1em; + display: block; + padding: 10px; + border: 1px solid #bbb; + background-color: #ddd; + color: #000; + overflow: auto; + border-radius: 2.5px; + -moz-border-radius: 2.5px; + margin: 0.5em 2em; +} + +a[href] { + text-decoration: none; + color: #0a5ba8; + } + +a[href]:hover { + text-decoration:underline +} + +a:visited { + color: #131580; + } + +a:active { + color: #0a5ba8; + } \ No newline at end of file diff --git a/src/user-guide/pom.xml b/src/user-guide/pom.xml index 5166987..58c04d8 100644 --- a/src/user-guide/pom.xml +++ b/src/user-guide/pom.xml @@ -38,6 +38,10 @@ + ${basedir}/src/docbkx/style/config.xsl + + ${basedir}/src/docbkx/style/user-guide.css + true 100 diff --git a/src/user-guide/src/docbkx/content/murano-dashboard.xml b/src/user-guide/src/docbkx/content/murano-dashboard.xml index 833d8e6..6403e58 100644 --- a/src/user-guide/src/docbkx/content/murano-dashboard.xml +++ b/src/user-guide/src/docbkx/content/murano-dashboard.xml @@ -53,8 +53,8 @@ All services should be created in the context of Environment - virtual Windows Data Center. After Environment is created services prototypes and then deploy the Environment. When deploy process is done instances - with your service will be spawned in Openstack. - To create service prototype navigate to environment services by + with your services will be spawned in Openstack. + To create a service prototype navigate to environment services by clicking on the environment name (or on the "Services" button) and click the "Create Service" button. @@ -64,7 +64,7 @@ - You have opportunity to create one of the following services: + You have an opportunity to create one of the following services: @@ -74,14 +74,14 @@ Once you choose service that you want to create click "Next" and fill the form. Forms for each service are specific. - To see more information about filling the form for a specified service follow one of the link below: + To see more information about filling the form for a specific service follow one of the link below: Active Directory: Active Directory is a directory service implemented by Microsoft for Windows domain networks. - In one installation in addition to primary Domain Controller + In one installation, in addition to primary Domain Controller, you can add optional count of secondary Domain Controllers. Any other services you are intending to create can be joined to that domain. @@ -154,11 +154,105 @@
Active Directory + + After you picked the Active Directory service in service creation + wizard you'll see the following form: + - + + + Enter or select values for this fields: + + + + + + + + Domain name + + + + Enter a desired name for a new domain. This name should fit to + DNS Domain Name requirements: it should contain + only A-Z, a-z, 0-9, (.) and (-) and should not end with a dash. + DNS server will be automatically set up on each of the Domain + Controller instances. + Period characters are allowed only when they + are used to delimit the components of domain style + names. Single-level domain is not appropriate. + Note: Only first 15 characters or characters + before first period is used as NetBIOS name. + + + + + Instance Count + + + You can create several Active Directory instances by setting + instance number larger than one. One primary + Domain Controller and a few secondary DCs will be created. + + + + + Account Name + + + You account will have Active Directory administrator rights. + So initial value is "Administrator" but you can change it to any name you like. + + + + + Administrator password + + + Windows requires strong password for service administration. + Your password should have at least one letter + in each + register, a number and a special character. + Password length should be + a minimum of 7 characters. + + Once you forget your password you won't be able + to + operate the service until recovery password + would be entered. So it's + better for Recovery and Administrator password + to be different. + + + + + Confirm password + + Password confirmation is required. + + + + Recovery password + + + Restrictions are the same as for the Administrator password. + Please provide password that is different from Administrator. + It's not required for form validation though. + + + + + Confirm password + + Password confirmation is required. + + + +
Internet Information Service @@ -207,16 +301,137 @@ + Enter or select values for the following fields: + + + + + + + Service Name + + + + Enter a desired name for a service. Just A-Z, + a-z, 0-9, dash and underline are allowed. + + + + + + Administrator password + + + + Windows requires strong password for service + administration. + Your password should have at least one letter + in each register, a number and a special character. + Password length should be a minimum of 7 characters. + + + + + + Confirm password + + + Password confirmation is required. + + + + + Active Directory is configured by the System Administrator + + + + + Enable this option only if you have properly configured rules + that will include service to the domain, that already exists in you environment. + Once you set this option to true, additional fields will appear. (See information below) + + + + + + Domain + + + + Service should be joined to the Active + Directory + domain. Please, create Active Directory Service + prototype first. + + + + + + Mixed-mode Authentication + + + + Mixed authentication mode allows the use of Windows + credentials but supplements them with local SQL + Server user accounts that the administrator may create and + maintain within SQL Server. If this mode is on SA password is required + + + + + + SA Password + + + + Set system administrator password for the MS SQL Server. + Password requirements are the same as previous. + + + + + + + In case pre-configured AD is enabled following fields will appeared: + + + + + + + + Active Directory User + Active Directory Password + + + + Specify administrator user credentials to the existent AD domain + (to which service service will be join according to your system automation setup) + + + + + + + + + +
@@ -242,7 +457,7 @@ You can monitor deploying process. Just go to the Log tab on service - detailed page where you can get by clicking on the service name. + detailed page, where you can get by clicking on the service name. @@ -258,7 +473,7 @@ - As long as installation and configuration are in progress environment + As long as installation and configuration are in progress, environment is in Deploying state. Depending on how many services you are deploying or how many nodes in your cluster, process of spawning instances, installation and post installation settings takes from 10 minutes up to one hour. @@ -269,7 +484,7 @@ - If installation process finished without any errors environment changes its status to + If installation process finished without any errors, environment changes its status to Ready: @@ -282,7 +497,7 @@ Working with deployed environment Congratulations! After some time waiting you are able to operate with the services. - To get information about installed services navigate to service detailed page. + To get information about installed services, navigate to service detailed page. To do that click on the environment name and then on the name of the service you what to know about. @@ -326,9 +541,9 @@
Redeploying Murano Environment - Murano gives opportunity to supplement already deployed environment. - If you deployed the Active Directory service and want to create - any other service just create desired service prototype and click on the "Deploy Environment" button. + Murano gives an opportunity to supplement already deployed environment. + Thus if you already deployed the Active Directory service and want to add + any other services just create desired service prototype and click the "Deploy Environment" button. During service prototype creation you can join this service to the existent Active Directory domain.
@@ -410,7 +625,7 @@
Renaming Murano Environment - It's possible to change name of your environment: just click the "More-> Edit Environment" button on environment index page: + It's possible to change a name of your environment: just click the "More-> Edit Environment" button on environment index page: @@ -433,7 +648,6 @@ Troubleshooting How to debug OpenStack Heat? - If you can execute Heat command via console interface - all good. It is the most simple way to check Heat state on the node - jest execute CLI command 'heat list'. @@ -443,18 +657,18 @@ If 'heat list' returns 503 error - It is means that OpenStack Heat configuration files contains incorrect + It means that OpenStack Heat configuration files contain incorrect credentials. Need to set 'user' = 'heat' and change passwords 'verybadpass' in all configuration files from directory /etc/heat/ If 'heat list' hangs up - Sometimes ypu can see that 'heat list' hangs up. The root of this + Sometimes you can see that 'heat list' hangs up. The root of this problem - connection to the rabbitMQ. How I can connect to LoadBalancer instance in Server Farms? - First of all you should have KeyPair file 'murano-lb-key', you can + First of all you should have KeyPair file 'murano-lb-key'. You can create this file using commands murano-lb-key.priv chmod 600 murano-lb-key.priv ]]> - And after that you should create server farms with this KeyPair. + And after that server farms need to be created with this KeyPair. The second step is to 'how to connect to VM with LoadBalancer': Murano dashboard can not connect to Murano API. How I can fix it? - This is problem has two ways to fix: + This problem has two ways to fix: Add string - - to file /etc/openstack-dashboard/local_settings (or - /etc/openstack-dashboard/local_settings.py - it is depends on OpenStack + to the /etc/openstack-dashboard/local_settings (or + /etc/openstack-dashboard/local_settings.py - it depends on OpenStack configuration) - and after that need to restart web server. + and after that web server restart is needed. Add keystone endpoints for Murano API - Sometimes we can see in logs of the deployments: + Sometimes we can see in deployments logs: - The root of this problem in incorrect configuration - Heat can not + The root of this problem is incorrect configuration - Heat can not create Load Balancer instance. Please, remember that you should have - admin access for project in OpenStack to deploy LoadBalancer and also, + admin access for the project in OpenStack to deploy LoadBalancer and also, you should have KeyPair with default name 'murano-lb-key'. Error in Murano API logs 'No module named helpers.token_sanitizer' - This is problem with pip version. Need to install pip 1.4 and after that reinstall murano-client, murano-common and murano-api. + This pip version problem. Need to install pip 1.4 and after that reinstall murano-client, murano-common and murano-api.
\ No newline at end of file diff --git a/src/user-guide/src/docbkx/images/cluster3.png b/src/user-guide/src/docbkx/images/cluster3.png new file mode 100644 index 0000000..ad1998e Binary files /dev/null and b/src/user-guide/src/docbkx/images/cluster3.png differ diff --git a/src/user-guide/src/docbkx/style/config.xsl b/src/user-guide/src/docbkx/style/config.xsl new file mode 100644 index 0000000..bc80627 --- /dev/null +++ b/src/user-guide/src/docbkx/style/config.xsl @@ -0,0 +1,10 @@ + + + + + + + + \ No newline at end of file diff --git a/src/user-guide/src/docbkx/style/user-guide.css b/src/user-guide/src/docbkx/style/user-guide.css new file mode 100644 index 0000000..4c7b14b --- /dev/null +++ b/src/user-guide/src/docbkx/style/user-guide.css @@ -0,0 +1,55 @@ +img { + max-width: 800px; + width: auto; + height: auto; +} + +body { + font-family: luxi sans,sans-serif; +} + +.screen { + font-family: monospace; + font-size: 1em; + display: block; + padding: 10px; + border: 1px solid #bbb; + background-color: #eee; + color: #000; + overflow: auto; + border-radius: 2.5px; + -moz-border-radius: 2.5px; + margin: 0.5em 2em; + +} + +.programlisting { + font-family: monospace; + font-size: 1em; + display: block; + padding: 10px; + border: 1px solid #bbb; + background-color: #BDBDBD; + color: #000; + overflow: auto; + border-radius: 2.5px; + -moz-border-radius: 2.5px; + margin: 0.5em 2em; +} + +a[href] { + text-decoration: none; + color: #0a5ba8; +} + +a[href]:hover { + text-decoration:underline +} + +a:visited { + color: #131580; +} + +a:active { + color: #0a5ba8; +} \ No newline at end of file