x
/
fuel-plugin-midonet
Code Issues Proposed changes

Sanitize documentation 

* Change version to 3.0.1
* Fix spelling, obsolete and inconsistent info
* Fix formatting
* Add TOC for PDF rendering

Change-Id: Ibfae141f9c9ca349faf166c8575b590c7d4b3733
This commit is contained in:
Samir Ibradžić 2016-03-07 23:31:39 +09:00
parent 33998879c4
commit 1ef42e665d
8 changed files with 426 additions and 322 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
README.rst
View File

@ -9,12 +9,27 @@ Compatible versions:
How to build the plugin:
- Install fuel plugin builder (fpb)
- Install Fuel plugin builder (fpb)
::
# pip install fuel-plugin-builder
- Clone the plugin repo and run fpb there:
git clone https://github.com/openstack/fuel-plugin-midonet
cd fuel-plugin-midonet/
fpb --build .
- Check if file midonet-fuel-plugin-3.0-3.0.0-1.noarch.rpm was created.
::
$ git clone https://github.com/openstack/fuel-plugin-midonet
$ cd fuel-plugin-midonet
$ fpb --build .
- Check if file midonet-fuel-plugin-3.0-3.0.1-1.noarch.rpm was created.
::
$ fuel plugins
id | name | version | package_version
---|---------------------|---------|----------------
1 | midonet-fuel-plugin | 3.0.1 | 3.0.0
Please refer to `Plugin Guide <./doc/user-guide.rst>`_ for documentation

10
doc/content/appendix.rst
View File

@ -1,5 +1,11 @@
Appendix
========
.. raw:: pdf
PageBreak oneColumn
Appendix B - references
=======================
- `MidoNet Web Site <http://midonet.org/>`_
- `MidoNet v2015.06 Documentation <http://docs.midonet.org/>`_

332
doc/content/bgp-peer.rst
View File

