Improve documentation for real
Documentation for new `midonet_gateway` and `midonet_host_registry`, fixing links on `metadata.json` and improving `Development` section of README Change-Id: I4a811b29512f40a68b7d15cf421624c3e66008fa
This commit is contained in:
Jaume Devesa
parent
554b21417b
commit
f141d8f1e8
|
|
@ -0,0 +1,5 @@
|
|||
Contribute with Puppet-MidoNet
|
||||
==============================
|
||||
|
||||
Check out on [Development Section of README](./README.md#Development) to see
|
||||
how to develop and contribute to this project.
|
||||
186
README.md
186
README.md
|
|
@ -1,25 +1,22 @@
|
|||
# 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)
|
||||
* [What MidoNet affects](#what-midonet-affects)
|
||||
* [Beginning with MidoNet](#beginning-with-midonet)
|
||||
4. [Usage](#usage)
|
||||
5. [Reference](#reference)
|
||||
* [Midonet Repository Class Reference](#midonet-repository)
|
||||
* [Midonet Agent Class Reference](#midonet-agent)
|
||||
* [Midonet API Class Reference](#midonet-api)
|
||||
* [Midonet CLI Class Reference](#midonet-cli)
|
||||
* [Neutron Plugin Class Reference](#neutron-plugin)
|
||||
6. [Limitations](#limitations)
|
||||
7. [Development](#development)
|
||||
* [Classes](#classes)
|
||||
* [Types](#types)
|
||||
6. [Limitations - OS compatibility, etc.](#limitations)
|
||||
7. [Development - Guide for contributing to the module](#development)
|
||||
|
||||
## Overview
|
||||
|
||||
Puppet module for install midonet components.
|
||||
Puppet module for install MidoNet components.
|
||||
|
||||
## Module Description
|
||||
|
||||
|
|
@ -34,28 +31,24 @@ docs](http://docs.midonet.org/docs/latest/reference-architecture/content/index.h
|
|||
|
||||
## Setup
|
||||
|
||||
### What midonet affects
|
||||
### What MidoNet affects
|
||||
|
||||
* This module affects the repository sources of the target system as well as
|
||||
new packages and their configuration files.
|
||||
|
||||
### Beginning with midonet
|
||||
### Beginning with MidoNet
|
||||
|
||||
To install the last stable release of Midonet OSS, just include the
|
||||
midonet class in your Puppet manifest:
|
||||
To install the last stable release of MidoNet OSS, just include the
|
||||
MidoNet class in your Puppet manifest:
|
||||
|
||||
include midonet
|
||||
|
||||
That will provide a full MidoNet installation (repos, cassandra, zookeeper,
|
||||
agent, midonet api, and midonet cli) in the target host, which is quite
|
||||
That will deploy a full MidoNet installation (repos, cassandra, zookeeper,
|
||||
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 would
|
||||
and distributed. However, for testing its features and demo purposes, it can
|
||||
be useful.
|
||||
|
||||
NOTE: The module also adds official OpenStack sources. It will use Icehouse or
|
||||
Juno depending on to underlay OS: Juno is not supported in Ubuntu 12.04 nor
|
||||
CentOS 6.x.
|
||||
|
||||
## Usage
|
||||
|
||||
To use this module in a more advanced way, please check out the
|
||||
|
|
@ -82,12 +75,12 @@ the variables that you want to override.
|
|||
|
||||
### Classes
|
||||
|
||||
#### Midonet Repository
|
||||
#### MidoNet Repository
|
||||
|
||||
Midonet Repository adds midonet's repos into target system. By default it installs
|
||||
last released version of midonet:
|
||||
MidoNet Repository adds MidoNet's repos into target system. By default it installs
|
||||
last released version of MidoNet:
|
||||
|
||||
To install other releases than the last default's Midonet OSS, you can override the
|
||||
To install other releases than the last default's MidoNet OSS, you can override the
|
||||
default's midonet\_repository atributes by a resource-like declaration:
|
||||
|
||||
class { 'midonet_repository':
|
||||
|
|
@ -111,9 +104,9 @@ or use a YAML file using the same attributes, accessible from Hiera:
|
|||
midonet_repository::openstack_release: 'juno'
|
||||
|
||||
|
||||
#### Midonet Agent
|
||||
#### MidoNet Agent
|
||||
|
||||
Midonet Agent is the Openvswitch datapath controller and must run in all the Hypervisor hosts.
|
||||
MidoNet Agent is the Openvswitch datapath controller and must run in all the Hypervisor hosts.
|
||||
|
||||
The easiest way to run the class is:
|
||||
|
||||
|
|
@ -147,7 +140,7 @@ You can alternatively use the Hiera's yaml style:
|
|||
- 'host3'
|
||||
|
||||
|
||||
#### Midonet API
|
||||
#### MidoNet API
|
||||
|
||||
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.
|
||||
|
|
@ -191,20 +184,22 @@ You can alternatively use the Hiera's yaml style:
|
|||
|
||||
Please note that Zookeeper port is not mandatory and defaulted to 2181.
|
||||
|
||||
#### Midonet CLI
|
||||
#### MidoNet CLI
|
||||
|
||||
Install the MidonetCLI this way:
|
||||
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](http://docs.midonet.org/docs/latest/quick-start-guide/rhel-7_juno-rdo/content/_midonet_cli_installation.html)
|
||||
Module does not configure the ~/.midonetrc file that `python-midonetclient`
|
||||
needs to run. Please, check out how to configure the MidoNet client
|
||||
[here](http://docs.midonet.org/docs/latest/quick-start-guide/rhel-7_juno-rdo/content/_midonet_cli_installation.html)
|
||||
|
||||
#### Neutron Plugin
|
||||
|
||||
Install and configure Midonet Neutron Plugin. Please note that manifest does
|
||||
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
|
||||
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:
|
||||
|
|
@ -230,12 +225,98 @@ You can alternatively use the Hiera's yaml style:
|
|||
midonet::neutron_plugin::password: '32.kjaxT0k3na'
|
||||
midonet::neutron_plugin::midonet_api_ip: 'service'
|
||||
|
||||
### Types
|
||||
|
||||
#### MidoNet Host Registry ###
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
$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'
|
||||
}
|
||||
|
||||
Note:
|
||||
|
||||
* **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 {'hostname':
|
||||
midonet_api_url => 'http://controller:8080',
|
||||
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' } ]
|
||||
}
|
||||
|
||||
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**, **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.
|
||||
|
||||
|
||||
## Limitations
|
||||
|
||||
This module supports:
|
||||
|
||||
* Ubuntu 14.04
|
||||
* Ubuntu 12.04
|
||||
* CentOS 6.6
|
||||
* CentOS 7
|
||||
|
||||
|
|
@ -244,8 +325,15 @@ should work without problems in any Puppet 3.x version.
|
|||
|
||||
## Development
|
||||
|
||||
We happily will accept patches and new ideas to improve this module. Clone
|
||||
MidoNet's puppet repo in:
|
||||
We happily will accept patches and new ideas to improve this module.
|
||||
|
||||
Check out current bugs or open new ones on JIRA project:
|
||||
|
||||
https://midonet.atlassian.net/projects/PUP
|
||||
|
||||
Feel free to assign an empty one to yourself!
|
||||
|
||||
Clone MidoNet's puppet repo in:
|
||||
|
||||
git clone https://github.com/midonet/puppet-midonet.git
|
||||
|
||||
|
|
@ -258,20 +346,28 @@ 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:
|
||||
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 beaker for integration testing, puppet-lint for syntax code convention and
|
||||
rspec por unit testing. To test the module before send a patch, execute:
|
||||
We are using beaker 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:
|
||||
|
||||
$ rake lint
|
||||
$ rake spec
|
||||
$ rake beaker
|
||||
$ gem install bundle $ cd <path_to_puppet-midonet> $ bundle install
|
||||
|
||||
inside the `midonet-midonet` directory
|
||||
And then run the syntax, unit, and smoke tests.
|
||||
|
||||
$ rake lint $ rake spec $ rake beaker
|
||||
|
||||
**Puppet-midonet** uses Docker as the backend provisioner for beaker, so to
|
||||
have Docker installed is mandatory.
|
||||
|
||||
Ping us on **#installers** channel on http://midonet.atlassian.org
|
||||
|
||||
## Release Notes
|
||||
|
||||
* v2015.1.0: Initial manifests
|
||||
* v2015.6.0: Adding `midonet_cli`, `midonet_host_registry` and
|
||||
`midonet_gateway` types.
|
||||
|
|
|
|||
|
|
@ -7,16 +7,16 @@ Puppet::Type.newtype(:midonet_gateway) do
|
|||
Example:
|
||||
|
||||
midonet_gateway {'hostname':
|
||||
midonet_api_url => 'http://controller:8080',
|
||||
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' },
|
||||
midonet_api_url => 'http://controller:8080',
|
||||
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' } ]
|
||||
advertise_net => [ { 'net_prefix' => '192.0.2.0', 'net_length' => '24' } ]
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -8,10 +8,10 @@ Puppet::Type.newtype(:midonet_host_registry) do
|
|||
Example:
|
||||
|
||||
midonet_host_registry {'hostname':
|
||||
$midonet_api_url => 'http://controller:8080',
|
||||
$username => 'admin',
|
||||
$password => 'admin',
|
||||
$ip_address => '123.23.43.2'
|
||||
$midonet_api_url => 'http://controller:8080',
|
||||
$username => 'admin',
|
||||
$password => 'admin',
|
||||
$underlay_ip_address => '123.23.43.2'
|
||||
}
|
||||
}
|
||||
ensurable
|
||||
|
|
|
|||
|
|
@ -4,9 +4,9 @@
|
|||
"author": "MidoNet",
|
||||
"summary": "Configure and install MidoNet components",
|
||||
"license": "Apache-2.0",
|
||||
"source": "https://github.com/midonet/arrakis",
|
||||
"project_page": "http://github.com/midonet/arrakis/tree/master/modules/midonet-midonet",
|
||||
"issues_url": "https://midonet.atlassian.net/projects/MDT",
|
||||
"source": "https://github.com/midonet/puppet-midonet",
|
||||
"project_page": "https://github.com/midonet/puppet-midonet",
|
||||
"issues_url": "https://midonet.atlassian.net/projects/PUP",
|
||||
"dependencies": [
|
||||
{ "name":"ripienaar-module_data","version_requirement":">=0.0.3" },
|
||||
{ "name":"puppetlabs-inifile", "version_requirement": ">=1.0.0 <2.0.0" },
|
||||
|
|
@ -24,7 +24,7 @@
|
|||
},
|
||||
{
|
||||
"operatingsystem": "Ubuntu",
|
||||
"operatingsystemrelease": ["12.04", "14.04"]
|
||||
"operatingsystemrelease": ["14.04"]
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue