X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=README.markdown;h=91de61e244282fbf00efa2fe33a220b986c0a2d0;hb=3c3ff2992b52aab697528c03b95f57686efd9597;hp=9f361691bd36dd6e29ac48001767a883b76d14ea;hpb=cf4b63aff8f3eb8b3a690ff7cd2ed749695f34d0;p=integration%2Fpackaging%2Fpuppet-opendaylight.git diff --git a/README.markdown b/README.markdown index 9f36169..91de61e 100644 --- a/README.markdown +++ b/README.markdown @@ -1,96 +1,198 @@ -[![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) - # OpenDaylight -#### Table of Contents +#### Table of Contents + 1. [Overview](#overview) 2. [Module Description](#module-description) 3. [Setup](#setup) - * [What `opendaylight` affects](#what-opendaylight-affects) - * [Beginning with `opendaylight`](#beginning-with-opendaylight) + +- [What `opendaylight` affects](#what-opendaylight-affects) +- [Beginning with `opendaylight`](#beginning-with-opendaylight) + 4. [Usage](#usage) - * [Karaf Features](#karaf-features) - * [Install Method](#install-method) - * [Ports](#ports) + +- [Karaf Features](#karaf-features) +- [RPM Repo](#rpm-repo) +- [Deb Repo](#deb-repo) +- [Ports](#ports) +- [Log Verbosity](#log-verbosity) +- [Enabling ODL HA](#enabling-odl-ha) + 5. [Reference ](#reference) -5. [Limitations](#limitations) -6. [Development](#development) +6. [Limitations](#limitations) +7. [Development](#development) +8. [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 a Deb. + +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 Helium 0.2.3 SR3. +By default, the master branch installs OpenDaylight from the latest testing RPM repository +or from the latest stable Deb repository depending on the OS. There are stable/ +branches that install OpenDaylight releases and service releases, like Beryllium or Beryllium SR3. ## 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. +- 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] for OpenDaylight. +- Manipulates OpenDaylight's configuration files according to the params + passed to the `::opendaylight` class. +- Starts the `opendaylight` systemd service. ### Beginning with `opendaylight` -To install and start OpenDaylight, include the `opendaylight` class: `include opendaylight`. +Getting started with the OpenDaylight Puppet module is as simple as declaring +the `::opendaylight` class. + +The [vagrant-opendaylight][11] project provides an easy way to experiment with +[applying the ODL Puppet module][12] to VMs. + +``` +# Provision a CentOS VM using puppet-opendaylight +$ vagrant up cent7_pup_rpm +$ vagrant ssh cent7_pup_rpm +$ sudo systemctl is-active opendaylight +active +``` ## Usage -The most basic usage, passing no parameters to the OpenDaylight class, will install and start OepnDaylight 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': } ``` ### 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': - extra_features => ['odl-ovsdb-plugin', 'odl-ovsdb-openstack'], + extra_features => ['odl-netvirt-openstack'], } ``` -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': default_features => ['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management'], } ``` -### Install Method +### RPM Repo -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 `rpm_repo` param can be used to configure which RPM repository +OpenDaylight is installed from. -It's recommended that most people use the default RPM-based install. +```puppet +class { 'opendaylight': + rpm_repo => 'opendaylight-40-release', +} +``` -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. +The naming convention follows the naming convention of the CentOS Community +Build System, which is where upstream ODL hosts its RPMs. The +`opendaylight-40-release` example above would install OpenDaylight Beryllium +4.0.0 from the [nfv7-opendaylight-40-release][18] repo. Repo names ending in +`-release` will always contain well-tested, officially released versions of +OpenDaylight. Repos ending in `-testing` contain frequent, but unstable and +unofficial, releases. The ODL version given in repo names shows which major +and minor version it is pinned to. The `opendaylight-40-release` repo will +always provide OpenDaylight Beryllium 4.0, whereas `opendaylight-4-release` +will provide the latest release with major version 4 (which could include +Service Releases, like SR2 4.2). -``` +For a full list of OpenDaylight releases and their CBS repos, see the +[OpenDaylight Deployment wiki][19]. + +This is only read for RedHat based operating systems. For Debian based OSs, +this values is `none`. + +### Deb Repo + +The `deb_repo` param can be used to configure which Deb repository +OpenDaylight is installed from. + +```puppet class { 'opendaylight': - install_method => 'tarball', - tarball_url => '', - unitfile_url => '', + deb_repo => 'ppa:odl-team/boron', } ``` +The naming convention is same as the naming convention of Launchpad PPA's, +which is where ODL .debs are hosted. The `ppa:odl-team/boron` example above +would install OpenDaylight Boron realease from the [odl-team's boron][20] repo. + +This is only read for Debian based operating systems. For RedHat based OSs, +this values is `none`. + ### 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 +class { 'opendaylight': + odl_rest_port => '8080', +} +``` +### Log Verbosity +It's possible to define custom logger verbosity levels via the `log_levels` +param. + +```puppet +class { 'opendaylight': + log_levels => { 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' }, +} ``` + +### Enabling ODL HA + +To enable ODL HA, use the `enable_ha` flag. It's disabled by default. + +When `enable_ha` is set to true the `ha_node_ips` should be populated with the +IP addresses that ODL will listen on for each node in the HA cluster and +`odl_bind_ip` should be set with the IP address from `ha_node_ips` configured +for the particular node that puppet is configuring as part of the +HA cluster. + +By default a single ODL instance will become the leader for the entire +datastore. In order to distribute the datastore over multiple ODL instances, +`ha_db_modules` parameter may be specified which will include the modules +desired to separate out from the default shard, along with the Yang namespace +for that module. + +```puppet class { 'opendaylight': - odl_rest_port => '8080', + enable_ha => true, + ha_node_ips => ['10.10.10.1', '10.10.10.1', '10.10.10.3'], + odl_bind_ip => 0, + ha_db_modules => {'default' => false, 'topology' => 'urn:opendaylight:topology'} } ``` @@ -100,25 +202,219 @@ 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 a Deb. +- `::opendaylight::config`: Manages ODL config, including Karaf features and + REST port. +- `::opendaylight::service`: Starts the OpenDaylight service. + +### `::opendaylight` + +#### Parameters + +##### `default_features` + +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 names as strings. + +##### `extra_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 names as strings. + +##### `odl_rest_port` + +Specifies the port for the ODL northbound REST interface to listen on. + +Default: `'8080'` + +Valid options: A valid port number as a string or integer. + +##### `rpm_repo` + +OpenDaylight CentOS CBS repo to install RPM from (opendaylight-4-testing, +opendaylight-40-release, ...). + +##### `deb_repo` + +OpenDaylight Launchpad PPA repo to install .deb from (ppa:odl-team/boron, +ppa:odl-team/carbon, ...). + +##### `log_levels` + +Custom OpenDaylight logger verbosity configuration. + +Default: `{}` + +Valid options: A hash of loggers to log levels. + +``` +{ 'org.opendaylight.ovsdb' => 'TRACE', 'org.opendaylight.ovsdb.lib' => 'INFO' } +``` + +Valid log levels are TRACE, DEBUG, INFO, WARN, and ERROR. + +The above example would add the following logging configuration to +`/opt/opendaylight/etc/org.ops4j.pax.logging.cfg`. + +``` +# Log level config added by puppet-opendaylight +log4j.logger.org.opendaylight.ovsdb = TRACE + +# Log level config added by puppet-opendaylight +log4j.logger.org.opendaylight.ovsdb.lib = INFO +``` + +To view loggers and their verbosity levels, use `log:list` at the ODL Karaf shell. + +``` +opendaylight-user@root>log:list +Logger | Level +---------------------------------- +ROOT | INFO +org.opendaylight.ovsdb | TRACE +org.opendaylight.ovsdb.lib | INFO +``` + +The main log output file is `/opt/opendaylight/data/log/karaf.log`. + +##### `enable_ha` + +Enable or disable ODL High Availablity. + +Default: `false` + +Valid options: The boolean values `true` and `false`. + +Requires: `ha_node_ips`, `odl_bind_ip` + +The ODL Clustering XML for HA are configured and enabled. + +##### `ha_node_ips` + +Specifies the IPs that are part of the HA cluster enabled by `enable_ha`. + +Default: \[] + +Valid options: An array of IP addresses `['10.10.10.1', '10.10.10.1', '10.10.10.3']`. + +Required by: `enable_ha` + +##### `ha_db_modules` + +Specifies the modules to use for distributing and sharding the ODL datastore. + +Default: `{'default'=> false}` + +Valid options: A hash of module and Yang namespace for the module (default has no namespace). + +Requires: `enable_ha` + +##### `ha_node_index` + +Specifies the index of the IP for the node being configured from the array `ha_node_ips`. + +Default: '' + +Valid options: Index of a member of the array `ha_node_ips`: `0`. + +This parameter is now deprecated and is no longer used. + +##### `security_group_mode` + +Specifies the mode to use for security groups. + +Default: `stateful` + +Valid options: `transparent`, `learn`, `stateless` + +##### `vpp_routing_node` + +Specifies the routing node for VPP deployment. A non-empty string will create config file +org.opendaylight.groupbasedpolicy.neutron.vpp.mapper.startup.cfg with routing-node set. + +Default: `''` + +Valid options: A valid host name to a VPP node handling routing. + +##### `java_opts` + +Specifies the Java options to run ODL with as a string. + +Default: `'-Djava.net.preferIPv4Stack=true'` + +Valid options: A string of valid Java options. + +##### `username` + +Specifies the username to set for admin role in ODL. + +Default: `'admin'` + +Valid options: A username string. + +##### `password` + +Specifies the password to set for admin role in ODL. + +Default: `'admin'` + +Valid options: A password string. ## Limitations -* Only 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. +- Tested on CentOS 7 and Ubuntu 16.04. +- Fedora is allowed but not well-tested, no Beaker coverage. ## Development -See [CONTRIBUTING.md](https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.md) for details about how to contribute to this 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 for information about releases. See the git commit history 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. + +[7]: http://www.opendaylight.org/ + +[8]: https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTING.markdown#issues + +[9]: https://github.com/dfarrell07/opendaylight-systemd/ + +[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]: http://cbs.centos.org/repos/nfv7-opendaylight-40-release/x86_64/os/Packages/ "OpenDaylight Beryllium CentOS CBS repo" + +[19]: https://wiki.opendaylight.org/view/Deployment#RPM "OpenDaylight RPMs and their repos" + +[20]: https://launchpad.net/~odl-team/+archive/ubuntu/boron