@ -1,31 +1,39 @@
Setting up test BGP peer
========================
`BGP <https://en.wikipedia.org/wiki/Border_Gateway_Protocol>`_ is routing is an
exterior gateway protocol supported and recommended to MidoNet
production use case. An external BGP peer is necessary for Floating IP (FIP) traffic
between the deployed OpenStack cloud instances and the external network(s).
These BGP peers are usually available for production or data-center ISP environments,
so for the sake of supporting BGP tests under lab or proof-of-concept conditions we
are providing instructions on how to set up a "fake" BGP peer that provide fully
functional external connectivity. This guide shows how it can be done by setting up
VyOS network operating system instance to serve up as an external BGP peer.
`BGP`_ is routing is an exterior gateway protocol supported and recommended to
MidoNet production use case. An external BGP peer is necessary for Floating IP
(FIP) traffic between the deployed OpenStack cloud instances and the external
network(s). These BGP peers are usually available for production or data-center
ISP environments, so for the sake of supporting BGP tests under lab or
proof-of-concept conditions we are providing instructions on how to set up a
"fake" BGP peer that provide fully functional external connectivity. This guide
shows how it can be done by setting up VyOS network operating system instance
to serve up as an external BGP peer.
`VyOS`_ is a community fork of `Vyatta`_, a Linux-based network operating
system that provides software-based network routing, firewall, and VPN
functionality.
.. _BGP: https://en.wikipedia.org/wiki/Border_Gateway_Protocol
.. _VyOS: http://vyos.net
.. _Vyatta: https://en.wikipedia.org/wiki/Vyatta
`VyOS <http://vyos.net>`_ is a community fork of
`Vyatta <https://en.wikipedia.org/wiki/Vyatta>`_, a Linux-based network operating
system that provides software-based network routing, firewall, and VPN functionality.
Introduction
------------
VyOS works just fine as a live OS when booted from
`VyOS ISO <http://mirror.vyos.net/iso/release/1.1.7/vyos-1.1.7-amd64.iso>`_
and configured properly, but we will cover some basic steps on how to install it
to an actual server or a virtual machine. Being a network operating system and a
router appliance, it makes sense to install it on a host that has multiple network
interfaces. Minimum hardware requirements for VyOS are single core CPU and 512MB of
RAM. It can run just fine without any permanent storage, which is only necessary to
save the configuration state.
VyOS works just fine as a live OS when booted from `VyOS ISO`_ and configured
properly, but we will cover some basic steps on how to install it to an actual
server or a virtual machine. Being a network operating system and a router
appliance, it makes sense to install it on a host that has multiple network
interfaces. Minimum hardware requirements for VyOS are single core CPU and
512MB of RAM. It can run just fine without any permanent storage, which is
only necessary to save the configuration state.
.. _VyOS ISO: <http://mirror.vyos.net/iso/release/1.1.7/vyos-1.1.7-amd64.iso
Required addressing information
-------------------------------
@ -41,9 +49,10 @@ in this guide:
Also, BGP protocol itself needs some parameters to be set up. For our simple
demonstration we assume that VyOS BGP peer that we are creating is going to
communicate with MidoNet gateway BGP peer. As a part of BGP specification, each
BGP peer has to have AS number which identifies it when connecting to other peers.
Also, BGP peers needs to find each other on specific IP addresses, belonging to a
same IP subnet. For our example, we assume following AS numbers and IP addresses:
BGP peer has to have AS number which identifies it when connecting to other
peers. Also, BGP peers needs to find each other on specific IP addresses,
belonging to a same IP subnet. For our example, we assume following AS numbers
and IP addresses:
- BGP IP subnet: **10.88.88.0/30**
- VyOS BGP peer IP address: **10.88.88.1**
@ -53,95 +62,98 @@ same IP subnet. For our example, we assume following AS numbers and IP addresses
|
Finally, to fulfill the purpose of this BGP setup, we need to know which Floating IP
subnet is going to be handled by MidoNet-based OpenStack cloud, so we specify subnet:
Finally, to fulfill the purpose of this BGP setup, we need to know which
Floating IP subnet is going to be handled by MidoNet-based OpenStack cloud,
so we specify subnet:
- Floating IP subnet: **200.200.200.0/24**
|
VyOS Installation
-----------------
We start installing by booting our server or VM from
`VyOS CD <http://mirror.vyos.net/iso/release/1.1.7/vyos-1.1.7-amd64.iso>`_
and logging in with username and password, both **vyos** by default. Following
that, we run this command to install VyOS to a hard drive:
We start installing by booting our server or VM from `VyOS ISO`_ and logging
in with username and password, both **vyos** by default. Following that,
we run this command to install VyOS to a hard drive:
::
vyos@vyos:~$ install image
vyos@vyos:~$ install image
After that the following installation prompts will be displayed:
::
Welcome to the VyOS install program. This script
will walk you through the process of installing the
VyOS image to a local hard drive.
Would you like to continue? (Yes/No) [Yes]: Yes
Probing drives: OK
Looking for pre-existing RAID groups...none found.
The VyOS image will require a minimum 1000MB root.
Would you like me to try to partition a drive automatically
or would you rather partition it manually with parted? If
you have already setup your partitions, you may skip this step
Welcome to the VyOS install program. This script
will walk you through the process of installing the
VyOS image to a local hard drive.
Would you like to continue? (Yes/No) [Yes]: Yes
Probing drives: OK
Looking for pre-existing RAID groups...none found.
The VyOS image will require a minimum 1000MB root.
Would you like me to try to partition a drive automatically
or would you rather partition it manually with parted? If
you have already setup your partitions, you may skip this step
Partition (Auto/Parted/Skip) [Auto]:
Partition (Auto/Parted/Skip) [Auto]:
I found the following drives on your system:
vda 4294MB
I found the following drives on your system:
vda 4294MB
Install the image on? [vda]:
Install the image on? [vda]:
This will destroy all data on /dev/vda.
Continue? (Yes/No) [No]:
This will destroy all data on /dev/vda.
Continue? (Yes/No) [No]:
Confirm the that you really want to install VyOS to the target disk drive by
typing **Yes**. The rest of the installation can be completed by simply pressing
Enter on each prompt, and typing the desired administrator password when asked:
typing **Yes**. The rest of the installation can be completed by simply
pressing Enter on each prompt, and typing the desired administrator password when
asked:
::
How big of a root partition should I create? (1000MB - 4294MB) [4294]MB:
How big of a root partition should I create? (1000MB - 4294MB) [4294]MB:
Creating filesystem on /dev/vda1: OK
Done!
Mounting /dev/vda1...
What would you like to name this image? [1.1.7]:
OK. This image will be named: 1.1.7
Copying squashfs image...
Copying kernel and initrd images...
Done!
I found the following configuration files:
/config/config.boot
/opt/vyatta/etc/config.boot.default
Which one should I copy to vda? [/config/config.boot]:
Creating filesystem on /dev/vda1: OK
Done!
Mounting /dev/vda1...
What would you like to name this image? [1.1.7]:
OK. This image will be named: 1.1.7
Copying squashfs image...
Copying kernel and initrd images...
Done!
I found the following configuration files:
/config/config.boot
/opt/vyatta/etc/config.boot.default
Which one should I copy to vda? [/config/config.boot]:
Copying /config/config.boot to vda.
Enter password for administrator account
Enter password for user 'vyos':
Retype password for user 'vyos':
I need to install the GRUB boot loader.
I found the following drives on your system:
vda 4294MB
Copying /config/config.boot to vda.
Enter password for administrator account
Enter password for user 'vyos':
Retype password for user 'vyos':
I need to install the GRUB boot loader.
I found the following drives on your system:
vda 4294MB
Which drive should GRUB modify the boot partition on? [vda]:
Which drive should GRUB modify the boot partition on? [vda]:
Setting up grub: OK
Done!
vyos@vyos:~$
Setting up grub: OK
Done!
vyos@vyos:~$
This means that the installation has been successful, time to reboot
VyOS and do some configuration:
::
vyos@vyos:~$ reboot
Proceed with reboot? (Yes/No) [No] Yes
vyos@vyos:~$ reboot
Proceed with reboot? (Yes/No) [No] Yes
Broadcast message from root@vyos (ttyS0) (Wed Mar 2 12:28:15 2016):
Broadcast message from root@vyos (ttyS0) (Mon Feb 29 12:28:15 2016):
The system is going down for reboot NOW!
The system is going down for reboot NOW!
Essential VyOS Configuration
@ -152,49 +164,49 @@ access. Do this by accessing **configuration** mode:
::
vyos@vyos:~$ configure
[edit]
vyos@vyos:~$ configure
[edit]
Set up management IP address, default gateway, ssh access and a DNS name:
::
vyos@vyos# set interfaces ethernet eth0 address 10.20.0.254/24
[edit]
vyos@vyos# set interfaces ethernet eth0 description MGMT
[edit]
vyos@vyos# set protocols static route 0.0.0.0/0 next-hop 10.20.0.1
[edit]
vyos@vyos# set service ssh port 22
[edit]
vyos@vyos# set service dns forwarding listen-on eth0
[edit]
vyos@vyos# set service dns forwarding name-server 8.8.8.8
[edit]
vyos@vyos# set interfaces ethernet eth0 address 10.20.0.254/24
[edit]
vyos@vyos# set interfaces ethernet eth0 description MGMT
[edit]
vyos@vyos# set protocols static route 0.0.0.0/0 next-hop 10.20.0.1
[edit]
vyos@vyos# set service ssh port 22
[edit]
vyos@vyos# set service dns forwarding listen-on eth0
[edit]
vyos@vyos# set service dns forwarding name-server 8.8.8.8
[edit]
To apply as well as save the configuration changes do:
::
vyos@vyos# commit
[ service ssh ]
Restarting OpenBSD Secure Shell server: sshd.
vyos@vyos# commit
[ service ssh ]
Restarting OpenBSD Secure Shell server: sshd.
[edit]
vyos@vyos# save
Saving configuration to '/config/config.boot'...
Done
[edit]
vyos@vyos# exit
exit
vyos@vyos:~$ exit
logout
[edit]
vyos@vyos# save
Saving configuration to '/config/config.boot'...
Done
[edit]
vyos@vyos# exit
exit
vyos@vyos:~$ exit
logout
Our VyOS instance should be accessible via ssh at 10.20.0.254 now:
::
$ ssh vyos@10.20.0.254
$ ssh vyos@10.20.0.254
VyOS BGP Configuration
@ -205,69 +217,69 @@ IP and AS addresses we mentioned above. Enter the configuration mode,
::
vyos@vyos:~$ configure
[edit]
vyos@vyos:~$ configure
[edit]
followed by a stream of commands:
::
set interfaces ethernet eth1 address 10.88.88.1/30
set policy prefix-list DEFAULT rule 100 action permit
set policy prefix-list DEFAULT rule 100 prefix 0.0.0.0/0
set policy prefix-list DEFAULT rule 999 action deny
set policy prefix-list DEFAULT rule 999 le 32
set policy prefix-list DEFAULT rule 999 prefix 0.0.0.0/0
set policy prefix-list fromAS12345 rule 100 action permit
set policy prefix-list fromAS12345 rule 100 le 32
set policy prefix-list fromAS12345 rule 100 prefix 200.200.200.0/24
set policy prefix-list fromAS12345 rule 999 action deny
set policy prefix-list fromAS12345 rule 999 le 32
set policy prefix-list fromAS12345 rule 999 prefix 0.0.0.0/0
commit
set interfaces ethernet eth1 address 10.88.88.1/30
set policy prefix-list DEFAULT rule 100 action permit
set policy prefix-list DEFAULT rule 100 prefix 0.0.0.0/0
set policy prefix-list DEFAULT rule 999 action deny
set policy prefix-list DEFAULT rule 999 le 32
set policy prefix-list DEFAULT rule 999 prefix 0.0.0.0/0
set policy prefix-list fromAS12345 rule 100 action permit
set policy prefix-list fromAS12345 rule 100 le 32
set policy prefix-list fromAS12345 rule 100 prefix 200.200.200.0/24
set policy prefix-list fromAS12345 rule 999 action deny
set policy prefix-list fromAS12345 rule 999 le 32
set policy prefix-list fromAS12345 rule 999 prefix 0.0.0.0/0
commit
set policy route-map fromAS12345 rule 100 match ip address prefix-list fromAS12345
set policy route-map fromAS12345 rule 100 action permit
set policy route-map fromAS12345 rule 999 action deny
commit
set policy route-map fromAS12345 rule 100 match ip address prefix-list fromAS12345
set policy route-map fromAS12345 rule 100 action permit
set policy route-map fromAS12345 rule 999 action deny
commit
set policy route-map toAS12345 rule 100 action permit
set policy route-map toAS12345 rule 100 match ip address prefix-list DEFAULT
set policy route-map toAS12345 rule 100 set metric 100
set policy route-map toAS12345 rule 999 action deny
commit
set policy route-map toAS12345 rule 100 action permit
set policy route-map toAS12345 rule 100 match ip address prefix-list DEFAULT
set policy route-map toAS12345 rule 100 set metric 100
set policy route-map toAS12345 rule 999 action deny
commit
set protocols bgp 65535 neighbor 10.88.88.2 default-originate route-map toAS12345
set protocols bgp 65535 neighbor 10.88.88.2 route-map export toAS12345
set protocols bgp 65535 neighbor 10.88.88.2 route-map import fromAS12345
set protocols bgp 65535 neighbor 10.88.88.2 soft-reconfiguration inbound
set protocols bgp 65535 neighbor 10.88.88.2 remote-as 12345
commit
set protocols bgp 65535 neighbor 10.88.88.2 default-originate route-map toAS12345
set protocols bgp 65535 neighbor 10.88.88.2 route-map export toAS12345
set protocols bgp 65535 neighbor 10.88.88.2 route-map import fromAS12345
set protocols bgp 65535 neighbor 10.88.88.2 soft-reconfiguration inbound
set protocols bgp 65535 neighbor 10.88.88.2 remote-as 12345
commit
Now, we can verify if our VyOS BGP peer is actually connected to the other BGP peer(s):
::
vyos@vyos# run show ip bgp summary
BGP router identifier 10.20.0.254, local AS number 65535
IPv4 Unicast - max multipaths: ebgp 1 ibgp 1
RIB entries 1, using 96 bytes of memory
Peers 1, using 4560 bytes of memory
vyos@vyos# run show ip bgp summary
BGP router identifier 10.20.0.254, local AS number 65535
IPv4 Unicast - max multipaths: ebgp 1 ibgp 1
RIB entries 1, using 96 bytes of memory
Peers 1, using 4560 bytes of memory
Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd
10.88.88.2 4 12345 7 8 0 0 0 00:04:22 1
Neighbor V AS MsgRcvd MsgSent TblVer InQ OutQ Up/Down State/PfxRcd
10.88.88.2 4 12345 7 8 0 0 0 00:04:22 1
Total number of neighbors 1
Total number of neighbors 1
If you see an output similar to the above, congratulations, you have set up your
VyOS BGP peer correctly! It is advised to save this configuration:
::
vyos@vyos# save
Saving configuration to '/config/config.boot'...
Done
[edit]
vyos@vyos# save
Saving configuration to '/config/config.boot'...
Done
[edit]
VyOS NAT Configuration
@ -285,31 +297,31 @@ public Internet:
::
set nat source rule 10 source address 200.200.200.0/24
set nat source rule 10 outbound-interface eth0
set nat source rule 10 protocol all
set nat source rule 10 translation address masquerade
commit
set nat source rule 10 source address 200.200.200.0/24
set nat source rule 10 outbound-interface eth0
set nat source rule 10 protocol all
set nat source rule 10 translation address masquerade
commit
Second, we create NAT rule that will allow traffic from out management
subnet, 10.20.0.0/24, to a fake public Floating IP subnet:
::
set nat source rule 11 source address 10.20.0.0/24
set nat source rule 11 outbound-interface eth1
set nat source rule 11 protocol all
set nat source rule 11 translation address masquerade
commit
set nat source rule 11 source address 10.20.0.0/24
set nat source rule 11 outbound-interface eth1
set nat source rule 11 protocol all
set nat source rule 11 translation address masquerade
commit
Don't forget to save this configuration:
::
vyos@vyos# save
Saving configuration to '/config/config.boot'...
Done
[edit]
vyos@vyos# save
Saving configuration to '/config/config.boot'...
Done
[edit]
Final consideration
@ -322,7 +334,7 @@ in the management network gateway router, 10.20.0.1. For example:
::
# ip route add 200.200.200.0/24 via 10.20.0.254
# ip route add 200.200.200.0/24 via 10.20.0.254
In case management gateway router is not accessible, the above
static route can be set at each individual host that needs to access

