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 #### Table of Contents
1. [Overview](#overview) 1. [Overview - What is the midonet module?](#overview)
2. [Module Description](#module-description) 2. [Module Description - What does the module do?](#module-description)
3. [Setup](#setup) 3. [Setup - The basics of getting started with midonet](#setup)
* [What MidoNet affects](#what-midonet-affects) 4. [Implementation - An under-the-hood peek at what the module is doing](#usage)
* [Beginning with MidoNet](#beginning-with-midonet) 5. [Limitations - OS compatibility, etc.](#limitations)
4. [Usage](#usage) 6. [Development - Guide for contributing to the module](#development)
5. [Reference](#reference) 6. [Contributors - Those with commits](#contributors)
* [Classes](#classes)
* [Types](#types)
6. [Limitations - OS compatibility, etc.](#limitations)
7. [Development - Guide for contributing to the module](#development)
## Overview ## 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 ## Module Description
MidoNet is an Apache licensed production grade network virtualization software The midonet module is a thorough attempt to make Puppet capable of managing
for Infrastructure-as-a-Service (IaaS) clouds. This module provides the puppet the entirety of MidoNet. This includes manifests to provision both open source
manifests to install all the components to deploy easily MidoNet in a and enterprise components:
production environment.
To know all the components and how they relate each other, check out [midonet * MidoNet Cluster (formerly known as the MidoNet API)
reference architecture * MidoNet CLI
docs](http://docs.midonet.org/docs/latest/reference-architecture/content/index.html) * 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 ## 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 To use this module correctly, the following dependencies have to be met:
MidoNet class in your Puppet manifest:
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) ### Installing midonet
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.
## Usage ```shell
puppet module install midonet-midonet
```
To use this module in a more advanced way, please check out the ### Beginning with midonet
[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):
--- A very basic installation of MidoNet on a controller node looks like the
:backends: following:
- yaml
- module_data
:yaml:
:datadirs:
- /var/lib/hiera
:logger: console
Any variable that you may use in your class declaration will override the ```puppet
defaults in `/etc/puppet/modules/midonet/data`, so you will only need to define include ::midonet::repository
the variables that you want to override.
## Reference class { '::midonet::cluster':
zookeeper_hosts => [ { 'ip' => '127.0.0.1' } ],
### Classes cassandra_servers => [ { 'ip' => '127.0.0.1' } ],
cassandra_rep_factor => '1',
#### MidoNet Agent keystone_admin_token => 'token',
keystone_host => '127.0.0.1',
MidoNet Agent is the Openvswitch datapath controller and must run in all the Hypervisor hosts. } ->
class { '::midonet::cli':
The easiest way to run the class is: username => 'admin',
password => 'safe_password',
include midonet::midonet_agent } ->
class { '::midonet::agent':
This call assumes that there is a zookeeper instance and a cassandra instance controller_host => '127.0.0.1',
running in the target machine, and will configure the midonet-agent to metadata_port => '8775',
connect to them. shared_secret => 'shared_secret',
zookeeper_hosts => [ { 'ip' => '127.0.0.1' } ],
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'}]
} }
```
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: class { '::midonet::agent':
- ip: 'host1' controller_host => '127.0.0.1',
port: 2183 metadata_port => '8775',
- ip: 'host2' shared_secret => 'shared_secret',
port: 2181 zookeeper_hosts => [ { 'ip' => '127.0.0.1' } ],
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
} }
```
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 For examples on how to use all the classes see the manifests in the `roles`
control the virtual network. A single instance of it can be enough. 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 ### midonet
module will spawn a midonet\_api without keystone authentication.
This is a quite naive deployment, just for demo purposes. A more realistic one midonet is a combination of Puppet manifest and ruby code to deliver
would be: configuration and extra functionality through *types* and *providers*.
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'
### Types ### Types
#### MidoNet Host Registry ### #### midonet_gateway_bgp
MidoNet defines Tunnel Zones as groups of hosts capable to send packages to The `midonet_gateway_bgp` provider allows to configure a BGP uplink in the
each other using networking tunnels from which we can create Virtual Networks gateway node.
on the overlay.
Each host that runs [#MidoNet Agent] should be part of at least one Tunnel Zone ```puppet
to send packets in the overlay to the rest of hosts of the Tunnel Zone. The midonet_gateway_bgp { 'edge-router':
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:
ensure => present, 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', username => 'admin',
password => 'admin', password => 'admin',
tenant_name => 'admin', tenant_name => 'admin',
interface => 'eth1', underlay_ip_address => $::ipaddress,
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' } ]
} }
```
More info at MidoNet ##### midonet_api_url
[docs|http://docs.midonet.org/docs/latest/quick-start-guide/ubuntu-1404_kilo/content/bgp_uplink_configuration.html]
* **midonet\_api\_url**, **username**, **password**, **tenant\_\name**: URL for the MidoNet API in the form of `http://<HOST>:<PORT>`.
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.
##### 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 ## Limitations
This module supports: The following platforms are supported:
* Ubuntu 14.04 * Ubuntu 14.04 (Trusty)
* CentOS 6.6 * Ubuntu 16.04 (Xenial)
* CentOS 7 * CentOS 7
This module has been tested in Puppet 3.7.3 version, but we believe that it The module has been tested in both Puppet versions `3.x` and `4.x`.
should work without problems in any Puppet 3.x version.
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 ## 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: 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! Feel free to assign an empty one to yourself!
Clone MidoNet's puppet repo in:
git clone https://github.com/midonet/puppet-midonet.git Contributors
------------
and send patches via: The github [contributor graph](https://github.com/openstack/puppet-midonet/graphs/contributors).
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.