From f141d8f1e823f02a19123ab6f7a0b077ab8fdbdc Mon Sep 17 00:00:00 2001 From: Jaume Devesa Date: Fri, 14 Aug 2015 13:17:32 +0200 Subject: [PATCH] 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 --- CONTRIBUTING.md | 5 + README.md | 186 +++++++++++++++++------ lib/puppet/type/midonet_gateway.rb | 18 +-- lib/puppet/type/midonet_host_registry.rb | 8 +- metadata.json | 8 +- 5 files changed, 163 insertions(+), 62 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..0b12413 --- /dev/null +++ b/CONTRIBUTING.md @@ -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. diff --git a/README.md b/README.md index aefa11a..b64b90c 100644 --- a/README.md +++ b/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 $ 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. diff --git a/lib/puppet/type/midonet_gateway.rb b/lib/puppet/type/midonet_gateway.rb index 6e41a57..199564f 100644 --- a/lib/puppet/type/midonet_gateway.rb +++ b/lib/puppet/type/midonet_gateway.rb @@ -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' } ] } } diff --git a/lib/puppet/type/midonet_host_registry.rb b/lib/puppet/type/midonet_host_registry.rb index 00d6d4d..11554cc 100644 --- a/lib/puppet/type/midonet_host_registry.rb +++ b/lib/puppet/type/midonet_host_registry.rb @@ -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 diff --git a/metadata.json b/metadata.json index a5c72f8..f156bd8 100644 --- a/metadata.json +++ b/metadata.json @@ -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"] } ] }