X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=README.markdown;h=03b88ee4fde302af5eaf41bb2b5a2ff2fcc4326e;hb=82d316ba7b9e6b4d61f48e8e6c4d9e3132ee79ae;hp=d2c9bbdf2c18bf4283f3a6653faa3e1827f86e72;hpb=6a79bb4d7bfcb00089c5427e805449f44f6cbba8;p=integration%2Fpackaging%2Fpuppet-opendaylight.git diff --git a/README.markdown b/README.markdown index d2c9bbd..03b88ee 100644 --- a/README.markdown +++ b/README.markdown @@ -1,101 +1,183 @@ -[![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) -1. [Module Description](#module-description) -1. [Setup](#setup) - * [What `opendaylight` affects](#what-opendaylight-affects) - * [Beginning with `opendaylight`](#beginning-with-opendaylight) -1. [Usage](#usage) - * [Karaf Features](#karaf-features) - * [Install Method](#install-method) - * [Ports](#ports) -1. [Reference ](#reference) - * [Classes](#classes) - * [Private Classes](#private-classes) - * [Public Classes](#public-classes) -1. [Limitations](#limitations) -1. [Development](#development) +2. [Module Description](#module-description) +3. [Setup](#setup) + +- [What `opendaylight` affects](#what-opendaylight-affects) +- [Beginning with `opendaylight`](#beginning-with-opendaylight) + +4. [Usage](#usage) + +- [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) +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][1]. ## 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). -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. +The stable/ branches install corresponding older ODL versions. ## 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][1], including a systemd unit file. +- Manipulates OpenDaylight's configuration files according to the params + passed to the `::opendaylight` class. +- Starts the `opendaylight` systemd service. ### Beginning with `opendaylight` -Getting started with the OpenDaylight Puppet module is as simple as declaring the ``::opendaylight` class. - -For an easy way to experiment with applying this Puppet module to running CentOS 7, Fedora 20 and Fedora 21 Vagrant boxes, head over to the [vagrant-opendaylight](https://github.com/dfarrell07/vagrant-opendaylight/) project. +Getting started with the OpenDaylight Puppet module is as simple as declaring +the `::opendaylight` class. ## 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': } ``` ### 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 Repository + +The `rpm_repo` param can be used to configure which RPM repository +OpenDaylight is installed from. + +```puppet +class { 'opendaylight': + rpm_repo => 'opendaylight-61-release', +} +``` -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 naming convention follows the naming convention of the CentOS Community +Build System, which is where upstream ODL hosts its RPMs. The +`opendaylight-61-release` example above would install OpenDaylight Carbon SR1 +6.1.0 from the [nfv7-opendaylight-61-release][2] 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-61-release` repo will +always provide OpenDaylight Carbon SR1 6.1, whereas `opendaylight-4-release` +will provide the latest release with major version 6 (which could include +Service Releases, like SR2 6.2). -It's recommended that most people use the default RPM-based install. +For additional information about ODL RPM repos, see the [Integration/Packaging +RPM repositories documentation][3]. -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. +This is only read for Red Hat-family operating systems. -``` +### Deb Repository + +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/carbon', } ``` +The naming convention is same as the naming convention of Launchpad PPA's, +which is where ODL .debs are hosted. The `ppa:odl-team/carbon` example above +would install OpenDaylight Carbon from the [boron launchpad repo][4]. + +This is only read for Debian-family operating systems. + ### 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'} } ``` @@ -105,25 +187,235 @@ 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-6-testing, +opendaylight-6-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`. + +##### `log_max_size` + +Maximum size of OpenDaylight's log file, `/opt/opendaylight/data/log/karaf.log`. + +Once this size is reached, the log will be rolled over, with up to +`log_max_rollover` log rollovers preserved in total. + +Default: `10GB` + +Valid options: A valid size as a string with unit specified. + +##### `log_max_rollover` + +Maximum number of OpenDaylight karaf.log rollovers to keep. + +Note that if this is set to 1, log rollovers will result in loosing newly +logged data. It's recommended to use values greater than one to prune from +the end of the log. + +Default: `2` + +Valid options: An integer greater than 0. + +##### `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` + +##### `snat_mechanism` + +Specifies the mechanism to be used for SNAT. + +Default: `controller` + +Valid options: `conntrack`, `controller` + +##### `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][5] for details about how to contribute to the +OpenDaylight Puppet module. + +## Release Notes + +See the [CHANGELOG][6] for information about releases. + +[1]: http://www.opendaylight.org/ "OpenDaylight homepage" + +[2]: http://cbs.centos.org/repos/nfv7-opendaylight-61-release/x86_64/os/Packages/ "OpenDaylight Carbon SR1 CentOS CBS repo" + +[3]: http://docs.opendaylight.org/en/latest/submodules/integration/packaging/docs/rpms.html#repositories "ODL RPM repo docs" + +[4]: https://launchpad.net/~odl-team/+archive/ubuntu/carbon "ODL Carbon Deb repo" -## Release Notes/Contributors +[5]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CONTRIBUTING.markdown "Contributing docs" -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. +[6]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CHANGELOG "Chagelog"