48
doc/content/description.rst
View File

@ -1,19 +1,22 @@
MidoNet Plugin for Fuel 7.0
===========================
.. raw:: pdf
PageBreak oneColumn
Introduction
============
MidoNet is an Apache licensed production grade network virtualization software
for Infrastructure-as-a-Service (IaaS) clouds. This plugin provides the puppet
manifests to install all the components to deploy easily MidoNet with Fuel in a
production environment.
for Infrastructure-as-a-Service (IaaS) clouds. Plugin for Fuel 7.0 provides the
puppet manifests to install all the components to deploy easily MidoNet with
Fuel in both lab or production environments.
MidoNet version that will be deployed is v2015.06_ and this plugin currently is
only compatible with version 7.0 of Mirantis OpenStack Fuel.
Fuel MidoNet plugin is capable of deploying MidoNet v2015.06_ on top of Mirantis
OpenStack Fuel version 7.0 (including Maintenance Update 2). There are no
prerequisites to use the MidoNet plugin: MidoNet is Open Source, and the plugin
sets the repositories from where download and install MidoNet packages.
There are no prerequisites to use the MidoNet plugin: MidoNet is Open Source,
and the plugin sets the repositories from where download and install MidoNet
packages.
This plugin also supports Midokura Enterprise MidoNet `(MEM)`_ installation by
This plugin also supports Midokura Enterprise MidoNet (MEM_) installation by
allowing the user to choose the option from the Fuel Web UI.
The packages are available to download from a password protected-repository.
The needed credentials will be provided_ by Midokura.
@ -25,19 +28,26 @@ Requirements
Requirement Version/Comment
======================= ===============
Fuel 7.0
MidoNet plugin for Fuel 3.0.0
MidoNet plugin for Fuel 3.0.1
======================= ===============
Limitations
-----------
* The plugin is **only** compatible with OpenStack environments deployed with
**Neutron + GRE** as network configuration in the environment configuration
options. However, VXLAN can be configured on the plugin settings after
the environment creation.
* The plugin has some limitations regarding node count scalability for NSDB
(Network State Database) and OpenStack Controller role nodes. Once number of
nodes with such roles have been determined on initial deployment, it can not
be changed. Compute role nodes are not affected by this limitation, current
plugin version supports Compute scalability.
* The plugin works with Ubuntu 14.XX environment.
* Current version of plugin can only deploy single MidoNet Gareway role node.
MidoNet itself supports any number of gateway nodes, it is only a plugin
limitation, additional nodes needs to be set up manually.
* The plugin works with Mirantis OpenStack deployed on Ubuntu 14.04.x operating
system environment.
.. _v2015.06: https://github.com/midonet/midonet/tree/stable/v2015.06.2
.. _(MEM): http://docs.midokura.com/docs/latest/manager-guide/content/index.html
.. _MEM: http://docs.midokura.com/docs/latest/manager-guide/content/index.html
.. _provided: http://www.midokura.com/mem-eval

