README.markdown

   1 [![Build Status](https://travis-ci.org/dfarrell07/puppet-opendaylight.svg)](https://travis-ci.org/dfarrell07/puppet-opendaylight) [![Dependency Status](https://gemnasium.com/dfarrell07/puppet-opendaylight.svg)](https://gemnasium.com/dfarrell07/puppet-opendaylight) [![Join the chat at https://gitter.im/dfarrell07/puppet-opendaylight](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/dfarrell07/puppet-opendaylight?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
   2
   3 # OpenDaylight
   4
   5 #### Table of Contents
   6 1. [Overview](#overview)
   7 1. [Module Description](#module-description)
   8 1. [Setup](#setup)
   9   * [What `opendaylight` affects](#what-opendaylight-affects)
  10   * [Beginning with `opendaylight`](#beginning-with-opendaylight)
  11 1. [Usage](#usage)
  12   * [Karaf Features](#karaf-features)
  13   * [Install Method](#install-method)
  14   * [Ports](#ports)
  15 1. [Reference ](#reference)
  16 1. [Limitations](#limitations)
  17 1. [Development](#development)
  18 1. [Release Notes/Contributors](#release-notescontributors)
  19
  20 ## Overview
  21
  22 Puppet module that installs and configures the [OpenDaylight Software Defined Networking (SDN) controller](http://www.opendaylight.org/).
  23
  24 ## Module Description
  25
  26 Deploys OpenDaylight to various OSs either via an RPM or directly from the ODL tarball release artifact.
  27
  28 All OpenDaylight configuration should be handled through the ODL Puppet module's [params](#parameters). If you need a new knob, [please raise an Issue](https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown#issues).
  29
  30 Both supported [install methods](#install-method) default to the latest stable OpenDaylight release, which is currently Helium 0.2.3 SR3.
  31
  32 ## Setup
  33
  34 ### What `opendaylight` affects
  35
  36 * Installs Java, which is required by ODL.
  37 * Creates `odl:odl` user:group if they don't already exist.
  38 * Installs [OpenDaylight](http://www.opendaylight.org/).
  39 * Installs a [systemd unitfile](https://github.com/dfarrell07/opendaylight-systemd/) or [Upstart config file](https://github.com/dfarrell07/puppet-opendaylight/blob/master/files/upstart.odl.conf) for OpenDaylight.
  40 * Manipulates OpenDaylight's configuration files according to the params passed to the `::opendaylight` class.
  41 * Starts the `opendaylight` systemd or Upstart service.
  42
  43 ### Beginning with `opendaylight`
  44
  45 Getting started with the OpenDaylight Puppet module is as simple as declaring the `::opendaylight` class.
  46
  47 The [vagrant-opendaylight](https://github.com/dfarrell07/vagrant-opendaylight/) project provides an easy way to experiment with [applying the ODL Puppet module](https://github.com/dfarrell07/vagrant-opendaylight/tree/master/manifests) to CentOS 7, Fedora 20 and Fedora 21 Vagrant boxes.
  48
  49 ```
  50 [~/vagrant-opendaylight]$ vagrant status
  51 Current machine states:
  52
  53 cent7_pup_rpm             not created (virtualbox)
  54 cent7_pup_tb              not created (virtualbox)
  55 cent7_rpm                 not created (virtualbox)
  56 f20_pup_rpm               not created (virtualbox)
  57 f20_pup_tb                not created (virtualbox)
  58 f20_rpm                   not created (virtualbox)
  59 f21_pup_rpm               not created (virtualbox)
  60 f21_pup_tb                not created (virtualbox)
  61 f21_rpm                   not created (virtualbox)
  62 [~/vagrant-opendaylight]$ vagrant up cent7_pup_rpm
  63 # A CentOS 7 VM is created and configured using the ODL Puppet mod's defaults
  64 [~/vagrant-opendaylight]$ vagrant ssh cent7_pup_rpm
  65 [vagrant@localhost ~]$ sudo systemctl is-active opendaylight
  66 active
  67 ```
  68
  69 ## Usage
  70
  71 The most basic usage, passing no parameters to the OpenDaylight class, will install and start OpenDaylight with a default configuration.
  72
  73 ```puppet
  74 class { 'opendaylight':
  75 }
  76 ```
  77
  78 ### Karaf Features
  79
  80 To set extra Karaf features to be installed at OpenDaylight start time, pass them in a list to the `extra_features` param. The extra features you pass will typically be driven by the requirements of your ODL install. You'll almost certainly need to pass some.
  81
  82 ```puppet
  83 class { 'opendaylight':
  84   extra_features => ['odl-ovsdb-plugin', 'odl-ovsdb-openstack'],
  85 }
  86 ```
  87
  88 OpenDaylight normally installs a default set of Karaf features at boot. They are recommended, so the ODL Puppet mod defaults to installing them. This can be customized by overriding the `default_features` param. You shouldn't normally need to do so.
  89
  90 ```puppet
  91 class { 'opendaylight':
  92   default_features => ['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management'],
  93 }
  94 ```
  95
  96 ### Install Method
  97
  98 The `install_method` param, and the associated `tarball_url` and `unitfile_url` params, are intended for use by developers who need to install a custom-built version of OpenDaylight, or for automated build processes that need to consume a tarball build artifact.
  99
 100 It's recommended that most people use the default RPM-based install.
 101
 102 If you do need to install from a tarball, simply pass `tarball` as the value for `install_method` and optionally pass the URL to your tarball via the `tarball_url` param. The default value for `tarball_url` points at OpenDaylight's latest release. The `unitfile_url` param points at the OpenDaylight systemd .service file used by the RPM and should (very likely) not need to be overridden.
 103
 104 ```puppet
 105 class { 'opendaylight':
 106   install_method => 'tarball',
 107   tarball_url    => '<URL to your custom tarball>',
 108   unitfile_url   => '<URL to your custom unitfile>',
 109 }
 110 ```
 111
 112 ### Ports
 113
 114 To change the port on which OpenDaylight's northbound listens for REST API calls, use the `odl_rest_port` param. This was added because OpenStack's Swift project uses a conflicting port.
 115
 116
 117 ```puppet
 118 class { 'opendaylight':
 119   odl_rest_port => '8080',
 120 }
 121 ```
 122
 123 ## Reference
 124
 125 ### Classes
 126
 127 #### Public classes
 128
 129 * `::opendaylight`: Main entry point to the module. All ODL knobs should be managed through its params.
 130
 131 #### Private classes
 132
 133 * `::opendaylight::params`: Contains default `opendaylight` class param values.
 134 * `::opendaylight::install`: Installs ODL from an RPM or tarball.
 135 * `::opendaylight::config`: Manages ODL config, including Karaf features and REST port.
 136 * `::opendaylight::service`: Starts the OpenDaylight service.
 137
 138 ### `::opendaylight`
 139
 140 #### Parameters
 141
 142 ##### `default_features`
 143
 144 Sets the Karaf features to install by default. These should not normally need to be overridden.
 145
 146 Default: `['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management']`
 147
 148 Valid options: A list of Karaf feature names as strings.
 149
 150 ##### `extra_features`
 151
 152 Specifies Karaf features to install in addition to the defaults listed in `default_features`.
 153
 154 You will likely need to customize this to your use-case.
 155
 156 Default: `[]`
 157
 158 Valid options: A list of Karaf feature names as strings.
 159
 160 ##### `install_method `
 161
 162 Specifies the install method by which to install OpenDaylight.
 163
 164 The RPM install method is less complex, more frequently consumed and recommended.
 165
 166 Default: `'rpm'`
 167
 168 Valid options: The strings `'tarball'` or `'rpm'`.
 169
 170 ##### `odl_rest_port `
 171
 172 Specifies the port for the ODL northbound REST interface to listen on.
 173
 174 Default: `'8080'`
 175
 176 Valid options: A valid port number as a string or integer.
 177
 178 ##### `tarball_url`
 179
 180 Specifies the ODL tarball to use when installing via the tarball install method.
 181
 182 Default: `'https://nexus.opendaylight.org/content/groups/public/org/opendaylight/integration/distribution-karaf/0.2.3-Helium-SR3/distribution-karaf-0.2.3-Helium-SR3.tar.gz'`
 183
 184 Valid options: A valid URL to an ODL tarball as a string.
 185
 186 ##### `unitfile_url`
 187
 188 Specifies the ODL systemd .service file to use when installing via the tarball install method.
 189
 190 It's very unlikely that you'll need to override this.
 191
 192 Default: `'https://github.com/dfarrell07/opendaylight-systemd/archive/master/opendaylight-unitfile.tar.gz'`
 193
 194 Valid options: A valid URL to an ODL systemd .service file (archived in a tarball) as a string.
 195
 196 ## Limitations
 197
 198 * Tested on Fedora 20, 21, CentOS 7 and Ubuntu 14.04.
 199 * CentOS 7 is currently the most stable OS option.
 200 * The RPM install method is likely more reliable than the tarball install method.
 201 * Our [Fedora 21 Beaker tests are failing](https://github.com/dfarrell07/puppet-opendaylight/issues/63), but it seems to be an issue with the Vagrant image, not the Puppet mod.
 202
 203 ## Development
 204
 205 We welcome contributions and work to make them easy!
 206
 207 See [CONTRIBUTING.markdown](https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown) for details about how to contribute to the OpenDaylight Puppet module.
 208
 209 ## Release Notes/Contributors
 210
 211 See the [CHANGELOG](https://github.com/dfarrell07/puppet-opendaylight/blob/master/CHANGELOG) or our [git tags](https://github.com/dfarrell07/puppet-opendaylight/releases) for information about releases. See our [git commit history](https://github.com/dfarrell07/puppet-opendaylight/commits/master) for contributor information.