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
  19 ## Overview
  20
  21 Puppet module that installs and configures the [OpenDaylight Software Defined Networking (SDN) controller](http://www.opendaylight.org/).
  22
  23 ## Module Description
  24
  25 Deploys OpenDaylight to various OSs either via an RPM or directly from the ODL tarball release artifact.
  26
  27 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).
  28
  29 Both supported [install methods](#install-method) default to the latest stable OpenDaylight release, which is currently Helium 0.2.3 SR3.
  30
  31 ## Setup
  32
  33 ### What `opendaylight` affects
  34
  35 * Installs Java, which is required by ODL.
  36 * Creates `odl:odl` user:group if they don't already exist.
  37 * Installs [OpenDaylight](http://www.opendaylight.org/).
  38 * 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.
  39 * Manipulates OpenDaylight's configuration files according to the params passed to the `::opendaylight` class.
  40 * Starts the `opendaylight` systemd or Upstart service.
  41
  42 ### Beginning with `opendaylight`
  43
  44 Getting started with the OpenDaylight Puppet module is as simple as declaring the `::opendaylight` class.
  45
  46 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.
  47
  48 ```
  49 [~/vagrant-opendaylight]$ vagrant status
  50 Current machine states:
  51
  52 cent7_pup_rpm             not created (virtualbox)
  53 cent7_pup_tb              not created (virtualbox)
  54 cent7_rpm                 not created (virtualbox)
  55 f20_pup_rpm               not created (virtualbox)
  56 f20_pup_tb                not created (virtualbox)
  57 f20_rpm                   not created (virtualbox)
  58 f21_pup_rpm               not created (virtualbox)
  59 f21_pup_tb                not created (virtualbox)
  60 f21_rpm                   not created (virtualbox)
  61 ```
  62
  63 ## Usage
  64
  65 The most basic usage, passing no parameters to the OpenDaylight class, will install and start OpenDaylight with a default configuration.
  66
  67 ```puppet
  68 class { 'opendaylight':
  69 }
  70 ```
  71
  72 ### Karaf Features
  73
  74 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.
  75
  76 ```puppet
  77 class { 'opendaylight':
  78   extra_features => ['odl-ovsdb-plugin', 'odl-ovsdb-openstack'],
  79 }
  80 ```
  81
  82 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.
  83
  84 ```puppet
  85 class { 'opendaylight':
  86   default_features => ['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management'],
  87 }
  88 ```
  89
  90 ### Install Method
  91
  92 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.
  93
  94 It's recommended that most people use the default RPM-based install.
  95
  96 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.
  97
  98 ```puppet
  99 class { 'opendaylight':
 100   install_method => 'tarball',
 101   tarball_url    => '<URL to your custom tarball>',
 102   unitfile_url   => '<URL to your custom unitfile>',
 103 }
 104 ```
 105
 106 ### Ports
 107
 108 To change the port OpenDaylight's northbound listens on for REST API calls, use the `odl_rest_port` param. This was added because OpenStack's Swift project uses a conflicting port.
 109
 110
 111 ```puppet
 112 class { 'opendaylight':
 113   odl_rest_port => '8080',
 114 }
 115 ```
 116
 117 ## Reference
 118
 119 ### Classes
 120
 121 #### Public classes
 122
 123 * `::opendaylight`: Main entry point to the module. All ODL knobs should be managed through its params.
 124
 125 #### Private classes
 126
 127 * `::opendaylight::params`: Contains default `opendaylight` class param values.
 128 * `::opendaylight::install`: Installs ODL from an RPM or tarball.
 129 * `::opendaylight::config`: Manages ODL config, including Karaf features and REST port.
 130 * `::opendaylight::service`: Starts the OpenDaylight service.
 131
 132 ### `::opendaylight`
 133
 134 #### Parameters
 135
 136 ##### `default_features`
 137
 138 Sets the Karaf features to install by default. These should not normally need to be overridden.
 139
 140 Default: `['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management']`
 141
 142 Valid options: A list of Karaf feature name strings.
 143
 144 ##### `extra_features`
 145
 146 Specifies Karaf features to install in addition to the defaults covered by `default_features`.
 147
 148 Default: `[]`
 149
 150 Valid options: A list of Karaf feature name strings.
 151
 152 ##### `install_method `
 153
 154 Determines the install method to use for OpenDaylight.
 155
 156 Default: `'rpm'`
 157
 158 Valid options: `'tarball'` or `'rpm'`
 159
 160 ##### `odl_rest_port `
 161
 162 Sets the port for the ODL northbound REST interface to listen on.
 163
 164 Default: `'8080'`
 165
 166 Valid options: Valid port numbers as strings or integers.
 167
 168 ##### `tarball_url`
 169
 170 Specifies the ODL tarball to use when installing via the tarball install method.
 171
 172 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'`
 173
 174 Valid options: A valid URL to an ODL tarball as a string.
 175
 176 ##### `unitfile_url`
 177
 178 Specifies the ODL systemd .service file to use when installing via the tarball install method.
 179
 180 It's very unlikely that you'll need to override this.
 181
 182 Default: `'https://github.com/dfarrell07/opendaylight-systemd/archive/master/opendaylight-unitfile.tar.gz'`
 183
 184 Valid options: A valid URL to a valid ODL system .service file in a tarball as a string.
 185
 186 ## Limitations
 187
 188 * Only tested on Fedora 20, 21, CentOS 7 and Ubuntu 14.04.
 189 * CentOS 7 is currently the most stable OS option.
 190 * 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.
 191
 192 ## Development
 193
 194 See [CONTRIBUTING.markdown](https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown) for details about how to contribute to the OpenDaylight Puppet module.
 195
 196 ## Release Notes/Contributors
 197
 198 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.