189
doc/content/guide.rst
View File

@ -1,3 +1,9 @@
.. raw:: pdf
PageBreak oneColumn
MidoNet Fuel Plugin User Guide
==============================
@ -8,93 +14,99 @@ MidoNet SDN controller as a Neutron backend.
MidoNet Networks
----------------
MidoNet changes the behaviour of Neutron deployments and understanding what
MidoNet plugin does (especially on Public Network Ranges) is essential to
configure the Fuel plugin properly.
MidoNet changes the behaviour of dafault Neutron deployments, understanding
what MidoNet plugin does, especially in regard to external networks, is
essential to configure and use MidoNet Fuel plugin properly.
MidoNet plugin is compatible with both **Neutron + GRE** and **Neutron + VxLAN**
environment, so let's focus on the deployment with ML2 first, to introduce the
differences that MidoNet plugin has.
MidoNet plugin is compatible with both **Neutron + GRE** and
**Neutron + VxLAN** network tunneling overlays, so let's focus on showing
the differences betewwn the Neutron dafault ML2 deployments first.
Without MidoNet plugin
``````````````````````
Neutron without MidoNet plugin
``````````````````````````````
Fuel 7.0 reference architecture has a schema with the `networks that deploys
<https://docs.mirantis.com/openstack/fuel/fuel-7.0/reference-architecture.html#neutron-with-gre-segmentation-and-ovs>`_.
ML2 networks:
Fuel 7.0 reference architecture contains some useful informaition in
`Neutron Network Topologies
<https://docs.mirantis.com/openstack/fuel/fuel-7.0/reference-architecture.html#neutron-with-gre-segmentation-and-ovs>`_
section. First, let's have an overview of Neutron-default ML2 topolgy:
.. image:: images/fuelml2gre.png
:width: 100%
In this schema, red network represents the Public + Floating IP range. That
means API access to services and Virtual Machines' Floating IPs share the same
L2/L3 network. This schema overloads the Controllers' traffic, since Neutron L3
service is running on the controller, answers ARP requests coming from inbound
traffic that belong to Virtual Machines' Floating IPs, NATs the Floating IP to
the private IP address of the Virtual Machine and puts the packet in the overlay
of the green network (br-tun).
In this topology, red, or "North" network represents the Public Internet,
including Floating IP subnet assigned to OpenStack cloud. That means API access
to services and Virtual Machines' Floating IPs share the same L2/L3 network.
This topology overloads the Controllers' traffic, since Neutron L3 agent
service is running on the controller, answers all ARP requests coming from
"North" traffic that belong to Virtual Machines' Floating IPs, does NAT on all
of the traffic destined to Floating IP assigned to Virtual Machines and places
the resulting packets in the overlay of the green, "South" network (br-tun).
Even in an HA deployment, the L3 agent only runs in one of the Controller, and
only gets spawned in another host if the previous one loses connectivity (log
into a controller and see how Pacemaker is configured).
Even in an HA deployment, the L3 agent only runs on one of the Controllers, and
only gets spawned in another host if the previous one loses connectivity
(active-standby Corosync / Pacemaker HA setup).
So Controller has to:
Node hosting Neutron Controller has to:
- Serve the API requests coming from users
- Run the data and messaging services (rabbitmq and mysql is running on the
- Run the data and RPC messaging services (Rabbitmq and MySQL is running on the
controllers as well)
- Handle all the N/S traffic that comes to and from the Virtual Machines.
- Handle all the North-South traffic that comes to and from the Virtual Machines.
With MidoNet plugin, separate the control traffic from the data one is easier.
With MidoNet plugin
```````````````````
Neutron with MidoNet plugin
```````````````````````````
In MidoNet, even the Floating IPs live in the overlay. Floating Range is
With MidoNet, Neutron separates the control traffic from the data traffic.
Even the Floating IPs live in the network overlay. Floating IP subnet is
separated from the services API network range (called Public Network on Fuel
and represented by the red network below) and MidoNet gateway advertises the
routes that belong to Floating Ranges to BGP peers. So MidoNet plugin forces
you to define a new Network on its settings, and allocation-range from
environment settings get overridden.
MidoNet deployment schema:
MidoNet deployment topology:
.. image:: images/midonet_fuel.png
:width: 100%
On this schema:
On this topology diagram:
- **Public API network** is the red one. Only *Controllers* and *Gateway* need
to access to it. It should be a BGP router listening on the network to learn the
Floating Range of the Virtual Machines.
- **External Public & API networks** is the red one on the diagram. Only
*Controllers* (access to OpenStack APIs and Horizon) and *Gateway* need
access to this network. On the external side of this underlay we expect
an ISP BGP router(s), ready to learn our OpenStack Floating IP subnet
route so it can pass traffic to our virtual machines.
- **Private network** is the green one. All the traffic between virtual
machines is tunneled by MidoNet over this network. Even Floating IP addresses.
- **Private network** underlay is the green one on the diagram. All the traffic
between virtual machines is tunneled by MidoNet on top of this network.
Including traffic to and form floating IP addresses.
- **Management network** is the blue one. All the nodes need to be connected to
it, this network is used by *NSDB* nodes to get information about Virtual
Network infrastructure and Virtual Machines' network flows.
- **Management network** is the blue one. All nodes need to be connected to
it, this network is used for access to *NSDB* nodes in order to access
virtual networks topology and flow information.
- **PXE/Admin network** is the grey one. Needed by Fuel master to orchestrate
- **PXE/Admin network** is the gray one. Needed by Fuel master to orchestrate
the deployment.
- **Storage network** is not represented, since MidoNet nodes are not involved
on it.
- **Storage network** is not shown on the diagram, as it is out of scope of
this guide (and NEutron & MidoNet itself).
MidoNet gateway is pure-distributed and you can put as many gateways as you
want, so you don't overload machines in N/S traffic. Once BGP sessions are
established and routes are exchanged (gateway has a quagga instance running on
it), N/S traffic comes routed from the Public API network to one of the MidoNet
Gateways. It does not matter which of them gets the packet, they work as if it
were a single machine. MidoNet Gateway sends the inbound packet directly to the
host that has the Virtual Machine that has to receive the traffic.
MidoNet gateway is native distributed system, one can place as many gateways
necessary, so North-South traffic can be distributed and balanced. Once BGP
sessions are established and routes are exchanged between BGP "peers",
each North-to-South network packet gets routed from the External Public API
network to one of the MidoNet gateways. It does not matter which of them gets
the packet, they work as if they are a single entity. MidoNet gateway sends
the inbound packet directly to the Compute that hosts the target virtual
machine.
Controller nodes get less overloaded, since they only need to answer user
requests and they almost don't handle VM traffic (only the metadata requests at
VM creation).
In this way controller nodes gets significantly less overloaded, since they
only need to answer user requests and they don't handle VM traffic at all
(the only exception is the metadata traffic at VM provisioning time).
Now we are ready to create a Fuel environment that uses MidoNet.
Following the learned concepts, we are ready to create a Fuel environment
that uses MidoNet.
Select Environment
@ -114,7 +126,15 @@ Select Environment
`the official Mirantis OpenStack documentation <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#create-a-new-openstack-environment>`_
to finish the configuration.
#. Once the environment is created, open the *Settings* tab of the Fuel Web UI.
Alternatively, this can be done in fuel cli:
::
$ fuel env --create --name test-deployment --rel 2 --net neutron --nst tun
Once the environment is created, open the *Settings* tab of the Fuel Web UI.
Install Midokura Enterprise MidoNet (Optional)
----------------------------------------------
@ -133,6 +153,7 @@ Install Midokura Enterprise MidoNet (Optional)
.. image:: images/mem_credentials.png
:width: 100%
Configure MidoNet Plugin
------------------------
@ -149,7 +170,7 @@ Configure MidoNet Plugin
#. Activate the option **Assign public networks to all nodes**.
By default, Fuel only gives public access to Controllers. We need to enable
this option in order to have external connectivity to Gateway Nodes.
this option in order to have external connectivity to Gateway nodes.
.. image:: images/public_to_all.png
:width: 100%
@ -161,29 +182,42 @@ Configure MidoNet Plugin
Let's explain them:
- **Tunnel Type**: Even you have chosen GRE tunnels on environment creation,
this is a convention because the deployment that Fuel does by default is the
closest to the MidoNet plugin one. Here you can choose between GRE or VXLAN as
tunneling technology.
- **Tunnel Type**: Here you can choose between GRE or VxLAN as
tunneling technology. Both are supported by MidoNet, but VxLAN is
recommended for its performance.
- **Public Network CIDR**: This option will be the CIDR of Neutron's External
Network. This range **MUST NOT** be the same as the *Public Network* section
of the *Settings* tab of the environment. There is no way to control this from
the plugin development, so this restriction is all up to you!
- **Floating Network subnet** Public Network CIDR**: This option represents
the CIDR of Neutron's external network (overriding Public Network CIDR for
the default Neutron ML2 plugin). This subnet **MUST NOT** be the same as
the *Public Network* CIDR section of the *Settings* tab of the
environment. Since there is no option to fine-tune this kind of network
separation control within Fuel core, one must use MidoNet Fuel plugin
settings to do it.
- **Public Gateway IP**: The IP address of the *Public Network CIDR*. It will be
the Gateway IP address of the MidoNet Virtual network. This IP address can not
be in the next section's range. . Recommendation: put the first IP address of
the CIDR. There is no way to control that this IP belongs to the CIDR in from
the plugin development, so be aware on the value you are setting.
- **Floating Network Gateway IP**: The Gateway IP address to the MidoNet
Virtual IP subnet. This IP address is usually set to the first available
IP in the subnet. Make sure that the address really belongs to the
*Floating Network subnet* CIDR.
- **Floating Range Start** and **Floating Range End**: First and last IP address
of the Floating range of IPs available to be used on Virtual Machines.
- **Floating Network Range Start** and **Floating Network Range End**:
First and last IP address of the Floating range of IPs available for use
on virtual machines.
- **Local AS** Your Autonomous System number to establish a BGP connection.
- **BGP routing subnet**: IP subnet in which BGP peers resides. Both local
and remote BGP peer IP addresses must belong to this subnet.
- **BGP local IP address** and **BGP local AS**: This pair of parameters
identifies BGP peer local to MidoNet gateway. They are usually given by
ISP to be set into your networking equipment (in this case your MidoNet
gateway) by the network administrators. "AS number" stands for Autonomous
System Number.
- **BGP peer IP address** and **BGP peer AS**: This pair of parameters
usually identifies BGP peer on the side of your ISP. They are usually
given by ISP to be set into your BGP peer so that those peers know where
to find each other.
- **BGP Peer X AS** and **BGP X IP Address**: Information needed to establish a
BGP connection to remote peers.
Assign Roles to Nodes
---------------------
@ -194,11 +228,13 @@ Assign Roles to Nodes
.. image:: images/nodes_to_roles.png
:width: 100%
#. Just follow one rule:
#. Some general advice to be followed:
- **DO NOT** assign the role **Gateway** and the role **Controller** altogether.
- **Gateway** role should be given to a dedicated node.
- **NSDB** role can be combined with any other roles, but note that it needs
at least 4GB RAM for itself (dedicated storage hihgly recommended).
- **NSDB** role can be combined with any other role.
Finish environment configuration
--------------------------------
@ -206,3 +242,4 @@ Finish environment configuration
#. Run `network verification check <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#verify-networks>`_
#. Press `Deploy button <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#deploy-changes>`_ to once you are done with environment configuration.

