x/puppet-midonet
Code Issues Proposed changes

Makes README.md beautiful and up to date

Browse Source 
Change-Id: Ib8cce9284486cf2e121794b559b93e1a95a7205c
This commit is contained in:
Alejandro Andreu 2016-11-03 18:34:33 +01:00
parent 10c97f3b10
commit a348017113
1 changed files with 236 additions and 327 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

531
README.md
View File

@ -1,334 +1,278 @@
# MidoNet
# midonet
#### Table of Contents
1. [Overview](#overview)
2. [Module Description](#module-description)
3. [Setup](#setup)
* [What MidoNet affects](#what-midonet-affects)
* [Beginning with MidoNet](#beginning-with-midonet)
4. [Usage](#usage)
5. [Reference](#reference)
* [Classes](#classes)
* [Types](#types)
6. [Limitations - OS compatibility, etc.](#limitations)
7. [Development - Guide for contributing to the module](#development)
1. [Overview - What is the midonet module?](#overview)
2. [Module Description - What does the module do?](#module-description)
3. [Setup - The basics of getting started with midonet](#setup)
4. [Implementation - An under-the-hood peek at what the module is doing](#usage)
5. [Limitations - OS compatibility, etc.](#limitations)
6. [Development - Guide for contributing to the module](#development)
6. [Contributors - Those with commits](#contributors)
## Overview
Puppet module for install MidoNet components.
This Puppet module is maintained by [Midokura](http://www.midokura.com)
and is used to flexibly configure and manage all MidoNet components.
To understand all MidoNet components and how they relate to each other,
check out the [MidoNet Reference Architecture](http://docs.midonet.org/docs/latest/reference-architecture/content/index.html).
## Module Description
MidoNet is an Apache licensed production grade network virtualization software
for Infrastructure-as-a-Service (IaaS) clouds. This module provides the puppet
manifests to install all the components to deploy easily MidoNet in a
production environment.
The midonet module is a thorough attempt to make Puppet capable of managing
the entirety of MidoNet. This includes manifests to provision both open source
and enterprise components:
To know all the components and how they relate each other, check out [midonet
reference architecture
docs](http://docs.midonet.org/docs/latest/reference-architecture/content/index.html)
* MidoNet Cluster (formerly known as the MidoNet API)
* MidoNet CLI
* MidoNet Agent (also known as Midolman)
* MEM
* MEM Insights
Uplink configuration for gateway nodes is also set up through the use of this
module. Currently both static and BGP uplinks are supported.
This module is tested in combination with other modules needed to build and
leverage a MidoNet installation.
## Setup
**What the neutron module affects:**
* [MidoNet](https://www.midonet.org/), which replaces the default plugin for
Neutron.
### Beginning with MidoNet
### Prerequisites
To install the last stable release of MidoNet OSS, just include the
MidoNet class in your Puppet manifest:
To use this module correctly, the following dependencies have to be met:
include midonet
* Have the gems `faraday` and `multipart-post` installed correctly (if using
Puppet 4.x use the `gem` executable from Puppet's main path)
* Have a working Zookeeper & Cassandra setup
That will deploy a full MidoNet installation (repos, agent, MidoNet API and MidoNet CLI)
in the target host, which is quite useless deployment, since MidoNet is a network controller
ready to be scalable and distributed. However, for testing its features and demo purposes, it can
be useful.
### Installing midonet
## Usage
```shell
puppet module install midonet-midonet
```
To use this module in a more advanced way, please check out the
[reference](#reference) section of this document. It is worth to highlight that
all the input variables have already a default input value, in a yaml document.
(We use R.I.Piennar [module data](https://www.devco.net/archives/2013/12/08/better-puppet-modules-using-hiera-data.php))
To leverage this feature, please add the following in your `/etc/puppet/hiera.yaml`
(or the Hiera configuration file that you are using):
### Beginning with midonet
---
:backends:
- yaml
- module_data
:yaml:
:datadirs:
- /var/lib/hiera
:logger: console
A very basic installation of MidoNet on a controller node looks like the
following:
Any variable that you may use in your class declaration will override the
defaults in `/etc/puppet/modules/midonet/data`, so you will only need to define
the variables that you want to override.
```puppet
include ::midonet::repository
## Reference
### Classes
#### MidoNet Agent
MidoNet Agent is the Openvswitch datapath controller and must run in all the Hypervisor hosts.
The easiest way to run the class is:
include midonet::midonet_agent
This call assumes that there is a zookeeper instance and a cassandra instance
running in the target machine, and will configure the midonet-agent to
connect to them.
This is a quite naive deployment, just for demo purposes. A more realistic one
would be:
class {'midonet::midonet_agent':
cassandra_seeds => ['host1', 'host2', 'host3'],
zk_servers => [{'ip' => 'host1', 'port' => '2183'},
{'ip' => 'host2', 'port' => '2181'}]
class { '::midonet::cluster':
zookeeper_hosts => [ { 'ip' => '127.0.0.1' } ],
cassandra_servers => [ { 'ip' => '127.0.0.1' } ],
cassandra_rep_factor => '1',
keystone_admin_token => 'token',
keystone_host => '127.0.0.1',
} ->
class { '::midonet::cli':
username => 'admin',
password => 'safe_password',
} ->
class { '::midonet::agent':
controller_host => '127.0.0.1',
metadata_port => '8775',
shared_secret => 'shared_secret',
zookeeper_hosts => [ { 'ip' => '127.0.0.1' } ],
}
```
Please note that Zookeeper port's value is not mandatory and it's already defaulted to 2181
And on compute nodes:
You can alternatively use the Hiera's yaml style:
```puppet
include ::midonet::repository
midonet::midonet_agent::zk_servers:
- ip: 'host1'
port: 2183
- ip: 'host2'
port: 2181
midonet::midonet_agent::cassandra_seeds:
- 'host1'
- 'host2'
- 'host3'
Note: midonet\_agent class already makes a call to midonet\_agent::install.
This class allows to choose whether you want it to install and manage Java, or
use an existing installations instead.
For this purpose a param has been added and its value has been defaulted to
'true'. Should you want to manage the Java installation from another puppet
module and avoid duplicated class declaration, change the value to 'false':
class { 'midonet::midonet_agent::install':
install_java => false
class { '::midonet::agent':
controller_host => '127.0.0.1',
metadata_port => '8775',
shared_secret => 'shared_secret',
zookeeper_hosts => [ { 'ip' => '127.0.0.1' } ],
}
```
You can alternatively use the Hiera's yaml style:
Afterwards on every controller/compute, the `midonet_host_registry` custom
type should be used to register the node in MidoNet.
midonet::midonet_agent::install::install_java: false
On gateway nodes one should install Midolman (see above) and configure the
uplink:
#### MidoNet API
* Use the `::midonet::gateway::static` class to configure a fake static uplink
* Use the `midonet_gateway_bgp` custom type to configure the BGP uplink
MidoNet API is the REST service where third-party software can connect to
control the virtual network. A single instance of it can be enough.
For examples on how to use all the classes see the manifests in the `roles`
folder at `midonet/puppet-midonet_openstack`.
The easiest way to run this class is:
include midonet::midonet_api
## Implementation
This call assumes that there is a zookeeper running in the target host and the
module will spawn a midonet\_api without keystone authentication.
### midonet
This is a quite naive deployment, just for demo purposes. A more realistic one
would be:
class {'midonet::midonet_api':
zk_servers => [{'ip' => 'host1', 'port' => '2183'},
{'ip' => 'host2', 'port' => '2181'}],
keystone_auth => true,
vtep => true,
api_ip => '92.234.12.4',
keystone_host => '92.234.12.9',
keystone_port => '35357', # Note: (35357 is already the default)
keystone_admin_token => 'arrakis',
keystone_tenant_name => 'other-than-services' # Note: ('services' by default)
}
You can alternatively use the Hiera's yaml style:
midonet::midonet_api::zk_servers:
- ip: 'host1'
port: 2183
- ip: 'host2'
port: 2181
midonet::midonet_api::vtep: true
midonet::midonet_api::keystone_auth: true
midonet::midonet_api::api_ip: '92.234.12.4'
midonet::midonet_api::keystone_host: '92.234.12.9'
midonet::midonet_api::keystone_port: 35357
midonet::midonet_api::keystone_admin_token: 'arrakis'
midonet::midonet_api::keystone_tenant_name: 'other-than-services'
Please note that Zookeeper port is not mandatory and defaulted to 2181.
Note: midonet\_api class already makes a call to midonet\_api::install. This
class allows you to choose whether you want it to install and manage Tomcat and
Java, or use existing installations of both instead.
For this purpose 2 parameters have been added and their values have been
defaulted to 'true'. Should you want to manage Tomcat and Java installation
from another puppet module and avoid duplicated class declaration, change the
values to 'false':
class { 'midonet::midonet_api::install':
install_java => false,
manage_app_server => false
}
You can alternatively use the Hiera's yaml style:
midonet::midonet_api::install::install_java: false
midonet::midonet_api::install::manage_app_server: false
#### MidoNet CLI
Install the MidoNetCLI this way:
include midonet::midonet_cli
Module does not configure the ~/.midonetrc file that `python-midonetclient`
needs to run. Please, check out how to configure the MidoNet client
[here](https://docs.midonet.org/docs/v2015.06/en/quick-start-guide/rhel-7_kilo-rdo/content/_midonet_cli_installation.html)
#### Neutron Plugin
Install and configure MidoNet Neutron Plugin. Please note that manifest does
install Neutron (because it is a requirement of 'python-neutron-plugin-midonet'
package) but it does not configure it nor run it. It just configure the specific
MidoNet plugin files. It is supposed to be deployed along any existing puppet
module that configures Neutron, such as [puppetlabs/neutron](https://forge.puppetlabs.com/puppetlabs/neutron/4.1.0)
The easiest way to run this class is:
include midonet::neutron_plugin
Although it is quite useless: it assumes that there is a Neutron server already
configured and a MidoNet API running at localhost with Mock authentication.
A more advanced call would be:
class {'midonet::neutron_plugin':
midonet_api_ip => '23.123.5.32',
username => 'neutron',
password => '32kjaxT0k3na',
project_id => 'service'
}
You can alternatively use the Hiera's yaml style:
midonet::neutron_plugin::midonet_api_ip: '23.213.5.32'
midonet::neutron_plugin::username: 'neutron'
midonet::neutron_plugin::password: '32.kjaxT0k3na'
midonet::neutron_plugin::midonet_api_ip: 'service'
midonet is a combination of Puppet manifest and ruby code to deliver
configuration and extra functionality through *types* and *providers*.
### Types
#### MidoNet Host Registry ###
#### midonet_gateway_bgp
MidoNet defines Tunnel Zones as groups of hosts capable to send packages to
each other using networking tunnels from which we can create Virtual Networks
on the overlay.
The `midonet_gateway_bgp` provider allows to configure a BGP uplink in the
gateway node.
Each host that runs [#MidoNet Agent] should be part of at least one Tunnel Zone
to send packets in the overlay to the rest of hosts of the Tunnel Zone. The
type `midonet_host_registry` allows you to register the host.
A [#MidoNet API] should already been deployed before and the [#MidoNet Agent]
should be running in the host we are registering.
This is the way to use it:
midonet_host_registry {$::fqdn:
$ensure => present,
$midonet_api_url => 'http://controller:8080',
$username => 'admin',
$password => 'admin',
$tenant_name => 'admin',
$underlay_ip_address => '123.23.43.2'
$tunnelzone_name => 'tzone0',
$tunnelzone_type => 'gre'
}
Notes:
* **midonet\_api\_url**, **username**, **password**, **tenant\_\name**:
Credentials to authenticate to Keystone through the MidoNet API service.
**tenant\_name** is defaulted to **admin** and is not mandatory.
* **underlay\_ip\_address**: Physical interface from where the packets will be
tunneled.
* **tunnelzone\_name**: Name of the Tunnel Zone. If the Tunnel Zone is does
not exist, the provider will create it. Defaulted to *tzone0*, so is not
mandatory to use this attribute unless you care too much about names or you
want more than one Tunnel Zone.
* **tunnelzone\_type**: Type of the tunnel. You can choose between *gre* and
*vxlan*. Defaulted to 'gre'.
More info at MidoNet
[docs|http://docs.midonet.org/docs/latest/quick-start-guide/ubuntu-1404_kilo/content/_midonet_host_registration.html]
#### MidoNet Gateway ####
This capability allows a Host that runs MidoNet to be declared as the gateway
of the installation and provide the necessary steps to put the packages from
the underlay to the overlay and viceversa. MidoNet needs to bind a Host
interface to *MidoNet Provider Router*, which is the router on top of the
Virtual Infrastructure.
Then, MidoNet starts BGP sessions to advertise the routes that manages and be
accessible from the Internet.
This is the way to use it:
midonet_gateway {$::fqdn:
```puppet
midonet_gateway_bgp { 'edge-router':
ensure => present,
midonet_api_url => 'http://controller:8080',
bgp_local_as_number => '65520',
bgp_advertised_networks => [ '200.200.0.0/24' ],
bgp_neighbors => [
{
'ip_address' => '192.168.1.6',
'remote_asn' => '65506',
'remote_net' => '192.168.1.0/24'
}
],
midonet_api_url => 'http://127.0.0.1:8181',
username => 'admin',
password => 'safe_password',
tenant_name => 'admin',
}
```
##### bgp_local_as_number
The local AS number that this gateway will use.
##### bgp_advertised_networks
An array listing all the floating IP networks that will be advertised.
##### bgp_neighbors
An array of BGP peers. Each on the elements needs to have the following
attributes:
* `ip_address`: IP address of the BGP peer
* `remote_asn`: Remote AS number
* `remote_net`: Network on which the BGP peer is
##### midonet_api_url
URL of the MidoNet API in the format `http://<HOST>:<PORT>`.
##### username
Username for the `admin` user. Defaults to `admin`.
##### password
Password for this user. Defaults to `admin`.
##### tenant_name
Tenant name on which we want to apply the changes. Defaults to `admin`.
#### midonet_host_registry
The `midonet_host_registry` registers a MidoNet node through the MidoNet API. It
is necessary to use this type on every node that runs Midolman.
```puppet
midonet_host_registry { 'myhost':
ensure => present,
midonet_api_url => 'http://127.0.0.1:8181',
tunnelzone_name => 'tzone0'
tunnelzone_type => 'gre',
username => 'admin',
password => 'admin',
tenant_name => 'admin',
interface => 'eth1',
local_as => '64512',
bgp_port => { 'port_address' => '198.51.100.2', 'net_prefix' => '198.51.100.0', 'net_length' => '30'},
remote_peers => [ { 'as' => '64513', 'ip' => '198.51.100.1' },
{ 'as' => '64513', 'ip' => '203.0.113.1' } ],
advertise_net => [ { 'net_prefix' => '192.0.2.0', 'net_length' => '24' } ]
underlay_ip_address => $::ipaddress,
}
```
More info at MidoNet
[docs|http://docs.midonet.org/docs/latest/quick-start-guide/ubuntu-1404_kilo/content/bgp_uplink_configuration.html]
##### midonet_api_url
* **midonet\_api\_url**, **username**, **password**, **tenant\_\name**:
Credentials to authenticate to Keystone through the MidoNet API service.
**tenant\_name** is defaulted to **admin** and is not mandatory.
* **interface**: Host Interface where the gateway port of the *MidoNet
Provider Router* will be binded.
* **local_as**: Local Autonomous System of MidoNet deployment.
* **bgp_port**: Information about the port that will be created on *MidoNet
Provider Router* and will serve as the gateway of the virtual
infrastructure.
* **remote_peers**: List of uplink peers to establish BGP connections to.
* **advertise_net**: List of Network that will be advertised on from MidoNet
on the BGP sessions.
URL for the MidoNet API in the form of `http://<HOST>:<PORT>`.
##### tunnelzone_name
Name of the tunnel zone where the host will be registered. Defaults to `tzone0`.
##### tunnelzone_type
The type of tunnel zone. Can be set to `gre` or `vxlan`. Defaults to `gre`.
##### username
Username of the `admin` user in Keystone. Defaults to `admin`.
##### password
Password of the `admin` user in Keystone. Defaults to `admin`.
##### tenant_name
Tenant name of the `admin` user. Defaults to `admin`.
##### underlay_ip_address
IP address that will be used to as the underlay layer to create the tunnels.
It will take the fact `$::ipaddress` by default.
#### midonet_client_conf
This type is used to manage the configuration at `/root/.midonetrc`.
```puppet
midonet_client_conf {
'cli/username': value => 'admin';
}
```
This would set the `username` setting inside the `cli` section to `admin`.
## Limitations
This module supports:
The following platforms are supported:
* Ubuntu 14.04
* CentOS 6.6
* Ubuntu 14.04 (Trusty)
* Ubuntu 16.04 (Xenial)
* CentOS 7
This module has been tested in Puppet 3.7.3 version, but we believe that it
should work without problems in any Puppet 3.x version.
The module has been tested in both Puppet versions `3.x` and `4.x`.
Please note that if there is a dedicated analytics node provisioned with
`::midonet::analytics` you will need to place a virtualhost file manually
on the controller for the midonet manager to be able to reach the
analytics endpoints (using `ProxyPass` is enough).
## Beaker-Rspec
This module has beaker-rspec tests
To run:
```shell
bundle install
bundle exec rspec spec/acceptance
```
## Development
We happily will accept patches and new ideas to improve this module.
The project follows for the most part the OpenStack development model.
Developer documentation for the entire puppet-openstack project is at:
* http://docs.openstack.org/developer/puppet-openstack-guide/
Check out current bugs or open new ones on JIRA project:
@ -336,42 +280,7 @@ Check out current bugs or open new ones on JIRA project:
Feel free to assign an empty one to yourself!
Clone MidoNet's puppet repo in:
git clone https://github.com/midonet/puppet-midonet.git
and send patches via:
git review
You can see the state of the patch in:
https://review.gerrithub.io/#/q/status:open+project:midonet/puppet-midonet
We are using a Gerrit's rebase-based branching policy. So please, submit a
single commit per change. If a commit has been rejected, do the changes you
need to do and squash your changes with the previous patch:
git commit --amend
We are using Vagrant for integration testing, puppet-lint for syntax code
convention and rspec por unit testing. To test the module before send a patch,
we recommend to use [bundle](http://bundler.io/) to install the dependencies:
$ gem install bundle $ cd <path_to_puppet-midonet> $ bundle install
And then run the syntax, unit, and smoke tests.
$ rake lint $ rake spec $ rake beaker
**Puppet-midonet** uses Vagrant as the backend provisioner for beaker, so to
have Vagrant installed is mandatory.
You can contact us on several channels:
https://github.com/midonet/midonet/wiki/Communication
## Release Notes
* v2015.1.0: Initial manifests
* v2015.6.0: Adding `midonet_cli`, `midonet_host_registry` and
`midonet_gateway` types.
Contributors
------------
The github [contributor graph](https://github.com/openstack/puppet-midonet/graphs/contributors).