You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by ke...@apache.org on 2013/10/08 21:27:39 UTC
[35/70] [partial] Adding documents from 4.2
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/gsoc-dharmesh.xml
----------------------------------------------------------------------
diff --git a/en-US/gsoc-dharmesh.xml b/en-US/gsoc-dharmesh.xml
new file mode 100644
index 0000000..5e2bf73
--- /dev/null
+++ b/en-US/gsoc-dharmesh.xml
@@ -0,0 +1,149 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "CloudStack_GSoC_Guide.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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 id="gsoc-dharmesh">
+ <title>Dharmesh's 2013 GSoC Proposal</title>
+ <para>This chapter describes Dharmrsh's 2013 Google Summer of Code project within the &PRODUCT; ASF project. It is a copy paste of the submitted proposal.</para>
+ <section id="abstract-dharmesh">
+ <title>Abstract</title>
+ <para>
+ The project aims to bring <ulink url="http://aws.amazon.com/cloudformation/"><citetitle>cloudformation</citetitle></ulink> like service to cloudstack. One of the prime use-case is cluster computing frameworks on cloudstack. A cloudformation service will give users and administrators of cloudstack ability to manage and control a set of resources easily. The cloudformation will allow booting and configuring a set of VMs and form a cluster. Simple example would be LAMP stack. More complex clusters such as mesos or hadoop cluster requires a little more advanced configuration. There is already some work done by Chiradeep Vittal at this front [5]. In this project, I will implement server side cloudformation service for cloudstack and demonstrate how to run mesos cluster using it.
+ </para>
+ </section>
+
+ <section id="mesos">
+ <title>Mesos</title>
+ <para>
+ <ulink url="http://incubator.apache.org/mesos/"><citetitle>Mesos</citetitle></ulink> is a resource management platform for clusters. It aims to increase resource utilization of clusters by sharing cluster resources among multiple processing frameworks(like MapReduce, MPI, Graph Processing) or multiple instances of same framework. It provides efficient resource isolation through use of containers. Uses zookeeper for state maintenance and fault tolerance.
+ </para>
+ </section>
+
+ <section id="mesos-use">
+ <title>What can run on mesos ?</title>
+
+ <para><emphasis role="bold">Spark:</emphasis> A cluster computing framework based on the Resilient Distributed Datasets (RDDs) abstraction. RDD is more generalized than MapReduce and can support iterative and interactive computation while retaining fault tolerance, scalability, data locality etc.</para>
+
+ <para><emphasis role="bold">Hadoop:</emphasis>: Hadoop is fault tolerant and scalable distributed computing framework based on MapReduce abstraction.</para>
+
+ <para><emphasis role="bold">Begel:</emphasis>: A graph processing framework based on pregel.</para>
+
+ <para>and other frameworks like MPI, Hypertable.</para>
+ </section>
+
+ <section id="mesos-deploy">
+ <title>How to deploy mesos ?</title>
+
+ <para>Mesos provides cluster installation <ulink url="https://github.com/apache/mesos/blob/trunk/docs/Deploy-Scripts.textile"><citetitle>scripts</citetitle></ulink> for cluster deployment. There are also scripts available to deploy a cluster on <ulink url="https://github.com/apache/mesos/blob/trunk/docs/EC2-Scripts.textile"><citetitle>Amazon EC2</citetitle></ulink>. It would be interesting to see if this scripts can be leveraged in anyway.</para>
+ </section>
+
+ <section id="deliverables-dharmesh">
+ <title>Deliverables</title>
+ <orderedlist>
+ <listitem>
+ <para>Deploy CloudStack and understand instance configuration/contextualization</para>
+ </listitem>
+ <listitem>
+ <para>Test and deploy Mesos on a set of CloudStack based VM, manually. Design/propose an automation framework</para>
+ </listitem>
+ <listitem>
+ <para>Test stackmate and engage chiradeep (report bugs, make suggestion, make pull request)</para>
+ </listitem>
+ <listitem>
+ <para>Create cloudformation template to provision a Mesos Cluster</para>
+ </listitem>
+ <listitem>
+ <para>Compare with Apache Whirr or other cluster provisioning tools for server side implementation of cloudformation service.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section id="arch-and-tools">
+ <title>Architecture and Tools</title>
+
+ <para>The high level architecture is as follows:</para>
+
+ <para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/mesos-integration-arch.jpg"/>
+ </imageobject>
+ </mediaobject>
+ </para>
+
+
+ <para>It includes following components:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>CloudFormation Query API server:</para>
+ <para>This acts as a point of contact to and exposes CloudFormation functionality as Query API. This can be accessed directly or through existing tools from Amazon AWS for their cloudformation service. It will be easy to start as a module which resides outside cloudstack at first and I plan to use dropwizard [3] to start with. Later may be the API server can be merged with cloudstack core. I plan to use mysql for storing details of clusters.</para>
+ </listitem>
+
+ <listitem>
+ <para>Provisioning:</para>
+
+ <para>Provisioning module is responsible for handling the booting process of the VMs through cloudstack. This uses the cloudstack APIs for launching VMs. I plan to use preconfigured templates/images with required dependencies installed, which will make cluster creation process much faster even for large clusters. Error handling is very important part of this module. For example, what you do if few VMs fail to boot in cluster ?</para>
+ </listitem>
+
+ <listitem>
+ <para>Configuration:</para>
+
+ <para>This module deals with configuring the VMs to form a cluster. This can be done via manual scripts/code or via configuration management tools like chef/ironfan/knife. Potentially workflow automation tools like rundeck [4] also can be used. Also Apache whirr and Provisionr are options. I plan to explore this tools and select suitable ones.</para>
+ </listitem>
+
+ </orderedlist>
+ </section>
+
+ <section id="api">
+ <title>API</title>
+
+ <para>Query <ulink url="http://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_Operations.html"><citetitle>API</citetitle></ulink> will be based on Amazon AWS cloudformation service. This will allow leveraging existing <ulink url="http://aws.amazon.com/developertools/AWS-CloudFormation"><citetitle>tools</citetitle></ulink> for AWS.</para>
+ </section>
+
+ <section id="timeline">
+ <title>Timeline</title>
+ <para>1-1.5 week : project design. Architecture, tools selection, API design</para>
+ <para>1-1.5 week : getting familiar with cloudstack and stackmate codebase and architecture details</para>
+ <para>1-1.5 week : getting familiar with mesos internals</para>
+ <para>1-1.5 week : setting up the dev environment and create mesos templates</para>
+ <para>2-3 week : build provisioning and configuration module</para>
+ <para>Midterm evaluation: provisioning module, configuration module</para>
+ <para>2-3 week : develope cloudformation server side implementation</para>
+ <para>2-3 week : test and integrate</para>
+ </section>
+
+ <section id="future-work">
+ <title>Future Work</title>
+ <orderedlist>
+ <listitem>
+ <para><emphasis role="bold">Auto Scaling:</emphasis></para>
+ <para>Automatically adding or removing VMs from mesos cluster based on various conditions like utilization going above/below a static threshold. There can be more sophisticated strategies based on prediction or fine grained metric collection with tight integration with mesos framework.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">Cluster Simulator:</emphasis></para>
+ <para>Integrating with existing simulator to simulate mesos clusters. This can be useful in various scenarios, for example while developing a new scheduling algorithm, testing autoscaling etc.</para>
+ </listitem>
+ </orderedlist>
+ </section>
+</chapter>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/gsoc-imduffy15.xml
----------------------------------------------------------------------
diff --git a/en-US/gsoc-imduffy15.xml b/en-US/gsoc-imduffy15.xml
new file mode 100644
index 0000000..652152f
--- /dev/null
+++ b/en-US/gsoc-imduffy15.xml
@@ -0,0 +1,395 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "CloudStack_GSoC_Guide.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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 id="gsoc-imduffy15">
+ <title>Ians's 2013 GSoC Proposal</title>
+ <para>This chapter describes Ians 2013 Google Summer of Code project within the &PRODUCT; ASF project. It is a copy paste of the submitted proposal.</para>
+ <section id="ldap-user-provisioning">
+ <title>LDAP user provisioning</title>
+ <para>
+ "Need to automate the way the LDAP users are provisioned into cloud stack. This will mean better
+ integration with a LDAP server, ability to import users and a way to define how the LDAP user
+ maps to the cloudstack users."
+ </para>
+ </section>
+ <section id="abstract">
+ <title>Abstract</title>
+ <para>
+ The aim of this project is to provide an more effective mechanism to provision users from LDAP
+ into cloudstack. Currently cloudstack enables LDAP authentication. In this authentication users
+ must be first setup in cloudstack. Once the user is setup in cloudstack they can authenticate
+ using their LDAP username and password. This project will improve Cloudstack LDAP integration
+ by enabling users be setup automatically using their LDAP credential
+ </para>
+ </section>
+ <section id="deliverables">
+ <title>Deliverables</title>
+ <itemizedlist>
+ <listitem>
+ <para>Service that retrieves a list of LDAP users from a configured group</para>
+ </listitem>
+ <listitem>
+ <para>Extension of the cloudstack UI "Add User" screen to offer user list from LDAP</para>
+ </listitem>
+ <listitem>
+ <para>Add service for saving new user it details from LDAP</para>
+ </listitem>
+ <listitem>
+ <para>BDD unit and acceptance automated testing</para>
+ </listitem>
+ <listitem>
+ <para>Document change details</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="quantifiable-results">
+ <title>Quantifiable Results</title>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>Given</entry>
+ <entry>An administrator wants to add new user to cloudstack and LDAP is setup in cloudstack</entry>
+ </row>
+ <row>
+ <entry>When</entry>
+ <entry>The administrator opens the "Add User" screen</entry>
+ </row>
+ <row>
+ <entry>Then</entry>
+ <entry>A table of users appears for the current list of users (not already created on cloudstack) from the LDAP group displaying their usernames, given name and email address. The timezone dropdown will still be available beside each user</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para/>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>Given</entry>
+ <entry>An administrator wants to add new user to cloudstack and LDAP is not setup in cloudstack</entry>
+ </row>
+ <row>
+ <entry>When</entry>
+ <entry>The administrator opens the "Add User" screen</entry>
+ </row>
+ <row>
+ <entry>Then</entry>
+ <entry>The current add user screen and functionality is provided</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para/>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>Given</entry>
+ <entry>An administrator wants to add new user to cloudstack and LDAP is setup in cloudstack</entry>
+ </row>
+ <row>
+ <entry>When</entry>
+ <entry>The administrator opens the "Add User" screen and mandatory information is missing</entry>
+ </row>
+ <row>
+ <entry>Then</entry>
+ <entry>These fields will be editable to enable you to populate the name or email address</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para/>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>Given</entry>
+ <entry>An administrator wants to add new user to cloudstack, LDAP is setup and the user being created is in the LDAP query group</entry>
+ </row>
+ <row>
+ <entry>When</entry>
+ <entry>The administrator opens the "Add User" screen</entry>
+ </row>
+ <row>
+ <entry>Then</entry>
+ <entry>There is a list of LDAP users displayed but the user is present in the list</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para/>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>Given</entry>
+ <entry>An administrator wants to add a new user to cloudstack, LDAP is setup and the user is not in the query group</entry>
+ </row>
+ <row>
+ <entry>When</entry>
+ <entry>The administrator opens the "Add User" screen</entry>
+ </row>
+ <row>
+ <entry>Then</entry>
+ <entry>There is a list of LDAP users displayed but the user is not in the list</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para/>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>Given</entry>
+ <entry>An administrator wants to add a group of new users to cloudstack</entry>
+ </row>
+ <row>
+ <entry>When</entry>
+ <entry>The administrator opens the "Add User" screen, selects the users and hits save</entry>
+ </row>
+ <row>
+ <entry>Then</entry>
+ <entry>The list of new users are saved to the database</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para/>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>Given</entry>
+ <entry>An administrator has created a new LDAP user on cloudstack</entry>
+ </row>
+ <row>
+ <entry>When</entry>
+ <entry>The user authenticates against cloudstack with the right credentials</entry>
+ </row>
+ <row>
+ <entry>Then</entry>
+ <entry>They are authorised in cloudstack</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para/>
+ <informaltable>
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>Given</entry>
+ <entry>A user wants to edit an LDAP user</entry>
+ </row>
+ <row>
+ <entry>When</entry>
+ <entry>They open the "Edit User" screen</entry>
+ </row>
+ <row>
+ <entry>Then</entry>
+ <entry>The password fields are disabled and cannot be changed</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para/>
+ </section>
+ <section id="the-design-document">
+ <title>The Design Document</title>
+ <para>
+ <emphasis role="bold">
+ LDAP user list service
+ </emphasis>
+ </para>
+ <para>
+ <emphasis role="bold">name:</emphasis> ldapUserList
+ </para>
+ <para>
+ <emphasis role="bold">responseObject:</emphasis> LDAPUserResponse {username,email,name}
+ </para>
+ <para>
+ <emphasis role="bold">parameter:</emphasis> listType:enum {NEW, EXISTING,ALL} (Default to ALL if no option provided)
+ </para>
+ <para>
+ Create a new API service call for retreiving the list of users from LDAP. This will call a new
+ ConfigurationService which will retrieve the list of users using the configured search base and the query
+ filter. The list may be filtered in the ConfigurationService based on listType parameter
+ </para>
+ <para>
+ <emphasis role="bold">
+ LDAP Available Service
+ </emphasis>
+ </para>
+ <para>
+ <emphasis role="bold">name:</emphasis> ldapAvailable
+ </para>
+ <para>
+ <emphasis role="bold">responseObject</emphasis> LDAPAvailableResponse {available:boolean}
+ </para>
+ <para>
+ Create a new API service call veriying LDAP is setup correctly verifying the following configuration elements are all set:
+ <itemizedlist>
+ <listitem>
+ <para>ldap.hostname</para>
+ </listitem>
+ <listitem>
+ <para>ldap.port</para>
+ </listitem>
+ <listitem>
+ <para>ldap.usessl</para>
+ </listitem>
+ <listitem>
+ <para>ldap.queryfilter</para>
+ </listitem>
+ <listitem>
+ <para>ldap.searchbase</para>
+ </listitem>
+ <listitem>
+ <para>ldap.dn</para>
+ </listitem>
+ <listitem>
+ <para>ldap.password</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ <emphasis role="bold">
+ LDAP Save Users Service
+ </emphasis>
+ </para>
+ <para>
+ <emphasis role="bold">name:</emphasis> ldapSaveUsers
+ </para>
+ <para>
+ <emphasis role="bold">responseObject:</emphasis> LDAPSaveUsersRssponse {list<![CDATA[<UserResponse>]]>}
+ </para>
+ <para>
+ <emphasis role="bold">parameter:</emphasis> list of users
+ </para>
+ <para>
+ Saves the list of objects instead. Following the functionality in CreateUserCmd it will
+ <itemizedlist>
+ <listitem>
+ <para>Create the user via the account service</para>
+ </listitem>
+ <listitem>
+ <para>Handle the response</para>
+ </listitem>
+ </itemizedlist>
+ It will be decided whether a transation should remain over whole save or only over individual users. A list of UserResponse will be returned.
+ </para>
+ <para>
+ <emphasis role="bold">
+ Extension of cloudstack UI "Add User" screen
+ </emphasis>
+ </para>
+ <para>
+ Extend account.js enable the adding of a list of users with editable fields where required. The new "add user" screen for LDAP setup will:
+ <itemizedlist>
+ <listitem>
+ <para>Make an ajax call to the ldapAvailable, ldapuserList and ldapSaveUsers services</para>
+ </listitem>
+ <listitem>
+ <para>Validate on username, email, firstname and lastname</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ <emphasis role="bold">
+ Extension of cloudstack UI "Edit User" screen
+ </emphasis>
+ </para>
+ <para>
+ Extend account.js to disable the password fields on the edit user screen if LDAP available, specifically:
+ <itemizedlist>
+ <listitem>
+ <para>Make an ajax call to the ldapAvailable, ldapuserList and ldapSaveUsers services</para>
+ </listitem>
+ <listitem>
+ <para>Validate on username, email, firstname and lastname. Additional server validation will nsure the password has not changed</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+ <section id="approach">
+ <title>Approach</title>
+ <para>
+ To get started a development cloudstack environment will be created with DevCloud used to verify changes. Once the schedule is agreed with the mentor the deliverables will be broken into small user stories with expected delivery dates set. The development cycle will focus on BDD, enforcing all unit and acceptance tests are written first.
+ </para>
+ <para>
+ A build pipe line for continious delivery environment around cloudstack will be implemented, the following stages will be adopted:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Stage</entry>
+ <entry>Action</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>Commit</entry>
+ <entry>Run unit tests</entry>
+ </row>
+ <row>
+ <entry>Sonar</entry>
+ <entry>Runs code quality metrics</entry>
+ </row>
+ <row>
+ <entry>Acceptance</entry>
+ <entry>Deploys the devcloud and runs all acceptance tests</entry>
+ </row>
+ <row>
+ <entry>Deployment</entry>
+ <entry>Deploy a new management server using Chef</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+ <section id="about-me">
+ <title>About me</title>
+ <para>
+ I am a Computer Science Student at Dublin City University in Ireland. I have interests in virtualization,
+automation, information systems, networking and web development
+ </para>
+ <para>
+ I was involved with a project in a K-12(educational) environment of moving their server systems over
+to a virtualized environment on ESXi. I have good knowledge of programming in Java, PHP and
+Scripting langages. During the configuration of an automation system for OS deployment I experienced
+some exposure to scripting in powershell, batch, vbs and bash and configuration of PXE images based
+of WinPE and Debian.
+Additionally I am also a mentor in an opensource teaching movement called CoderDojo, we teach kids
+from the age of 8 everything from web page, HTML 5 game and raspberry pi development. It's really
+cool.
+ </para>
+ <para>
+ I’m excited at the opportunity and learning experience that cloudstack are offering with this project.
+ </para>
+ </section>
+</chapter>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/gsoc-meng.xml
----------------------------------------------------------------------
diff --git a/en-US/gsoc-meng.xml b/en-US/gsoc-meng.xml
new file mode 100644
index 0000000..1de259d
--- /dev/null
+++ b/en-US/gsoc-meng.xml
@@ -0,0 +1,235 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "CloudStack_GSoC_Guide.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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 id="gsoc-meng">
+ <title>Meng's 2013 GSoC Proposal</title>
+ <para>This chapter describes Meng's 2013 Google Summer of Code project within the &PRODUCT; ASF project. It is a copy paste of the submitted proposal.</para>
+ <section id="Project-Description">
+ <title>Project Description</title>
+ <para>
+ Getting a hadoop cluster going can be challenging and painful due to the tedious configuration phase and the diverse idiosyncrasies of each cloud provider. Apache Whirr<ulink url="http://whirr.apache.org/ "><citetitle>[1]</citetitle></ulink> and Provisionr is a set of libraries for running cloud services in an automatic or semi-automatic fashion. They take advantage of a cloud-neutral library called jclouds<ulink url=" http://www.jclouds.org/documentation/gettingstarted/what-is-jclouds/"><citetitle>[2]</citetitle></ulink> to create one-click, auto-configuring hadoop clusters on multiple clouds. Since jclouds supports CloudStack API, most of the services provided by Whirr and Provisionr should work out of the box on CloudStack. My first task is to test that assumption, make sure everything is well documented, and correct all issues with the latest version of CloudStack (4.0 and 4.1).
+ </para>
+
+<para>
+The biggest challenge for hadoop provisioning is automatically configuring each instance at launch time based on what it is supposed to do, a process known as contextualization<ulink url="http://dl.acm.org/citation.cfm?id=1488934"><citetitle>[3]</citetitle></ulink><ulink url="http://www.nimbusproject.org/docs/current/clouds/clusters2.html "><citetitle>[4]</citetitle></ulink>. It causes last minute changes inside an instance to adapt to a cluster environment. Many automated cloud services are enabled by contextualization. For example in one-click hadoop clusters, contextualization basically amounts to generating and distributing ssh key pairs among instances, telling an instance where the master node is and what other slave nodes it should be aware of, etc. On EC2 contextualization is done via passing information through the EC2_USER_DATA entry<ulink url="http://aws.amazon.com/amazon-linux-ami/ "><citetitle>[5]</citetitle></ulink><ulink url="https://svn.apache.org/repos/asf/whirr/bra
nches/contrib-python/src/py/hadoop/cloud/data/hadoop-ec2-init-remote.sh"><citetitle>[6]</citetitle></ulink>. Whirr and Provisionr embrace this feature to provision hadoop instances on EC2. My second task is to test and extend Whirr and Provisionr’s one-click solution on EC2 to CloudStack and also improve CloudStack’s support for Whirr and Provisionr to enable hadoop provisioning on CloudStack based clouds.
+</para>
+<para>
+My third task is to add a Query API that is compatible with Amazon Elastic MapReduce (EMR) to CloudStack. Through this API, all hadoop provisioning functionality will be exposed and users can reuse cloud clients that are written for EMR to create and manage hadoop clusters on CloudStack based clouds.
+</para>
+ </section>
+
+ <section id="Project-Details">
+ <title>Project Details</title>
+ <para>
+ Whirr defines four roles for the hadoop provisioning service: Namenode, JobTracker, Datanode and TaskTraker. With the help of CloudInit<ulink url="https://help.ubuntu.com/community/CloudInit "><citetitle>[7]</citetitle></ulink> (a popular package for cloud instance initialization), each VM instance is configured based on its role and a compressed file that is passed in the EC2_USER_DATA entry. Since CloudStack also supports EC2_USER_DATA, I think the most feasible way to have hadoop provisioning on CloudStack is to extend Whirr’s solution on EC2 to CloudStack platform and to make necessary adjustment based on CloudStack’s
+ </para>
+
+ <para>
+ Whirr and Provisionr deal with two critical issues in their role configuration scripts (configure-hadoop-role_list): SSH key authentication and hostname configuration.
+ </para>
+ <orderedlist>
+ <listitem><para>
+ SSH Key Authentication. The need for SSH Key based authentication is required so that the master node can login to slave nodes to start/stop hadoop daemons. Also each node needs to login to itself to start its own hadoop daemons. Traditionally this is done by generating a key pair on the master node and distributing the public key to all slave nodes. This can be only done with human intervention. Whirr works around this problem on EC2 by having a common key pair for all nodes in a hadoop cluster. Thus every node is able to login to one another. The key pair is provided by users and obtained by CloudInit inside an instance from metadata service. As far as I know, Cloudstack does not support user-provided ssh key authentication. Although CloudStack has the createSSHKeyPair API<ulink url="http://cloudstack.apache.org/docs/en-US/Apache_CloudStack/4.0.2/html/Installation_Guide/using-sshkeys.html "><citetitle>[8]</citetitle></ulink> to generate SSH keys and users can create an instance
template that supports SSH keys, there is no easy way to have a unified SSH key on all cluster instances. Besides Whirr prefers minimal image management, so having a customized template doesn’t seem quite fit here.
+ </para></listitem>
+ <listitem><para>
+ Hostname configuration. The hostname of each instance has to be properly set and injected into the set of hadoop config files (core-site.xml, hdfs-site.xml, mapred-site.xml ). For an EC2 instance, its host name is converted from a combination of its public IP and an EC2-specific pre/suffix (e.g. an instance with IP 54.224.206.71 will have its hostname set to ec2-54-224-206-71.compute-1.amazonaws.com). This hostname amounts to the Fully Qualified Domain Name that uniquely identifies this node on the network. As for the case of CloudStack, if users do not specify a name the hostname that identifies a VM on a network will be a unique UUID generated by CloudStack<ulink url="https://cwiki.apache.org/CLOUDSTACK/allow-user-provided-hostname-internal-vm-name-on-hypervisor-instead-of-cloud-platform-auto-generated-name-for-guest-vms.html"><citetitle>[9]</citetitle></ulink>.
+
+
+
+ </para></listitem>
+ </orderedlist>
+ <para>
+ These two are the main issues that need support improvement on the CloudStack side. Other things like preparing disks, installing hadoop tarballs and starting hadoop daemons can be easily done as they are relatively role/instance-independent and static. Runurl can be used to simplify user-data scripts.
+
+
+
+ </para>
+ <para>
+ After we achieve hadoop provisioning on CloudStack using Whirr we can go further to add a Query API to CloudStack to expose this functionality. I will write an API that is compatible with Amazon Elastic MapReduce Service (EMR)<ulink url="http://docs.aws.amazon.com/ElasticMapReduce/latest/API/Welcome.html "><citetitle>[10]</citetitle></ulink> so that users can reuse clients that are written for EMR to submit jobs to existing hadoop clusters, poll job status, terminate a hadoop instance and do other things on CloudStack based clouds. There are eight actions<ulink url="http://docs.aws.amazon.com/ElasticMapReduce/latest/API/API_Operations.html "><citetitle>[11]</citetitle></ulink> now supported in EMR API. I will try to implement as many as I can during the period of GSoC. The following statements give some examples of the API that I will write.
+ </para>
+ <programlisting><![CDATA[
+ https://elasticmapreduce.cloudstack.com?Action=RunJobFlow &Name=MyJobFlowName &Instances.MasterInstanceType=m1.small &Instances.SlaveInstanceType=m1.small &Instances.InstanceCount=4
+]]></programlisting>
+<para>
+This will launch a new hadoop cluster with four instances using specified instance types and add a job flow to it.
+</para>
+<programlisting><![CDATA[
+https://elasticmapreduce.cloudstack.com?Action=AddJobFlowSteps &JobFlowId=j-3UN6WX5RRO2AG &Steps.member.1.Name=MyStep2 &Steps.member.1.HadoopJarStep.Jar=MyJar
+]]></programlisting>
+<para>
+This will add a step to the existing job flow with ID j-3UN6WX5RRO2AG. This step will run the specified jar file.
+</para>
+<programlisting><![CDATA[
+https://elasticmapreduce.cloudstack.com?Action=DescribeJobFlows &JobFlowIds.member.1=j-3UN6WX5RRO2AG
+]]></programlisting>
+<para>
+This will return the status of the given job flow.
+</para>
+ </section>
+
+ <section id="Roadmap">
+ <title>Roadmap</title>
+
+ <para><emphasis role="bold">Jun. 17 ∼ Jun. 30</emphasis> </para>
+ <orderedlist>
+ <listitem><para>
+ Learn CloudStack and Apache Whirr/Provisionr APIs; Deploy a CloudStack cluster.
+ </para></listitem>
+
+ <listitem><para>
+ Identify how EC2_USER_DATA is passed and executed on each CloudStack instance.
+ </para></listitem>
+ <listitem><para>
+ Figure out how the files passed in EC2_USER_DATA are acted upon by CloudInit.
+ </para></listitem>
+ <listitem><para>
+ Identify files in /etc/init/ that are used or modified by Whirr and Provisionr for hadoop related configuration.
+ </para></listitem>
+ <listitem><para>
+ Deploy a hadoop cluster on CloudStack via Whirr/Provisionr. This is to test what are missing in CloudStack or Whirr/Provisionr in terms of their support for each other.
+ </para></listitem>
+ </orderedlist>
+ <para><emphasis role="bold">Jul. 1∼ Aug. 1</emphasis> </para>
+ <orderedlist>
+ <listitem><para>
+ Write scripts to configure VM hostname on CloudStack with the help of CloudInit;
+ </para></listitem>
+ <listitem><para>
+ Write scripts to distribute SSH keys among CloudStack instances. Add the capability of using user-provided ssh key for authentication to CloudStack.
+ </para></listitem>
+ <listitem><para>
+ Take care of the other things left for hadoop provisioning, such as mounting disks, installing hadoop tarballs, etc.
+ </para></listitem>
+ <listitem><para>
+ Compose files that need to be passed in EC2_USER_DATA to each CloudStack instance . Test these files and write patches to make sure that Whirr/Provisionr can succefully deploy one-click hadoop clusters on CloudStack.
+ </para></listitem>
+ </orderedlist>
+ <para><emphasis role="bold">Aug. 3 ∼ Sep. 8</emphasis> </para>
+ <orderedlist>
+ <listitem><para>
+ Design and build an Elastic Mapreduce API for CloudStack that takes control of hadoop cluster creation and management.
+ </para></listitem>
+ <listitem><para>
+ Implement the eight actions defined in EMR API. This task might take a while.
+ </para></listitem>
+
+ </orderedlist>
+ <para><emphasis role="bold">Sep. 10 ∼ Sep. 23</emphasis> </para>
+ <orderedlist>
+ <listitem><para>
+
+ Code cleaning and documentation wrap up.
+
+ </para></listitem>
+
+ </orderedlist>
+
+
+ </section>
+
+ <section id="Deliverables-meng">
+ <title>Deliverables</title>
+ <orderedlist>
+ <listitem><para>
+
+ Whirr has limited support for CloudStack. Check what’s missing and make sure all steps are properly documented on the Whirr and CloudStack websites.
+ </para></listitem>
+ <listitem><para>
+ Contribute code to CloudStack and and send patches to Whirr/Provisionr if necessary to enable hadoop provisioning on CloudStack via Whirr/Provisionr.
+ </para></listitem>
+ <listitem><para>
+ Build an EMR-compatible API for CloudStack.
+ </para></listitem>
+ </orderedlist>
+ </section>
+ <section id="Nice-to-have">
+ <title>Nice to have</title>
+ <para>In addition to the required deliverables, it’s nice to have the following:</para>
+ <orderedlist>
+ <listitem><para>
+
+ The capability to add and remove hadoop nodes dynamically to enable elastic hadoop clusters on CloudStack.
+
+ </para></listitem>
+ <listitem><para>
+ A review of the existing tools that offer one-click provisioning and make sure that they support CloudStack based clouds.
+ </para></listitem>
+ </orderedlist>
+ </section>
+
+ <section id="References">
+ <title>References</title>
+
+ <orderedlist>
+ <listitem><para>
+
+ http://whirr.apache.org/
+ </para></listitem>
+ <listitem><para>
+ http://www.jclouds.org/documentation/gettingstarted/what-is-jclouds/
+ </para></listitem>
+ <listitem><para>
+ Katarzyna Keahey, Tim Freeman, Contextualization: Providing One-Click Virtual Clusters
+ </para></listitem>
+ <listitem><para>
+ http://www.nimbusproject.org/docs/current/clouds/clusters2.html
+ </para></listitem>
+ <listitem><para>
+ http://aws.amazon.com/amazon-linux-ami/
+ </para></listitem>
+ <listitem><para>
+ https://svn.apache.org/repos/asf/whirr/branches/contrib-python/src/py/hadoop/cloud/data/hadoop-ec2-init-remote.sh
+ </para></listitem>
+ <listitem><para>
+ https://help.ubuntu.com/community/CloudInit
+ </para></listitem>
+ <listitem><para>
+ http://cloudstack.apache.org/docs/en-US/Apache_CloudStack/4.0.2/html/Installation_Guide/using-sshkeys.html
+ </para></listitem>
+ <listitem><para>
+ https://cwiki.apache.org/CLOUDSTACK/allow-user-provided-hostname-internal-vm-name-on-hypervisor-instead-of-cloud-platform-auto-generated-name-for-guest-vms.html
+ </para></listitem>
+ <listitem><para>
+http://docs.aws.amazon.com/ElasticMapReduce/latest/API/Welcome.html
+ </para></listitem>
+ <listitem><para>
+ http://docs.aws.amazon.com/ElasticMapReduce/latest/API/API_Operations.html
+ </para></listitem>
+ <listitem><para>
+ http://buildacloud.org/blog/235-puppet-and-cloudstack.html
+ </para></listitem>
+ <listitem><para>
+http://chriskleban-internet.blogspot.com/2012/03/build-cloud-cloudstack-instance.html
+ </para></listitem>
+ <listitem><para>
+ http://gehrcke.de/2009/06/aws-about-api/
+ </para></listitem>
+ <listitem><para>
+ Apache_CloudStack-4.0.0-incubating-API_Developers_Guide-en-US.pdf
+ </para></listitem>
+
+ </orderedlist>
+ </section>
+
+</chapter>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/gsoc-shiva.xml
----------------------------------------------------------------------
diff --git a/en-US/gsoc-shiva.xml b/en-US/gsoc-shiva.xml
new file mode 100644
index 0000000..400af3c
--- /dev/null
+++ b/en-US/gsoc-shiva.xml
@@ -0,0 +1,70 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "CloudStack_GSoC_Guide.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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 id="gsoc-shiva">
+ <title>Shiva Teja's 2013 GSoC Proposal</title>
+ <para>This chapter describes Shiva Teja's 2013 Google Summer of Code project within the &PRODUCT; ASF project. It is a copy paste of the submitted proposal.</para>
+ <section id="gsoc-abstract-shiva">
+ <title>Abstract</title>
+ <para>
+ The aim of this project is to create a new modular UI for Apache CloudStack using Bootstrap by Twitter and Backbone.js. To achieve this easily, I'll be creating a RESTful wrapper API on top of the current CloudStack API. I hope this project will make custom UIs for CloudStack very easy.</para>
+
+ <para>Why does CloudStack need a new UI?</para>
+
+ <para>The current UI cannot be reused easliy to make a custom UI. The UI I will be making using backbone.js can be reused very easily to make custom UIs. The models, views, routers etc can remain the same in all the UIs. The user interface can be changed just by changing the templates. Check the implementation details below for further details.</para>
+
+ <para>Why does it need a RESTful wrapper API ?</para>
+
+ <para>Backbone.js heavily depends on RESTful architecture. Making a new UI with backbone.js using a query based API might not be easy.</para>
+ </section>
+ <section id="gsoc-deliverables-shiva">
+ <title>List of deliverables</title>
+ <orderedlist>
+ <listitem><para>A new UI for CloudStack(with almost all features in the current UI and new ones, if any).</para></listitem>
+ <listitem><para>A RESTful wrapper API on top of the CloudStack API</para></listitem>
+ <listitem><para>Some documentation about using this UI to make a custom UI.</para></listitem>
+ </orderedlist>
+ </section>
+ <section id="gsoc-approach-shiva">
+ <title>Approach</title>
+ <para>Wrapper API: Backbone.js, by default, uses four HTTP methods(GET, PUT, POST, DELETE) for communicating with the server. It uses GET to fetch a resource from the server, POST to create a resource, PUT to update the resource and DELETE to delete the resource. A query based API can probably be used to make the UI by overriding backbone's<ulink url="http://backbonejs.org/#Sync"><citetitle> default sync function</citetitle></ulink>. But it makes more sense to have an API which supports the above mentioned method and is resource based. This RESTful API works on top of the CloudStack API. The main task is to map the combinations of these HTTP methods and the resources to appropriate CloudStack API command. The other task is to decide on how the URLs should look like. Say for starting a virtual machine, for it to be RESTful, we have to use POST as we are creating a resource, or a PUT as we are changing the state of a virtual machine. So the possible options on the URL could be to do
a POST /runningvirtualmachines and respond with 201 Created code or a PUT on /virtualmachines/id and respond with 200 OK. If these are decided, the wrapper can be generated or be written manually, which can use defined patters to map to appropriate CloudStack API commands(Similar to what cloudmonkey does. See this <ulink url="https://github.com/shivateja/cloudstack-restful-api"><citetitle>prototype</citetitle></ulink>. I can use cloudmonkey's code to generate the required API entity verb relationships. Each verb will have a set of rules saying what method should be used in the RESTful API and how should it look like in the URL. Another possible way could be to group entities first manually and write the wrapper manually(something like zone/pods/cluster). Some possibilities have been discussed in <ulink url="http://mail-archives.apache.org/mod_mbox/cloudstack-dev/201304.mbox/%3CCAJrLSbaqa08uHw_xETt7Q59Nex%3DThQzvqEJyoXK8Q-OwN04Suw%40mail.gmail.com%3E"><citetitle>this thread</citetit
le></ulink>.</para>
+
+ <para>UI: It will be a single page app. It'll use <ulink url="http://underscorejs.org/#template">client side templating</ulink> for rendering. This makes it very easy to make a custom UI because it can be achieved just by changing the templates. Backbone views will make use of these templates to render the appropriate models/collections. A completely new interface can be written just by changing the templates. Javascript code can completely remain the same. The views will take care of appropriate DOM events. Such event will correspond to appropriate model/collection chages, thus causing appropriate API calls.</para>
+ </section>
+ <section id="gsoc-schedule-shiva">
+ <title>Approximate Schedle</title>
+ <para>Till June 17 - Decide on how the RESTful API should look like and design algorithms to generate the wrapper.</para>
+ <para>July 5(soft deadline), July 10(hard deadline) : Wrapper API will be ready.</para>
+ <para>July 12(soft) - July 15(hard): Make basic wireframes and designs for the website and get them approved.</para>
+ <para>July 29(mid term evaluation) : All the basic models, views, routes of the UI should be ready along with a few templates.</para>
+ <para>August 15(hard deadline, shouldn't take much time actually) - A basic usable UI where users can just list all the entities which are present in the current UI's main navigation( Like Instances, Templates, Accounts etc)</para>
+ <para>September 1(hard) - From this UI, users should be able to launch instances, edit settings of most of the entities.</para>
+ <para>September 16(Pencil down!) - Fix some design tweaks and finish a completely usable interface with functions similar to current UI.</para>
+ <para>September 23 - Finish the documentation on how to use this UI to make custom UIs.</para>
+ </section>
+ <section id="gsoc-aboutme-shiva">
+ <title>About Me</title>
+ <para> I am a 2nd year computer science undergrad studying at IIT Mandi, India. I've been using Python for an year and a half now. I've used Django, Flask and Tornado for my small projects. Along with Python, I use C++ for competitive programming. Recently, I fell in love with Haskell. I've always been fascinated about web technologies.</para>
+ </section>
+</chapter>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/gsoc-tuna.xml
----------------------------------------------------------------------
diff --git a/en-US/gsoc-tuna.xml b/en-US/gsoc-tuna.xml
new file mode 100644
index 0000000..0988734
--- /dev/null
+++ b/en-US/gsoc-tuna.xml
@@ -0,0 +1,231 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "CloudStack_GSoC_Guide.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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 id="gsoc-tuna">
+ <title>Nguyen's 2013 GSoC Proposal</title>
+ <para>This chapter describes Nguyen 2013 Google Summer of Code project within the &PRODUCT; ASF project. It is a copy paste of the submitted proposal.</para>
+ <section id="add-xen-xcp-support-for-gre-sdn-controller">
+ <title>Add Xen/XCP support for GRE SDN controller</title>
+ <para>
+ "This project aims to enhance the current native SDN controller in supporting Xen/XCP and integrate successfully the open source SDN controller (FloodLight) driving Open vSwitch through its interfaces."
+ </para>
+ </section>
+ <section id="Abstract">
+ <title>Abstract</title>
+ <para>
+ SDN, standing for Software-Defined Networking, is an approach to building data network equipments and softwares. It were invented by ONRC, Stanford University. SDN basically decouples the control from physical networking boxes and given to a software application called a controller. SDN has three parts: controller, protocols and switch; In which, OpenFlow is an open standard to deploy innovative protocols. Nowaday, more and more datacenters use SDN instead of traditional physical networking boxes. For example, Google announced that they completely built its own switches and SDN confrollers for use in its internal backbone network.
+ </para>
+ <para>
+ OpenvSwitch, an open source software switch, is widely used as a virtual switch in virtualized server environments. It can currently run on any Linux-based virtualization platform, such as: KVM, Xen (XenServer, XCP, Xen hypervisor), VirtualBox... It also has been ported to a number of different operating systems and hardware platforms: Linux, FreeBSD, Windows and even non-POSIX embedded systems. In cloud computing IaaS, using OpenvSwitch instead of Linux bridge on compute nodes becomes an inevitable trend because of its powerful features and the ability of OpenFlow integration as well.
+ </para>
+ <para>
+ In CloudStack, we already have a native SDN controller. With KVM hypervisor, developers can easily install OpenvSwitch module; whereas, Xen even has a build-in one. The combination of SDN controller and OpenvSwitch gives us many advanced things. For example, creating GRE tunnels as an isolation method instead of VLAN is a good try. In this project, we are planning to support GRE tunnels in Xen/XCP hypervisor with the native SDN controller. When it's done, substituting open-sources SDN controllers (floodlight, beacon, pox, nox) for the current one is an amazing next step.
+ </para>
+ </section>
+ <section id="design-desription">
+ <title>Design description</title>
+ <para>
+ CloudStack currently has a native SDN Controller that is used to build meshes of GRE tunnels between Xen hosts. There consists of 4 parts: OVS tunnel manager, OVS Dao/VO, Command/Answer and Ovs tunnel plugin. The details are as follow:
+ </para>
+ <para>
+ <emphasis role="bold">OVS tunnel manager:</emphasis> Consist of OvsElement and OvsTunnelManager.
+ </para>
+ <para>
+ OvsElement is used for controlling Ovs tunnel lifecycle (prepare, release)
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>prepare(network, nic, vm, dest): create tunnel for vm on network to dest</para>
+ </listitem>
+ <listitem>
+ <para>release(network, nic, vm): destroy tunnel for vm on network</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ OvsTunnelManager drives bridge configuration and tunnel creation via calling respective commands to Agent.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>destroyTunnel(vm, network): call OvsDestroyTunnelCommand to destroy tunnel for vm on network</para>
+ </listitem>
+ <listitem>
+ <para>createTunnel(vm, network, dest): call OvsCreateTunnelCommand to create tunnel for vm on network to dest</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis role="bold">OVS tunnel plugin:</emphasis> These are ovstunnel and ovs-vif-flows.py script, writen as XAPI plugin. The OVS tunnel manager will call them via XML-RPC.
+ </para>
+ <para>
+ Ovstunnel plugin calls corresponding vsctl commands for setting up the OVS bridge, creating GRE tunnels or destroying them.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>setup_ovs_bridge()</para>
+ </listitem>
+ <listitem>
+ <para>destroy_ovs_bridge()</para>
+ </listitem>
+ <listitem>
+ <para>create_tunnel()</para>
+ </listitem>
+ <listitem>
+ <para>destroy_tunnel()</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Ovs-vif-flow.py clears or applies rule for VIFs every time it is plugged or unplugged from a OVS bridge.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>clear_flow()</para>
+ </listitem>
+ <listitem>
+ <para>apply_flow()</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis role="bold">OVS command/answer:</emphasis> It is designed under the format of requests and answers between Manager and Plugin. These commands will correspondence exactly the mentioned manipulations.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>OvsSetupBridgeCommand</para>
+ </listitem>
+ <listitem>
+ <para>OvsSetupBridgeAnswer</para>
+ </listitem>
+ <listitem>
+ <para>OvsDestroyBridgeCommand</para>
+ </listitem>
+ <listitem>
+ <para>OvsDestroyBridgeAnswer</para>
+ </listitem>
+ <listitem>
+ <para>OvsCreateTunnelCommand</para>
+ </listitem>
+ <listitem>
+ <para>OvsCreateTunnelAnswer</para>
+ </listitem>
+ <listitem>
+ <para>OvsDestroyTunnelCommand</para>
+ </listitem>
+ <listitem>
+ <para>OvsDestroyTunnelAnswer</para>
+ </listitem>
+ <listitem>
+ <para>OvsFetchInterfaceCommand</para>
+ </listitem>
+ <listitem>
+ <para>OvsFetchInterfaceAnswer</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis role="bold">OVS Dao/VO</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>OvsTunnelInterfaceDao</para>
+ </listitem>
+ <listitem>
+ <para>OvsTunnelInterfaceVO</para>
+ </listitem>
+ <listitem>
+ <para>OvsTunnelNetworkDao</para>
+ </listitem>
+ <listitem>
+ <para>OvsTunnelNetworkVO</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="integrate-floodLight-as-sdn-controller">
+ <title>Integrate FloodLight as SDN controller</title>
+ <para>
+ I think that we maybe deploy FloodLight Server as a new SystemVM. This VM acts like current SystemVMs. One Floodlight SystemVM per Zone, so it can manage for virtual switches under this zone.
+ </para>
+ </section>
+ <section id="Deliverables">
+ <title>Deliverables</title>
+ <para>
+ GRE has been used as isolation method in CloudStack when deploy with Xen/XCP hosts.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>User set sdn.ovs.controller parameter in Global Setting to true. He deploys Advance Networking and chooses GRE as isolation method</para>
+ </listitem>
+ <listitem>
+ <para>Make use of Floodlight instead of native SDN controller.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="About-me">
+ <title>About me</title>
+ <para>
+ My name is Nguyen Anh Tu, a young and enthusiastic researcher in Cloud Computing Center - Viettel Research and Development Institute, Vietnam. Since last year, we has built Cloud Platform based on CloudStack, starting with version 3.0.2. As the results, some advanced modules were successfully developed, consists of:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>Encrypt Data Volume for VMs.</para>
+ </listitem>
+ <listitem>
+ <para>Dynamic Allocate Memory for VMs by changing policy on Squeeze Daemon.</para>
+ </listitem>
+ <listitem>
+ <para>AutoScale without using NetScale.</para>
+ </listitem>
+ <listitem>
+ <para>Deploy a new SystemVM type for Intrustion Detection System.</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Given the working experience and recent researches, I have obtained remarkably the understanding of specific knowledges to carry on this project, details as follow:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>Java source code on CloudStack: Design Pattern, Spring framework.</para>
+ </listitem>
+ <listitem>
+ <para>Bash, Python programming.</para>
+ </listitem>
+ <listitem>
+ <para>XAPI plugin.</para>
+ </listitem>
+ <listitem>
+ <para>XML-RPC.</para>
+ </listitem>
+ <listitem>
+ <para>OpenVSwitch on Xen.</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Other knowledges:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>XAPI RRD, XenStore.</para>
+ </listitem>
+ <listitem>
+ <para>Ocaml Programming (XAPI functions).</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+</chapter>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/guest-ip-ranges.xml
----------------------------------------------------------------------
diff --git a/en-US/guest-ip-ranges.xml b/en-US/guest-ip-ranges.xml
new file mode 100644
index 0000000..c49dc6a
--- /dev/null
+++ b/en-US/guest-ip-ranges.xml
@@ -0,0 +1,32 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+-->
+<section id="guest-ip-ranges">
+ <title>Guest IP Ranges</title>
+ <para>The IP ranges for guest network traffic are set on a per-account basis by the user. This
+ allows the users to configure their network in a fashion that will enable VPN linking between
+ their guest network and their clients.</para>
+ <para>In shared networks in Basic zone and Security Group-enabled Advanced networks, you will have
+ the flexibility to add multiple guest IP ranges from different subnets. You can add or remove
+ one IP range at a time. For more information, see <xref linkend="multiple-ip-range"/>.</para>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/guest-network.xml
----------------------------------------------------------------------
diff --git a/en-US/guest-network.xml b/en-US/guest-network.xml
new file mode 100644
index 0000000..692eb29
--- /dev/null
+++ b/en-US/guest-network.xml
@@ -0,0 +1,29 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+-->
+
+<section id="guest-network">
+ <title>Guest Network</title>
+ <para>In a &PRODUCT; cloud, guest VMs can communicate with each other using shared infrastructure with the security and user perception that the guests have a private LAN.</para>
+ <para>The &PRODUCT; virtual router is the main component providing networking features for guest traffic.</para>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/guest-nw-usage-with-traffic-sentinel.xml
----------------------------------------------------------------------
diff --git a/en-US/guest-nw-usage-with-traffic-sentinel.xml b/en-US/guest-nw-usage-with-traffic-sentinel.xml
new file mode 100644
index 0000000..d6fc10b
--- /dev/null
+++ b/en-US/guest-nw-usage-with-traffic-sentinel.xml
@@ -0,0 +1,72 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+-->
+<section id="guest-nw-usage-with-traffic-sentinel">
+ <title>Guest Network Usage Integration for Traffic Sentinel</title>
+ <para>To collect usage data for a guest network, &PRODUCT; needs to pull the data from an external
+ network statistics collector installed on the network. Metering statistics for guest networks
+ are available through &PRODUCT;’s integration with inMon Traffic Sentinel.</para>
+ <para>Traffic Sentinel is a network traffic usage data collection package. &PRODUCT; can feed
+ statistics from Traffic Sentinel into its own usage records, providing a basis for billing users
+ of cloud infrastructure. Traffic Sentinel uses the traffic monitoring protocol sFlow. Routers
+ and switches generate sFlow records and provide them for collection by Traffic Sentinel, then
+ &PRODUCT; queries the Traffic Sentinel database to obtain this information</para>
+ <para>To construct the query, &PRODUCT; determines what guest IPs were in use during the current
+ query interval. This includes both newly assigned IPs and IPs that were assigned in a previous
+ time period and continued to be in use. &PRODUCT; queries Traffic Sentinel for network
+ statistics that apply to these IPs during the time period they remained allocated in &PRODUCT;.
+ The returned data is correlated with the customer account that owned each IP and the timestamps
+ when IPs were assigned and released in order to create billable metering records in &PRODUCT;.
+ When the Usage Server runs, it collects this data.</para>
+ <para>To set up the integration between &PRODUCT; and Traffic Sentinel:</para>
+ <orderedlist>
+ <listitem>
+ <para>On your network infrastructure, install Traffic Sentinel and configure it to gather
+ traffic data. For installation and configuration steps, see inMon documentation at <ulink
+ url="http://inmon.com.">Traffic Sentinel Documentation</ulink>.</para>
+ </listitem>
+ <listitem>
+ <para>In the Traffic Sentinel UI, configure Traffic Sentinel to accept script querying from
+ guest users. &PRODUCT; will be the guest user performing the remote queries to gather
+ network usage for one or more IP addresses.</para>
+ <para>Click File > Users > Access Control > Reports Query, then select Guest from the
+ drop-down list.</para>
+ </listitem>
+ <listitem>
+ <para>On &PRODUCT;, add the Traffic Sentinel host by calling the &PRODUCT; API command
+ addTrafficMonitor. Pass in the URL of the Traffic Sentinel as protocol + host + port
+ (optional); for example, http://10.147.28.100:8080. For the addTrafficMonitor command
+ syntax, see the API Reference at <ulink
+ url="http://cloudstack.apache.org/docs/api/index.html">API
+ Documentation</ulink>.</para>
+ <para>For information about how to call the &PRODUCT; API, see the Developer’s Guide at
+ <ulink url="http://cloudstack.apache.org/docs/en-US/index.html">
+ &PRODUCT; API Developer's Guide</ulink>.</para>
+ </listitem>
+ <listitem>
+ <para>Log in to the &PRODUCT; UI as administrator.</para>
+ </listitem>
+ <listitem>
+ <para>Select Configuration from the Global Settings page, and set the following:</para>
+ <para>direct.network.stats.interval: How often you want &PRODUCT; to query Traffic
+ Sentinel.</para>
+ </listitem>
+ </orderedlist>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/guest-traffic.xml
----------------------------------------------------------------------
diff --git a/en-US/guest-traffic.xml b/en-US/guest-traffic.xml
new file mode 100644
index 0000000..943073e
--- /dev/null
+++ b/en-US/guest-traffic.xml
@@ -0,0 +1,43 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+-->
+<section id="guest-traffic">
+ <title>Guest Traffic</title>
+ <para>A network can carry guest traffic only between VMs within one zone. Virtual machines in different zones cannot communicate with each other using their IP addresses; they must communicate with each other by routing through a public IP address.</para>
+ <para>See a typical guest traffic setup given below:</para>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="./images/guest-traffic-setup.png" />
+ </imageobject>
+ <textobject><phrase>guest-traffic-setup.png: Depicts a guest traffic setup</phrase></textobject>
+ </mediaobject>
+ <para>Typically, the Management Server automatically creates a virtual router for each network. A
+ virtual router is a special virtual machine that runs on the hosts. Each virtual router in an
+ isolated network has three network interfaces. If multiple public VLAN is used, the router will
+ have multiple public interfaces. Its eth0 interface serves as the gateway for the guest traffic
+ and has the IP address of 10.1.1.1. Its eth1 interface is used by the system to configure the
+ virtual router. Its eth2 interface is assigned a public IP address for public traffic. If
+ multiple public VLAN is used, the router will have multiple public interfaces.</para>
+ <para>The virtual router provides DHCP and will automatically assign an IP address for each guest VM within the IP range assigned for the network. The user can manually reconfigure guest VMs to assume different IP addresses.</para>
+ <para>Source NAT is automatically configured in the virtual router to forward outbound traffic for all guest VMs</para>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/ha-enabled-vm.xml
----------------------------------------------------------------------
diff --git a/en-US/ha-enabled-vm.xml b/en-US/ha-enabled-vm.xml
new file mode 100644
index 0000000..19666a4
--- /dev/null
+++ b/en-US/ha-enabled-vm.xml
@@ -0,0 +1,29 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+-->
+
+<section id="ha-enabled-vm">
+ <title>HA-Enabled Virtual Machines</title>
+ <para>The user can specify a virtual machine as HA-enabled. By default, all virtual router VMs and Elastic Load Balancing VMs are automatically configured as HA-enabled. When an HA-enabled VM crashes, &PRODUCT; detects the crash and restarts the VM automatically within the same Availability Zone. HA is never performed across different Availability Zones. &PRODUCT; has a conservative policy towards restarting VMs and ensures that there will never be two instances of the same VM running at the same time. The Management Server attempts to start the VM on another Host in the same cluster.</para>
+ <para>HA features work with iSCSI or NFS primary storage. HA with local storage is not supported.</para>
+ </section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/ha-for-hosts.xml
----------------------------------------------------------------------
diff --git a/en-US/ha-for-hosts.xml b/en-US/ha-for-hosts.xml
new file mode 100644
index 0000000..15b5fa7
--- /dev/null
+++ b/en-US/ha-for-hosts.xml
@@ -0,0 +1,30 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+-->
+
+<section id="ha-for-hosts">
+ <title>HA for Hosts</title>
+ <para>The user can specify a virtual machine as HA-enabled. By default, all virtual router VMs and Elastic Load Balancing VMs are automatically configured as HA-enabled. When an HA-enabled VM crashes, &PRODUCT; detects the crash and restarts the VM automatically within the same Availability Zone. HA is never performed across different Availability Zones. &PRODUCT; has a conservative policy towards restarting VMs and ensures that there will never be two instances of the same VM running at the same time. The Management Server attempts to start the VM on another Host in the same cluster.</para>
+ <para>HA features work with iSCSI or NFS primary storage. HA with local storage is not supported.</para>
+ <xi:include href="dedicated-ha-hosts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/ha-management-server.xml
----------------------------------------------------------------------
diff --git a/en-US/ha-management-server.xml b/en-US/ha-management-server.xml
new file mode 100644
index 0000000..1afebce
--- /dev/null
+++ b/en-US/ha-management-server.xml
@@ -0,0 +1,30 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+-->
+
+<section id="ha-management-server">
+ <title>HA for Management Server</title>
+ <para>The &PRODUCT; Management Server should be deployed in a multi-node configuration such that it is not susceptible to individual server failures. The Management Server itself (as distinct from the MySQL database) is stateless and may be placed behind a load balancer.</para>
+ <para>Normal operation of Hosts is not impacted by an outage of all Management Serves. All guest VMs will continue to work.</para>
+ <para>When the Management Server is down, no new VMs can be created, and the end user and admin UI, API, dynamic load distribution, and HA will cease to work.</para>
+ </section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/hardware-config-eg.xml
----------------------------------------------------------------------
diff --git a/en-US/hardware-config-eg.xml b/en-US/hardware-config-eg.xml
new file mode 100644
index 0000000..3174bfa
--- /dev/null
+++ b/en-US/hardware-config-eg.xml
@@ -0,0 +1,29 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+-->
+<section id="hardware-config-eg">
+ <title>Example Hardware Configuration</title>
+ <para>This section contains an example configuration of specific switch models for zone-level
+ layer-3 switching. It assumes VLAN management protocols, such as VTP or GVRP, have been
+ disabled. The example scripts must be changed appropriately if you choose to use VTP or
+ GVRP.</para>
+ <xi:include href="dell62xx-hardware.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="cisco3750-hardware.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/hardware-firewall.xml
----------------------------------------------------------------------
diff --git a/en-US/hardware-firewall.xml b/en-US/hardware-firewall.xml
new file mode 100644
index 0000000..efab3c7
--- /dev/null
+++ b/en-US/hardware-firewall.xml
@@ -0,0 +1,32 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+-->
+<section id="hardware-firewall">
+ <title>Hardware Firewall</title>
+ <para>All deployments should have a firewall protecting the management server; see Generic
+ Firewall Provisions. Optionally, some deployments may also have a Juniper SRX firewall that will
+ be the default gateway for the guest networks; see <xref
+ linkend="external-guest-firewall-integration"/>.</para>
+ <xi:include href="generic-firewall-provisions.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="external-guest-firewall-integration.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="vnmc-cisco.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ <xi:include href="external-guest-lb-integration.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
+</section>
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/health-checks-for-lb-rules.xml
----------------------------------------------------------------------
diff --git a/en-US/health-checks-for-lb-rules.xml b/en-US/health-checks-for-lb-rules.xml
new file mode 100644
index 0000000..be2aec0
--- /dev/null
+++ b/en-US/health-checks-for-lb-rules.xml
@@ -0,0 +1,51 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+-->
+<section id="health-checks-for-lb-rules">
+ <!-- CLOUDSTACK-443 -->
+ <title>Health Checks for Load Balancer Rules</title>
+ <para>(NetScaler load balancer only; requires NetScaler version 10.0)
+ </para>
+ <para>Health checks are used in load-balanced applications to ensure that requests are forwarded
+ only to running, available services.
+ When creating a load balancer rule, you can specify a health check policy.
+ This is in addition to specifying the
+ stickiness policy, algorithm, and other load balancer rule options.
+ You can configure one health check policy per load balancer rule.</para>
+ <para>Any load balancer rule defined on a NetScaler load balancer in &PRODUCT; can have a health check policy.
+ The policy consists of a ping path, thresholds to define "healthy" and "unhealthy" states,
+ health check frequency, and timeout wait interval.</para>
+ <para>When a health check policy is in effect,
+ the load balancer will stop forwarding requests to any resources that are found to be unhealthy.
+ If the resource later becomes available again, the periodic health check
+ will discover it, and the resource will once again be added to the pool of resources that can
+ receive requests from the load balancer.
+ At any given time, the most recent result of the health check is displayed in the UI.
+ For any VM that is attached to a load balancer rule with a health check configured,
+ the state will be shown as UP or DOWN in the UI depending on the result of the most recent health check.</para>
+ <para>You can delete or modify existing health check policies.</para>
+ <para>To configure how often the health check is performed by default, use the global
+ configuration setting healthcheck.update.interval (default value is 600 seconds).
+ You can override this value for an individual health check policy.</para>
+ <para>For details on how to set a health check policy using the UI, see <xref linkend="add-load-balancer-rule"/>.</para>
+</section>
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/b23872a5/en-US/host-add-vsphere.xml
----------------------------------------------------------------------
diff --git a/en-US/host-add-vsphere.xml b/en-US/host-add-vsphere.xml
new file mode 100644
index 0000000..b478464
--- /dev/null
+++ b/en-US/host-add-vsphere.xml
@@ -0,0 +1,28 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
+%BOOK_ENTITIES;
+]>
+
+<!-- Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you 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.
+-->
+
+<section id="host-add-vsphere">
+ <title>Adding a Host (vSphere)</title>
+ <para>For vSphere servers, we recommend creating the cluster of hosts in vCenter and then adding the entire cluster to &PRODUCT;. See Add Cluster: vSphere.</para>
+</section>