README.markdown

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