Add docs for MidoNet networking plugin [CLOUDSTACK-996]

Signed-off-by: Dave Cahill <dcahill@midokura.com>
This commit is contained in:
Dave Cahill 2013-04-19 17:31:44 +09:00 committed by Alena Prokharchyk
parent c745e6d28e
commit 67d0411d73
11 changed files with 480 additions and 0 deletions

View File

@ -0,0 +1,22 @@
<!-- 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.
-->
<!ENTITY PRODUCT "CloudStack">
<!ENTITY BOOKID "Technical Documentation">
<!ENTITY YEAR "2013">
<!ENTITY HOLDER "Apache Software Foundation">

View File

@ -0,0 +1,52 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE book 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;
<!ENTITY % xinclude SYSTEM "http://www.docbook.org/xml/4.4/xinclude.mod">
%xinclude;
]>
<!-- 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.
-->
<book>
<bookinfo id="midonet_plugin">
<title>&PRODUCT; Plugin Guide for the MidoNet Plugin</title>
<productname>Apache CloudStack</productname>
<productnumber>4.2.0</productnumber>
<edition>1</edition>
<pubsnumber></pubsnumber>
<abstract>
<para>
Plugin Guide for the MidoNet Plugin.
</para>
</abstract>
<corpauthor>
<inlinemediaobject>
<imageobject>
<imagedata fileref="Common_Content/images/title_logo.svg" format="SVG" />
</imageobject>
</inlinemediaobject>
</corpauthor>
<xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>
<xi:include href="plugin-midonet-about.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="plugin-midonet-usage.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include href="plugin-midonet-revisions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</book>

View File

@ -0,0 +1,27 @@
<?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;
<!ENTITY % xinclude SYSTEM "http://www.docbook.org/xml/4.4/xinclude.mod">
%xinclude;
]>
<!-- 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="About-the-MidoNet-Plugin" >
<title>The MidoNet Plugin</title>
<xi:include href="plugin-midonet-introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
<xi:include href="plugin-midonet-features.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
</chapter>

View File

@ -0,0 +1,57 @@
<?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;
<!ENTITY % xinclude SYSTEM "http://www.docbook.org/xml/4.4/xinclude.mod">
%xinclude;
]>
<!-- 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="Features-of-the-MidoNet-Plugin">
<title>Features of the MidoNet Plugin</title>
<note>
<para>
In &PRODUCT; 4.2.0 only the KVM hypervisor is supported for use in combination with MidoNet.
</para>
</note>
<para>In &PRODUCT; release 4.2.0 this plugin supports several services in the Advanced Isolated network mode.
</para>
<para>
When tenants create new isolated layer 3 networks, instead of spinning up extra Virtual Router VMs, the relevant L3 elements (routers etc) are created in the MidoNet virtual topology by making the appropriate calls to the MidoNet API. Instead of using VLANs, isolation is provided by MidoNet.
</para>
<para>
Aside from the above service (Connectivity), several extra features are supported in the 4.2.0 release:
</para>
<itemizedlist>
<listitem><para>DHCP</para></listitem>
<listitem><para>Firewall (ingress)</para></listitem>
<listitem><para>Source NAT</para></listitem>
<listitem><para>Static NAT</para></listitem>
<listitem><para>Port Forwarding</para></listitem>
</itemizedlist>
<para>
The plugin has been tested with MidoNet version 12.12. (Caddo).
</para>
</section>

View File

@ -0,0 +1,26 @@
<?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;
<!ENTITY % xinclude SYSTEM "http://www.docbook.org/xml/4.4/xinclude.mod">
%xinclude;
]>
<!-- 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="Introduction-to-the-MidoNet-Plugin">
<title>Introduction to the MidoNet Plugin</title>
<para>The MidoNet plugin allows &PRODUCT; to use the MidoNet virtualized networking solution as a provider for &PRODUCT; networks and services. For more information on MidoNet and how it works, see <ulink url="http://www.midokura.com/midonet/">http://www.midokura.com/midonet/</ulink>.</para>
</section>

View File

