Getting Started with MidoNet

Demuxx edited this page Oct 31, 2016 · 11 revisions

Introduction

This guide intends to easily get you started with using MidoNet.

Try MidoNet with Quickstart

For the impatient users; we have a fast path to get started. This is not intended for production environments.

MidoNet Quickstart enables you to start an all-in-one node OpenStack + MidoNet environment with a single command. It installs MidoNet and OpenStack from packages and configures/runs OpenStack to use MidoNet as the Neutron plugin.

Use the following command on a 64-bit Ubuntu 14.04 environment to run the MidoNet Quickstart: $ curl -sL https://quickstart.midonet.org | sudo bash This command will install MidoNet with OpenStack. Once finished, you will be told how to log into Horizon.

Get familiar with MidoNet

In order to install MidoNet you will need to be familiar with the basic concepts of MidoNet.

We recommend you read the following:

Before you start

As any software, MidoNet has prerequisites that must be carefully reviewed before the install.

Installing MidoNet

There are two ways to install MidoNet: building from source or downloading packages.

In addition of the nightly builds, packages of community supported versions will be available soon.

See the Release Schedule for details.

Install from sources

The install from sources is only recommended if you want to install MidoNet on an unsupported distribution.

Follow the Install from sources guide.

Install from packages

This is the recommended way to install MidoNet for production, pre-production or lab environments.

To install MidoNet on Ubuntu, refer to the Quick Start Guides.

Those who would like to try out MidoNet on operating systems derived from RHEL or Fedora, such as CentOS, Scientific Linux and others may use the same procedure as that for RHEL, above, with the exceptions outlined here: guide on RDO wiki.

Building Packages Quickstart

This quick start guide will install the necessary prerequisites and build dependencies needed for MidoNet, then build the project and all its modules. On an Ubuntu 14.04.2 LTS with 4 CPUs, 8Gb RAM and 40Gb Disk space, the time needed to build the Debian and RPM packages is roughly 7 minutes without tests. Note that the quality of internet connection and availability of resources needed from the internet can effect this value. To install protobuf takes roughly 5 minutes.

 ~$ sudo apt-get install git -y
 ~$ git clone https://github.com/midonet/midonet

 ~$ echo | sudo add-apt-repository ppa:openjdk-r/ppa
 ~$ sudo apt-get update
 ~$ sudo apt-get install openjdk-8-jdk -y

 ~$ sudo apt-get install ruby-dev build-essential -y
 ~$ sudo apt-get install -y ruby rpm ruby-ronn && sudo gem install fpm

 ~$ wget https://github.com/google/protobuf/releases/download/v2.6.1/protobuf-2.6.1.tar.gz
 ~$ tar -xzf protobuf-2.6.1.tar.gz
 ~$ cd protobuf-2.6.1
 ~$ ./configure
 ~$ make
 ~$ sudo make install
 ~$ sudo ldconfig
 ~$ cd -
 ~$ rm -rf protobuf-2.6.1
 ~$ rm protobuf-2.6.1.tar.gz

 ~$ cd midonet
 ~/midonet$ ./gradlew debian -x test
 ~/midonet$ ./gradlew rpm -x test 

The resulting packages can be found in the following locations:

 ./midolman/build/packages/midolman***.deb
 ./midonet-cluster/build/packages/midonet-cluster***.deb
 ./python-midonetclient/python-midonetclient***.deb
 ./midonet-util/build/packages/midonet-tools***.deb     
 ./midolman/build/packages/midolman-5.0-0.0.***.el7.noarch.rpm
 ./cluster/midonet-cluster/build/packages/midonet-cluster-5.0-0.0.***.el7.noarch.rpm
 ./python-midonetclient/python-midonetclient-5.0-0.0.***.el7.noarch.rpm

Getting up to speed with MidoNet

Before you can start playing around with MidoNet, log in to the OpenStack dashboard (Horizon) as a cloud administrative user, and create a MidoNet project with these pieces in place:

  • admin user
  • security group with some rules
  • private network
  • external network
  • tenant router
  • VM with an associated floating IP address

For detailed procedures refer to the OPENSTACK ADMIN USER GUIDE:

http://docs.openstack.org/user-guide-admin/index.html

Note: All the examples provided here require access to the MidoNet CLI.

Launching the MidoNet CLI

In the terminal of the host running the MidoNet CLI enter the command:

midonet-cli midonet>

The second line (midonet>) is the familiar MidoNet CLI prompt where you can type in commands. It will accompany you throughout this tutorial.

MidoNet Provider Router

The MidoNet Provider Router is created automatically. It connects your tenant router(s) with an external network. The connection between the MidoNet Provider Router and the external network is also created automatically. The Provider Router does not have any tenant (project) associated that's why you can view it directly after you log it to the MidoNet CLI:

midonet> list router router router1 name MidoNet Provider Router state up

Listing the Provider Router's ports

To list the port on the MidoNet Provider Router, enter the command:

midonet> router router1 list port port port0 device router1 state up mac 02:fb:21:dc:49:62 address 169.254.255.1 net 169.254.255.0/30 peer router0:port0 port port1 device router1 state up mac 02:f3:fa:89:34:c6 address 198.51.100.1 net 198.51.100.0/24 peer bridge0:port0

The above output reveals the following information:

  • port0 is peered with router0 (tenant-router) via the 169.254.255.1 link-local address.
  • port1 is peered with port0 on bridge0.

Selecting your project

To select the project (tenant) that you created in OpenStack issue this command:

midonet> pusht <your-project-id>

where <your-project-id> is your project's ID in OpenStack. For example:

