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

@@ -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.

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)
+    * [What MidoNet affects](#what-midonet-affects)
-    * [Beginning with midonet](#beginning-with-midonet)
+    * [Beginning with MidoNet](#beginning-with-midonet)
 4. [Usage](#usage)
 5. [Reference](#reference)
-    * [Midonet Repository Class Reference](#midonet-repository)
+    * [Classes](#classes)
-    * [Midonet Agent Class Reference](#midonet-agent)
+    * [Types](#types)
-    * [Midonet API Class Reference](#midonet-api)
+6. [Limitations - OS compatibility, etc.](#limitations)
-    * [Midonet CLI Class Reference](#midonet-cli)
+7. [Development - Guide for contributing to the module](#development)
-    * [Neutron Plugin Class Reference](#neutron-plugin)
-6. [Limitations](#limitations)
-7. [Development](#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
+To install the last stable release of MidoNet OSS, just include the
-midonet class in your Puppet manifest:
+MidoNet class in your Puppet manifest:
 
     include midonet
 
-That will provide a full MidoNet installation (repos, cassandra, zookeeper,
+That will deploy a full MidoNet installation (repos, cassandra, zookeeper,
-agent, midonet api, and midonet cli) in the target host, which is quite
+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
+MidoNet Repository adds MidoNet's repos into target system. By default it installs
-last released version of midonet:
+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
+We happily will accept patches and new ideas to improve this module.
-MidoNet's puppet repo in:
+
+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
+single commit per change. If a commit has been rejected, do the changes you
-to do and squash your changes with the previous patch:
+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
+We are using beaker for integration testing, puppet-lint for syntax code
-rspec por unit testing. To test the module before send a patch, execute:
+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
+    $ gem install bundle $ cd <path_to_puppet-midonet> $ bundle install
-    $ rake spec
-    $ rake beaker
 
-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.

lib/puppet/type/midonet_host_registry.rb

@@ -11,7 +11,7 @@ Puppet::Type.newtype(:midonet_host_registry) do
           $midonet_api_url     => 'http://controller:8080',
           $username            => 'admin',
           $password            => 'admin',
-          $ip_address => '123.23.43.2'
+          $underlay_ip_address => '123.23.43.2'
         }
   }
   ensurable

metadata.json

@@ -4,9 +4,9 @@
   "author": "MidoNet",
   "summary": "Configure and install MidoNet components",
   "license": "Apache-2.0",
-  "source": "https://github.com/midonet/arrakis",
+  "source": "https://github.com/midonet/puppet-midonet",
-  "project_page": "http://github.com/midonet/arrakis/tree/master/modules/midonet-midonet",
+  "project_page": "https://github.com/midonet/puppet-midonet",
-  "issues_url": "https://midonet.atlassian.net/projects/MDT",
+  "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"]
     }
   ]
 }