README.markdown

   1 [![Build Status][4]][1]
   2 [![Dependency Status][5]][2]
   3 [![Join the chat at https://gitter.im/dfarrell07/puppet-opendaylight][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 Networking (SDN) controller](http://www.opendaylight.org/).
  25
  26 ## Module Description
  27
  28 Deploys OpenDaylight to various OSs either via an RPM or directly from the ODL tarball release artifact.
  29
  30 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).
  31
  32 Both supported [install methods](#install-method) default to the latest stable OpenDaylight release, which is currently Helium 0.2.3 SR3.
  33
  34 ## Setup
  35
  36 ### What `opendaylight` affects
  37
  38 * Installs Java, which is required by ODL.
  39 * Creates `odl:odl` user:group if they don't already exist.
  40 * Installs [OpenDaylight](http://www.opendaylight.org/).
  41 * 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.
  42 * Manipulates OpenDaylight's configuration files according to the params passed to the `::opendaylight` class.
  43 * Starts the `opendaylight` systemd or Upstart service.
  44
  45 ### Beginning with `opendaylight`
  46
  47 Getting started with the OpenDaylight Puppet module is as simple as declaring the `::opendaylight` class.
  48
  49 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.
  50
  51 ```
  52 [~/vagrant-opendaylight]$ vagrant status
  53 Current machine states:
  54
  55 cent7_pup_rpm             not created (virtualbox)
  56 cent7_pup_tb              not created (virtualbox)
  57 cent7_rpm                 not created (virtualbox)
  58 f20_pup_rpm               not created (virtualbox)
  59 f20_pup_tb                not created (virtualbox)
  60 f20_rpm                   not created (virtualbox)
  61 f21_pup_rpm               not created (virtualbox)
  62 f21_pup_tb                not created (virtualbox)
  63 f21_rpm                   not created (virtualbox)
  64 [~/vagrant-opendaylight]$ vagrant up cent7_pup_rpm
  65 # A CentOS 7 VM is created and configured using the ODL Puppet mod's defaults
  66 [~/vagrant-opendaylight]$ vagrant ssh cent7_pup_rpm
  67 [vagrant@localhost ~]$ sudo systemctl is-active opendaylight
  68 active
  69 ```
  70
  71 ## Usage
  72
  73 The most basic usage, passing no parameters to the OpenDaylight class, will install and start OpenDaylight with a default configuration.
  74
  75 ```puppet
  76 class { 'opendaylight':
  77 }
  78 ```
  79
  80 ### Karaf Features
  81
  82 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.
  83
  84 ```puppet
  85 class { 'opendaylight':
  86   extra_features => ['odl-ovsdb-plugin', 'odl-ovsdb-openstack'],
  87 }
  88 ```
  89
  90 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.
  91
  92 ```puppet
  93 class { 'opendaylight':
  94   default_features => ['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management'],
  95 }
  96 ```
  97
  98 ### Install Method
  99
 100 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.
 101
 102 It's recommended that most people use the default RPM-based install.
 103
 104 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.
 105
 106 ```puppet
 107 class { 'opendaylight':
 108   install_method => 'tarball',
 109   tarball_url    => '<URL to your custom tarball>',
 110   unitfile_url   => '<URL to your custom unitfile>',
 111 }
 112 ```
 113
 114 ### Ports
 115
 116 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.
 117
 118
 119 ```puppet
 120 class { 'opendaylight':
 121   odl_rest_port => '8080',
 122 }
 123 ```
 124
 125 ## Reference
 126
 127 ### Classes
 128
 129 #### Public classes
 130
 131 * `::opendaylight`: Main entry point to the module. All ODL knobs should be managed through its params.
 132
 133 #### Private classes
 134
 135 * `::opendaylight::params`: Contains default `opendaylight` class param values.
 136 * `::opendaylight::install`: Installs ODL from an RPM or tarball.
 137 * `::opendaylight::config`: Manages ODL config, including Karaf features and REST port.
 138 * `::opendaylight::service`: Starts the OpenDaylight service.
 139
 140 ### `::opendaylight`
 141
 142 #### Parameters
 143
 144 ##### `default_features`
 145
 146 Sets the Karaf features to install by default. These should not normally need to be overridden.
 147
 148 Default: `['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management']`
 149
 150 Valid options: A list of Karaf feature names as strings.
 151
 152 ##### `extra_features`
 153
 154 Specifies Karaf features to install in addition to the defaults listed in `default_features`.
 155
 156 You will likely need to customize this to your use-case.
 157
 158 Default: `[]`
 159
 160 Valid options: A list of Karaf feature names as strings.
 161
 162 ##### `install_method `
 163
 164 Specifies the install method by which to install OpenDaylight.
 165
 166 The RPM install method is less complex, more frequently consumed and recommended.
 167
 168 Default: `'rpm'`
 169
 170 Valid options: The strings `'tarball'` or `'rpm'`.
 171
 172 ##### `odl_rest_port `
 173
 174 Specifies the port for the ODL northbound REST interface to listen on.
 175
 176 Default: `'8080'`
 177
 178 Valid options: A valid port number as a string or integer.
 179
 180 ##### `tarball_url`
 181
 182 Specifies the ODL tarball to use when installing via the tarball install method.
 183
 184 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'`
 185
 186 Valid options: A valid URL to an ODL tarball as a string.
 187
 188 ##### `unitfile_url`
 189
 190 Specifies the ODL systemd .service file to use when installing via the tarball install method.
 191
 192 It's very unlikely that you'll need to override this.
 193
 194 Default: `'https://github.com/dfarrell07/opendaylight-systemd/archive/master/opendaylight-unitfile.tar.gz'`
 195
 196 Valid options: A valid URL to an ODL systemd .service file (archived in a tarball) as a string.
 197
 198 ## Limitations
 199
 200 * Tested on Fedora 20, 21, CentOS 7 and Ubuntu 14.04.
 201 * CentOS 7 is currently the most stable OS option.
 202 * The RPM install method is likely more reliable than the tarball install method.
 203 * 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.
 204
 205 ## Development
 206
 207 We welcome contributions and work to make them easy!
 208
 209 See [CONTRIBUTING.markdown](https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown) for details about how to contribute to the OpenDaylight Puppet module.
 210
 211 ## Release Notes/Contributors
 212
 213 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.
 214
 215
 216 [1]: https://travis-ci.org/dfarrell07/puppet-opendaylight
 217 [2]: https://gemnasium.com/dfarrell07/puppet-opendaylight
 218 [3]: https://gitter.im/dfarrell07/puppet-opendaylight?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
 219 [4]: https://travis-ci.org/dfarrell07/puppet-opendaylight.svg
 220 [5]: https://gemnasium.com/dfarrell07/puppet-opendaylight.svg
 221 [6]: https://badges.gitter.im/Join%20Chat.svg