X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=README.markdown;h=327720d35dcd8e123e4763403530fa4afdef5134;hb=refs%2Fchanges%2F77%2F55577%2F1;hp=8aa81818a7116e274240f51f2c06ebc551f4c43d;hpb=088d183ff3529fc95c49030a76e29de6299f588f;p=integration%2Fpackaging%2Fpuppet-opendaylight.git diff --git a/README.markdown b/README.markdown index 8aa8181..327720d 100644 --- a/README.markdown +++ b/README.markdown @@ -1,4 +1,6 @@ -[![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) +[![CI Status][4]][1] +[![Dependency Status][5]][2] +[![Project Chatroom][6]][3] # OpenDaylight @@ -15,51 +17,70 @@ 1. [Reference ](#reference) 1. [Limitations](#limitations) 1. [Development](#development) +1. [Release Notes/Contributors](#release-notescontributors) ## Overview -Puppet module for deploying the [OpenDaylight Software Defined Networking (SDN) controller](http://www.opendaylight.org/). +Puppet module that installs and configures the [OpenDaylight Software Defined +Networking (SDN) controller][7]. ## Module Description -Installs and configures the [OpenDaylight SDN controller](http://www.opendaylight.org/). +Deploys OpenDaylight to various OSs either via an RPM or directly from the +ODL tarball release artifact. -Both supported [install methods](#install-method) default to the latest stable OpenDaylight release, which is currently Helium 0.2.3 SR3. +All OpenDaylight configuration should be handled through the ODL Puppet +module's [params](#parameters). If you need a new knob, [please raise an +Issue][8]. + +Both supported [install methods](#install-method) default to the latest +stable OpenDaylight release, which is currently [Lithium 3.2.0][18]. ## Setup ### What `opendaylight` affects -* Installs [OpenDaylight](http://www.opendaylight.org/). -* Installs a [systemd unitfile](https://github.com/dfarrell07/opendaylight-systemd/) for OpenDaylight. -* Starts the `opendaylight` systemd service. -* Creates `odl:odl` user:group if they don't already exist. * Installs Java, which is required by ODL. +* Creates `odl:odl` user:group if they don't already exist. +* Installs [OpenDaylight][7]. +* Installs a [systemd unitfile][9] or [Upstart config file][10] for +OpenDaylight. +* Manipulates OpenDaylight's configuration files according to the params +passed to the `::opendaylight` class. +* Starts the `opendaylight` systemd or Upstart service. ### Beginning with `opendaylight` -Getting started with the OpenDaylight Puppet module is as simple as declaring the `::opendaylight` class. +Getting started with the OpenDaylight Puppet module is as simple as declaring +the `::opendaylight` class. -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. +The [vagrant-opendaylight][11] project provides an easy way to experiment +with [applying the ODL Puppet module][12] to CentOS 7, Fedora 20 and Fedora +21 Vagrant boxes. ``` [~/vagrant-opendaylight]$ vagrant status Current machine states: +cent7 not created (virtualbox) cent7_pup_rpm not created (virtualbox) +cent7_ansible not created (virtualbox) cent7_pup_tb not created (virtualbox) cent7_rpm not created (virtualbox) -f20_pup_rpm not created (virtualbox) -f20_pup_tb not created (virtualbox) -f20_rpm not created (virtualbox) f21_pup_rpm not created (virtualbox) f21_pup_tb not created (virtualbox) f21_rpm not created (virtualbox) +[~/vagrant-opendaylight]$ vagrant up cent7_pup_rpm +# A CentOS 7 VM is created and configured using the ODL Puppet mod's defaults +[~/vagrant-opendaylight]$ vagrant ssh cent7_pup_rpm +[vagrant@localhost ~]$ sudo systemctl is-active opendaylight +active ``` ## Usage -The most basic usage, passing no parameters to the OpenDaylight class, will install and start OpenDaylight with a default configuration. +The most basic usage, passing no parameters to the OpenDaylight class, will +install and start OpenDaylight with a default configuration. ```puppet class { 'opendaylight': @@ -68,7 +89,10 @@ class { 'opendaylight': ### Karaf Features -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. +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. ```puppet class { 'opendaylight': @@ -76,7 +100,10 @@ class { 'opendaylight': } ``` -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. +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. ```puppet class { 'opendaylight': @@ -86,11 +113,19 @@ class { 'opendaylight': ### Install Method -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. +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. It's recommended that most people use the default RPM-based install. -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. +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. ```puppet class { 'opendaylight': @@ -102,7 +137,8 @@ class { 'opendaylight': ### Ports -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. +To change the port on which OpenDaylight's northbound listens for REST API +calls, use the `odl_rest_port` param. ```puppet @@ -117,14 +153,16 @@ class { 'opendaylight': #### Public classes -* `::opendaylight`: Main entry point to the module. All ODL knobs should be managed through its params. +* `::opendaylight`: Main entry point to the module. All ODL knobs should be +managed through its params. #### Private classes -* `opendaylight::params`: Contains default `opendaylight` class param values. -* `opendaylight::config`: Manages ODL config, including Karaf features and REST port. -* `opendaylight::install`: Installs ODL from an RPM or tarball. -* `opendaylight::service`: Starts the OpenDaylight service. +* `::opendaylight::params`: Contains default `opendaylight` class param values. +* `::opendaylight::install`: Installs ODL from an RPM or tarball. +* `::opendaylight::config`: Manages ODL config, including Karaf features and +REST port. +* `::opendaylight::service`: Starts the OpenDaylight service. ### `::opendaylight` @@ -132,64 +170,101 @@ class { 'opendaylight': ##### `default_features` -Sets the Karaf features to install by default. These should not normally need to be overridden. +Sets the Karaf features to install by default. These should not normally need +to be overridden. Default: `['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management']` -Valid options: A list of Karaf feature name strings. +Valid options: A list of Karaf feature names as strings. ##### `extra_features` -Specifies Karaf features to install in addition to the defaults covered by `default_features`. +Specifies Karaf features to install in addition to the defaults listed in +`default_features`. + +You will likely need to customize this to your use-case. Default: `[]` -Valid options: A list of Karaf feature name strings. +Valid options: A list of Karaf feature names as strings. ##### `install_method ` -Determines the install method to use for OpenDaylight. +Specifies the install method by which to install OpenDaylight. + +The RPM install method is less complex, more frequently consumed and +recommended. Default: `'rpm'` -Valid options: `'tarball'` or `'rpm'` +Valid options: The strings `'tarball'` or `'rpm'`. ##### `odl_rest_port ` -Sets the port for the ODL northbound REST interface to listen on. +Specifies the port for the ODL northbound REST interface to listen on. Default: `'8080'` -Valid options: Valid port numbers as strings or integers. +Valid options: A valid port number as a string or integer. ##### `tarball_url` -Specifies the ODL tarball to use when installing via the tarball install method. +Specifies the ODL tarball to use when installing via the tarball install +method. -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'` +Default: `'https://nexus.opendaylight.org/content/repositories/opendaylight.release/org/opendaylight/integration/distribution-karaf/0.3.2-Lithium-SR2/distribution-karaf-0.3.2-Lithium-SR2.tar.gz'` Valid options: A valid URL to an ODL tarball as a string. ##### `unitfile_url` -Specifies the ODL systemd .service file to use when installing via the tarball install method. +Specifies the ODL systemd .service file to use when installing via the tarball +install method. It's very unlikely that you'll need to override this. Default: `'https://github.com/dfarrell07/opendaylight-systemd/archive/master/opendaylight-unitfile.tar.gz'` -Valid options: A valid URL to a valid ODL system .service file in a tarball as a string. +Valid options: A valid URL to an ODL systemd .service file (archived in a +tarball) as a string. ## Limitations -* Only tested on Fedora 20, 21, CentOS 7 and Ubuntu 14.04. +* Tested on Fedora 20, 21, CentOS 7 and Ubuntu 14.04. * CentOS 7 is currently the most stable OS option. -* 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. +* The RPM install method is likely more reliable than the tarball install +method. +* Our [Fedora 21 Beaker tests are failing][13], but it seems to be an issue +with the Vagrant image, not the Puppet mod. ## Development -See [CONTRIBUTING.markdown](https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown) for details about how to contribute to the OpenDaylight Puppet module. +We welcome contributions and work to make them easy! + +See [CONTRIBUTING.markdown][14] for details about how to contribute to the +OpenDaylight Puppet module. ## Release Notes/Contributors -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. +See the [CHANGELOG][15] or our [git tags][16] for information about releases. +See our [git commit history][17] for contributor information. + + +[1]: https://travis-ci.org/dfarrell07/puppet-opendaylight +[2]: https://gemnasium.com/dfarrell07/puppet-opendaylight +[3]: https://gitter.im/dfarrell07/puppet-opendaylight?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge +[4]: https://travis-ci.org/dfarrell07/puppet-opendaylight.svg +[5]: https://gemnasium.com/dfarrell07/puppet-opendaylight.svg +[6]: https://badges.gitter.im/Join%20Chat.svg +[7]: http://www.opendaylight.org/ +[8]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown#issues +[9]: https://github.com/dfarrell07/opendaylight-systemd/ +[10]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/files/upstart.odl.conf +[11]: https://github.com/dfarrell07/vagrant-opendaylight/ +[12]: https://github.com/dfarrell07/vagrant-opendaylight/tree/master/manifests +[13]: https://github.com/dfarrell07/puppet-opendaylight/issues/63 +[14]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown +[15]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CHANGELOG +[16]: https://github.com/dfarrell07/puppet-opendaylight/releases +[17]: https://github.com/dfarrell07/puppet-opendaylight/commits/master +[18]: https://www.opendaylight.org/software/downloads/lithium