X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=README.markdown;h=91de61e244282fbf00efa2fe33a220b986c0a2d0;hb=refs%2Fchanges%2F40%2F60540%2F2;hp=b084b7193d6ab4b7559658f29147e405dcff235f;hpb=64f8b92b44aa1bd8ca59ae0b8d83ae80946b5722;p=integration%2Fpackaging%2Fpuppet-opendaylight.git diff --git a/README.markdown b/README.markdown index b084b71..91de61e 100644 --- a/README.markdown +++ b/README.markdown @@ -1,69 +1,420 @@ -[![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) +# OpenDaylight #### Table of Contents 1. [Overview](#overview) -2. [Module Description - What the module does and why it is useful](#module-description) -3. [Setup - The basics of getting started with opendaylight](#setup) - * [What opendaylight affects](#what-opendaylight-affects) - * [Setup requirements](#setup-requirements) - * [Beginning with opendaylight](#beginning-with-opendaylight) -4. [Usage - Configuration options and additional functionality](#usage) -5. [Reference - An under-the-hood peek at what the module is doing and how](#reference) -5. [Limitations - OS compatibility, etc.](#limitations) -6. [Development - Guide for contributing to the module](#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. +Puppet module that installs and configures the [OpenDaylight Software Defined +Networking (SDN) controller][7]. ## Module Description -Stands up the OpenDaylight SDN controller from an RPM, including systemd configuration. +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]. + +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 +### What `opendaylight` affects -* Installs OpenDaylight archive in /opt/ -* Installs a systemd unit file for OpenDaylight -* Creates an `odl` group if it doesn't 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] for OpenDaylight. +- Manipulates OpenDaylight's configuration files according to the params + passed to the `::opendaylight` class. +- Starts the `opendaylight` systemd service. -### Beginning with opendaylight +### Beginning with `opendaylight` -TODO: Update +Getting started with the OpenDaylight Puppet module is as simple as declaring +the `::opendaylight` class. -``` -The very basic steps needed for a user to get the module up and running. +The [vagrant-opendaylight][11] project provides an easy way to experiment with +[applying the ODL Puppet module][12] to VMs. -If your most recent release breaks compatibility or requires particular steps for upgrading, you may wish to include an additional section here: Upgrading (For an example, see http://forge.puppetlabs.com/puppetlabs/firewall). +``` +# Provision a CentOS VM using puppet-opendaylight +$ vagrant up cent7_pup_rpm +$ vagrant ssh cent7_pup_rpm +$ sudo systemctl is-active opendaylight +active ``` ## Usage -TODO: Update +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. + +```puppet +class { 'opendaylight': + 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. + +```puppet +class { 'opendaylight': + default_features => ['config', 'standard', 'region', 'package', 'kar', 'ssh', 'management'], +} +``` + +### RPM Repo + +The `rpm_repo` param can be used to configure which RPM repository +OpenDaylight is installed from. +```puppet +class { 'opendaylight': + rpm_repo => 'opendaylight-40-release', +} ``` -Put the classes, types, and resources for customizing, configuring, and doing the fancy stuff with your module here. + +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': + 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 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': + 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'} +} ``` ## Reference -TODO: Update +### Classes + +#### Public classes + +- `::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::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' } ``` -Here, list the classes, types, providers, facts, etc contained in your module. This section should include all of the under-the-hood workings of your module so people know what the module is touching on their system but don't need to mess with things. (We are working on automating this section!) + +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 -* The target OS must use systemd (Fedora 15+, CentOS 7+). -* Currently only supports RPM-based installs. +- 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) for information about releases and [CONTRIBUTORS](https://github.com/dfarrell07/puppet-opendaylight/blob/master/CONTRIBUTORS) file for a list of folks who have contributed. +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