X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=README.markdown;h=13603999525cdbf817ca9779d7a0d7d271054c84;hb=refs%2Fchanges%2F77%2F66777%2F10;hp=038795c69c8410bdb5060b1f10bba2d77233090e;hpb=7f4a4c079bb80453d62b2f12d0b56cd1bffe17c2;p=integration%2Fpackaging%2Fpuppet-opendaylight.git diff --git a/README.markdown b/README.markdown index 038795c..1360399 100644 --- a/README.markdown +++ b/README.markdown @@ -1,69 +1,441 @@ -[![Build Status](https://travis-ci.org/dfarrell07/dfarrell07-opendaylight.svg)](https://travis-ci.org/dfarrell07/dfarrell07-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][1]. ## 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). + +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 +### What `opendaylight` affects + +- 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. -* Installs OpenDaylight archive in /opt/ -* Installs a systemd unit file for OpenDaylight -* Creates an `odl` group if it doesn't exist +## Usage + +The most basic usage, passing no parameters to the OpenDaylight class, will +install and start OpenDaylight with a default configuration. -### Beginning with opendaylight +```puppet +class { 'opendaylight': +} +``` -TODO: Update +### 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'], +} ``` -The very basic steps needed for a user to get the module up and running. -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). +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'], +} ``` -## Usage +### RPM Repository + +The `rpm_repo` param can be used to configure which RPM repository +OpenDaylight is installed from. + +```puppet +class { 'opendaylight': + rpm_repo => 'https://nexus.opendaylight.org/content/repositories/opendaylight-oxygen-epel-7-$basearch-devel', +} +``` -TODO: Update +The URL should be formatted like a baseurl in RPM .repo config files. In +particular, note the $basearch variable, which should be left form the +package manager (yum, dnf) to populate. +For additional information about ODL RPM repos, see the [Integration/Packaging +RPM repositories documentation][2]. + +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': + 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][3]. + +This is only read for Debian-family operating systems. + +### 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' }, +} ``` -Put the classes, types, and resources for customizing, configuring, and doing the fancy stuff with your module here. + +### 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'} +} ``` +### Configuring websocket address + +Websocket address can be configured to the IP of ODL rather than default 0.0.0.0. This IP will +be defined by `odl_bind_ip`. + +### Enabling TLS with OpenDaylight + +It is possible to enable TLS encrypted communication for OpenDaylight Northbound REST +along with Southbound OVSDB/OpenFlow communication with Open vSwitch. To enable +TLS, use the `enable_tls` flag. This option will create two keystores in OpenDaylight +which are stored in '/opt/opendaylight/configuration/ssl'. The first keystore +is the controller keystore, which will hold the private key and ODL certificate, +along with the Certificate Authority (CA) certificate if provided. The second +keystore is the trust keystore, which will hold the trusted OVS switch certificates. + +In order to enable TLS, it is required to provide the `tls_keystore_password` +parameter. This represents the password to use for the controller and truststore +keystores. With only providing these parameters, ODL will generate the +controller keystore with a random private key and self-signed certficate. + +Additionally the `tls_key_file` and `tls_cert_file` parameters may be provided. +These represent ODL's private key file and certificate file to be used when building +the controller keystore. Optionally the `tls_ca_cert_file` may be provided which +will chain the CA certificate to the keystore for client validation. + +`tls_trusted_certs` may be provided as an array of trusted certificates to be +added to the trusted keystore. This allows OpenDaylight to identify trusted +clients which may connect to ODL Southbound and Northbound. + ## 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` + +Repo URL to install ODL RPM from, in .repo baseurl format. + +##### `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. ``` -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!) +{ '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. + +##### `log_mechanism` + +Logging mechanism for karaf logs. They are logged either to a file or console. +When `log_mechanism` is `file`, log files are configured as per `log_max_size` +and `log_max_rollover`. + +Default: `file` + +Valid options: `file`, `console`. + +##### `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. + +##### `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 -* 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/dfarrell07-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][4] for details about how to contribute to the +OpenDaylight Puppet module. + +## Release Notes + +See the [CHANGELOG][5] for information about releases. + +[1]: http://www.opendaylight.org/ "OpenDaylight homepage" + +[2]: http://docs.opendaylight.org/en/latest/submodules/integration/packaging/docs/rpms.html#repositories "ODL RPM repo docs" + +[3]: https://launchpad.net/~odl-team/+archive/ubuntu/carbon "ODL Carbon Deb repo" -## Release Notes/Contributors +[4]: 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/dfarrell07-opendaylight/blob/master/CHANGELOG) for information about releases and [CONTRIBUTORS](https://github.com/dfarrell07/dfarrell07-opendaylight/blob/master/CONTRIBUTORS) file for a list of folks who have contributed. +[5]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CHANGELOG "Chagelog"