@ -0,0 +1,90 @@
<?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;
<!ENTITY % xinclude SYSTEM "http://www.docbook.org/xml/4.4/xinclude.mod">
%xinclude;
]>
<!-- 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="Prerequisites">
<title>Prerequisites</title>
<para>In order to use the MidoNet plugin, the compute hosts must be running the MidoNet Agent, and the MidoNet API server must be available. Please consult the MidoNet User Guide for more information. The following section describes the &PRODUCT; side setup.</para>
<orderedlist>
<listitem>
<para>&PRODUCT; needs to have at least one physical network with the isolation method set to "MIDO". This network should be enabled for the Guest and Public traffic types.</para>
</listitem>
<listitem>
<para>Next, we need to set the following &PRODUCT; settings under "Global Settings" in the UI:</para>
<table frame='all'><title>&PRODUCT; settings</title>
<tgroup cols='3' align='left' colsep='1' rowsep='1'>
<thead>
<row>
<entry>Setting Name</entry>
<entry>Description</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>midonet.apiserver.address</entry>
<entry>Specify the address at which the Midonet API server can be contacted</entry>
<entry>http://192.168.1.144:8081/midolmanj-mgmt</entry>
</row>
<row>
<entry>midonet.providerrouter.id</entry>
<entry>Specifies the UUID of the Midonet provider router</entry>
<entry>d7c5e6a3-e2f4-426b-b728-b7ce6a0448e5</entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
<listitem>
<para>
We also want MidoNet to take care of public traffic, so in <emphasis>componentContext.xml</emphasis> we need to replace this line:
<programlisting><![CDATA[<bean id="PublicNetworkGuru" class="com.cloud.network.guru.PublicNetworkGuru">]]>
</programlisting>
With this:
<programlisting><![CDATA[<bean id="PublicNetworkGuru" class="com.cloud.network.guru.MidoNetPublicNetworkGuru">]]>
</programlisting>
</para>
</listitem>
</orderedlist>
<note>
<para>
On the compute host, MidoNet takes advantage of per-traffic type VIF driver support in &PRODUCT; KVM.
</para>
<para>
In agent.properties, we set the following to make MidoNet take care of Guest and Public traffic:
<programlisting>libvirt.vif.driver.Guest=com.cloud.network.resource.MidoNetVifDriver
libvirt.vif.driver.Public=com.cloud.network.resource.MidoNetVifDriver</programlisting>
This is explained further in MidoNet User Guide.
</para>
</note>
</section>

View File

@ -0,0 +1,39 @@
<?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;
<!ENTITY % xinclude SYSTEM "http://www.docbook.org/xml/4.4/xinclude.mod">
%xinclude;
]>
<!-- 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="Enabling-the-service-provider">
<title>Enabling the MidoNet service provider via the API</title>
<para>
To enable via the API, use the following API calls:</para>
<para><emphasis>addNetworkServiceProvider</emphasis></para>
<itemizedlist>
<listitem><para>name = "MidoNet"</para></listitem>
<listitem><para>physicalnetworkid = &lt;the uuid of the physical network&gt;</para></listitem>
</itemizedlist>
<para><emphasis>updateNetworkServiceProvider</emphasis></para>
<itemizedlist>
<listitem><para>id = &lt;the provider uuid returned by the previous call&gt;</para></listitem>
<listitem><para>state = "Enabled"</para></listitem>
</itemizedlist>
</section>

View File

@ -0,0 +1,45 @@
<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE appendix 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.
-->
<appendix id="appe-cloudstack-Revision_History">
<title>Revision History</title>
<simpara>
<revhistory>
<revision>
<revnumber>0-0</revnumber>
<date>Wed Mar 13 2013</date>
<author>
<firstname>Dave</firstname>
<surname>Cahill</surname>
<email>dcahill@midokura.com</email>
</author>
<revdescription>
<simplelist>
<member>Documentation created for 4.2.0 version of the MidoNet Plugin</member>
</simplelist>
</revdescription>
</revision>
</revhistory>
</simpara>
</appendix>

View File

@ -0,0 +1,65 @@
<?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;
<!ENTITY % xinclude SYSTEM "http://www.docbook.org/xml/4.4/xinclude.mod">
%xinclude;
]>
<!-- 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="plugin-midonet-ui">
<title>Enabling the MidoNet service provider via the UI</title>
<para>To allow &PRODUCT; to use the MidoNet Plugin the network service provider needs to be enabled on the physical network.
</para>
<para>
The steps to enable via the UI are as follows:
<orderedlist>
<listitem><para>
In the left navbar, click Infrastructure
</para></listitem>
<listitem><para>
In Zones, click View All
</para></listitem>
<listitem><para>
Click the name of the Zone on which you are setting up MidoNet
</para></listitem>
<listitem><para>
Click the Physical Network tab
</para></listitem>
<listitem><para>
Click the Name of the Network on which you are setting up MidoNet
</para></listitem>
<listitem><para>
Click Configure on the Network Service Providers box
</para></listitem>
<listitem><para>
Click on the name MidoNet
</para></listitem>
<listitem><para>
Click the Enable Provider button in the Network tab
</para></listitem>
</orderedlist>
</para>
</section>

View File

@ -0,0 +1,29 @@
<?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;
<!ENTITY % xinclude SYSTEM "http://www.docbook.org/xml/4.4/xinclude.mod">
%xinclude;
]>
<!-- 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="Using-the-MidoNet-Plugin" >
<title>Using the MidoNet Plugin</title>
<xi:include href="plugin-midonet-preparations.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
<xi:include href="plugin-midonet-ui.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
<xi:include href="plugin-midonet-provider.xml" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
</chapter>

View File

@ -0,0 +1,28 @@
# Publican configuration file for CloudStack Complete Documentation Set
# Contains all technical docs except release notes
# Config::Simple 4.58
# Tue May 29 00:57:27 2012
#
# 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.
xml_lang: en-US
type: Book
docname: MidoNet_Plugin_Guide
brand: cloudstack
chunk_first: 1
chunk_section_depth: 1
condition: install