114
doc/content/installation.rst
View File

@ -1,12 +1,44 @@
.. raw:: pdf
PageBreak oneColumn
Installation Guide
==================
Install the Plugin
------------------
To install the MidoNet Fuel plugin:
#. Download MidoNet plugin v3.0.1 from `Fuel Plugins Catalog`_
#. Log into Fuel Master node and install the plugin using the
`Fuel CLI <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#using-fuel-cli>`_:
::
# fuel plugins --install midonet-fuel-plugin-3.0-3.0.1-1.noarch.rpm
#. Verify that the plugin is installed correctly:
::
# fuel plugins
id | name | version | package_version
---|---------|---------|----------------
9 | midonet | 3.0.1 | 3.0.0
Enable Experimental Features
----------------------------
#. To be able to install **MidoNet**, you should enable `Experimental Features`_.
To do so, manually modify the ``/etc/fuel/version.yaml`` file in *Fuel Master*
To be able to use MidoNet Fuel plugin correctly, Fuel `Experimental Features`_
must be enabled. This is done automatically by plugin post-install script,
assuming the plugin is installed on top of clean Fuel master installation.
In case the process has to be done manually, follow these steps:
#. Modify the ``/etc/fuel/version.yaml`` file in *Fuel Master*
host to add ``experimental`` to the ``feature_groups`` list in the ``VERSION``
section, just below ``mirantis`` item:
@ -20,59 +52,34 @@ Enable Experimental Features
#. Restart the *Nailgun* container with dependencies by running::
$ dockerctl restart nailgun
$ dockerctl restart nginx
$ dockerctl shell cobbler
$ cobbler sync
$ exit
# dockerctl restart nailgun
# dockerctl restart nginx
# dockerctl shell cobbler
# cobbler sync
# exit
#. Make sure the *nginx* and the *nailgun* docker services finished the restart
process before go on with the new section::
$ dockerctl check
Install the Plugin
------------------
To install the MidoNet Fuel plugin:
#. Download it from the `Fuel Plugins Catalog`_
#. Copy the *rpm* file to the Fuel Master node:
::
[root@home ~]# scp midonet-fuel-plugin-3.0-3.0.0-1.noarch.rpm \
root@fuel-master:/tmp
#. Log into Fuel Master node and install the plugin using the
`Fuel CLI <https://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#using-fuel-cli>`_:
::
[root@fuel-master ~]# fuel plugins --install \
midonet-fuel-plugin-3.0-3.0.0-1.noarch.rpm
#. Verify that the plugin is installed correctly:
::
[root@fuel-master ~]# fuel plugins
id | name | version | package_version
---|---------|---------|----------------
9 | midonet | 3.0.0 | 3.0.0
# dockerctl check
Create the MidoNet roles
------------------------
MidoNet needs two roles besides the ones provided with Fuel:
MidoNet core functionality depends on two roles that are not provided by Fuel
on default:
- the **NSDB** role, which will install the Network State DataBase services
(ZooKeeper and Cassandra).
- the **NSDB** role, which deploys the Network State DataBase services, namely
ZooKeeper and Cassandra.
- the **Gateway** role, that will provide the HA Gateway machine for inbound and
outbound traffic of the *OpenStack* deployment. (See `User Guide
<./guide.rst>`_ for more info about networking in MidoNet)
- the **Gateway** role, which provides the MidoNet gateway service needed for
handling external *OpenStack* traffic. (See `MidoNet Fuel Plugin User Guide`_ for
more info about networking in MidoNet)
The above roles are added automatically by plugin post-install script,
assuming the plugin is installed on top of clean Fuel master installation.
In case the process has to be done manually, follow these steps:
NSDB role
`````````
@ -139,15 +146,17 @@ Gateway role
Edit the Fuel deployment graph dependency cycle
-----------------------------------------------
Now, you'll need to create a group inside
`Fuel's Deployment Graph <https://docs.fuel-infra.org/fuel-dev/develop/modular-architecture.html#granular-deployment-process>`_
to put the
tasks related to the recently created roles on the Fuel Deployment Graph.
The roles that were just added needs to be accompanied with appropriate
deployment tasks, so that `Fuel's Deployment Graph
<https://docs.fuel-infra.org/fuel-dev/develop/modular-architecture.html#granular-deployment-process>`_
is fully populated. Again, needed deployment tasks are added automatically by
plugin post-install script, assuming the plugin is installed on top of clean
Fuel master installation. In case the process still has to be done manually,
follow these steps:
#. Create a group type for Fuel 7.0 in a YAML file called
``/tmp/midonet_groups.yaml`` with the following content::
- id: nsdb
parameters:
strategy:
@ -211,10 +220,10 @@ tasks related to the recently created roles on the Fuel Deployment Graph.
fuel rel --rel 2 --deployment-tasks --upload
#. Though current Fuel Plugins Framework only allows to apply tasks on
*pre_deployment* and *post_deployment* stages for 7.0 Fuel release,
adding these groups and these tasks into the main graph will allow **NSDB**
and **Gateway** associated tasks to:
#. Current Fuel Plugins framework only allows to apply tasks on
*pre_deployment* and *post_deployment* stages, adding these groups
and tasks into the main graph will allow **NSDB** and **Gateway**
associated tasks to:
- Configure *logging* to see Puppet and MCollective logs related to the tasks
from the Fuel Web UI.
@ -228,3 +237,4 @@ tasks related to the recently created roles on the Fuel Deployment Graph.
.. _Experimental Features: https://docs.mirantis.com/openstack/fuel/fuel-7.0/operations.html#enable-experimental-features
.. _Fuel Plugins Catalog: https://www.mirantis.com/products/openstack-drivers-and-plugins/fuel-plugins/

