X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=README.markdown;h=13603999525cdbf817ca9779d7a0d7d271054c84;hb=refs%2Fchanges%2F77%2F66777%2F10;hp=423f687c9d84dc0c2fb754b518337dc74c1a89a2;hpb=4d170c8f68334bc1e8c4e0e6569a5b4d259683fd;p=integration%2Fpackaging%2Fpuppet-opendaylight.git diff --git a/README.markdown b/README.markdown index 423f687..1360399 100644 --- a/README.markdown +++ b/README.markdown @@ -1,97 +1,60 @@ -[![CI Status][4]][1] -[![Dependency Status][5]][2] -[![Project Chatroom][6]][3] - # 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) - * [Log Verbosity](#log-verbosity) - * [Enabling ODL OVSDB L3](#enabling-odl-ovsdb-l3) -1. [Reference ](#reference) -1. [Limitations](#limitations) -1. [Development](#development) -1. [Release Notes/Contributors](#release-notescontributors) +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 that installs and configures the [OpenDaylight Software Defined -Networking (SDN) controller][7]. +Networking (SDN) controller][1]. ## Module Description -Deploys OpenDaylight to various OSs either via an RPM or directly from the -ODL tarball release artifact. +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]. +module's [params](#parameters). -Both supported [install methods](#install-method) default to the latest -stable OpenDaylight release, which is currently [a Beryllium ERP][18]. +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 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. +- 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. -The [vagrant-opendaylight][11] project provides an easy way to experiment -with [applying the ODL Puppet module][12] to CentOS 7, Fedora 22 and Fedora -23 Vagrant boxes. - -``` -[~/vagrant-opendaylight]$ vagrant status -Current machine states: - -cent7 not created (libvirt) -cent7_rpm_he_sr4 not created (libvirt) -cent7_rpm_li_sr2 not created (libvirt) -cent7_rpm_be not created (libvirt) -cent7_ansible not created (libvirt) -cent7_ansible_be not created (libvirt) -cent7_ansible_path not created (libvirt) -cent7_pup_rpm not created (libvirt) -cent7_pup_custom_logs not created (libvirt) -cent7_pup_tb not created (libvirt) -f22_rpm_li not created (libvirt) -f22_ansible not created (libvirt) -f22_pup_rpm not created (libvirt) -f23_rpm_li not created (libvirt) -f23_rpm_li_sr1 not created (libvirt) -f23_rpm_li_sr2 not created (libvirt) -f23_rpm_li_sr3 not created (libvirt) -f23_rpm_be not created (libvirt) -f23_ansible not created (libvirt) -f23_pup_rpm not created (libvirt) - -[~/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 @@ -111,7 +74,7 @@ certainly need to pass some. ```puppet class { 'opendaylight': - extra_features => ['odl-ovsdb-plugin', 'odl-ovsdb-openstack'], + extra_features => ['odl-netvirt-openstack'], } ``` @@ -126,36 +89,48 @@ class { 'opendaylight': } ``` -### 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 => 'https://nexus.opendaylight.org/content/repositories/opendaylight-oxygen-epel-7-$basearch-devel', +} +``` + +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. -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. +For additional information about ODL RPM repos, see the [Integration/Packaging +RPM repositories documentation][2]. -It's recommended that most people use the default RPM-based install. +This is only read for Red Hat-family operating systems. -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. +### 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][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', @@ -173,32 +148,76 @@ class { 'opendaylight': } ``` -### Enabling ODL OVSDB L3 +### Enabling ODL HA + +To enable ODL HA, use the `enable_ha` flag. It's disabled by default. -To enable the ODL OVSDB L3, use the `enable_l3` 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_l3 => true, + 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 ### Classes #### 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::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::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` @@ -224,24 +243,22 @@ Default: `[]` Valid options: A list of Karaf feature names as strings. -##### `install_method ` - -Specifies the install method by which to install OpenDaylight. +##### `odl_rest_port` -The RPM install method is less complex, more frequently consumed and -recommended. +Specifies the port for the ODL northbound REST interface to listen on. -Default: `'rpm'` +Default: `'8080'` -Valid options: The strings `'tarball'` or `'rpm'`. +Valid options: A valid port number as a string or integer. -##### `odl_rest_port ` +##### `rpm_repo` -Specifies the port for the ODL northbound REST interface to listen on. +Repo URL to install ODL RPM from, in .repo baseurl format. -Default: `'8080'` +##### `deb_repo` -Valid options: A valid port number as a string or integer. +OpenDaylight Launchpad PPA repo to install .deb from (ppa:odl-team/boron, +ppa:odl-team/carbon, ...). ##### `log_levels` @@ -281,87 +298,144 @@ org.opendaylight.ovsdb.lib | INFO The main log output file is `/opt/opendaylight/data/log/karaf.log`. -##### `enable_l3` +##### `log_max_size` -Enable or disable ODL OVSDB L3 forwarding. +Maximum size of OpenDaylight's log file, `/opt/opendaylight/data/log/karaf.log`. -Default: `'no'` +Once this size is reached, the log will be rolled over, with up to +`log_max_rollover` log rollovers preserved in total. -Valid options: The strings `'yes'` or `'no'` or boolean values `true` and `false`. +Default: `10GB` -The ODL OVSDB L3 config in `/opt/opendaylight/etc/custom.properties` is set to -the value of the `enable_l3` param. +Valid options: A valid size as a string with unit specified. -A manifest like +##### `log_max_rollover` -```puppet -class { 'opendaylight': - enable_l3 => true, -} -``` +Maximum number of OpenDaylight karaf.log rollovers to keep. -Would would result in +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. -``` -ovsdb.l3.fwd.enabled=yes -``` +Default: `2` -##### `tarball_url` +Valid options: An integer greater than 0. -Specifies the ODL tarball to use when installing via the tarball install -method. +##### `log_mechanism` -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'` +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`. -Valid options: A valid URL to an ODL tarball as a string. +Default: `file` -##### `unitfile_url` +Valid options: `file`, `console`. -Specifies the ODL systemd .service file to use when installing via the tarball -install method. +##### `enable_ha` -It's very unlikely that you'll need to override this. +Enable or disable ODL High Availablity. -Default: `'https://github.com/dfarrell07/opendaylight-systemd/archive/master/opendaylight-unitfile.tar.gz'` +Default: `false` -Valid options: A valid URL to an ODL systemd .service file (archived in a -tarball) as a string. +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 -* Tested on Fedora 22, 23, CentOS 7 and Ubuntu 14.04. -* CentOS 7 is currently the most stable OS option. -* The RPM install method is likely more reliable than the tarball install -method. +- Tested on CentOS 7 and Ubuntu 16.04. +- Fedora is allowed but not well-tested, no Beaker coverage. ## Development We welcome contributions and work to make them easy! -See [CONTRIBUTING.markdown][14] for details about how to contribute to the +See [CONTRIBUTING.markdown][4] for details about how to contribute to the OpenDaylight Puppet module. -## Release Notes/Contributors - -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]: http://cbs.centos.org/repos/nfv7-opendaylight-4-testing/x86_64/os/Packages/ +## 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" + +[4]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CONTRIBUTING.markdown "Contributing docs" + +[5]: https://git.opendaylight.org/gerrit/gitweb?p=integration/packaging/puppet-opendaylight.git;a=blob;f=CHANGELOG "Chagelog"