midonet> pusht 031ac72f54ee434a9079c1fc0baddacf tenant_id: 031ac72f54ee434a9079c1fc0baddacf

Listing tenant bridges

To display the list of bridges (networks) for the selected tenant, enter the command:

midonet> bridge list bridge bridge0 name my-private-network state up

The output shows:

  • The alias (bridge0) for the private network you created in OpenStack (my-private-network).
  • The bridge's state is up.

Listing tenant routers

To obtain the information about the router(s) for the current tenant, enter the command:

midonet> router list router router0 name tenant-router state up infilter chain0 outfilter chain1

The output reveals the following information:

  • There is just one router, alias (router0). This is the tenant router that you created in OpenStack, named tenant-router.
  • The tenant-router's state is up.
  • Two rule chains are associated with the router: an infilter (pre-routing) and outfilter (post-routing) chain. They were created automatically.

Viewing pre-routing rule information

To display information about the router's pre-routing rule chain, enter the command:

midonet> chain chain0 list rule rule rule0 dst 198.51.100.3 proto 0 tos 0 in-ports router0:port0 pos 1 type dnat action accept target 172.16.3.3 rule rule1 dst 198.51.100.2 proto 0 tos 0 in-ports router0:port0 pos 2 type rev_snat action accept

Viewing post-routing rule information

To display information about the post-routing rule chain, enter the command:

midonet> chain chain1 list rule rule rule0 src 172.16.3.3 proto 0 tos 0 out-ports router1:port0 pos 1 type snat action accept target 198.51.100.3 rule rule1 proto 0 tos 0 out-ports router1:port0 pos 2 type snat action accept target 198.51.100.2:1

Getting router port information

To view information about the ports on the tenant-router (router0), enter the command:

midonet> router router0 list port port port0 device router0 state up mac 02:77:ae:ff:d8:20 address 169.254.255.2 net 169.254.255.0/30 peer router1:port0 port port1 device router0 state up mac 02:4c:f1:ed:6b:df address 172.16.3.1 net 172.16.3.0/24 peer bridge0:port0

The output shows the following information about the two ports on router0:

  • Both ports are up, and their MAC addresses and assigned IP and network addresses are listed.
  • port0 is connected to port 0 on router1. 169.254.255.2 is a link-local address and the 169.254.255.0/30 network is an address in the link-local address block. This is one of the interfaces that are automatically created to connect virtual routers.
  • port1 is connected to port0 on bridge0. This is the network:router_interface for the private network you configured on OpenStack, demo-private-net (bridge0).

Viewing route information

Routes are set up automatically for you when you configure your network in OpenStack, so you probably won't need to modify them. If you need to view the information about the routes configured on the tenant router, run this command:

midonet> router router0 list route route route0 type normal src 0.0.0.0/0 dst router0:port0 weight 0 route route1 type normal src 0.0.0.0/0 dst weight 100 route route2 type normal src 0.0.0.0/0 dst router0:port1 weight 100 route route3 type normal src 172.16.3.0/24 172.16.3.2 port router0:port1 weight 100 route route4 type normal src 0.0.0.0/0 dst router0:port1 weight 0

Tunnel zones

A tunnel zone is an isolation zone for hosts. Physical hosts in the same tunnel zone, can communicate directly with one another. MidoNet supports two types of tunnel zones for separating physical hosts in the underlay, GRE (default) and VXLAN.

To create a tunnel zone use the command:

create tunnel-zone name <tz-name> type <tz-type>

where tz-type is tunnel zone type, gre or vxlan. For example:

midonet> create tunnel-zone name gre-tunnel-zone type gre tzone0

Getting a list of hosts

To admit a host into a tunnel zone first get the list of all the available hosts. For example:

midonet> list host host host0 name compute-1 alive true host host1 name compute-2 alive true

Admitting a host to tunnel zone

To admit a host into a tunnel zone you need to add one of its interfaces to it.

First get the list of all the host's interfaces by using the command:

host <host-alias> list interface

where <host-alias> is the host alias obtained earlier by issuing thehost list command. For example:

midonet> host host0 list interface iface lo host_id host0 status 3 addresses [u'127.0.0.1', u'0:0:0:0:0:0:0:1'] / mac 00:00:00:00:00:00 mtu 65536 type Virtual endpoint LOCALHOST iface eth0 host_id host0 status 3 addresses [u'10.1.2.200', u'fe80:0:0:0:250:56ff:fe93:c9a4'] / mac 00:50:56:93:c9:a4 mtu 1500 type Physical endpoint PHYSICAL

Take note of the IP address of the interface that you want to add to the tunnel zone.

Add host0 as a new member of the tunnel zone tzone0 using this command:

midonet> tunnel-zone tzone0 add member host host0

Specify the IP of the interface on host0 that you want to add to tzone0:

midonet> tunnel-zone tzone0 add member host host0 address 10.1.2.200

In the above command:

  • tzone0 = the tunnel zone you want to add the member (host) to
  • host0 = the alias of the host you want to add
  • 10.1.2.200 = the IP address of the host you want to add

Getting tunnel zone information

To display information about a tunnel zone, issue this command:

midonet> tunnel-zone tzone0 list member zone tzone0 host host0 address 10.1.2.200

The command output shows the following information:

  • The name of the tunnel zone in question (tzone0)
  • The alias of the host(s) in the tunnel zone (for now, there's just one host in it, host0)
  • The IP address assigned to the host(s)

Go further with MidoNet

See the MidoNet operations guide and API reference in the Documentation site.

In particular, you will find in the operations guide instructions to setup the gateway nodes using BGP.