20
doc/content/licenses.rst
View File

@ -1,5 +1,11 @@
Licenses
========
.. raw:: pdf
PageBreak oneColumn
Appendix B - licenses
=====================
Third Party Components Used in MidoNet OSS
------------------------------------------
@ -24,15 +30,15 @@ Hibernate Validator http://hibernate.org/validator Apache 2
HttpComponents http://hc.apache.org Apache 2.0
infinispan http://infinispan.org/ Apache 2.0
Jackson http://jackson.codehaus.org Apache 2.0
Java https://www.java.com Oracle’s Binary Code License Agreement
Java https://www.java.com Oracle Binary Code License Agreement
Jcabi Aspects http://aspects.jcabi.com/index.html BSD Three Clause
Jetty http://eclipse.org/jetty/ Apache 2.0. May also be licensed under Eclipse 1.0
Jetty http://eclipse.org/jetty/ Apache 2.0. and Eclipse 1.0
jminix https://code.google.com/p/jminix/ Apache 2.0
JMockit http://jmockit.org MIT
jna https://github.com/twall/jna Apache 2.0 for versions 4.0 and later. Earlier versions used LGPL 2.1
jna https://github.com/twall/jna LGPL 2.1. v4.0 and later: Apache 2.0.
JsonPath https://github.com/jayway/JsonPath Apache 2.0
JSch http://www.jcraft.com BSD-style
LOGBack http://logback.qos.ch EPL 1.0. Also available under LGPL 2.1
LOGBack http://logback.qos.ch EPL 1.0. and LGPL 2.1
Metrics https://dropwizard.github.io/metrics Apache 2.0
mockito https://github.com/mockito/mockito MIT
netty http://netty.io Apache 2.0
@ -50,6 +56,7 @@ Scallop https://github.com/scallop/scallop MIT
slf4j http://www.slf4j.org MIT
=================== =================================================== ================
Puppet Modules
--------------
@ -65,3 +72,4 @@ puppetlabs-apt Apache 2.0
puppetlabs-java Apache 2.0
puppetlabs-tomcat Apache 2.0
====================== ==========

10
doc/user-guide.rst
View File

@ -1,11 +1,16 @@
========================================
Guide to the MidoNet Plugin for Fuel 7.0
========================================
|
|
|
This document will guide you through the steps of install, configure and use the
MidoNet plugin for Fuel.
Sections
--------
.. contents::
.. section-numbering::
.. include:: content/description.rst
.. include:: content/terms.rst
@ -13,3 +18,4 @@ Sections
.. include:: content/guide.rst
.. include:: content/licenses.rst
.. include:: content/appendix.rst